Facebook Messaging Referrals

Facebook Messaging Referrals is a Facebook-specific inbound-only message type that provides information about how the recipient got into an existing thread via one of the following ways:

• An m.me link with a referral parameter
• Clicking on a Facebook Messenger conversation advertisement
• Starting or resuming a conversation thread from the Facebook Chat Plugin

m.me links with a referral parameter

m.me links provides your business a way to redirect customers to communicate with a specific Facebook page. When your customers click on an m.me link, your business will receive an inbound message with type facebookReferral from Conversations API. In case the link contains a referral parameter (ref), this information is also included in the inbound message.

For example, a customer clicking on the link http://m.me/<PAGE_NAME>?ref=my-referral-parameter will receive an facebookReferral inbound message similar to the following one.

{
  "id": "c3fefc2a9e754e878777b557f2e9d977",
  "conversationId": "9702e94e560845868c7fb03a1cd23928",
  "platform": "facebook",
  "to": "103865305630237",
  "from": "5306019189461056",
  "channelId": "d8f3d7ab604b4bac8faa96d02ed83b0f",
  "type": "facebookReferral",
  "content": {
    "facebookReferral": {
      "ref": "my-referral-parameter",
      "source": "SHORTLINK",
      "type": "OPEN_THREAD"
    }
  },
  "direction": "received",
  "status": "received",
  "createdDatetime": "2022-04-28T12:21:02.792Z",
  "updatedDatetime": "2022-04-28T12:21:02.792Z"
}

Please note that the content.facebookReferral.ref field contains the information from the URL ref query parameter. Please refer to the facebookReferral object for more information about this message type. You can also refer to the Facebook m.me link requirements to understand what's necessary for using m.me links.

Facebook Messenger conversation advertisement

When customers click on a Facebook Messenger conversation advertisement, Conversations API also delivers an inbound message with type facebookReferral similar to the following one.

{
  "id": "d16d39a760314d1fb026f10e6835c58e",
  "conversationId": "2b9fd2d6b87041ceb6485d8f8c97ab77",
  "platform": "facebook",
  "to": "103955145046384",
  "from": "3919556244813081",
  "channelId": "2cc5f8a4020747be80c6b1f70c9f6eb3",
  "type": "facebookReferral",
  "content": {
    "facebookReferral": {
      "ref": "my-referral-parameter",
      "source": "ADS",
      "type": "OPEN_THREAD",
      "ad_id": "6045246247433",
      "ads_context_data": {
        "ad_title": "My advertisement title",
        "photo_url": "https://www.yourcompany.com/photo.png",
        "video_url": "https://www.yourcompany.com/video.mp4",
        "post_id": "392982738592",
        "product_id": "8478935323493"
      }
    }
  },
  "direction": "received",
  "status": "received",
  "createdDatetime": "2022-04-22T14:09:37.449Z",
  "updatedDatetime": "2022-04-22T14:09:37.449Z"
}

Facebook Chat plugin

The Facebook Chat plugin allows you to integrate Facebook Messenger into your company's website. When your customers, browsing your website, start or resume a conversation thread using the Facebook Chat plugin, Conversations API will deliver an inbound message with type facebookReferral similar to the following one.

{
  "id": "d16d39a760314d1fb026f10e6835c58e",
  "conversationId": "2b9fd2d6b87041ceb6485d8f8c97ab77",
  "platform": "facebook",
  "to": "103955145046384",
  "from": "3919556244813081",
  "channelId": "2cc5f8a4020747be80c6b1f70c9f6eb3",
  "type": "facebookReferral",
  "content": {
    "facebookReferral": {
      "ref": "my-referral-parameter",
      "source": "CUSTOMER_CHAT_PLUGIN",
      "type": "OPEN_THREAD"
    }
  },
  "direction": "received",
  "status": "received",
  "createdDatetime": "2022-04-22T14:09:37.449Z",
  "updatedDatetime": "2022-04-22T14:09:37.449Z"
}