Button Template

A button template message allows you to send a message that contains text and up to three attached buttons that allow the message recipient to choose from different options. The buttons can open web pages in the in-app browser or send the recipient's selection to you via the messaging_postback webhook notification. You can then send information about the selection back to the recipient.

Before you start

This guide assumes you have set up your webhooks server to receive notifications and subscribed your app to Instagram messages and messaging_postbacks events.

You will need:

• The ID for the Instagram professional account (IG_ID)
• The Instagram-scoped ID (IGSID) for the person to whom you are sending the message

Host URL

https://graph.instagram.com

Button types

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.

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.

Send a button template message

To send a message using the button template, send a POST request to the /<IG_ID>/messages endpoint with the following parameters:

• recipient.id set to the Instagram-scoped ID of the person you are sending the message
• message.attachment object with:
  • type set to template
  • payload object with:
    • template_type set to button
    • text set to the text that prompts the recipient to click a button
    • buttons set to an array of button objects with the button type, URL or payload and title

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":"<IGSID>"
  },
  "message":{
    "attachment":{
      "type":"template",
      "payload":{
        "template_type":"button",
        "text":"What do you want to do next?",
        "buttons":[
          {
            "type":"web_url",
            "url":"https://www.instagram.com",
            "title":"Visit Instagram",
          }, {
            "type":"postback",
            "payload":"postback_payload",
            "title":"postback button",
          }
        ]
      }
    }
  }
}' "https://graph.instagram.com/v20.0/me/messages?access_token=INSTAGRAM_ACCESS_TOKEN"  

On success your app receives a JSON response with the recipient ID and message ID.

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

Properties

message.attachment

message.attachment.payload