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:

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

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

PropertyTypeDescription

id

String

The PSID of the user that triggered the webhook event.

user_ref

String

The user_ref of the user that triggered the webhook event. This is only available for webhook event from the chat plugin.

recipient

PropertyTypeDescription

id

String

Your Page ID.

referral

PropertyTypeDescription

source

String

The source of the referral. Supported values:

  • MESSENGER_CODE
  • DISCOVER_TAB
  • ADS
  • SHORTLINK
  • CUSTOMER_CHAT_PLUGIN

type

String

The referral type. Currently supports OPEN_THREAD.

ref

String

The optional ref attribute set in the referrer.

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