Messenger Platform
messaging_referrals Webhook Event Reference
Updated: Jul 1, 2025
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
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.Contents
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>,
"flow_id": <ID_OF_THE_PARTNER_APP_WELCOME_MESSAGE_FLOW>
}
}
}
For more information about the flow ID, please refer to Welcome Message Flows.
Properties
sender
sender Field
| Description |
|---|---|
id string | The Page-scoped ID for the person who sent a message to 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:
|
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. |
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. |
Did you find this page helpful?
