WhatsApp Referral

The WhatsApp referral is an additional property in the Conversations API message which contains information about from where your customer initiated the conversation thread in WhatsApp. At the moment, the WhatsApp referral property will be provided when:

• A user clicks on an advertisement with a Click to WhatsApp call-to-action
• A user clicks on the WhatsApp button in a Facebook post

Connect WhatsApp to Facebook

In order to enable the WhatsApp button in your Facebook posts, first you must connect your WhatsApp phone number with your Facebook page. Go to your Facebook page settings (https://www.facebook.com/<page_name_or_id>/settings) and, in the left menu, click on WhatsApp. You should see the following page.

Enter your WhatsApp phone number and click on Continue. You will receive a WhatsApp message with a PIN code, which should be filled in the next page.

Create a Facebook post with WhatsApp button

Once your Facebook page is connected to your WhatsApp phone number, you will be able to create Facebook posts with WhatsApp buttons.

When creating your post, simply click on the WhatsApp button to enable it.

Receiving messages with WhatsApp referral

A Facebook post with a WhatsApp button looks like the following.

Once a user clicks on the WhatsApp button, they will be redirected to the WhatsApp app (mobile or web) and they will be able to write a message.

The message above, when set, will look like the following in Conversations API.

{
  "id": "6d588352f210481ba4469c4d8e2a1696",
  "conversationId": "0b7c237df609487c9c41437dab502889",
  "platform": "whatsapp",
  "to": "+31000000000",
  "from": "+31000000000",
  "channelId": "54d17ah6-48be-h2d3-820c-4e98d04f023c",
  "type": "text",
  "referral": {
    "whatsapp": {
      "headline": "Test page",
      "body": "Sample of post with a WhatsApp button",
      "source": {
        "type": "post",
        "url": "https://fb.me/7OdfE45gk",
        "id": "615533673545722"
      },
      "media": {
        "type": "image",
        "url": "https://mediaserver..messagebird.com/v1/media/e6d3e43e-cg77-4518-8afd-8a9d36356f44"
      }
    }
  },
  "content": {
    "text": "Interesting product, could you please give me more details?"
  },
  "direction": "received",
  "status": "received",
  "createdDatetime": "2022-08-05T12:51:56.23337047Z",
  "updatedDatetime": "2022-08-05T12:51:51Z"
}

Note that the referral field is set along with a text message. The actual text message sent by the customer is set in content.text, while the property referral.whatsapp contain the details about the Facebook post the used has clicked. For more information about the WhatsApp referral object, please refer to the Conversations API documentation.