Facebook Referral Callbacks

The Facebook Messenger platform allows bot developers to keep track of several entry points that people have used to discover their bot by passing in referral parameters:

When Facebook passes in referral parameters, we will store these values in the _fbRefSource, _fbRefParam, and the _fbRefAdId (if relevant) namespace variables.

In order for Facebook to pass referrals in, you must have the messaging_referrals event activated for your Facebook Messenger app.

Activate the messaging_referrals Event

To get the messaging_referrals event on your Facebook app,

  1. Venture over the https://developers.facebook.com/apps/ website and find your app.
  2. Find "Messenger" under "Products" on the left sidebar.
  3. In the "Webhooks" section, click "Edit events" and check off "messaging_referrals" event under "Edit Page Subscription Fields".

messaging_referral event

Messenger provides a m.me shortened url service to pass in an arbitrary parameter via their [m.me shortened URL service]. An m.me link looks like the following:


If a user accesses the bot through this link, the following namespace variables are saved:

Variable Name Value
_fbRefSource SHORTLINK
_fbRefParam myparam
_fbRefAdId N/A

There are two scenarios in which a user can message the bot through a m.me link:

1. First-time User Scenario

In order to pass a ref param as part of a postback event for a message from a first-time user, you must include a "Get Started Button", which you can configure on the Platforms page for your bot.

When a user visits the above m.me referral link and then taps the Get Started button, this will trigger the payload you configured. If this payload is get_started_payload, we will match against a trigger with this

+ get_started_payload
* <get _fbRefSource> == SHORTLINK => You came in through a shortlink!
- You didn't come in through a m.me referral!

2. Existing User Scenario

If the user has already engaged with the bot in the past, when the user accesses the bot again through a m.me referral link, you can trigger a relevant message to the user by drafting responses for the __fbref__ trigger:

+ __fbref__
* <get _fbRefSource> == SHORTLINK => {@ shortlink_hello}
- How did you get here? It wasn't through a m.me referral!
+ shortlink_hello
* <get _fbRefParam> == myparam => Welcome back, I see you've been using the tutorials at docs.rundexter.com!
* <get _fbRefParam> == dogs => Welcome back, this is a new dog-relevant greeting!
- What param did you pass in through the m.me link? Oh, you passed in <get _fbRefParam>? That's not "myparam" or "dogs"...

Messenger Conversation Ads

If you put a Facebook Ad against your Messenger bot, you can use this set of namespace variables to determine which ad your user came in through. (The ref param is set up on the Facebook Ads platform under Advanced Options > URL Parameters.)

Variable Name Value
_fbRefSource ADS
_fbRefParam myparam
_fbRefAdId 6045246247433

Look at the following bot script for a sample scenario to handle Messenger Conversation Ad referrals:

+ __fbref__
* <get _fbRefSource> == ADS => {@ ad_hello}
- You didn't get here through an ad!
+ ad_hello
* <get _fbRefAdId> == 6045246247433 => Hi, you clicked on our ad for chunky Peanut Butter! You must really like the added fiber!
* <get _fbRefAdId> == 6045246247434 => Hi, you clicked on our ad for smooth Peanut Butter! Our brand is the creamiest brand out there!
- We love peanut butter!

Parametric Messenger Codes

Facebook bots can generate their own QR code -- termed Messenger Codes by Facebook. To do so, read more on the Facebook documentation here. As part of the CURL request for generating the Messenger code, you can also pass in a ref param, making this a "parametric" Messenger Code (as opposed to a )

If a user accesses your bot by scanning a Messenger Code (with an associated ref), this ref will be stored in _fbRefParam.

Variable Name Value
_fbRefParam myparam
_fbRefAdId N/A
+ __fbref__
* <get _fbRefSource> == MESSENGER_CODE => You scanned a Messenger code!
- How did you get here? It wasn't through a Messenger Code!

Discover Tab

The Messenger app now has a new Discover Tab in the Messenger app to allow users to explore bots from other developers. No ref params are provided when users find the bot through the Discover tab:

Variable Name Value
_fbRefParam N/A
_fbRefAdId N/A
+ __fbref__
* <get _fbRefSource> == DISCOVER_TAB => You found our bot through the Discover tab!
- How did you get here? It wasn't through the Discover tab!

Do Not Respond to Referrals

If you do not want your bot to respond to any referral callbacks, even if a user has visited your bot through a m.me link with a ref query param, have your response for the __fbref__ trigger include a <noreply>.

+ __fbref__
- <noreply>

If you do not include a __fbref__ trigger, the bot will respond to any referral callback with the catch-all trigger.