Add Persistent Menu and Buttons to your messenger bot

In my previous post How to build Facebook Messenger Chat Bot using PHP, I illustrated how to develop a simple chat bot that respond back with text message. Now that we have a Bot, it’s time to personalize it. We can make it more user friendly as well as visually appealing by adding features like Persistent Menu, Get Started Button and Greeting Text.

These features are available by configuring Thread Settings. In order to configure the Thread Settings, you need to make a POST call to /me/thread_settings?access_token=PAGE_ACCESS_TOKEN with the parameters in the body.

In this article, I will start with setting up Persistent Menu. Then I will talk on handling POSTBACK response using PHP. Next I will show how to add GET Started Button. Finally, I will show how to add Greeting Text.

So, what is Persistent Menu?

Persistent Menu

Literally, persistent means continuing to exist or occur over a prolonged period. The Persistent Menu is always available to the user. This menu should contain top-level actions that users can enact at any point. Having a persistent menu easily communicates the basic capabilities of your bot for first-time and returning users.
The menu can be invoked by a user, by tapping on the 3-caret icon on the left of the composer.

How to setup Persistent Menu?

It is very easy to add Persistent Menu to your Chat Bot. You just need to make a POST request to Facebook Graph API with required parameters. Here’s the sample cURL request:

curl -X POST -H "Content-Type: application/json" -d '{
  "setting_type" : "call_to_actions",
  "thread_state" : "existing_thread",
  "call_to_actions":[
    {
      "type":"postback",
      "title":"Help",
      "payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_HELP"
    },
    {
      "type":"postback",
      "title":"Latest Posts",
      "payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_LATEST_POSTS"
    },
    {
      "type":"web_url",
      "title":"View Website",
      "url":"http://yoursite.com/"
    }
  ]
}' "https://graph.facebook.com/v2.6/me/thread_settings?access_token=PAGE_ACCESS_TOKEN"

In the above example, call_to_actions contains the menu items. You can have maximum 5 items which can be either postback or web_url. In addition to this, the title has a 30 character limit. PAGE_ACCESS_TOKEN is the Page Access Token of the Page with which your bot is associated.

If successfully setup, you will get the following response:

{"result":"Successfully added structured menu CTAs"}

Here’s how a Persistent Menu looks like.

In case you need to delete the Persistent Menu, send a DELETE request.

curl -X DELETE -H "Content-Type: application/json" -d '{
  "setting_type":"call_to_actions",
  "thread_state":"existing_thread"
}' "https://graph.facebook.com/v2.6/me/thread_settings?access_token=PAGE_ACCESS_TOKEN"

Update:
You can also add Unicode characters and emojis to your persistent menu items. To do this you just need to type or paste those characters to the title attributes. You can copy emojis from here http://getemoji.com/. Here is how persistent menu looks with Unicode characters and emojis.

Here is example code for above menu.

curl -X POST -H "Content-Type: application/json" -d '{
  "setting_type" : "call_to_actions",
  "thread_state" : "existing_thread",
  "call_to_actions":[
    {
      "type":"postback",
      "title":"Help - सहयोग ",
      "payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_HELP"
    },
    {
      "type":"postback",
      "title":"Latest Posts",
      "payload":"DEVELOPER_DEFINED_PAYLOAD_FOR_LATEST_POSTS"
    },
    {
      "type":"web_url",
      "title":"😁 Contact Us",
      "url":"http://thedebuggers.com/contact-us"
    }
  ]
}' "https://graph.facebook.com/v2.6/me/thread_settings?access_token=PAGE_ACCESS_TOKEN"

Note: For multi level (nested) persistent menu, follow this article Nested Persistent Menu using Messenger Profile API.

Handling POSTBACK requests

When we click a Button having POSTBACK payload, Facebook sends request to our webhook endpoint. This request contains Postback with Payload. You can add the following PHP snippets to detect the Postback event:

// Read raw data from the request body and 
$input = json_decode(file_get_contents('php://input'), true);

