Referência do evento de webhook `messaging_referrals`

Este retorno de chamada ocorre quando o usuário já tem um tópico com o bot e acessa o tópico de uma destas formas:

Seguindo um link m.me com um parâmetro de referência
Clicando em um anúncio de conversa do Messenger
Iniciando ou retomando uma conversa a partir do plugin de bate-papo do cliente

Para rastrear referências em tópicos novos, consulte o evento de postback.

Para começar a receber esses eventos, é preciso assinar messaging_referrals nas configurações de webhook do seu app.

Exemplos

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

Referência de anúncio

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

Plugin de bate-papo com o cliente

Alteração disruptiva (5 de maio de 2020)

O evento de webhook messaging_referrals da Graph API 7.0 ou versões posteriores do plugin de bate-papo não retornará o campo sender.id. Ele retornará o novo campo sender.user_ref. A partir de 2 de novembro de 2020, as alterações entrarão em vigor para todas as versões mais antigas da Graph API.

Novo evento do webhook de referências (Graph API v7.0 ou posteriores e todas as versões a partir de 2 de novembro de 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>"
  }
}

Antigo evento do webhook de referências (Graph API v6.0 ou anteriores e todas as versões até 2 de novembro de 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>"
  }
}

Propriedades

`sender`

Propriedade	Tipo	Descrição
`id`	Cadeia de caracteres	O PSID (Número de identificação no escopo da Página) do usuário que acionou o evento de webhook.
`user_ref`	Cadeia de caracteres	O parâmetro user_ref do usuário que acionou o evento de webhook. Disponível somente para o evento de webhook do plugin de bate-papo.

`recipient`

Propriedade	Tipo	Descrição
`id`	Cadeia de caracteres	Seu ID da Página.

`referral`

Propriedade	Tipo	Descrição
`source`	String	A origem da referência. Valores compatíveis: `ADS` `SHORTLINK` `CUSTOMER_CHAT_PLUGIN`
`type`	String	O tipo de referência. Atualmente, é compatível com `OPEN_THREAD`.
`ref`	String	O atributo `ref` opcional definido no referenciador. Só há compatibilidade com caracteres alfanuméricos, assim como -, _ e =.
`referer_uri`	String	O URI do site onde a mensagem foi enviada no plugin de bate-papo do Facebook.
`is_guest_user`	String	Uma sinalização que indica se o usuário é um convidado do plugin de bate-papo do Facebook.
`ads_context_data`	Objeto	Dados com informações sobre o anúncio de CTM a partir do qual o usuário iniciou o tópico.

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

Referência do evento de webhook messaging_referrals