Facebook Messenger channel message support

The Facebook Messenger channel of the Conversation API supports a wide variety of message types.

Sending Messages

The following table details the mapping between the Conversation API generic message format and the way Messenger renders the messages on mobile devices.

Note

If you want to send messages outside the standard 24h response window, you can do so by adding Messenger channel specific properties in your message request. For more information, see Facebook Messenger channel properties.

Message Type Natively Supported? Special Instructions
Text Message Yes, this type of message is natively supported. For example:
Text Message

The code to send a text message for this channel doesn't differ from the generic message and can be viewed here.

Media Message Yes, this type of message is natively supported for the following media types:
  • Image
  • Video
  • Audio
  • Document
For example:
Media Message

The code to send a media message for this channel doesn't differ from the generic message and can be viewed here.

Choice Message Yes, this type of message is natively supported for the following choice types:
  • Text Choice
  • URL Choice
  • Location Choice
For example:
Choice Message

The code to send a choice message for this channel doesn't differ from the generic message and can be viewed here.

Card Message Yes, this type of message is natively supported. Note that the media_message property only supports images. For example:
Card Message

The code to send a card message for this channel doesn't differ from the generic message and can be viewed here.

Carousel Message Yes, this type of message is natively supported. Note that the media_message property only supports images. For example:
Carousel Message

The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed here.

Location Message Yes, this type of message is natively supported. For example:
Location Message

The code to send a location message for this channel doesn't differ from the generic message and can be viewed here.

Receiving Delivery Receipts

Messages sent on the Facebook Messenger channel can have one of three statuses: DELIVERED, READ, or FAILED. If the status is FAILED, a reason will be included that provides more information about the failure. Below is an example of a Conversation API POST to the MESSAGE_DELIVERY webhook with a READ receipt; a FAILED receipt would have a different status and reason.

Copy
Copied
{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "accepted_time": "2020-10-01T12:10:00.530Z",
  "event_time": "2020-10-01T12:10:03.624Z",
  "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
  "message_delivery_report": {
    "message_id": "01EKJ13DYJX54C0N062N0Q1J9F",
    "conversation_id": "01EKJ0KSWXMVDF05MG9TQ20S06",
    "status": "READ",
    "channel_identity": {
      "channel": "MESSENGER",
      "identity": "534183549153491",
      "app_id": "01EB37HMH1M6SV18ASNS3G135H"
    },
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW",
    "metadata": ""
  }
}

Receiving Messages

Facebook Messenger channel supports various kinds of contact messages - text, media, media card, location, and quick replies. All of these are delivered by Conversation API with a POST request to the MESSAGE_INBOUND webhook:

Text message response webhook example

Below is an example of a Conversation API POST to the MESSAGE_INBOUD webhook for a text message response:

Copy
Copied
{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "accepted_time": "2020-10-01T12:06:13.806686Z",
  "event_time": "2020-10-01T12:06:13.254Z",
  "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
  "message": {
    "id": "01EKJ0WGFM7TR314K4D9Y31J5S",
    "direction": "TO_APP",
    "contact_message": {
      "text_message": {
        "text": "This is text message from a Messenger user."
      }
    },
    "channel_identity": {
      "channel": "MESSENGER",
      "identity": "534183549153491",
      "app_id": "01EB37HMH1M6SV18ASNS3G135H"
    },
    "conversation_id": "01EKJ0KSWXMVDF05MG9TQ20S06",
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW",
    "metadata": "",
    "accept_time": "2020-10-01T12:06:13.794339Z"
  }
}

Location message response webhook

Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a location message:

Copy
Copied
{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "accepted_time": "2020-10-01T12:07:35.513615Z",
  "event_time": "2020-10-01T12:07:34.935Z",
  "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
  "message": {
    "id": "01EKJ0Z07XKM6H04VB5Q941QBP",
    "direction": "TO_APP",
    "contact_message": {
      "location_message": {
        "title": "",
        "coordinates": {
          "latitude": 55.73064,
          "longitude": 13.160131
        },
        "label": ""
      }
    },
    "channel_identity": {
      "channel": "MESSENGER",
      "identity": "534183549153491",
      "app_id": "01EB37HMH1M6SV18ASNS3G135H"
    },
    "conversation_id": "01EKJ0KSWXMVDF05MG9TQ20S06",
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW",
    "metadata": "",
    "accept_time": "2020-10-01T12:07:35.496355Z"
  }
}

Media message response webhook

Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a media message:

Copy
Copied
{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "accepted_time": "2020-10-01T12:10:55.073703Z",
  "event_time": "2020-10-01T12:10:53.991Z",
  "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
  "message": {
    "id": "01EKJ1534NWK5R02TGWEJN13HA",
    "direction": "TO_APP",
    "contact_message": {
      "media_message": {
        "url": "https://scontent.xx.fbcdn.net/v/t1.15752-9/174244980_1170704636714502_2133968827805507208_n.jpg"
      }
    },
    "channel_identity": {
      "channel": "MESSENGER",
      "identity": "534183549153491",
      "app_id": "01EB37HMH1M6SV18ASNS3G135H"
    },
    "conversation_id": "01EKJ0KSWXMVDF05MG9TQ20S06",
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW",
    "metadata": "",
    "accept_time": "2020-10-01T12:10:55.060170Z"
  }
}

Card message repsonse webhook

Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a media card message:

Copy
Copied
{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "accepted_time": "2020-10-01T12:10:55.073703Z",
  "event_time": "2020-10-01T12:10:53.991Z",
  "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
  "message": {
    "id": "01EKJ1534NWK5R02TGWEJN13HA",
    "direction": "TO_APP",
    "contact_message": {
      "media_card_message": {
        "url": "https://scontent.xx.fbcdn.net/v/t1.15752-9/174244980_1170704636714502_2133968827805507208_n.jpg",
        "caption": "caption text"
      }
    },
    "channel_identity": {
      "channel": "MESSENGER",
      "identity": "534183549153491",
      "app_id": "01EB37HMH1M6SV18ASNS3G135H"
    },
    "conversation_id": "01EKJ0KSWXMVDF05MG9TQ20S06",
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW",
    "metadata": "",
    "accept_time": "2020-10-01T12:10:55.060170Z"
  }
}

Quick Reply message response webhook

Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a quick reply message:

Copy
Copied
{
  "app_id": "01EGQYR8N9S5VF096DQKYF08JD",
  "accepted_time": "2020-10-01T12:39:48.469849Z",
  "event_time": "2020-10-01T12:39:48.296Z",
  "project_id": "ab5536b1-31b0-45e8-aec6-b35f13c41d0b",
  "message": {
    "id": "01EKJ2SZX9N6F11SJ11G511H6J",
    "direction": "TO_APP",
    "contact_message": {
      "choice_response_message": {
        "message_id": "01EKJ2SWHGDMYA0F0F1PQJ09WQ",
        "postback_data": "suggested reply postback"
      }
    },
    "channel_identity": {
      "channel": "MESSENGER",
      "identity": "534183549153491",
      "app_id": "01EGQYR8N9S5VF096DQKYF08JD"
    },
    "conversation_id": "01EHY7KA6ZC03C1Q5QTRZ60GDA",
    "contact_id": "01EHY7KA2BYT8A11E6Y2271NHA",
    "metadata": "",
    "accept_time": "2020-10-01T12:39:48.457764Z"
  }
}
Was this page helpful?