There can be different entry points to your bot with capabilities to trigger different functionalities. Let's look at 2 such options:
One of the ways to interact with the bot on Facebook messenger is to follow the m.me link of the bot. This m.me link is the shortened URL that redirects a user directly to the chat window in messenger. Example - https://m.me/thebot
You can now add an additional parameter to this m.me link which is then sent to the bot. Example - https://m.me/thebot?ref=myrefparam
Whenever the m.me link is used with the referral paramerter for the bot on Gupshup platform, the bot receives the value of that parameter in the messageobj 's referralParam element.
Sample JSON of the parameters received by the bot
{
"botname": "thebot",
"contextobj": {
"botname": "thebot",
"channeltype": "fb",
"contextid": "12961285222",
"contexttype": "p2p"
},
"messageobj": {
"referralParam": "myrefparam",
"text": "startchattingevent",
"type": "event"
},
"senderobj": {
"channelid": "12961285222",
"channeltype": "fb",
"display": "John Doe",
"subdisplay": ""
},
"channel": "fb",
"sender": "12961285222",
"message": "startchattingevent"
}
If you are using the Gupshup's IDE Bot Builder to develop the bot then you will receive this JSON in EventHandler function.
The sample code to handle this is:
function EventHandler(context, event) {
if(event.messageobj.referralParam=='myrefparam'&& event.messageobj.type=='event'){
context.sendResponse("Hello, I am a bot. How can I help");
}
}
Important notes :
1. To receive this referral parameter messaging_referral has to be checked in the webhook settings for your app on developers.facebook.com.
2. This ref parameter is treated as a string. If you want to send more complex, structured data, it must be encoded. The maximum length is 2,083 characters.
3. 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.
Parametric Codes can be scanned to instantly link the user to your bot. You can stick these codes on fliers, ads, or anywhere else where you want your bot to be used by people. This is different than the static code because you can pass in a ref parameter which is sent to the bot as a postback when the code is scanned.
You can also generate multiple parametric codes with different ref parameters for a single bot depending upon the use case.
How to generate a parametric code?
You will have to call the graph API of facebook to do so.
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>"
Read this documentation for more information.
How to handle the response on Gupshup?
When the parametric code is scanned, the value of the “ref” parameter is sent to the EventHandler of the IDE Bot Builder code as a referral parameter. Hence you can define your logic based on the value.
Sample JSON received by the bot:
{
"botname": "xyzbankbot",
"contextobj": {
"botname": "xyzbankbot",
"channeltype": "fb",
"contextid": "16837306669484",
"contexttype": "p2p"
},
"messageobj": {
"referralParam": "billboard-ad",
"text": "startchattingevent",
"type": "event"
},
"senderobj": {
"channelid": "16837306669484",
"channeltype": "fb",
"display": "John",
"subdisplay": ""
},
"channel": "fb",
"sender": "16837306669484",
"message": "startchattingevent"
}
Your bot on Gupshup platform should be published on Facebook
Example:
If you created a code with
"data": {
"ref":"xyzbank"
}
Then you can handle this in the code as:
function EventHandler(context, event) {
if(event.messageobj.referralParam=='xyzbank'&& event.messageobj.type=='event'){
context.sendResponse("Hello "+event.senderobj.display+". I am the XYZbank bot. I can help you with many things but first please enter your phone number");
}
}