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 included defined by objects in the buttons array. For the persistent menu, buttons are defined by objects in the call_to_actions array. For more information on the specific purpose and format of each button type, see below.

Contents

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.

Supported Usage

The URL button is supported for use with the following:

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

Required Domain Whitelisting

To display a webpage 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 are opened by your Messenger bot.

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>"
}

Share Button

The share button allows the message recipient to share the content of a message you sent with others on Messenger. The name and icon of your Page appear as an attribution at the top of the shared content. The attribution opens a conversation with your bot when tapped.

With the share button, you can share the exact message or specify a new generic template message in the share_contents property. If you specify a new generic template, the message recipient will be able to add a message to the share. This is useful if you want change the look or add content to the original message.

Supported Usage

The share button is supported for use with the following:

  • Generic template
  • List template
  • Media template

Button Format

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

{
  "type":"element_share"
}

For share buttons using the element_share feature, only the generic template with one URL button is supported.

{
  "type": "element_share",
  "share_contents": { 
    "attachment": {
      "type": "template",
      "payload": {
        <GENERIC_TEMPLATE_OBJECT>
      }
    }
  }
}

Buy Button

The buy button begins the in-conversation payments flow. When tapped, the button opens a checkout dialog, where the message recipient may choose their payment method, shipping address, and other details. This makes it possible for you to offer products in-conversation that a message recipient can purchase from start to finish with their Facebook account.

For more information on implementing payments in Messenger, see Payments.

Supported Usage

The buy button is supported for use with the following:

  • Generic template
  • List template
  • Media template

Availability

The Buy Button is only available for US users. You will get the following error if you try to send to a user that is not in US.

{
  "error":{"message":"(#200) The user is not eligible to receive payment messages.",
  "type":"OAuthException",
  "code":200,
  "error_subcode":2018112,
  "fbtrace_id":"DdAqW91SO+K"
}

You can also use the User Profile API and check the is_payment_enabled field to see if a user is eligible for payment before hand.

Button Format

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

{
  "type":"payment",
  "title":"<BUTTON_TEXT>",
  "payload":"<STRING_SENT_TO_WEBHOOK>",
  "payment_summary":{
    "currency":"<CURRENCY_ABBREVIATION>",
    "payment_type":"<FIXED_AMOUNT | FLEXIBLE_AMOUNT>",
    "is_test_payment" : <TRUE | FALSE >, 
    "merchant_name":"<YOUR_BUSINESS_NAME>",
    "requested_user_info":[
      "shipping_address",
      "contact_name",
      "contact_phone",
      "contact_email"
    ],
    "price_list":[
      {
        "label":"<ITEM_NAME>",
        "amount":"<ITEM_PRICE"
      },
      ...
    ]
  }
}

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 (BETA)

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.