Buttons

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.

URL Button

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.

App Links

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.

Supported Usage

The URL button is supported for use with the following:

• Persistent menu
• Generic template
• List template
• Button template
• Media template

Messenger Extensions SDK - Required Domain Whitelisting

Button Format

For a complete list of button properties, see the URL button reference.

{
  "type": "web_url",
  "url": "<URL_TO_OPEN_IN_WEBVIEW>",
  "title": "<BUTTON_TEXT>",
}

Postback Button

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.

Supported Usage

The postback button is supported for use with the following:

• Persistent menu
• Generic template
• List template
• Button template
• Media template

Button Format

For a complete list of button properties, see the postback button reference.

{
  "type": "postback",
  "title": "<BUTTON_TEXT>",
  "payload": "<STRING_SENT_TO_WEBHOOK>"
}

Call Button

The call button dials a phone number when tapped. Phone number should be in the format +<COUNTRY_CODE><PHONE_NUMBER>, e.g. +15105559999.

Supported Usage

The call button is supported for use with the following:

• Generic template
• List template
• Button template
• Media template

Button Format

For a complete list of button properties, see the call button reference.

{
  "type":"phone_number",
  "title":"<BUTTON_TEXT>",
  "payload":"<PHONE_NUMBER>"
}

Log In Button

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.

Supported Usage

The log in button is supported for use with the following:

• Generic template
• List template
• Button template
• Media template

Button Format

For a complete list of button properties, see the log in button reference.

{
  "type": "account_link",
  "url": "<YOUR_LOGIN_URL>"
}

Log Out Button

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.

Supported Usage

The log out button is supported for use with the following:

• Generic template
• List template
• Button template
• Media template

Button Format

For a complete list of button properties, see the log out button reference.

{
  "type": "account_unlink"
}

Game Play Button

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.

Button Format

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.

Best Practices