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.

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 image-based media formats:
  • jpg
  • png
  • ico
  • bmp
For example:
Media Message
Note that the image size should be less than 8 MB.

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 on the Instagram app on Android and iOS. For example:
Choice Message
Note that choice messages are not supported on the Instagram web client. Instead, the message is transposed as a text message without choice buttons.

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 when sending image media. 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. For example:
Carousel Message
Note that outer choices are not supported.

The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed here.
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

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

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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

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:

Copy
Copied
{
  "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. All of these are delivered by Conversation API with a POST request to the MESSAGE_INBOUND webhook.

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.

Text message response webhook example

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

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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:

Copy
Copied
{
  "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}}]}]}"
  }
}
Was this page helpful?
SecurityPrivacyLegal & ComplianceCookie Statement
© 2022 Sinch. All rights reserved.