Referral object

Learn about the Referral object used by the Automation Framework and Bot v3 API

Some channels enable users to enter conversations from sources like ads, QR or other scannable codes, or plain links. The referral object captures these points of entry and passes them along.

Here's an example of a referral object:

{
  "ref": "abc123-something-something-referral-data-from-a-llink",
  "type": "OPEN_THREAD",
  "source": "SHORTLINK"
}

Brands can configure the payloads and data associated with these referral sources, and the Automation Framework can deliver the data to bots. This is presently only passed for Facebook Messenger referrals.

Here's a breakdown of the fields associated with referral objects:

Field

Description

ref

The identifier or payload associated with the specific referral method. For example, the value of the ref query parameter of a Facebook Messenger shortlink.

source

The referral source. For example, SHORTLINK, ADS, or MESSENGER_CODE. Facebook Messenger only.

type

The type of referral. Presently, only OPEN_THREAD appears in this field. Facebook Messenger only.

adId

Facebook Ads identifier. Only present for ADS sources. Facebook Messenger only.

refererUri

For Facebook Customer Chat Plugin use-cases, the site URI from which messages were sent.