Our business messaging API supports sending and receiving messages on Instagram Messaging.
Being able to send Instagram messages requires requesting access via the Channels portal. Without onboarding with Instagram via the portal, you can not make use of this part of the API.
Feature | Support | Remarks |
---|---|---|
delivery notification | yes | Occurs when your message is delivered to the Instagram platform. Delivery notifications are sent to the status report webhooks. |
text messages | yes | The maximum length of a Instagram message is 1.000 characters and it must be UTF-8 encoded. |
media | yes | Media name attribute should end in the proper file extension. Only one media file is allowed per message; when sending multiple files, each file will be sent in its own Instagram message. When the linked media doesn't exist/can't be found, the message will not be sent at all. The provided text message is sent in a separate Instagram message. |
media: images | yes | Maximum file size for an uploaded image is 8 MB. All common MIME types supported. For example: image/jpeg, image/png, image/x-icon, image/bmp. |
media: gif | no | Will only display the first frame of the GIF. |
media: audio | no | |
media: video | coming soon | Only supported by sharing a Instagram post containing a video. |
reply suggestions | yes | Maximum label length: 20 characters. |
rich card | yes | Support for generic template. |
rich carousel | yes | Support for generic template. Maximum of 10 templates supported. |
message tags | Yes | Allows messaging outside the standard messaging window of 24 hours. |
handover protocol | yes | Allows handover to the Instagram Inbox for live agents. |
To be able to onboard, you need to set-up the following:
Onboarding is done via our Channels portal. On our portal, you will be presented with a Facebook login pop up where you need to login with your Facebook account that is linked to your Instagram Business account.
In this pop up you will need to authorize our Facebook app, called CM.com Business Messaging to send and receive Instagram messages on behalf of your Instagram account.
This app requires the following permissions to work correctly:
If you choose to de-select these permissions in the Facebook pop up, we will not be able to complete the onboarding. It is allowed to have multiple Instagram accounts under one CM.com account.
Sending Instagram messages using the CM.com Business Messaging API also requires you to adhere to the Instagram Policy & Guidelines.
Please note that you must comply to Instagram's Technical Requirements. Specifically for incoming messages:
Note that in case of Instagram, the Instagram account that is used for sending messages is also still available in the regular Instagram app, from the Instagram website and from other 3rd party Instagram apps. Our API only has permissions to send messages on behalf of the Instagram account, it's not exclusively in control of that Instagram account.
This means that it will be possible to send messages using Instagram as well as using our API, and that might lead to situations where the API will relay replies to messages you sent via the Instagram app or website.
In those cases it will seem like messages are missing from a conversation when you use both ways of communicating with your end-users.
Our recommendation is to use the API exclusively for these Instagram accounts, and not switch between the Instagram app or website and the API, because the API won't "know" about the messages you sent using the app or website, but it will receive the replies to those messages.
The only way to have a Instagram conversation with end-users is when the end-user starts the conversation by sending you an initial message.
Instagram has rate limits in place; the per day rate limit is equal to 200 * the number of people the customer can message via Instagram.
If you choose to revoke any of the permissions given during the onboarding process on Facebooks side, we might no longer be able to deliver messages.
Unlike other channels, Instagram Messaging does not use telephone numbers as identifiers for sender (from
) and recipient (to.number
), instead it uses a so called "Instagram Scoped User ID (IGSID)" for the recipient and a "Instagram Account ID" for the sender. A person is assigned a unique IGSID for each Instagram Business account they start a conversation with.
Your Instagram Account ID is visible in the CM.com platform under channels...Instagram
.
If you send a message including both an image and some text, Instagram will display these as separate messages; typically the text will be the first message.
See the Instagram message with text and image example.
Quick replies provide a way to present a set of buttons in-conversation for users to reply with. A maximum of 13 quick replies are supported and each quick reply allows up to 20 characters before being truncated. Quick replies only support plain text. Note: quick replies are only visible in the Instagram app, not via web browser.
The following restrictions apply for a quick reply:
Field | Required | Remarks |
---|---|---|
label | Yes | Maximum length is 20 characters. |
postbackdata | Yes | Maximum length is 1000 characters. |
More info can be found in the rich content description.
For Instagram Messaging, experiences must have an escalation path that allows end-users to speak to a human agent instead of a bot. If you have a custom inbox solution, you can handle the human agent escalation by yourself by switching between a bot and live agents in your inbox solution.
If you don't have a custom inbox solution, we provide support to escalate to the Instagram inbox of your Instagram account instead by following the steps below.
In order to allow CM.com to perform a handover to your Instagram inbox, you need to update the settings of your Facebook page that is linked with your Instagram account after you have successfully onboarded in the CM.com platform.
In your Facebook page settings, go to Advanced messaging
and browse to Handover protocol
.
Click on the Configure
button and select CM.com Business Messaging
as the primary receiver for the handover protocol.
To provide the end-user to speak with a human agent via the Instagram inbox, you must send a quick reply with HUMAN_AGENT
as postback data.
If the end-user then selects this quick reply, the handover event will be triggered by CM.com, changing the conversation from the app to the message inbox in Instagram.
After the handover event has been triggered, CM.com has no control of the conversation for 24 hours. During this timeframe, a human agent has to escalate the conversation with the end-user via your Instagram account. These messages will not be tracked by CM.com during the 24 hour timeframe until it has expired.
If your human agent is done with the conversation or want CM.com to take control again, sending a message via the Business Messaging API will cancel the handover protocol. This will make CM.com take control again of the conversation with the end-user.
Rich cards, called Generic Templates in Instagram Messenger, offer a way for you to offer a richer in-conversation experience than standard text messages by integrating buttons, images and more alongside text in a single message. Rich cards can be used for many purposes, such as displaying product information or asking the message recipient to choose from a pre-determined set of options.
Note: this is supported only for the Instagram App.
Note: when using a carousel (2 to 10 generic templates), put the cards containing a media image and at least a button first and/or second, as the behavior and sizing of the rest of the cards is affected by them.
A simple structured message that must include a title and must include at least one of the following: a subtitle, an image and/or up to three buttons.
This template will be used if fields are given that are not covered by other Instagram templates.
The following restrictions apply for a generic template:
Field | Support | Required | Remarks |
---|---|---|---|
cards | Yes | Yes (If header not defined) | Maximum 10 allowed per message. At least one property must be set in addition to header. |
header | Yes | Yes (If cards not defined) | Displayed as the title. Maximum length is 80 characters. |
defaultAction | Yes | No | Make the template behave as if it is an open url button when a user taps it. |
text | Yes | No | Displayed as the subtitle. Maximum length is 80 characters. |
mediaUri | Yes | No | The URL of the image to display. |
suggestions | Yes | No | Maximum of 3 buttons per card. |
You can use the following matrix to check what type of message will be send with the included inputs.
Text | Default Action | Media | Suggestions | Header | Output |
---|---|---|---|---|---|
x | x | x | x | x | Not supported |
x | x | x | x | √ | Generic template with just a title |
√ | x | x | x | √ | Generic template with a title and a subtitle |
√ | x | √ | x | √ | Generic template with a title, a subtitle and a media image. |
√ | x | x | √ | √ | Generic template with a title, a subtitle and up to 3 buttons. |
x | x | √ | x | √ | Generic template with a title and a media image. |
x | x | √ | √ | √ | Generic template with a title, a media image and up to 3 buttons. |
x | x | x | √ | √ | Generic template with a title and up to 3 buttons. |
√ | x | √ | √ | √ | Generic template with a title, a subtitle, a media image and up to 3 buttons. |
√ | √ | x | x | √ | Generic template with a title, a subtitle and a default action. |
x | √ | x | x | √ | Generic template with a title and a default action. |
x | √ | √ | x | √ | Generic template with a title, a media image and a default action. |
x | √ | x | √ | √ | Generic template with a title, a default action and up to 3 buttons. |
√ | √ | √ | √ | √ | Generic template with a title, a subtitle, a default action, a media image and up to 3 buttons. |
Since Instagram Messaging is used for 2-way communication (chat) it is important to also implement an Inbound flow. You can find more information about how to do this using our API documentation of the Inbound webhook. Note that for Instagram you need to set up your webhook API in the Channels app, not in the Gateway app.
An explanation on how to send rich content messages in general can be found in the rich content description.
The example below will send a simple text-only Instagram message.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Your Instagram account ID",
"to": [
{
"number": "Recipients IGSID"
}
],
"allowedChannels": ["Instagram"],
"body": {
"type": "auto",
"content": "CM.com - Be part of it."
}
}
]
}
}
In the example below we send a simple rich content message that contains both text and an image that Instagram will display as two separate messages.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Your Instagram account ID",
"to": [
{
"number": "Recipients IGSID"
}
],
"allowedChannels": ["Instagram"],
"body": {
"type": "auto",
"content": "Fallback Text"
},
"richContent": {
"conversation": [
{
"text": "CM.com - Be part of it.",
"media": {
"mediaName": "cm-tablet.jpg",
"mediaUri": "https://www.cm.com/cdn/web/blog/featured/cm-tablet.jpg",
"mimeType": "image/jpeg"
}
}
]
}
}
]
}
}
In the example below we send a rich content message that contains a text and some reply suggestions.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Your Instagram account ID",
"to": [
{
"number": "Recipients IGSID"
}
],
"body": {
"content": ""
},
"allowedChannels": ["Instagram"],
"richContent": {
"conversation": [
{
"text": "Hi, what can I do for you?",
"suggestions": [
{
"action": "Reply",
"label": "Call me",
"postbackdata": "CALL"
},
{
"action": "Reply",
"label": "Email me",
"postbackdata": "EMAIL"
},
{
"action": "Reply",
"label": "Send me an sms",
"postbackdata": "SMS"
}
]
}
]
}
}
]
}
}
In the example below we send a rich content message that contains a text and some reply suggestions. One of the suggestions with postback data HUMAN_AGENT
will trigger the handover protocol.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Your Instagram account ID",
"to": [
{
"number": "Recipients IGSID"
}
],
"body": {
"content": ""
},
"allowedChannels": ["Instagram"],
"richContent": {
"conversation": [
{
"text": "Hi, what can I do for you?",
"suggestions": [
{
"action": "Reply",
"label": "Ask a question",
"postbackdata": "QUESTION"
},
{
"action": "Reply",
"label": "Talk to live agent",
"postbackdata": "HUMAN_AGENT"
}
]
}
]
}
}
]
}
}
In the example below we send a rich content message that contains a rich card. The rich card is composed of a title, a subtitle, a default action, a media image and two suggestions. One of the suggestions will open an external url, while the other suggestion will start a handover protocol based upon it's postback data HUMAN_AGENT
.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Your Instagram account ID",
"to": [
{
"number": "Recipients IGSID"
}
],
"body": {
"content": ""
},
"allowedChannels": ["Instagram"],
"richContent": {
"conversation": [
{
"header": "We are CM.com!",
"text": "Visit our website or start a chat with one of our employee's!",
"defaultAction": {
"action": "OpenUrl",
"url": "https://cm.com"
},
"media": {
"mediaUri": "https://www.cm.com/cdn/web/blog/featured/cm-tablet.jpg"
},
"suggestions": [
{
"action": "OpenUrl",
"label": "Visit our website!",
"url": "https://cm.com"
},
{
"action": "Reply",
"label": "I want to chat!",
"postbackdata": "HUMAN_AGENT"
}
]
}
]
}
}
]
}
}
In the example below we send a rich content message that contains a carousel of rich cards. The rich cards have multiple different compositions in which they are shown to the end user.
Three possible different compositions are:
It's possible to mix different elements with each other.
{
"messages": {
"authentication": {
"producttoken": "Your product token"
},
"msg": [
{
"from": "Your Instagram account ID",
"to": [
{
"number": "Recipients IGSID"
}
],
"body": {
"content": ""
},
"allowedChannels": ["Instagram"],
"richContent": {
"conversation": [
{
"carousel": {
"cards": [
{
"header": "We are CM.com!",
"text": "Visit our website or start a chat with one of our employee's!",
"media": {
"mediaUri": "https://www.cm.com/cdn/web/blog/featured/cm-tablet.jpg"
},
"suggestions": [
{
"action": "OpenUrl",
"label": "Visit our website!",
"url": "https://cm.com"
},
{
"action": "Reply",
"label": "I want to chat!",
"postbackdata": "HUMAN_AGENT"
}
]
},
{
"header": "Our logo!",
"defaultAction": {
"action": "OpenUrl",
"url": "https://cm.com"
},
"media": {
"mediaUri": "https://www.cm.com/cdn/web/blog/featured/cm-tablet.jpg"
}
},
{
"header": "Conversational Channels",
"text": "Here's a selection of some of the channels we support!",
"suggestions": [
{
"action": "OpenUrl",
"label": "WhatsApp!",
"url": "https://www.cm.com/whatsapp/"
},
{
"action": "OpenUrl",
"label": "Instagram Messaging!",
"url": "https://www.cm.com/instagram-messaging"
},
{
"action": "OpenUrl",
"label": "RCS!",
"url": "https://www.cm.com/rcs/"
}
]
}
]
}
}
]
}
}
]
}
}