Questo documento è stato aggiornato.
La traduzione in Italiano non è ancora completa.
Aggiornamento inglese: 14 mar 2022
Aggiornamento Italiano: 29 mar 2018

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

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 FieldDescription

id

string

The ID for your Facebook Page

referral

PropertyTypeDescription

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

PropertyTypeDescription

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.