Справка по событию Webhooks `messaging_referrals`

Этот обратный вызов выполняется, когда пользователь уже начал переписку с ботом и перешел в неё:

по ссылке m.me с реферальным параметром;
нажав рекламу с переходом в Messenger;
начав или продолжив переписку в плагине чата.

Информацию об отслеживании реферальных параметров в новых переписках см. в документации по событию обратного вызова.

Чтобы получать эти события, необходимо подписаться на messaging_referrals в настройках Webhooks вашего приложения.

Примеры

Ссылки m.me

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

Рефералы в объявлениях

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

Плагин чата с клиентами

Важное изменение (5 мая 2020 г.)

В API Graph версии 7.0 и более новых событие Webhook messaging_referrals от плагина чата не будет возвращать поле sender.id. Вместо этого будет возвращаться новое поле sender.user_ref. Это изменение вступает в силу для всех предыдущих версий API Graph 2 ноября 2020 г.

Новое событие Webhook перехода (API Graph версии 7.0 и более новых, а также все версии API Graph начиная со 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>"
  }
}

Старое событие Webhook перехода (API Graph версии 6.0 и более старых до 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>"
  }
}

Свойства

`sender`

Свойство	Тип	Описание
`id`	строка	PSID пользователя, который запустил событие Webhook.
`user_ref`	Строка	user_ref пользователя, который запустил событие Webhook. Доступно только для события Webhook плагина чата.

`recipient`

Свойство	Тип	Описание
`id`	строка	ID вашей Страницы.

`referral`

Свойство	Тип	Описание
`source`	Строка	Источник этого реферала. Поддерживаемые значения: `ADS`; `SHORTLINK`; `CUSTOMER_CHAT_PLUGIN`.
`type`	Строка	Тип реферала. В настоящий момент поддерживается `OPEN_THREAD`.
`ref`	Строка	Свойство `ref`, заданное в реферале (необязательно). Поддерживаются только буквы и цифры, а также символы -, _, и =.
`referer_uri`	Строка	URI сайта, с которого было отправлено сообщение в плагин чата Facebook.
`is_guest_user`	Строка	Флаг, который указывает, является ли пользователь гостем из плагина чата Facebook.
`ads_context_data`	Объект	Информация об объявлении с переходом в Messenger, из которого пользователь начал переписку.

`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.

Справка по событию Webhooks messaging_referrals