# 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](/docs/conversation/channel-support/facebook-messenger/properties).

If you want to use Marketing Messages to send messages outside the standard messaging window, see [Marketing Messages](#marketing-messages).

| Message Type | Natively Supported? |
|  --- | --- |
| Text Message | Yes, this type of message is natively supported. For example: ![Text Message](/assets/messenger_text_message_isolated.a5560d047680f10107a4fc41b807b0a846e111a42b1ef5b26289f7bf8fbfc1ea.46a24e6c.png) |
| Media Message | Yes, this type of message is natively supported for the following media types:ImageVideoAudioDocumentFor example: ![Media Message](/assets/messenger_media_message_isolated.ed3563ede0deee63a269ba8df9e51d45a98ea6fce519da76d1137b8fc7d05a29.46a24e6c.png) |
| Choice Message | Yes, this type of message is natively supported for the following choice types:Text ChoiceURL ChoiceLocation ChoiceCall ChoiceFor example: ![Choice Message](/assets/messenger_choice_message_isolated.f4b8e69d3012c9614b580a0bae2bca46a7447b4d1b0488e8b2f5bf8fa51ea2e8.46a24e6c.png) |
| Card Message | Yes, this type of message is natively supported. Note that the `media_message` property only supports images. For example: ![Card Message](/assets/messenger_card_message_isolated.5d6a5d6330a8b465c6c31dd5ae9617694462f4feaa16d398af97614dc60e3d02.46a24e6c.png) |
| Carousel Message | Yes, this type of message is natively supported. Note that the `media_message` property only supports images. For example: ![Carousel Message](/assets/messenger_carousel_message_isolated.1a7f14faa3be0a398b98f5bddbe69099b0958aec5b768fa444b70810fb73204b.46a24e6c.png) |
| Location Message | Yes, this type of message is natively supported. For example: ![Location Message](/assets/messenger_location_message_isolated.adc032d5a3096ad7a16055b91e6acdebcbba803a58bf9410c380c9d8cd5517ea.46a24e6c.png) |


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


```json
{
  "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": ""
  }
}
```

### Marketing Messages

Marketing Messages is a messaging functionality supported by Meta on their Messenger platform. These messages allow the businesses to send proactive, automated messages to users (their customers) who have opted-in to receiving them, thus driving the engagement, efficiently increasing customer retention rate, and boosting sales. Businesses will be able to send sales notifications, updates, newsletters – whatever they like, with frequency options ranging from daily to monthly. This allows businesses to reach their customers at any moment in their journey. Meta provides this functionality without any messaging fee.

#### Requesting user opt-in

Marketing Messages can be sent only to a user who opted in. For more information about ways to get opt-ins, visit: [https://developers.facebook.com/docs/messenger-platform/send-messages/recurring-notifications/ways-to-get-opt-ins](https://developers.facebook.com/docs/messenger-platform/send-messages/recurring-notifications/ways-to-get-opt-ins)

An opt-in can be requested using a template message. For complex template parameters, use the following format: `elements[0].title`. For more information about template parameters, see [https://developers.facebook.com/docs/messenger-platform/marketing-messages#sample-opt-in-request](https://developers.facebook.com/docs/messenger-platform/marketing-messages#sample-opt-in-request)

Example opt-in request:


```json
{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "recipient": {
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW"
  },
  "message": {
    "template_message": {
      "channel_template": {
        "MESSENGER": {
          "template_id": "notification_messages",
          "parameters": {
            "title": "Receive our marketing messages",
            "image_url": "https://scontent.xx.fbcdn.net/v/t1.15752-9/174244980_1170704636714502_2133968827805507208_n.jpg",
            "payload": "PAYLOAD"
          }
        }
      }
    }
  }
}
```

Note:
At this time, users are not able to create channel-specific templates for the Facebook Messenger channel. If you do not have access to a Facebook Messenger channel-specific template, you may use the [explicit channel message feature](/docs/conversation/api-reference/conversation/messages/messages_sendmessage#messages/messages_sendmessage/t=request&path=message&oneof=0/explicit_channel_message) of the Conversation API to send an opt-in request.

#### Sending Marketing Messages

A Marketing Message can be any type of message. It just needs to include the `notification_messages_token` received during opt-in. For more information, see [Receiving user Opt-in/out](#receiving-user-opt-inout) and [Facebook Messenger channel properties](/docs/conversation/channel-support/facebook-messenger/properties)

## Receiving Messages

Facebook Messenger channel supports various kinds of contact messages - text, media, media card, location, and quick replies.

Note:
Please note that the media URLs included in the contact messages are valid for 7 days.
After that the media is deleted from Conversation API storage.

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:


```json
{
  "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:


```json
{
  "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:


```json
{
  "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:


```json
{
  "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:


```json
{
  "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"
  }
}
```

## Receiving user opt-in/out

Messenger users can, at any time, opt-in or opt-out of receiving marketing messages.

Note:
Opt-in/out for Marketing Messages does not affect sending standard messages using the standard messaging window.

### Opt-in

Below is an example of a Conversation API `POST` to the `OPT_IN` webhook:


```json
{
  "app_id": "01EGQYR8N9S5VF096DQKYF08JD",
  "accepted_time": "2023-09-18T09:50:55.941943739Z",
  "event_time": "2023-09-18T09:50:54.229Z",
  "project_id": "ab5536b1-31b0-45e8-aec6-b35f13c41d0b",
  "opt_in_notification": {
    "contact_id": "01EHY7KA2BYT8A11E6Y2271NHA",
    "channel": "MESSENGER",
    "identity": "534183549153491",
    "status": "OPT_IN_SUCCEEDED",
    "request_id": "01HAKV6EY5NBKXS130EKKV4C0A",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": "{\"payload\":\"PAYLOAD\",\"notification_messages_token\":\"812753123357423491\",\"token_expiry_timestamp\":2145916800000,\"notification_messages_timezone\":\"UTC\"}",
  "correlation_id": ""
}
```

### Opt-out

Below is an example of a Conversation API `POST` to the `OPT_OUT` webhook:


```json
{
  "app_id": "01EGQYR8N9S5VF096DQKYF08JD",
  "accepted_time": "2023-09-18T11:04:14.947458371Z",
  "event_time": "2023-09-18T11:04:14.812Z",
  "project_id": "ab5536b1-31b0-45e8-aec6-b35f13c41d0b",
  "opt_out_notification": {
    "contact_id": "01EHY7KA2BYT8A11E6Y2271NHA",
    "channel": "MESSENGER",
    "identity": "534183549153491",
    "status": "OPT_OUT_SUCCEEDED",
    "request_id": "01HAKZCPV3CDMRTA53F5QNNT8E",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": "{\"payload\":\"PAYLOAD\",\"notification_messages_token\":\"812753123357423491\",\"token_expiry_timestamp\":2145916800000}",
  "correlation_id": ""
}
```