Instagram Messaging

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.

Fact sheet

Prerequisites

To be able to onboard, you need to set-up the following:

• Facebook account
• Facebook account with a Business Facebook Page
• Instagram business account
• Facebook Page with admin access connected with your Instagram Business account.

Link your Instagram account to CM.com

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:

• "Access profile and posts from the Instagram account connected to your Page"
• "Manage and access Page conversations in Messenger"
• "Show a list of the Pages you manage"
• "Manage and access messages for the Instagram account connected to your Page"
• "Manage accounts, settings and webhooks for a Page"

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.

Do not link advertisement accounts or other assets to your connected assets of your Instagram account which are shown in the Meta business settings.

Business rules

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:

• When you make use of media messages, ensure you only store the privacy aware CDN URL in your system and use this link to render the media made accessible. See also Media Message.
• Ensure you process Story Reply messages. A Story Reply message is sent to you when a user replies to your Instagram Story. See also Story Reply.
• Ensure you process Message Delete events. Message Delete events occur when a message in Instagram is deleted by a user. See also Message Delete.
• Ensure you process Instagram Story Mention events. Story Mention events occur when a user mentions your business in their Story. See also Story Mention.
• Ensure your messaging experience has an escalation path to a human agent. If you have a custom inbox solution, you can handle the escalation yourself. If not, you can use the Handover to Instagram Inbox. See also Instagram Handover Protocol.

Considerations

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 hourly rate limit is equal to 200 * the number of people the customer can message via Instagram. This limit is high enough for most use cases. So if you have 1 conversation with 1 customer you can sent maximum 200 messages back to this customer. If there are 2 conversations with 2 customer you can sent maximum 400 messages back to these customers.

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.

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

Input matrix

You can use the following matrix to check what type of message will be sent with the included inputs.

Text

Direct message with plain text content

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."
                }
            }
        ]
    }
}

Media

The following media types are supported:

Display order

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.

Direct message with text and image

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.png",
                                "mediaUri": "https://www.cm.com/cdn/cm/cm.png",
                                "mimeType": "image/png"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Direct message with text and video

In the example below we send a simple rich content message that contains both text and a video 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": "your-video.mp4",
                                "mediaUri": "your-video-url.mp4",
                                "mimeType": "video/mp4"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Direct message with text and audio

In the example below we send a simple rich content message that contains both text and audio 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": "your-audio.mp4",
                                "mediaUri": "your-audio-url.mp4",
                                "mimeType": "audio/mp4"
                            }
                        }
                    ]
                }
            }
        ]
    }
}

Quick reply

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 and openURL. Note: quick replies are only visible in the Instagram app, not via web browser.

The following action is supported by Instagram as quick reply.

The following restrictions apply for a quick reply:

More info can be found in the rich content description.

Direct message with quick reply suggestions

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"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Rich card

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:

The following actions are supported by Instagram as rich card buttons.

A single Rich Card with a title, a subtitle, a media image and two suggestions

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 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!",
                            "media": {
                                "mediaUri": "https://www.cm.com/cdn/web/en/small/connect-test.png"
                            },
                            "suggestions": [
                                {
                                    "action": "OpenUrl",
                                    "label": "Visit our website!",
                                    "url": "https://cm.com",
                                    "postbackdata": "VISIT_WEBSITE"
                                },
                                {
                                    "action": "Reply",
                                    "label": "I want to chat!",
                                    "postbackdata": "HUMAN_AGENT"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

A carousel of Rich Cards with different compositions of a title, a subtitle, a media image and multiple suggestions

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:

1. A title, a subtitle, a media image and two suggestions.
2. A title and a media image.
3. A title, a subtitle and three suggestions.

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/cm/cm.png"
                                        },
                                        "suggestions": [
                                            {
                                                "action": "OpenUrl",
                                                "label": "Visit our website!",
                                                "url": "https://cm.com"
                                            },
                                            {
                                                "action": "Reply",
                                                "label": "I want to chat!",
                                                "postbackdata": "HUMAN_AGENT"
                                            }
                                        ]
                                    },
                                    {
                                        "header": "Our logo!",
                                        "media": {
                                            "mediaUri": "https://www.cm.com/cdn/cm/cm.png"
                                        }
                                    },
                                    {
                                        "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/"
                                            }  
                                        ]
                                    }
                                ]
                            }                                                      
                        }
                    ]
                }
            }
        ]
    }
}

Message Tags

Message tags enable sending important and personally relevant 1:1 updates to users outside the standard messaging window of 24 hours. This enables greater flexibility in how you interact with people, as well as the types of experiences you can build for Instagram Messaging. They may not be used to send promotional content (e.g. deals, offers, coupons, discounts, etc.). Use of tags outside of the approved use cases may result in restrictions on the Instagram Account to send messages. See the Messenger Platform and IG Messaging API Policy Overview for details.

The following message tags are supported:

Direct message with message tag

In the example below we send a simple text message with a message tag "HUMAN_AGENT" applied. This tag allows a human agent to respond to a user's inquiry outside of the standard 24 hour messaging window, up to 7 days after the user's last message.

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your Instagram account ID",
                "to": [
                    {
                        "number": "Recipients IGSID"
                    }
                ],
                "body": {
                    "type": "auto",
                    "content": "Fallback Text"
                },
                "allowedChannels": ["Instagram"],
                "richContent": {
                    "conversation": [
                        {
                            "text": "Dear customer, we have an update regarding your question",
                            "tag": "HUMAN_AGENT"
                        }
                    ]
                }
            }
        ]
    }
}

