`messaging_referrals` Webhook Event Reference

This callback will occur when the user already has a thread with the bot and user comes to the thread from:

Following an m.me link with a referral parameter
Clicking on a Messenger Conversation Ad
Starting or resuming a conversation from the customer chat plugin.

For tracking referrals in new threads, refer to Postback Event.

To start receiving these events you need to subscribe to messaging_referrals in the webhook settings for your app.

Examples

m.me Link

{
  "sender": {
    "id": "<PSID>"
  },
  "recipient": {
    "id": "<PAGE_ID>"
  },
  "timestamp": 1458692752478,
  "referral": {
    "ref": <REF_DATA_PASSED_IN_M.ME_PARAM>,
    "source": "SHORTLINK",
    "type": "OPEN_THREAD",
  }
}

Ad Referral

{
  "sender": {
    "id": "<PSID>"
  },
  "recipient": {
    "id": "<PAGE_ID>"
  },
  "timestamp": 1458692752478,
  "referral": {
    "ref": <REF_DATA_IF_SPECIFIED_IN_THE_AD>,
    "ad_id": <ID_OF_THE_AD>,
    "source": "ADS",
    "type": "OPEN_THREAD",
    "ads_context_data": {
      "ad_title": <TITLE_OF_THE_AD>,
      "photo_url": <URL_OF_THE_IMAGE_FROM_AD_THE_USER_IS_INTERESTED_IN>,
      "video_url": <THUMBNAIL_URL_OF_THE_VIDEO_FROM_THE_AD>,
      "post_id": <ID_OF_THE_POST>,
      "product_id": <PRODUCT_ID>
    }
  }
}

Customer Chat Plugin

Breaking Change (May 5, 2020)

Graph API v7.0+ messaging_referrals webhook event from the chat plugin will not be returning sender.id field. It will return a new sender.user_ref field. This changes will take effect on all older Graph API versions starting Nov 2, 2020.

New Referral Webhook Event (Graph API v7.0+ and all Graph API versions starting Nov 2, 2020)

{
  "sender":{
    "user_ref":"<USER_REF>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp": 1458692752478,
  "referral": {
     "ref": "<REF_DATA_PASSED_IN_CODE>",
     "source": "CUSTOMER_CHAT_PLUGIN",
     "type": "OPEN_THREAD",
     "referer_uri": "<WEBSITE_URL>"
  }
}

Old Referral Webhook Event (Graph API <= v6.0 - Available until Nov 2, 2020)

{
  "sender":{
    "id":"<PSID>"
  },
  "recipient":{
    "id":"<PAGE_ID>"
  },
  "timestamp": 1458692752478,
  "referral": {
     "ref": "<REF_DATA_PASSED_IN_CODE>",
     "source": "CUSTOMER_CHAT_PLUGIN",
     "type": "OPEN_THREAD",
     "referer_uri": "<WEBSITE_URL>"
  }
}

Properties

`sender`

`sender` Field	Description
`id` string	The Page-scoped ID for the person who sent a message to your business
`user_ref` string	The reference for a person who used the Chat Plugin to messsage your business

`recipient`

`recipient` Field	Description
`id` string	The ID for your Facebook Page

`referral`

Property	Type	Description
`source`	String	The source of the referral. Supported values: `ADS` `SHORTLINK` `CUSTOMER_CHAT_PLUGIN`
`type`	String	The referral type. Currently supports `OPEN_THREAD`.
`ref`	String	The optional `ref` attribute set in the referrer. Only alphanumeric characters as well as -, _, and = are supported.
`referer_uri`	String	The URI of the site where the message was sent in the Facebook chat plugin.
`is_guest_user`	String	A flag indicating whether the user is a guest user from Facebook Chat Plugin
`ads_context_data`	Object	The data contaning information about the CTM ad, the user initiated the thread from.

`ads_context_data`

Property	Type	Description
`ad_title`	String	Title of the Ad.
`photo_url`	String	[Optional] Url of the image from the Ad the user is interested.
`video_url`	String	[Optional] Thumbnail url of the the video from the ad.
`post_id`	String	ID of the post.
`product_id`	String	[Optional] Product ID from the Ad the user is interested.

messaging_referrals Webhook Event Reference

Contents