GuidesReference
BlogUpdatesSlackGitHubConsole

Referral codes

Suggest Edits

Meya supports "deep linking" to your bot with two distinct benefits:

  1. Invoke specific flows based on a parameter in a link (URL) to your bot
  2. Identify how users came to discover your bot by tagging the user with a referral code in the Meya database

Referrals in Messenger can be accessed via links or parametric codes (for scanning). Some common use-cases include: ads, segmenting users, analytics and specific promos and specials. Learn more on Facebook docs.

🚧

For referrals to work with Facebook Messenger, you must enable the messaging_referrals subscription on your webhook connected to your Facebook app.

Facebook Messenger referrals can be accessed via links in the following format:
https://m.me/your_bot_name?ref=custom_tag_goes_here

On your bot's Messenger integration page, you will find a section for referrals:

1896

The list of bot referral codes

1960

Constructing a referral code

📘

User-generated referrals

If a user comes in with a referral code that has not been defined yet, a new one will be created.

📘

Using referrals in Facebook ad units

You can copy the "Ad payload" as the USER_DEFINED_PAYLOAD in a Facebook ad unit that directs users to your bot.

🚧

Facebook Messenger first time referrals

For referrals to work with Messenger you have to have a "Get started" button set with your bot. The referral flow will override this setting, but the get started button must exist for referrals to work.

How it works

The code will be saved in the user scope database with the following keys when a link is clicked:

KeyNotesExamples
referralIs overwritten every time the user clicks. Stores the last referral link that was clicked.{{ user.referral }}
self.db.user.get("referral")
first_referralIs written the first time the user clicks the referral link. In Messenger, this corresponds to the "Get started" button click.{{ user.first_referral }}
self.db.user.get("first_referral")

Parametric codes

Every referral code will also have a corresponding parametric code that can be scanned by the user. They're great for sticking on fliers, ads, or anywhere in the real world where you want people to try your bot.

946

🚧

Do not hot link the image

The URI for the Messenger Code is not permanent. Click the image to download and cache the image file.

Passing dynamic data with referral code

Use-case: If your require dynamic data to be passed in with your referral code, you can include it as part of the referral code.

Let's say you have an existing referral code jobs and you would like to pass in the particular job id (ex. 1234) along with the referral code. Rather than create hundreds of referral codes, you can use the following pattern:

https://www.messenger.com/t/284441248606993?ref=jobs__1234

By separating the referral and the data with a double underscore __ Meya will then includes the data on flow scope at {{ flow.value }}.

How-to:

  1. Navigate to YOUR_BOT > Integrations > Messenger
  2. At bottom of page click Create New Referral
  3. Add a code and specify an associated flow (ex. code="jobs", flow="ref_with_data")
  4. Link to your bot using the pattern https://www.messenger.com/t/xxxxxxxx?ref=YOURCODE__CUSTOMDATA
  5. Read flow.value in your flow or custom component which will be set to CUSTOMDATA
1216

Create a referral code

states:
    first:
        component: meya.text
        properties:
            text: "You passed in: {{ flow.value }}"
635

What it looks like in Messenger

Updated almost 6 years ago