Marketing Messages

📘

Before using Instagram Marketing Messages

Please note that it is not possible to set up Instagram Marketing Messages yourself, for this you need the help of our support department. If you are interested in this position, please contact your account manager. If you are not yet a customer, please contact our support department.

With Marketing Messages you can send (recurring) notifications on a topic, a user has opted-in to. During the 24-hour messaging window, you can send users this notification opt-in request for a daily basis. Users can opt-in to receive Marketing Messages any time after this opt-in request is sent. Once a user opts-in, you are allowed to send Marketing Messages related to the topic they opted-in to on a daily basis.

Best practices

• Your opt-in request, including the title and image, encompasses the types of Marketing Message users can expect to receive, such as order updates, product recommendations, or certain offers.
• When sending more than one opt-in request to a user, each opt-in request should clearly state the different, specific types of Marketing Message the user can expect to receive.
• You must not use Marketing Messages, including opt-in requests, to spam users. This includes sending duplicate opt-in requests at high frequencies to the same users.

Users can provide feedback on your messaging experience, including blocking your messaging, which may result in restrictions on your use of Marketing Messages. You should regularly review your opt-in requests and Marketing Messages to see if they meet the best practices above.

Limitations

• You can only send one opt in request to a person per week for the same, specific topic.
• You may only send a request for a user to opt-in to Marketing Messages within the standard 24 hour messaging window. A user’s action of opting-in to Marketing Messages does not open the 24 hour messaging window.
• Do not send duplicate opt-in requests to users, which is defined as having the same title and image_url.
• You can only see if a person has opted in to receiving Marketing Messages.
• If a person has chosen to stop receiving Marketing Messages, your notifications will no longer be delivered to that person and you will receive an error.
• A person can block, mute, or report your messaging.

Sending Marketing Messages Opt-In Requests

🚧

This is currently only supported for the Instagram Mobile App. (Not clickable on IG web)

Before sending Marketing Messages, users must opt-in via an opt-in request. You must not send more than one opt-in request to a user per week on the same, specific topic. If you attempt to send an opt-in request to a user for the same topic in less than a week, the request will be blocked and you will receive an error message. In addition, there must be an open 24 hour messaging window before you can send an opt-in request to the user. Users can opt-in to receive Marketing Messages for multiple topics in the same thread. When a user chooses to opt-in on your Marketing Message a opt-in event will be triggered, see incoming events for more information on Instagram Marketing Messages events.

You can send an opt-in request as a single suggestion. The following restrictions apply for an opt-in message:

The following fields can be included as part of opt-in:

Marketing Messages Opt-In Request

In the example below we send a Marketing Message opt-in request that gives the recipient the option to opt-in on your notifications.

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your Instagram account ID",
                "to": [
                    {
                        "number": "Recipients IGSID"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Instagram"],
                "richContent": {
                    "conversation": [
                        {
                            "suggestions": [
                                {
                                    "action": "optin",
                                    "postbackdata": "OPT_IN",
                                    "label": "Receive daily product updates",
                                    "media": {
                                        "mediaName": "cm.png",
                                        "mediaUri": "https://www.cm.com/cdn/cm/cm.png",
                                        "mimeType": "image/png"
                                    },
                                    "optin": {
                                        "reoptin": true,
                                        "timezone": "Europe/Amsterdam"
                                    }
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Sending Marketing Messages Notifications

🚧

Important

A Marketing Messages message token is generated per opt-in (per user) which can then be used to send Marketing Messages. This means that instead of the users PSID you need to use the specific notification token received when the user opted-into your opt-in request to send Marketing Messages to this user.

📘

Notification frequency (Daily)

After a user opt-in, you are able to sent this user a notification once every calendar day which starts from 12:00am until 11:59pm in the time zone set by you.

📘

The NOTIFICATION_TAG

You can sent any type of Instagram message as a Marketing Message (except a opt-in request) as long as you use the notification token linked to the user as the recipient in combination with the "NOTIFICATION_MESSAGE" tag.

Sending Marketing Messages

In the example below we send a text message as a Marketing Message. Reminder: Every message type can be used as a Marketing Message as long as you combine the notification token with the "NOTIFICATION_MESSAGE" tag.

{
    "messages": {
        "authentication": {
            "producttoken": "Your product token"
        },
        "msg": [
            {
                "from": "Your Instagram account ID",
                "to": [
                    {
                        "number": "The notification token of the user"
                    }
                ],
                "body": {
                    "content": ""
                },
                "allowedChannels": ["Instagram"],
                 "richContent": {
                    "conversation": [
                        {
                            "text": "CM.com - Be part of it.",
                            "tag": "NOTIFICATION_MESSAGE"
                        }
                    ]
                }
            }
        ]
    }
}

Handover protocol

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.

Configure your Facebook page

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.

Handover to Instagram inbox

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.

Direct message with quick reply suggestion for handover protocol

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"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Receiving messages / Inbound flow

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 incoming messages. Note that for Instagram you need to set up your webhook API in the Channels app, not in the Gateway app.