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.

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

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.

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

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.