Instagram Messaging

Button Template

Updated: Apr 1, 2026

The button template sends a text message with up to three attached buttons. This template is useful for offering the message recipient options to choose from, such as predetermined responses to a question, or actions to take.

Limitations

This feature is currently not available in the web version.

Template Payload

For a complete list of template properties, refer to the Properties section below.

"payload": {
  "template_type":"button",
  "text":"<MESSAGE_TEXT>",
  "buttons":[
    <BUTTON_OBJECT>,
    <BUTTON_OBJECT>,
    ...
  ]
}

Available Buttons

URL Button

The URL Button opens a web page in the in-app browser. 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.

Button Format

{
  "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 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.

Button Format

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

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

Example Request

For complete request details and properties, refer to the Properties section below.

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"<IGID>"
  },
  "message":{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"button",
        "text":"What do you want to do next?",
        "buttons":[
          {
            "type":"web_url",
            "url":"https://www.messenger.com",
            "title":"Visit Messenger"
          },
          {
            ...
          },
          {...}
        ]
      }
    }
  }
}' "https://graph.facebook.com/v13.0/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Example Response

{
  "recipient_id": "1254477777772919",
  "message_id": "AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P"
}

Properties

`recipient`

Description of the message recipient. All requests must include one of the following properties to identify the recipient.

Property	Type	Description
`recipient.id`	String	IG Scoped User ID (IGSID) of the message recipient.

`message`

Description of the message to be sent.

Property	Type	Description
`message.attachment`	Object	An object describing attachments to the message.

`message.attachment`

Property	Type	Description
`type`	String	Value must be `template`.
`payload`	Object	`payload` of the template.

`message.attachment.payload`

Property	Type	Description
`template_type`	String	Value must be `button`.
`text`	String	UTF-8-encoded text of up to 640 characters. Text will appear above the buttons.
`buttons`	Array<button>	Set of 1-3 buttons that appear as call-to-actions.

Did you find this page helpful?