Quick Replies

Quick replies provide a way to present a set of up to 11 buttons in-conversation that contain a title and optional image, and appear prominently above the composer. You can also use quick replies to request a person's location.


When a quick reply is tapped, the buttons are dismissed, and the title of the tapped button is posted to the conversation as a message. A messages event will be sent to your webhook that contains the button title and an optional payload.

For a complete list of API calls and request properties, see the Quick Replies Reference.

Contents

Sending Quick Replies

To send a quick reply, add the quick_replies array to a text message, and include objects that define up to 11 quick reply buttons.

Text Quick Replies

Text quick replies may also be sent with an optional image that appears as an icon beside the title.

    ...
      
    "quick_replies":[
      {
        "content_type":"text",
        "title":"<BUTTON_TEXT>",
        "image_url":"http://example.com/img/red.png",
        "payload":"<STRING_SENT_TO_WEBHOOK>"
      }
    ]

    ...

For a complete list of API calls and request properties, see the Quick Replies Reference.

Location Quick Reply

The Messenger Platform supports a special 'location' quick reply that is used to request a person's location. When the location quick reply is tapped, a searchable map will be displayed that the person may use to set their location.

The latitude and longitude of the location will be sent to you in the payload.coordinates property of the webhook event.

    ...
  
    "quick_replies":[
      {
        "content_type":"location"
      }
    ]
  
    ...
    

For a complete list of API calls and request properties, see the Quick Replies Reference.

Example Request

For a complete list of API calls and request properties, see the Quick Replies Reference.

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"<PSID>"
  },
  "message":{
    "text": "Here's a quick reply!",
    "quick_replies":[
      {
        "content_type":"text",
        "title":"Search",
        "payload":"<POSTBACK_PAYLOAD>",
        "image_url":"http://example.com/img/red.png"
      },
      {
        "content_type":"location"
      },
      {
        "content_type":"text",
        "title":"Something Else",
        "payload":"<POSTBACK_PAYLOAD>"
      }
    ]
  }
}' "https://graph.facebook.com/v2.6/me/messages?access_token=<PAGE_ACCESS_TOKEN>"

Example Response

{
  "recipient_id": "1254477777772919",
  "message_id": "mid.$cAAJsujCd2ORj_1qmrFdzhVa-4cvO"
}  

Webhook Event

When a Quick Reply is tapped, a text message will be sent to your webhook Message Received Callback.

The text of the message will correspond to the title of the Quick Reply. The message object will also contain a field named quick_reply containing the payload data on the Quick Reply.

Text Quick Reply Webhook Event

{
  "object": "page",
  "entry": [
    {
      "id": "682498171943165",
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "1254459154682919"
          },
          "recipient": {
            "id": "682498171943165"
          },
          "timestamp": 1502905976377,
          "message": {
            "quick_reply": {
              "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_GREEN"
            },
            "mid": "mid.$cAAJsujCd2ORkHXKOOVd7C1F97Zto",
            "seq": 9767,
            "text": "Green"
          }
        }
      ]
    }
  ]
}

Location Quick Reply Webhook Event

{
  "object": "page",
  "entry": [
    {
      "id": "<PAGE_ID>",
      "time": 1472672934319,
      "messaging": [
        {
          "sender": {
            "id": "<PSID>"
          },
          "recipient": {
            "id": "<PAGE_ID>"
          },
          "timestamp": 1472672934259,
          "message": {
            "mid": "mid.1472672934017:db566db5104b5b5c08",
            "seq": 297,
            "attachments": [
              {
                "title": "Facebook HQ",
                "url": "https://www.facebook.com/l.php?u=https%....5-7Ocxrmg",
                "type": "location",
                "payload": {
                  "coordinates": {
                    "lat": 37.483872693672,
                    "long": -122.14900441942
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Best Practices

Use quick replies to prompt for specific next steps.

Be brief — long quick replies will be truncated.

Don't use for actions you'd like to be permanent: quick replies disappear after the next message.