Most message templates, as well as the persistent menu, support buttons that invoke different types of actions. These buttons allow you to easily offer the message recipient actions they can take in response to the template, such as opening the Messenger webview, starting a payment flow, sending a postback message to your webhook, and more.
For message templates, buttons are defined by objects in the buttons
array. For the persistent menu, buttons are defined by objects in the call_to_actions
array.
The URL Button opens a web page in the Messenger webview. This allows you to enrich the conversation with a web-based experience, where you have the full development flexibility of the web. For example, you might display a product summary in-conversation, then use the URL button to open the full product page on your website.
If the site contains App Links, the button will launch the specified native app.
The Facebook Crawler needs to read the app link metatags for the redirect to work. Note that if you just implemented the tags in your website, you can request a new scrape with the Sharing Debugger Tool. After the crawler has scraped the site, new URL buttons sent should follow the redirect behavior.
The URL button is supported for use with the following:
To display a webpage with the Messenger Extensions SDK enabled in the Messenger webview you must whitelist the domain, including sub-domain, in the whitelisted_domains
property of your bot's Messenger Profile. This ensures that only trusted domains have access to user information available via SDK functions.
For more information on whitelisting domains, see the whitelisted_domains
reference.
For a complete list of button properties, see the URL button reference.
{
"type": "web_url",
"url": "<URL_TO_OPEN_IN_WEBVIEW>",
"title": "<BUTTON_TEXT>",
}
The postback button sends a messaging_postbacks
event to your webhook with the string set in the payload
property. This allows you to take an arbitrary actions when the button is tapped. For example, you might display a list of products, then send the product ID in the postback to your webhook, where it can be used to query your database and return the product details as a structured message.
The postback button is supported for use with the following:
For a complete list of button properties, see the postback button reference.
{
"type": "postback",
"title": "<BUTTON_TEXT>",
"payload": "<STRING_SENT_TO_WEBHOOK>"
}
The call button dials a phone number when tapped. Phone number should be in the format +<COUNTRY_CODE><PHONE_NUMBER>
, e.g. +15105559999
.
The call button is supported for use with the following:
For a complete list of button properties, see the call button reference.
{
"type":"phone_number",
"title":"<BUTTON_TEXT>",
"payload":"<PHONE_NUMBER>"
}
The log in button is used in the account linking flow, which lets you link the message recipient's identity on Messenger with their account on your site by directing them to your web-based login flow for authentication.
For more on using the log in button for account linking, see Account Linking.
The log in button is supported for use with the following:
For a complete list of button properties, see the log in button reference.
{
"type": "account_link",
"url": "<YOUR_LOGIN_URL>"
}
The log out button is used in the account linking flow to unlink the message recipient's identity on Messenger with their account on your site.
For more on using the log out button for account unlinking, see Account Linking.
The log out button is supported for use with the following:
For a complete list of button properties, see the log out button reference.
{
"type": "account_unlink"
}
The game play button launches an Instant Game that is associated with your Facebook Page. To customize how your game is opened, you can set a payload
property in the request that will be sent to the game on launch, as well as an optional game_metadata.player_id
or game_metadata.context_id
property, which allows your bot to start the game in a specific context against a single player or an existing group.
The payload
property should be serialized JSON. It is deserialized by the Instant Games SDK.
For a complete list of button properties, see the Game Play Button Reference.
{
"type":"game_play",
"title":"Play",
"payload":"{<SERIALIZED_JSON_PAYLOAD>}",
"game_metadata": { // Only one of the below
"player_id": "<PLAYER_ID>",
"context_id": "<CONTEXT_ID>"
}
}
Refer to Game Play webhook event for the event that will be sent to the bot when a user finishes a game round.
Use buttons to prompt for follow-up or further interaction with a particular message.
Start with a verb to help people understand the action they're taking.
Use URL buttons for tasks that you want completed on your website (ex: purchases, account linking, etc.). Make it clear you’re sending people outside of Messenger.
Send a response after someone taps a callback button. This confirms that you've processed or completed their action (ex: canceling a reservation, answering a question).
Don't use buttons when their action depends on the current state of the bot, since they'll be permanently available in the thread.
Don't use more than 1-3 words or add punctuation. Try to keep your text under 20 characters, including spaces.
Don't rely on URLs for every button. The more interactions you can build within Messenger, the more seamless your experience will be.
Don't use a single callback button. Where's only one button to choose from, people often think it's a continuation of your message text and don't understand it's an action you want them to take.