Messenger Code API

Messenger Codes can be scanned to instantly link the user to your bot, no typing needed.


They're great for sticking on fliers, ads, or anywhere in the real world where you want people to try your bot.

All owners of Facebook pages can find their page's Messenger Code using the page admin tool or in the Pages Manager app.

Beyond this, there may be situations where you wish to programmatically get your bot's Messenger Code.

Static Codes

Getting the static Messenger Code is useful if you're running a tool that manages messaging on behalf of many different pages. In such a situation, you might want to request a code on behalf of your client and display it in a prominent place in the UI your customers see.

Parametric CodesNEW!

Developers can also arbitrarily generate codes to pass different ref parameters to the same bot. You might use this to track which codes are getting scanned the most. A bot could even activate different functionality based on which code was scanned. For instance, a restaurant could put a different code on a each table to pass along to the bot where food should be delivered.

You can watch for users scanning parametric codes in the postback and referral webhook events.

Calling the API

Calling this API requires an access token for the page.

Generating a static code

curl -X POST -H "Content-Type: application/json" -d '{
  "type": "standard",
  "image_size": 1000
}' "https://graph.facebook.com/v2.6/me/messenger_codes?access_token=<ACCESS_TOKEN>"

Generating a parametric code

curl -X POST -H "Content-Type: application/json" -d '{
  "type": "standard",
  "data": {
    "ref":"billboard-ad"
  },
  "image_size": 1000
}' "https://graph.facebook.com/v2.6/me/messenger_codes?access_token=<ACCESS_TOKEN>"

Parameters

Name Description Required

type

"standard" for a static or parametric Messenger code for the bot.

Y

image_size

The size, in pixels, for the image you are requesting. Supported range: 100-2000 px, defaults to 1000px.

N

data

If creating a parametric code, pass {"data":{"ref":"YOUR_REF_HERE"}}.


The ref is a string of max 250 characters. Valid characters are a-z A-Z 0-9 +/=-.:_

N

Response

{ 
  "uri": "YOUR_CODE_URL_HERE"
}
Name Description

uri

The URI that you can download your Messenger Code at.

This is not a permanent URI; you should download and cache the image as soon as possible.

Tip: You can replace the image in the center with any image you want. It won't affect the functionality of the code.

Responding to Scans

After generating a parametric code, you should watch for the ref parameter in two places:

  • If the user is entering the bot for the first time, the postback webhook will be called.

  • If the user is re-entering the bot by scanning the code, the referral webhook will be called.