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"
    }
  }
}

Ads that click to Messenger

Ads that click to Messenger are 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"
    }
  }
}

Ads that click to WhatsApp

Ads that click to WhatsApp are a specific type of ad that sends the user to a conversation in WhatsApp. These ads can be created in Facebook by selecting the Messages objective in the Ads creation page.

In addition to generating a referral event, the resulting details will be stored in the user's client.raw object. When these details are stored, you will be able to post conversion events for that conversation.

Here's an example referral:

{
  "referral": {
    "code": "1234567890",
    "details": {
      "ctwa_clid": "ARCyp87FhJaKKiQqAP52kFsRe0AmmbZ1NN8jJ2fvNHyBqMwDHKQBjCJu1bN6W4G2ueq3GmA_5tN8zk4dnhrlG_18delJc8R8Ldc9vGE_nk9AgMDz",
      "source_id": "1234567890",
      "source_type": "ad",
      "source_url": "https://fb.me/AAAAA"
    }
  }
}

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"
  }
}

Instagram story mention

When a user mentions your Professional Instagram account in their story, a referral event will be triggered in the following circumstances:

1. If the user mentioning your business account has their account set to public, or
2. If the business account is a follower of the user who posted the story

The referral code will always have the value of story-mention, and the details object will include a source key with a URL to view the story:

{
  "referral": {
    "code": "story-mention",
    "details": {
      "source": "https://{subdomain}.zendesk.com/sc/instagram/5963c0d619a30a2e00de36b8/MjEzNDU2Nzg5MGFiY2RlZmc=",
      "type": "story"
    }
  }
}

Note: Instagram stories expire after 24 hours, and the provided URL will only work while the user's story remains active.

Conversion events

The conversion events API lets you share your user's interactions with third party channels. By tracking these interactions, you can understand and improve the performance of your ads and referrals.

Meta conversions

To track conversions for Messenger, Instagram, or WhatsApp, make a request to the Conversion Events API.

The request should include the channel as a key at the root of the object, and it in turn must contain the payload field.

payload should contain the exact structure expected by Meta's Conversions API except for the user_data field of the server event parameters, which will be provided by Zendesk.

For example:

curl https://{subdomain}.zendesk.com/sc/v2/apps/{app_id}/conversations/{conversation_id}/conversionEvents \
     -X POST \
     --user '{key_id}:{secret}' \
     -H 'content-type: application/json' \
     -d '{
        "messenger|instagram|whatsapp": {
          "payload": {
            "data": [
              {
                "action_source": "business_messaging",
                "event_name": "TestEvent",
                "event_time": 1752161233,
                "messaging_channel": "messenger|instagram|whatsapp"
              }
            ]
          }
        }
      }'

Note: If the conversation is not linked to the specified channel, a 400 bad_request error will be returned.

Note: To post a conversion event for WhatsApp, the end user must have first generated a referral event through ads that click to WhatsApp.

Meta's Dataset ID is returned in the response, which you can use in order to view the event in Meta's events manager.

For example: https://business.facebook.com/events_manager2/list/dataset/0000000000000000

{
 "conversionEvents": {
   "datasetId": "0000000000000000",
   "eventsReceived": 1
 }
}