Conversation Referrals

A conversation:referral webhook is triggered when a user is referred to an existing conversation. This can happen in multiple ways depending on the channel. For example, it might take the form of a link, a QR code, an action from a bot, and so forth. If the user is not yet part of a conversation, the user’s action will instead trigger a conversation:create webhook.

An m.me link can refer a user to an existing conversation. The link can be constructed using the name of the Facebook Page and an optional reference string using the following template: http://m.me/<PAGE_NAME>?ref=<REF_PARAM>.

The http://m.me/zendesk?ref=sunshine link triggers a referral webhook in Sunshine Conversation with a payload similar to this:

{
    "referral": {
        "code": "sunshine",
        "details": {
            "source": "MESSENGER_CODE",
            "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=sunshine:

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

Both Telegram and Viber use deep linking in order to let users create conversations with bots. In Telegram, the link is specific to every bot https://t.me/<bot username> and can take two special parameters: start or startgroup. Viber is a bit more flexible. The URL needs the chat URI and then accepts two parameters viber://pa?chatURI=<URI>&context=<Your Context>&text=<Your Text>.

Using either of the two following deep links results in this payload:

  • https://t.me/zendesk?start=sunshine
  • viber://pa?chatURI=zendesk&context=sunshine
{
    "referral": {
        "code": "sunshine"
    }
}

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 sunshine as the code will result in this payload:

{
    "referral": {
        "code": "sunshine"
    }
}