# Instagram channel message support

The Instagram 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 Instagram renders the messages on mobile devices.

Note
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](/docs/conversation/channel-support/instagram/properties).

| Message Type | Natively Supported? |
|  --- | --- |
| Text Message | Yes, this type of message is natively supported. For example: ![Text Message](/assets/instagram_text_message_isolated.18faa3b2c0fd958aaa25a61b804005170e7a50240259af0d5ce064a8df1fe547.01afcbcc.png) |
| Media Message | Yes, this type of message is natively supported for the following image-based media formats:`jpg``png``ico``bmp`For example: ![Media Message](/assets/instagram_media_message_isolated.9faf4491a55d9520246df6b28584ef909fada733270637fc20997e6e747ae430.01afcbcc.png)  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:Text ChoiceFor example: ![Choice Message](/assets/instagram_choice_message_isolated.5ce6ba110210799766e9ca6e6bf9e4be1d7121af0c7a2cb0450e4118de08ef6d.01afcbcc.png)  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: ![Card Message](/assets/instagram_card_message_isolated.1d3f101792613b3fa8cf19e1ea861209f7504582b7283001a88ba3e8137f790a.01afcbcc.png) |
| Carousel Message | Yes, this type of message is natively supported. For example: ![Carousel Message](/assets/instagram_carousel_message_isolated.35c695578e974e13de686b2fb3667f5a3bcd4e7669bf81e1584adf0b057208a1.01afcbcc.png)   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: ![Location Message](/assets/instagram_location_message_isolated.e06fd1dcad6398a8fbfb2702853537a4570ea7c5947af0ebc1f3fe4a4dad469e.01afcbcc.png) |


### Receiving Delivery Receipts

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


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

### Sending Private Replies for Instagram Comments

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.

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

Note
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:


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


```json
{
  "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](/docs/conversation/api-reference/conversation/events/):


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

![Instagram Private Reply](/assets/instagram_private_reply.64436a961ee76bdda39be5e81425cc4adba4a6bddf593e06815d0bf47d4a8a2c.01afcbcc.jpg)

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:


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

Note
Make sure your webhook is subscribed to `EVENT_DELIVERY` trigger to be able to receive status updates for your private reply messages.

## Receiving Messages

The Instagram channel supports various kinds of contact messages - text, media, quick replies, icebreakers, story replies, story mention, and media share.

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.

Note:
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](/docs/conversation/api-reference/conversation/contact/contact_getcontact).

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](#sending-private-replies-for-instagram-comments).

### Text message response webhook example

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


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

### Media message response webhook example

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`:


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

### Quick Reply or card choice message response webhook example

Below is an example of a Conversation API `POST` to the `MESSAGE_INBOUND` webhook for a quick reply or card choice message response:


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

### Ice Breaker message response webhook example

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:


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

### Story reply message response webhook example

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:


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

### Story mention message response webhook example

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:


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

### Media share message response webhook example

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:


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

### Shop product referral message response webhook example

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:


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

### Unsupported media share message response webhook example

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


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