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, email address, and phone number.


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

The following quick reply types are supported:

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

Text Quick Reply

Text quick replies may also be sent with an optional image that appears as an icon beside the title. You may also send a quick reply with an image and an empty title string to create an icon-only quick reply.

Syntax

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

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

Webhook Event

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

The text property of the event 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.

{
  "object": "page",
  "entry": [
    {
      "id": "<PAGE_ID>",
      "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

The location quick reply allows your bot 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.

Syntax

{
  "content_type":"location"
}

Webhook Event

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

The latitude and longitude of the location will be sent to you in the payload.coordinates property of the 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
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

User Phone Number Quick Reply

This feature requires Messenger v144 on iOS and v142 on Android.

The user phone number quick reply allows you to ask a user for the phone number. When the phone number quick reply is sent, the Messenger Platform will automatically pre-fill the displayed quick reply with the phone number from the user's profile information.

If the user's profile does not have a phone number, the quick reply will not be shown.

The bot will not receive the phone number until the user clicks the quick reply.

Choosing the quick reply transmits the information once and does not constitute permission to access the information in the future.

Syntax

{
  "content_type":"user_phone_number"
}

Webhook Event

When the user taps the quick reply, the phone number will be passed in the payload attribute of the messages webhook event.

{
  "object": "page",
  "entry": [
    {
      "id": "<PAGE_ID>",
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "1254459154682919"
          },
          "recipient": {
            "id": "682498171943165"
          },
          "timestamp": 1502905976377,
          "message": {
            "quick_reply": {
              "payload": "<PHONE_NUMBER>"
            },
            "mid": "mid.$cAAJsujCd29DfHXKOOVd7C1F97Zto",
            "seq": 9767,
            "text": "<PHONE_NUMBER>"
          }
        }
      ]
    }
  ]
}

User Email Quick Reply

This feature requires Messenger v144 on iOS and v142 on Android.

The user email quick reply allows you to ask a user for the phone number. When the email quick reply is sent, the Messenger Platform will automatically pre-fill the displayed quick reply with the email from the user's profile information.

If the user's profile does not have an email address, the quick reply will not be shown.

The bot will not receive the email until the user clicks the quick reply.

Choosing the quick reply transmits the information once and does not constitute permission to access the information in the future.

Syntax

{
  "content_type":"user_email"
}

Webhook Event

When the user taps the quick reply, the email address will be passed in the payload attribute of the messages webhook event.

{
  "object": "page",
  "entry": [
    {
      "id": "<PAGE_ID>",
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "1254459154682919"
          },
          "recipient": {
            "id": "682498171943165"
          },
          "timestamp": 1502905976377,
          "message": {
            "quick_reply": {
              "payload": "<EMAIL_ADDRESS>"
            },
            "mid": "mid.$cAAJsujCd29DfHXKOOVd7C1F97Zto",
            "seq": 9767,
            "text": "<EMAIL_ADDRESS>"
          }
        }
      ]
    }
  ]
}

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.