Messaging

Many types of unstructured content can be sent with Instagram Messaging, including texts, images, and videos.

Messaging Platform Policy

To send messages to someone on Instagram, the conversation must be initiated by the user. Messages sent with the Messenger Platform must comply with the policies and guidelines for what types of content and under what conditions they can be sent. For more details, see the Messenger Platform Policy Overview.

Send API

The Send API is the main API used to send messages to users, including text, attachments, sender actions, and more.

Messages from users will by default go to the Instagram inbox requests folder unless there's any prior conversation in the other folders or that the business follow the user. When replying to the thread via Send API, messages will be automatically move from requests folder to General folder.

Requirements

  • A page access token with instagram_manage_messages permission is required to interact with this endpoint. Apps in Development Mode or Standard Access, are restricted to message people that have a role in the app.
  • Use Graph API v5.0 and above. Some newer features require later version of graph API.
  • Instagram Messaging experiences must have an escalation path to a human agent. Experiences can start from an automation to qualify intent but must have a way for users to chat with a human agent as needed.
  • All messages sent by a human agent outside of the 24hr must leverage the HUMAN_AGENT tag. HUMAN_AGENT tag allows messages to be sent within 7 days after the last user’s message.

Note: Dev mode/live mode have been replaced with standard/advance access for business apps. Refer to the documentation for more details

Content

List of Supported Messages

Action TypeMessage TypeIs Supported

Message

Text

Message

Image

Supported formats are: jpg, png, ico, bmp. It should be less than 8 MB.

Message

Product Template

Message

Generic Template

Message

Sticker

Supported sticker: like_heart

Message

Attachments (video, voice, file)

Reaction

React

Supported reaction: love

Reaction

Unreact

Media Share

Image

Media Share

Video

Media Share

Story

Media Share

IGTV

Media Share

Reels

Text / Link

curl -X POST -H "Content-Type: application/json" -d '{
  "recipient": {
    "id": "<IGSID>"
  },
  "message": {
    "text": "<TEXT>"
  },
}' "https://graph.facebook.com/v12.0/me/messages?access_token={PAGE_ACCESS_TOKEN}"  

Text must be UTF-8 and has a 1000 bytes limit. Links within the text must be valid formatted URLs.

Image

...
  "message":{
    "attachment":{
      "type":"image", 
      "payload":{
        "url":"<ASSET_URL>"
      }
    }
  }
...

Sticker (Like Heart)

...
  "message": {
    "attachment":{
      "type":"like_heart"
    }
  }
...

Media Share

...
  "message":{
    "attachment":{
      "type":"media_share", 
      "payload":{
        "id":"<MEDIA_ID>"
      }
    }
  }
...

Only media owned by the business will be supported. Developers can leverage IG Media API to get MEDIA_ID

Product Template

Product template is only available on Graph API v8.0+

The product template is a structured message that can be used to render products that have been uploaded to Facebook catalog. Product template can include up to 10 products in the elements array of the payload.

...
"payload": {
  "template_type":"product",
  "elements":[
     {
        "id":"<PRODUCT_ID>",
      },
    ]
  }
...

Reaction

Reaction allow businesses to like a specific message sent by the user.

...
  "sender_action": "react",
  "payload": {
    "message_id": "<MID>",
    "reaction": "love"
  }
...
...
  "sender_action": "unreact",
  "payload": {
    "message_id": "<MID>"
  }
...

Generic Template

The generic template is a simple structured message that includes a title, subtitle, image, and up to three buttons. You may also specify a default_action object that sets a URL that will be opened in the Instagram webview when the template is tapped.

For a complete list of template properties, see the Generic Template reference.

"payload": {
  "template_type":"generic",
  "elements":[
     {
      "title":"<TITLE_TEXT>",
      "image_url":"<IMAGE_URL_TO_DISPLAY>",
      "subtitle":"<SUBTITLE_TEXT>",
      "default_action": {
        "type": "web_url",
        "url": "<DEFAULT_URL_TO_OPEN>",
      },
      "buttons":[<BUTTON_OBJECT>, ...]      
    },
    ...
  ]
}

The Messenger Platform supports the sending of a horizontally scrollable carousel of generic templates. To create a scrollable carousel, include up to 10 generic templates in the elements array of the payload.

"payload": {
  "template_type":"generic",
  "elements":[
    <GENERIC_TEMPLATE>,
    <GENERIC_TEMPLATE>,
    ...
  ]
}

API Response

A successful Send API request returns a JSON string containing identifiers for the message and its recipient.

{
  "recipient_id": "<IGSID>",
  "message_id": "<MESSAGE_ID>"
}

Reaction response will not contain message_id.

...
{
  "recipient_id": "<IGSID>"
}
...

Rate Limits

The Instagram Messaging rate limit is based on the number of API calls a user can make within a given period. If this limit is exceeded, API calls initiated by the app or user will fail.

You can refer to rate limit documentation for full details of the various rate limits for Instagram Messaging.

Error Codes

When a Send API request fails, you'll receive a JSON response describing the corresponding error code and message.

CodeSubcodeMessage

100

2534014

No matching Instagram user

100

2534037

The action is invalid since it's not the thread owner.

100

2534025

The comment is invalid for a private reply

100

2534015

Invalid message data

100

2018320

Invalid product id

100

2534013

The page is not linked to an Instagram account

100

2534029

The business has been blocked from sending messages via the IG Messaging API

10

2534022

This message is sent outside of allowed window.

613

2534040

Calls to this api have exceeded the rate limit.

200

2534041

The account owner has disabled access to instagram direct messages.

Instagram Inbox Folder Behavior

When you switch to a Professional account, you’ll have access to an inbox that allows you to organize messages and control notifications. This organized inbox has 2 tabs: Primary and General.

  • Primary: The Primary tab is for messages you’d like to see first. All messages will appear in the Primary tab, but you can swipe them into the General tab. Notifications for unread messages are turned on for the Primary tab, but you can turn them off in Settings.

  • General: The General tab is for messages you’d like to get back to later. Notifications for unread messages are turned off for the General tab, but you can turn them on in Settings.

  • Requests: You can also see message requests in your inbox. Requests are direct messages from accounts that you don’t follow. You can choose to accept or deny these requests, and request messages aren’t marked as “seen” until you accept them. You can also move accepted messages into the Primary or General tabs.

Instagram Messaging APIs currently doesn’t support inbox folder capability. All messages (regardless of it's folder grouping in Instagram app Inbox) will be delivered without any indication on where the thread is located on the Instagram app Inbox folder. Webhooks/messages received via API will not be considered as read in the Instagram app inbox. Once the business reply via the API, the thread will be considered read.

To help keep your Instagram inbox organized, all message requests that you answer using a third-party tool will be moved to the General folder. Here’s how your Instagram inbox will function:

  • New chats from people you follow will continue to appear in the Primary folder.
  • Existing chats that are already in your Instagram inbox will remain in the folder you’ve previously selected.
  • Even if you've changed your settings to allow messages from certain people to go directly to your Primary folder, if you're answering these messages using a third-party tool, they'll go to your General folder.
  • You’ll still be able to move individual messages between the General and Primary folders.

For more details, please refer to this link.