Skip to main content
SocialAPI lists the direct message (DM) conversations of a connected Instagram Business or Creator account, reads their messages, and sends replies with text, attachments, quick replies, buttons, and cards. A conversation is one person talking to the Instagram account. The endpoints are the ones every platform uses, described in Direct messages. This page holds the rules that are specific to Instagram, including the differences between Instagram Login and Facebook Login. Instagram lets the account message a person only inside the 24-hour messaging window that the person’s last message opened, or up to 7 days with HUMAN_AGENT on Instagram Login, once enabled for your SocialAPI account. A DM request costs 1 interaction credit, however many messages it sends. Reads, reactions, typing indicators, seen receipts, and participant profiles cost nothing.

Endpoints

{conversation_id} in the /v1/inbox/conversations paths is the conversation id. {message_id} is a message’s platform_id. In the profile path, {account_id} is the connected account’s acc_ ID and {participant_id} is the conversation’s participant_id, the person’s Instagram-scoped ID. See IDs.

Your first message

List the Instagram conversations of one connected account:
Response (HTTP 200):
Reply inside the messaging window:
Response (HTTP 200):
message_ids lists the SocialAPI ID of every message the request sent, in send order. The conversation and message fields are described in Conversations and Read messages.

The messaging window

An Instagram account can message a person only within 24 hours of the person’s last message. Each new message from the person restarts the 24 hours. Outside the window, the send returns 400 platform.instagram.window_closed, and Instagram delivers nothing.
  • After a refusal. Once Instagram refuses a conversation for a closed window, SocialAPI refuses later sends on that conversation with the same code and error.meta.blocked_locally: true, until the person messages the account again, or 24 hours after Instagram’s refusal, whichever comes first. These refusals cost no credit. A send that goes out with HUMAN_AGENT is not refused this way. See The messaging window.
  • Private replies. A private reply does not open the window. The person’s answer to it does.
  • Automations. An Automation never sends message_tag, so its DMs follow the 24-hour window.

Reply after 24 hours with HUMAN_AGENT

message_tag: "HUMAN_AGENT" lets a member of your team reply to a conversation between 24 hours and 7 days after the person’s last message. It applies only to accounts connected through Instagram Login.
The response is the same as an untagged send. How it works:
  • For replies your team types. Send HUMAN_AGENT only on a reply a member of your team types to a person who is waiting for help. Workflows, Automations, bots, and AI agents acting on their own send without the tag, so they reply within 24 hours of the person’s last message. Broadcasts and promotions also send without the tag. Meta’s messaging policy applies to every tagged message.
  • Turn it on. Ask support to enable HUMAN_AGENT for your SocialAPI account. Until then, a send with the tag returns 403 messaging.tag_not_enabled.
  • Window. Within 24 hours of the person’s last message, the message is sent without the tag, as an ordinary reply. More than 7 days after it, the send returns 400 messaging.human_agent_window_closed, and the person must message the account first.
  • Allowed values. HUMAN_AGENT is the only value. Any other value, or the tag on an account connected through Facebook Login, returns 422 messaging.tag_not_supported. Send without message_tag instead.

Message types and sizes

An Instagram DM carries text, attachments, quick replies, buttons, or cards. The request fields are in Send a message. SocialAPI sends the text first, then each attachment in order, as separate messages: text plus 2 images arrives as 3 messages and costs 1 credit. Instagram sets these sizes and refuses a larger message:
  • Attachment sources. Each item of attachments[] has a source_type of url, media_id, or platform_attachment_id. type is required with platform_attachment_id: without it, the request returns 400 validation.attachment_type_required. Instagram fetches a url attachment itself, so the URL must be reachable without a login. If Instagram cannot fetch or accept the file, the send returns 422 platform.instagram.attachment_failed.
  • Interactive content. Up to 13 quick replies, a button template with 1 to 3 buttons, or up to 10 cards, 1 of the 3 per message. The rules are in Interactive messages. A tap on a quick reply or a postback button arrives as a dm.postback event.
  • Threaded replies. reply_to_message_id works on Facebook Login. On Instagram Login, a send with it returns 422 platform.instagram.invalid_parameter. Send the message without it.

React to a message

POST /v1/inbox/conversations/{conversation_id}/messages/{message_id}/reaction adds the account’s reaction to a message, and replaces the account’s earlier reaction on it. reaction is a single emoji character, and Instagram accepts any emoji. Anything else returns 400 validation.invalid_reaction. DELETE on the same path, with account_id as a query parameter, removes the reaction. Both work on Instagram Login and Facebook Login, return { "success": true }, and cost no credit.
Response (HTTP 200):
A reaction the person adds to one of your messages sends no event.

Typing indicators and seen receipts

POST /v1/inbox/conversations/{conversation_id}/sender-action with action set to typing_on or typing_off shows or hides a typing indicator, and mark_seen marks the person’s messages as seen. Instagram shows the action only while the person is signed in. If Instagram refuses the action because the window is closed or a scope is missing, the call returns 400 platform.instagram.window_closed or 403 platform.instagram.permission_denied. It works on both login paths and costs no credit. The request and the action values are in Typing indicators and seen receipts. Instagram does not report when the person is typing, so SocialAPI has no event for it.

