Using m.me Links

m.me is a shortened URL service operated by Facebook that redirects users to a person, page, or bot in Messenger.

You can use them on your website, email newsletters, and more. It works on mobile as well as desktop.

The format of the link is http://m.me/PAGE_NAME, where PAGE_NAME is the handle of the Facebook page the bot is linked to.

Passing Parameters via M.me Links

In addition to giving bot developers a way to link to their bot, Messenger Platform now also supports the passing an arbitrary parameter via these links.

This can be used for many purposes. It could be used to track different links placed in different channels to see which is most effective. It could also be used to tie a Messenger user to a session or account in an external app. It could even be used to direct the user to specific content or features available within the bot.

Passing a Parameter

A m.me link with an added parameter looks like this: http://m.me/mybot?ref=myparam

The value of the ref parameter will be passed to the server via webhook.

Reading the Passed Parameter

When an m.me link with a ref parameter opens Messenger to your bot, there are two possible scenarios you should be aware of:

1. First-Time Use Scenario

If you have configured a "Get Started" button for your page, we will deliver the passed ref param as part of the postback event that is normally sent when the button is tapped.

{
  "sender":{
    "id":"USER_ID"
  },
  "recipient":{
    "id":"PAGE_ID"
  },
  "timestamp":1458692752478,
  "postback":{
    "payload":"USER_DEFINED_PAYLOAD",
    "referral": {
      "ref": ref_data_in_m_dot_me_param,
      "source": "SHORTLINK",
      "type": "OPEN_THREAD",
    }
  }
}

In the above, USER_DEFINED_PAYLOAD refers to the payload you previously configured to be sent in the postback.

The referral portion always follows this format:

"referral": {
  "ref": ref_data_in_m_dot_me_param,
  "source": "SHORTLINK",
  "type": "OPEN_THREAD",
 }
Field Value Description

ref

The arbitrary data that was originally passed in the ref param added to the m.me link.

source

The source of this referral. For m.me links, the value of source is “SHORTLINK”. For referrals from Messenger Conversation Ads, the value of source is "ADS".

type

The identifier for the referral. For referrals coming from m.me links, it will always be "OPEN_THREAD".

2. Existing User Scenario

If the user already has a thread with your bot, when the user follows your m.me link, Messenger does not show any "Get Started" screen, it just opens the thread.

In this case, your webhook will immediately receive a messaging_referrals event. The webhook must have already subscribed to this event in order to be notified of the referral in this scenario.

The messaging_referrals webhook event follows this format:

{
  "sender":{
    "id":"USER_ID"
  },
  "recipient":{
    "id":"PAGE_ID"
  },
  "timestamp":1458692752478,
  "referral": {
    "ref": ref_data_in_m_dot_me_param,
    "source": "SHORTLINK",
    "type": "OPEN_THREAD",
  }
}

Caveats

  • In order to protect our users' privacy, every time the bot's backend is notified of a user entering the bot via an m.me link with a ref parameter, an informational message is displayed in the thread: "You have entered this conversation by following a link. We've let PAGE_NAME know you're here."

  • If a page hasn't set up a "Get Started" button and the user has no prior conversation with the bot, the referral will not be conveyed to the bot. Therefore, to use this feature you must set a get started for your page.

  • The referral will not be passed to the bot for non-developer users if the Facebook page the bot is attached to is not published.

  • This feature is supported on Messenger for iOS and Android version 92.0 and above. The ref parameter will not be passed in earlier versions.

  • We treat ref as a string. If you want to send more complex, structured data, it must be encoded. The maximum length is 2,083 characters.

  • source and type are identifiers whose value are fixed for m.me referrals. In the future, Messenger may use this mechanism to inform the bot of refferals coming from other channels, which would require using other identifiers in these fields.

  • ref_data delivery is similar to postback event. If a user blocks a bot, then ref_data is not delivered to the webhook.

  • ref_data is locally retained in Messenger until the user actually enters the thread, then transmitted. If the user cancels and goes to another screen in messenger, it will be lost.

  • If the user clicks a m.me link passing a ref parameter on one client, backs out, then subsequently enters the same bot on a different client, the ref parameter passed originally will be lost and not delivered.

  • The FB page that the bot is bound to must be set to published for the links to work in all cases.