$page_id = $input['entry'][0]['id'];
$sender = $input['entry'][0]['messaging'][0]['sender']['id'];
$message = isset($input['entry'][0]['messaging'][0]['message']['text']) ? $input['entry'][0]['messaging'][0]['message']['text']: '' ;
$postback = isset($input['entry'][0]['messaging'][0]['postback']['payload']) ? $input['entry'][0]['messaging'][0]['postback']['payload']: '' ;

if($message || $postback) { 
  
  
  if($message) {
  		 // If Page receives Message, process the Message and prepare content to reply
       $reply = 'Message received: ' . $message;
  }
  else {
    
    // If Page receives Postback, process the Postback and prepare content to reply
      
    switch($postback) {
    
      case 'DEVELOPER_DEFINED_PAYLOAD_FOR_HELP':
        $reply = 'You clicked Help button';
        break;
        
      case 'DEVELOPER_DEFINED_PAYLOAD_FOR_LATEST_POSTS':
        $reply = 'You clicked Latest Post button';
        break;
    
    
    }
  
  }
  
  
   $responseJSON = '{
    "recipient":{
      "id":"'.$sender.'"
    },
    "message": {
            "text":"'. $reply .'"
        }
  }';
  $access_token = 'your_page_access_token';
  
  //Graph API URL
  $url = 'https://graph.facebook.com/v2.7/me/messages?access_token='.$access_token;
  // Using cURL to send a JSON POST data
  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $responseJSON);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
  $result = curl_exec($ch);
  curl_close($ch);
  
}

Get Started Button

Get Started button can be displayed in the Welcome Screen as a entry point to the conversation. When this button is tapped, facebook will trigger the postback received callback and deliver the person’s page-scoped ID (PSID). You can then present a personalized message to greet the user or present buttons to prompt him or her to take an action.

This button is only rendered the first time the user interacts with a the Page on Messenger.

In order to add Get Started button, you need to make a POST request to Facebook Graph API as:

curl -X POST -H "Content-Type: application/json" -d '{
  "setting_type":"call_to_actions",
  "thread_state":"new_thread",
  "call_to_actions":[
    {
      "payload":"USER_DEFINED_PAYLOAD"
    }
  ]
}' "https://graph.facebook.com/v2.6/me/thread_settings?access_token=PAGE_ACCESS_TOKEN"

When above request is made, you will see the Get Started button similar as follows:

Like Persistent Menu, we can also remove Get Started Button. In order to delete, send a DELETE request:

curl -X DELETE -H "Content-Type: application/json" -d '{
  "setting_type":"call_to_actions",
  "thread_state":"new_thread"
}' "https://graph.facebook.com/v2.6/me/thread_settings?access_token=PAGE_ACCESS_TOKEN"

Greeting Text

You can set a greeting text for new conversations. Typical greeting might be your bot’s functionality or description of your page. You can even personalize the text with the person’s name by adding template string {{user_first_name}}, {{user_last_name}}
{{user_full_name}} to the Greeting Text.

Here’s how to add a Greeting Text:

curl -X POST -H "Content-Type: application/json" -d '{
  "setting_type":"greeting",
  "greeting":{
    "text":"Hi {{user_first_name}}, welcome to The Debuggers"
  }
}' "https://graph.facebook.com/v2.6/me/thread_settings?access_token=PAGE_ACCESS_TOKEN"

In order to delete, send a DELETE request as follows:

curl -X DELETE -H "Content-Type: application/json" -d '{
  "setting_type":"greeting"
}' "https://graph.facebook.com/v2.6/me/thread_settings?access_token=PAGE_ACCESS_TOKEN"

Conclusion

Today I discussed on Configuring the Thread Settings on Messenger to improve the user-experience of your integration. Get Started Button and Greeting Text act as entry point to the conversation whereas Persistent Menu help user to quickly use general feature of your bot. Setting up these features is quite easy and straightforward. Isn’t it?

You may also like: Messenger Bot Subscription System Using Broadcast API in PHP