Participant profile

GET /v1/platforms/instagram/accounts/{account_id}/participants/{participant_id}/profile returns the profile of a person in a conversation, including whether the person follows the account (is_user_follow_business) and whether the account follows the person (is_business_follow_user). It works on both login paths.
Response (HTTP 200):
  • Consent. Instagram discloses a profile only for a person who messaged the account or tapped an icebreaker or the persistent menu. For anyone else, the call returns 403 platform.instagram.230. That error means Instagram withholds the data: it does not mean the person does not follow the account.
  • Absent follow flags. An absent follow flag means the person does not follow in that direction, or Instagram did not report it. The response does not tell the two apart.
  • Freshness. Read the follow fields at each call: they change whenever someone follows or unfollows.
  • Deleted accounts. A participant whose Instagram account was deleted or deactivated returns 404 platform.instagram.9010.

Incoming messages

  • Story mentions. A story that mentions the account arrives as dm.received with an attachment of type story_mention, not as mention.received.
  • Unsent messages. When the person unsends a message, SocialAPI sends a dm.deleted event and the message disappears from the conversation.
  • Messages sent from the Instagram app. A message the account sends from the Instagram app appears in the conversation and sends a dm.sent event.
  • Edits. A message the person edits sends no event.

Instagram Login and Facebook Login

Both login paths list conversations, read messages, send text, attachments, and interactive content, react, send typing indicators and seen receipts, and read participant profiles. They differ in these rows: Every scope SocialAPI requests is listed in Instagram scopes and Facebook Login scopes.

What Instagram does not allow

  • Messaging a person first. The account can message a person only after the person messaged it, or through a private reply to their comment.
  • Unsending or deleting a sent DM. Instagram does not let apps unsend or delete a message. Only the Instagram app can.
  • HUMAN_AGENT on Facebook Login. Connect the account through Instagram Login to reply after 24 hours.
  • Threaded replies on Instagram Login. reply_to_message_id fails. Send the message without it.
  • Old message requests. Instagram does not return conversations in the account’s Requests folder that have had no activity for 30 days.

Limits

Errors and debugging

Check these in order when an Instagram DM call fails:
  1. 403 account.permission_missing. The account lacks the permission the call needs: messages.read to read a participant profile, and messages.write to send a message, a reaction, or a sender action.
  2. 404 conversation.not_found, 401 platform.instagram.auth, 403 account.reconnection_required. 404 conversation.not_found: no conversation has that id, or, on a send, the conversation belongs to another connected account than account_id. The other two mean the token is no longer valid and the account needs reconnecting.
  3. 400 platform.instagram.window_closed. The messaging window is closed. Wait for the person to message the account, or, on Instagram Login with HUMAN_AGENT enabled, send a typed reply with message_tag.
  4. 403 messaging.tag_not_enabled, 422 messaging.tag_not_supported, 400 messaging.human_agent_window_closed. A HUMAN_AGENT send is not enabled, not allowed on this account, or too late: see Reply after 24 hours with HUMAN_AGENT.
  5. 400 validation.*. The body is wrong. error.meta.field names the field. The codes are in Send a message.
  6. 422 platform.instagram.attachment_failed. Instagram could not fetch or accept an attachment. Check that the URL is public and the file matches Message types and sizes.
  7. 422 platform.instagram.invalid_parameter. Instagram rejected a parameter, for example reply_to_message_id on Instagram Login. Retrying unchanged does not help.
  8. 422 platform.instagram.thread_unavailable. Instagram refused to deliver to this conversation, which can be restricted or unavailable. Retrying does not help.
  9. 403 platform.instagram.permission_denied. The platform scopes granted at connect do not cover the action. Reconnect the account and approve every scope.
  10. 409 platform.instagram.no_page. A send on a Facebook Login account with no linked Facebook Page. Reconnect the account.
  11. 403 platform.instagram.230, 404 platform.instagram.9010. A participant profile Instagram withholds, or a participant whose account no longer exists.
  12. 429 messaging.recipient_limit. Too many different people were messaged this calendar day (UTC). Wait for the Retry-After header. Nothing was sent and no credit was used.
  13. 429 validation.interaction_limit_exhausted, 429 messaging.velocity_limit, 429 platform.instagram.rate_limit, 429 platform.instagram.throttled. Your plan’s allowance, the account’s sending pace (429 messaging.velocity_limit: wait for the Retry-After header), or Instagram’s own limit. 429 platform.instagram.throttled: wait for the Retry-After header, then retry. Read the Retry-After header when it is present: see Rate limits.
If a send fails part way, the earlier messages stay delivered, and the error carries error.meta.sent_count and error.meta.failed_index. Every code is in Errors, and Instagram’s own codes are in Instagram and Facebook errors.

Scopes

A scoped API key needs these scopes:

Events

Instagram accounts emit these DM events to your webhook endpoints. Payloads are in Webhook events. An account without the messages.read permission receives none of these events, except dm.status.read when the account has messages.write.

Use from an AI agent

There is no tool for reactions or for participant profiles. See MCP tools.
Last modified on November 15, 2026