Conversation referrals

A "referral" in Zendesk messaging occurs when a user is directed to a conversation for a particular reason. This can happen in multiple ways depending on the channel. For example, it might take the form of a link or a QR code which the user interacted with that leads them to engage in a conversation with your business.

Referral events

When a referral event causes a new conversation to be created, the conversation:create webhook event will include a referral key with more details about the source of the referral. If a user is referred back to an existing conversation, a conversation:referral webhook event is generated instead. The schema definition for each of these events can be found in the API specification.

In either case, the referral object will always include a referral code, and some types of referrals will also include a details object with more context.

Use cases

Messenger's m.me link

An m.me link can be used to refer a user to Facebook Messenger. The link will take them to a conversation with your Facebook page, with the option to supply an additional ref param. If a ref is supplied, a referral event will be triggered.

For example, a user following this link:

https://m.me/<PAGE_NAME>?ref=my_referral_code

will trigger a conversation:create or conversation:referral event with the following details:

{
  "referral": {
    "code": "my_referral_code",
    "details": {
      "source": "SHORTLINK",
      "type": "OPEN_THREAD"
    }
  }
}

Facebook's conversion ad

Facebook's conversion ad is a specific type of ad that sends the user to a conversation in Messenger. These ads can be created in Facebook by selecting the Messages objective in the Ads creation page.

When creating an ad, an extra ref parameter can be provided for additional information. Here's an example with ref=my_referral_code:

{
  "referral": {
    "code": "my_referral_code",
    "details": {
      "source": "ADS",
      "type": "OPEN_THREAD",
      "ad_id": "6045246247433"
    }
  }
}

Bot deep links

Both Telegram and Viber use deep linking in order to let users create conversations with bots.

In Telegram, you can specify the start query parameter to trigger a referral event:

https://t.me/<BOT_NAME>?start=my_referral_code

For Viber, specify the chat URI for your bot, and a context param with your referral code:

viber://pa?chatURI=<CHAT_URI>&context=my_referral_code

Bot deep links on Telegram or Viber will produce the following referral payload:

{
  "referral": {
    "code": "my_referral_code"
  }
}

WeChat QR code

Scanning a WeChat QR code when the user is already a follower will also act as a referral. Creating a QR code with my_referral_code as the code will result in this payload:

{
  "referral": {
    "code": "my_referral_code"
  }
}