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: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 returns400 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.
- 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_AGENTis the only value. Any other value, or the tag on an account connected through Facebook Login, returns422 messaging.tag_not_supported. Send withoutmessage_taginstead.
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 asource_typeofurl,media_id, orplatform_attachment_id.typeis required withplatform_attachment_id: without it, the request returns400 validation.attachment_type_required. Instagram fetches aurlattachment itself, so the URL must be reachable without a login. If Instagram cannot fetch or accept the file, the send returns422 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
postbackbutton arrives as adm.postbackevent. - Threaded replies.
reply_to_message_idworks on Facebook Login. On Instagram Login, a send with it returns422 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.
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.
- 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.receivedwith an attachment of typestory_mention, not asmention.received. - Unsent messages. When the person unsends a message, SocialAPI sends a
dm.deletedevent 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.sentevent. - 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_idfails. 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:403 account.permission_missing. The account lacks the permission the call needs:messages.readto read a participant profile, andmessages.writeto send a message, a reaction, or a sender action.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 thanaccount_id. The other two mean the token is no longer valid and the account needs reconnecting.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 withmessage_tag.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.400 validation.*. The body is wrong.error.meta.fieldnames the field. The codes are in Send a message.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.422 platform.instagram.invalid_parameter. Instagram rejected a parameter, for examplereply_to_message_idon Instagram Login. Retrying unchanged does not help.422 platform.instagram.thread_unavailable. Instagram refused to deliver to this conversation, which can be restricted or unavailable. Retrying does not help.403 platform.instagram.permission_denied. The platform scopes granted at connect do not cover the action. Reconnect the account and approve every scope.409 platform.instagram.no_page. A send on a Facebook Login account with no linked Facebook Page. Reconnect the account.403 platform.instagram.230,404 platform.instagram.9010. A participant profile Instagram withholds, or a participant whose account no longer exists.429 messaging.recipient_limit. Too many different people were messaged this calendar day (UTC). Wait for theRetry-Afterheader. Nothing was sent and no credit was used.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 theRetry-Afterheader), or Instagram’s own limit.429 platform.instagram.throttled: wait for theRetry-Afterheader, then retry. Read theRetry-Afterheader when it is present: see Rate limits.
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.
Related
- Instagram API: capabilities, connection, and scopes for Instagram
- Instagram comments: private replies that start a conversation from a comment
- Direct messages: the endpoints and fields every platform shares
- Automations: send Instagram DMs and answer button taps without your own handler
- Webhook events: the DM event payloads