Quick Replies

Quick replies provide a way to present a set of up to 13 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.

Sending Quick Replies

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

The following quick reply types are supported:

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient":{
    "id":"<PSID>"
  },
  "messaging_type": "RESPONSE",
  "message":{
    "text": "Pick a color:",
    "quick_replies":[
      {
        "content_type":"text",
        "title":"Red",
        "payload":"<POSTBACK_PAYLOAD>",
        "image_url":"http://example.com/img/red.png"
      },{
        "content_type":"text",
        "title":"Green",
        "payload":"<POSTBACK_PAYLOAD>",
        "image_url":"http://example.com/img/green.png"
      }
    ]
  }
}' "https://graph.facebook.com/v19.0/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. If the content_type for a quick reply is specified as text, it is required to specify a non-empty title.

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": "m_AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P",
            "text": "Green"
          }
        }
      ]
    }
  ]
}

User Phone Number Quick Reply

The user phone number quick reply allows you to ask a user for their 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": "m_AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P",
            "text": "<PHONE_NUMBER>"
          }
        }
      ]
    }
  ]
}

User Email Quick Reply

The user email quick reply allows you to ask a user for their email. 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": "m_AG5Hz2Uq7tuwNEhXfYYKj8mJEM_QPpz5jdCK48PnKAjSdjfipqxqMvK8ma6AC8fplwlqLP_5cgXIbu7I3rBN0P",
            "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.

Developer Support