The Instagram channel of the Conversation API supports a wide variety of message types.
The following table details the mapping between the Conversation API generic message format and the way Instagram renders the messages on mobile devices.
If you want to send messages outside the standard 24-hour response window, you can do so by adding Instagram channel specific properties in your message request. For more information, see Instagram Messenger channel properties.
| Message Type | Natively Supported? |
|---|---|
| Text Message | Yes, this type of message is natively supported. For example: |
| Media Message | Yes, this type of message is natively supported for the following image-based media formats:
 Note that the image size should be less than 8 MB. |
| Choice Message | Yes, this type of message is natively supported on the Instagram app on Android and iOS for the following choice types:
 Note that choice messages are not supported on the Instagram web client. Instead, the message is transposed as a text message without choice buttons. |
| Card Message | Yes, this type of message is natively supported when sending image media. For example: |
| Carousel Message | Yes, this type of message is natively supported. For example: Note that outer choices are not supported. |
| Location Message | No, this type of message is not natively supported. The message is transposed as a text message that contains a URL that points to the Google Maps app. For example: |
Messages sent on the Instagram channel can have one of three statuses: DELIVERED (Instagram Echo), READ (Instagram Seen), 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 DELIVERED receipt; a READ or FAILED receipt would have a different status and reason.
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"accepted_time": "2021-05-30T22:11:53.319Z",
"event_time": "2021-05-30T22:11:54.260Z",
"project_id": "5b7c830f-4183-4275-a028-13e40c98e29e",
"message_delivery_report": {
"message_id": "01F6ZNAQB7K25X1MHX2P6T1RE7",
"conversation_id": "01F6T8NG7D6M3Y0DT0RMDP1KFE",
"status": "DELIVERED",
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "3964920326927846",
"app_id": "01F6T8M717SPW0186EC5A90Z0E"
},
"contact_id": "01F6T8NG3ZWF460K28RHAM1DHW",
"metadata": ""
}
}Every time a comment is made to a post or live broadcast made from your Instagram business account, you'll receive a callback containing the ID and text of the comment. Instagram allows this comment to be replied to with a single message, called a private reply.
Sending a private reply message won't open a conversation window with the user. An additional MO after the private reply is required to open a conversation window.
Besides that, comments and private replies don't involve Conversation API contacts like usual messages. You'll notice that the contact_id field will be blank and you can use the comment id as the recipient instead.
After a comment is made, you'll receive a comment_event callback, indicating that a user commented on one of your posts or live broadcasts.
Make sure your webhook is subscribed to the EVENT_INBOUND trigger in order to receive these comment callbacks.
Below is an example of a comment_event callback resulting from a comment on a post:
{
"app_id": "01FDYKZMF0TZT91SFFQ0E51Q46",
"event_time": "2021-12-15T12:04:42Z",
"project_id": "37526c91-52b0-4047-9ebf-91a620316cb6",
"event": {
"direction": "TO_APP",
"contact_event": {
"comment_event": {
"id": "18018439735349275",
"text": "Comment's text.",
"comment_type": "FEED",
"commented_on": "https://www.instagram.com/p/TR5H4zzrHnL/",
"user": "user_name"
}
},
"contact_id": "",
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "4428763530500068",
"app_id": "01FDYKZMF0TZT91SFFQ0E51Q46"
},
"accept_time": "2021-12-15T12:04:44.042093Z",
"processing_mode": "CONVERSATION"
},
"message_metadata": ""
}This is an example of a comment_event callback resulting from a comment on a live broadcast:
{
"app_id": "01FDYKZMF0TZT91SFFQ0E51Q46",
"event_time": "2021-12-15T12:05:49Z",
"project_id": "37526c91-52b0-4047-9ebf-91a620316cb6",
"event": {
"direction": "TO_APP",
"contact_event": {
"comment_event": {
"id": "18188618677150629",
"text": "Comment's text.",
"comment_type": "LIVE",
"commented_on": "https://instagram.com/stories/page_name/2742232824292453908",
"user": "user_name"
}
},
"contact_id": "",
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "4428764930500068",
"app_id": "01FDYKZMF0TZT91SFFQ0E51Q46"
},
"accept_time": "2021-12-15T12:05:50.140259Z",
"processing_mode": "CONVERSATION"
},
"message_metadata": ""
}Below are the fields specific to the comment_event callback:
| Field | Type | Description |
|---|---|---|
| comment_type | string | Either LIVE or FEED. Indicates the type of media on which the comment was made. |
| commented_on | string | Instagram's URL of the live broadcast or the post on which the comment was made (permalink). |
| user | string | Username of the account that commented in the live broadcast or post. |
After receiving the comment_event callback, you can send a private reply to the comment by using a comment_reply_event along with the received comment ID as the recipient, using the event endpoint:
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"recipient": {
"identified_by": {
"channel_identities": [
{
"channel": "INSTAGRAM",
"identity": "17399379355201568"
}
]
}
},
"event": {
"comment_reply_event": {
"text": "Private reply from Conv API!"
}
}
}Below is an example of a private reply displayed on the user's device:
After your private reply is sent, you'll also receive delivery receipts callbacks for the different event status. Example of a read status indicating that the private reply message was read by the user:
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"accepted_time": "2021-08-24T20:13:33.630Z",
"event_time": "2021-08-24T20:13:42.516Z",
"project_id": "5b7c830f-4183-4275-a028-13e40c98e29e",
"event_delivery_report": {
"event_id": "01FDYRP5Z1JQ3MEG6H1Q1RH46T",
"status": "READ",
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "17399379355201568",
"app_id": "01F6T8M717SPW0186EC5A90Z0E"
},
"contact_id": "",
"metadata": ""
}
}Make sure your webhook is subscribed to EVENT_DELIVERY trigger to be able to receive status updates for your private reply messages.
The Instagram channel supports various kinds of contact messages - text, media, quick replies, icebreakers, story replies, story mention, and media share.
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.
If you receive an Inbound Message callback for an MO message sent on the Instagram channel, the corresponding payload will not include the Instagram username. You may use the contact_id and channel_identity values included in the callback to retreive the username with the Get Contact Conversation API operation.
Some specific types of media can also be delivered with a POST request to the UNSUPPORTED webhook because of various limitations. These include: Instagram TV/Reels shares, media shares from private accounts, voice messages, and GIPHYs.
Instagram also supports receiving comments via the EVENT_INBOUND webhook. For more information, see Sending Private Replies for Instagram Comments.
Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a text message response:
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"accepted_time": "2021-05-30T21:57:05.043890Z",
"event_time": "2021-05-30T21:57:04.198Z",
"project_id": "5b7c830f-4183-4275-a028-13e40c98e29e",
"message": {
"id": "01F6ZMFKRHKW7E0P58M9VM041G",
"direction": "TO_APP",
"contact_message": {
"text_message": {
"text": "Hello"
}
},
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "3964920326927846",
"app_id": "01F6T8M717SPW0186EC5A90Z0E"
},
"conversation_id": "01F6T8NG7D6M3Y0DT0RMDP1KFE",
"contact_id": "01F6T8NG3ZWF460K28RHAM1DHW",
"metadata": "",
"accept_time": "2021-05-30T21:57:04.981939Z"
}
}Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a media message response. The metadata field contains a serialized JSON with a type indicating the media type, which can be one of: image, video, audio or file:
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"accepted_time": "2021-05-30T22:00:08.160953Z",
"event_time": "2021-05-30T22:00:04.654Z",
"project_id": "5b7c830f-4183-4275-a028-13e40c98e29e",
"message": {
"id": "01F6ZMN6KDYRQJ0YFS14J21ZAM",
"direction": "TO_APP",
"contact_message": {
"media_message": {
"url": "https://lookaside.fbsbx.com/ig_messaging_cdn/?asset_id=17965090030414009&signature=AbwaqAK9-9W3Srei7Xmb7n2cmz_-29VpeaoF2o_0PZKMkjG80p0HjSpmcdgJp11ocVdCCiuT_bhQ7KSUuUPxZmth8ce-N8hR3e4NrShN2ZM2JmrOl5ZEePls66E7QAYKpvnVDTKVsVD4Wb2iFXLEVbTbgF7fmIGLo3jXasLeDDkoMV23JA",
"thumbnail_url": ""
}
},
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "3964920326927846",
"app_id": "01F6T8M717SPW0186EC5A90Z0E"
},
"conversation_id": "01F6T8NG7D6M3Y0DT0RMDP1KFE",
"contact_id": "01F6T8NG3ZWF460K28RHAM1DHW",
"metadata": "{\"type\":\"image\"}",
"accept_time": "2021-05-30T22:00:08.095568Z"
}
}Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a quick reply or card choice message response:
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"accepted_time": "2021-05-30T22:03:09.244231Z",
"event_time": "2021-05-30T22:03:06.344Z",
"project_id": "5b7c830f-4183-4275-a028-13e40c98e29e",
"message": {
"id": "01F6ZMTQDHY3MK0S48QBH102HV",
"direction": "TO_APP",
"contact_message": {
"choice_response_message": {
"message_id": "01F6ZMTJNTSRF50T4EDNBX08HJ",
"postback_data": "choice_yes"
}
},
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "3964920326927846",
"app_id": "01F6T8M717SPW0186EC5A90Z0E"
},
"conversation_id": "01F6T8NG7D6M3Y0DT0RMDP1KFE",
"contact_id": "01F6T8NG3ZWF460K28RHAM1DHW",
"metadata": "",
"accept_time": "2021-05-30T22:03:09.181128Z"
}
}Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for an Ice Breaker message response. The metadata field contains a serialized JSON with the Ice Breaker payload:
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"accepted_time": "2021-05-30T22:01:45.364076Z",
"event_time": "2021-05-30T22:01:44.467Z",
"project_id": "5b7c830f-4183-4275-a028-13e40c98e29e",
"message": {
"id": "01F6ZMR5FN2JVH0X6ZEJ720BRN",
"direction": "TO_APP",
"contact_message": {
"text_message": {
"text": "Ice breaker text"
}
},
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "3964920326927846",
"app_id": "01F6T8M717SPW0186EC5A90Z0E"
},
"conversation_id": "01F6T8NG7D6M3Y0DT0RMDP1KFE",
"contact_id": "01F6T8NG3ZWF460K28RHAM1DHW",
"metadata": "{\"payload\":\"Ice breaker payload\"}",
"accept_time": "2021-05-30T22:01:45.294585Z"
}
}Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a story reply message response. The metadata field contains a serialized JSON with the story ID:
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"accepted_time": "2021-05-30T22:06:18.448186Z",
"event_time": "2021-05-30T22:06:16.726Z",
"project_id": "5b7c830f-4183-4275-a028-13e40c98e29e",
"message": {
"id": "01F6ZN0G58SMME0V2J8PCG1XN3",
"direction": "TO_APP",
"contact_message": {
"media_card_message": {
"url": "https://lookaside.fbsbx.com/ig_messaging_cdn/?asset_id=17934482515542967&signature=AbzZf9xi48_XSHNiyGhefmDpEDEb_EHg0sj6fuvzF0xCPlKPYesJR5m_kPNvNnpPO3NDiLhqAEPYwp7FiiXi7IbkTCqtQSsM7e7l4tiUdqGolWf2M8tbda8DWOmzRxX_8DqUu4W8VE752SuYstuQ1q02ZBUkx8Tcl2Z8y7rmNeAdDXoyOw",
"caption": "Story reply text"
}
},
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "3964920326927846",
"app_id": "01F6T8M717SPW0186EC5A90Z0E"
},
"conversation_id": "01F6T8NG7D6M3Y0DT0RMDP1KFE",
"contact_id": "01F6T8NG3ZWF460K28RHAM1DHW",
"metadata": "{\"story_id\":\"12219538774322346\"}",
"accept_time": "2021-05-30T22:06:18.384472Z"
}
}Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a story mention message response. The metadata field contains a serialized JSON with a type indicating that the message is a Story Mention:
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"accepted_time": "2021-05-28T14:17:19.865915Z",
"event_time": "2021-05-28T14:17:15.822Z",
"project_id": "5b7c830f-4183-4275-a028-13e40c98e29e",
"message": {
"id": "01F6SNC9KVC4QA0B5CJA3F01C5",
"direction": "TO_APP",
"contact_message": {
"media_message": {
"url": "https://lookaside.fbsbx.com/ig_messaging_cdn/?asset_id=17988851035358143&signature=AbwpO8_zezVsF3xAmVMQoWiUQsrN9rASmbo_v3pbAQOIdPnpL6LfgJ_4zNfk6_Kb-jEuTMc9erD0oEeVFC95fId77zWaAn1nU9C82zXXWDf029uCJKw9NO0b3cq7PRBQIqXmRj6K8IzAlbIJ5LTsqyS2vlBsOf4DjLsjPiG93brgWNMM1A",
"thumbnail_url": ""
}
},
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "4165102890214238",
"app_id": "01F6T8M717SPW0186EC5A90Z0E"
},
"conversation_id": "01F6SNC9R047F30W3B4NHK1RC2",
"contact_id": "01F6SNC9NVV4D31P87FZP51AT7",
"metadata": "{\"type\":\"story_mention\"}",
"accept_time": "2021-05-28T14:17:19.805777Z"
}
}Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a media share message response. The metadata field contains a serialized JSON with a type indicating that the message is a Media Share:
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"accepted_time": "2021-05-28T14:17:19.865915Z",
"event_time": "2021-05-28T14:17:15.822Z",
"project_id": "5b7c830f-4183-4275-a028-13e40c98e29e",
"message": {
"id": "01F6SNC9KVC4QA0B5CJA3F01C5",
"direction": "TO_APP",
"contact_message": {
"media_message": {
"url": "https://lookaside.fbsbx.com/ig_messaging_cdn/?asset_id=17988851035358143&signature=AbwpO8_zezVsF3xAmVMQoWiUQsrN9rASmbo_v3pbAQOIdPnpL6LfgJ_4zNfk6_Kb-jEuTMc9erD0oEeVFC95fId77zWaAn1nU9C82zXXWDf029uCJKw9NO0b3cq7PRBQIqXmRj6K8IzAlbIJ5LTsqyS2vlBsOf4DjLsjPiG93brgWNMM1A"
}
},
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "4165102890214238",
"app_id": "01F6T8M717SPW0186EC5A90Z0E"
},
"conversation_id": "01F6SNC9R047F30W3B4NHK1RC2",
"contact_id": "01F6SNC9NVV4D31P87FZP51AT7",
"metadata": "{\"type\":\"share\"}",
"accept_time": "2021-05-28T14:17:19.805777Z"
}
}Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for a shop product referral message response. The metadata field contains a serialized JSON with the product ID:
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"accepted_time": "2021-05-30T22:01:45.364076Z",
"event_time": "2021-05-30T22:01:44.467Z",
"project_id": "5b7c830f-4183-4275-a028-13e40c98e29e",
"message": {
"id": "01FG2557843KP0RXG333P2M46W",
"direction": "TO_APP",
"contact_message": {
"text_message": {
"text": "Message referring to a product from IG shop!"
}
},
"channel_identity": {
"channel": "INSTAGRAM",
"identity": "4165102890214238",
"app_id": "01F6T8M717SPW0186EC5A90Z0E"
},
"conversation_id": "01F6SNC9R047F30W3B4NHK1RC2",
"contact_id": "01F6SNC9NVV4D31P87FZP51AT7",
"metadata": "{\"product_id\":\"14239320930272293\"}",
"accept_time": "2021-05-30T22:01:45.294585Z"
}
}Below is an example of a Conversation API POST to the MESSAGE_INBOUND webhook for an unsupported media share message response:
{
"app_id": "01F6T8M717SPW0186EC5A90Z0E",
"accepted_time": "2021-05-28T14:13:06.271849Z",
"event_time": "2021-05-28T14:13:06.223973Z",
"project_id": "5b7c830f-4183-4275-a028-13e40c98e29e",
"unsupported_callback": {
"channel": "INSTAGRAM",
"payload": "{\"object\":\"instagram\",\"entry\":[{\"time\":1622211185048,\"id\":\"id\",\"messaging\":[{\"sender\":{\"id\":\"sender-id\"},\"recipient\":{\"id\":\"recipient-id\"},\"timestamp\":1622211184495,\"message\":{\"mid\":\"message-mid\",\"is_unsupported\":true}}]}]}"
}
}