Skip to content

Instagram DM API

The Instagram DM API lets a developer bring Instagram conversations into a SaaS product, customer inbox, support workflow, or automation through one API.

List Conversations request
curl "{{API_BASE_URL}}/v1/messages?platform=instagram&accountId=acc_ig_biz_789&limit=20" \
    -H "x-access-key: your-api-key"
Illustrative request
Example line 1

curl "{{API_BASE_URL}}/v1/messages?platform=instagram&accountId=acc_ig_biz_789&limit=20" \

Illustrative request
Example line 2

-H "x-access-key: your-api-key"

The core workflow is to List Conversations for a connected account, Read Message History for a specific conversation, and Send Replies to a participant while handling the 24-hour window that applies to Instagram messaging.

Instagram DM API overview and reader task

The Instagram DM API is designed for a reader who needs to implement or evaluate an Instagram direct-message workflow inside their own product. Instead of rebuilding the underlying messaging integration for each connected account, the workflow starts from a connected Instagram professional account and uses a single accountId to scope conversation, history, and reply operations. That makes the same contract usable in a SaaS product, a customer inbox, a support workflow, or an automation that needs to act on customer messages without moving the conversation out of the product experience.

Input contract: connected account, accountId, and authentication

Before calling a messaging operation, connect an Instagram professional account and obtain its integration identifier. The connected Instagram integration's id is used as the accountId in messaging requests, so the first implementation check is to confirm that the accountId belongs to the intended connected Instagram account. Every request is authenticated by sending the access key in the x-access-key header. The implementation should include that header on each request and correct it if a request is not accepted for the connected account before retrying conversation or reply operations.

List Conversations: exact request and field map

List Conversations fetches conversations for a connected account and returns each participant's name, username, and profile picture, together with the most recent message and the updated time for the conversation. The request example in the List Conversations request example uses platform=instagram, accountId, and limit=20, and the List Conversations response example shows the response fields that a client should map into an inbox list. A practical failure check is to verify that the returned selfId and selfUsername match the connected account before rendering participants, because the participant list includes both the other person and the connected account identity. When nextCursor is present, another page is available and the client should continue pagination with that cursor rather than assuming the first page is complete.

Read Message History: conversation ID, pagination, and thread reconstruction

Read Message History loads the messages inside a specific conversation so a client can rebuild a full thread on its side. The conversation ID is passed to the Messages endpoint together with platform=instagram and the connected accountId, and the returned messages are paginated, with each message carrying its sender and timestamp. The implementation check is to confirm that the conversation ID came from List Conversations for the same accountId, then page through the history until no further page is indicated, preserving sender and timestamp order when reconstructing the thread for display or support notes.

Send Replies: recipientId, sent message ID, and the 24-hour window

Send Replies replies to a recipient with one call, and the response returns the sent message ID so the client can track delivery. The recipient is identified from conversation data: use the intended participant's ID as the recipientId when sending the reply, and distinguish that participant from the connected account's own identity in the participants list. The key failure case is the 24-hour window: Meta only allows sends within 24 hours of the user's last message, and that is a platform rule rather than a client-side preference. When the window has closed, the API surfaces the failure clearly, so the client should show the failure state in the inbox and avoid marking the reply as sent or storing a sent message ID that was not returned.

Build Your Own Inbox: decision criteria and limitations

Building your own inbox is the right choice when the product needs a branded support inbox or needs Instagram DMs wired into its own tools, because the same conversation, history, and reply operations that power a dashboard inbox are available through the API. A dashboard inbox is simpler when the team only needs to view and answer conversations without embedding them in the product. The decision should be based on whether the workflow must live inside the product experience, whether support staff need participant and last-message context in their own interface, and whether the team can handle the 24-hour window failure state in its own UI. The source also describes approval for instagram_business_manage_messages and OAuth handled end to end, which is relevant context when evaluating whether a separate Meta developer app and App Review are needed on the client side.

List Conversations request and response field map
FieldLocationRequiredness / conditionNotes
platformQuery parameterRequired in sampleValue: instagram
accountIdQuery parameterRequired in sampleExample: acc_ig_biz_789; connected Instagram integration id
limitQuery parameterPresent in sampleExample: 20
x-access-keyHeaderRequired for authenticationSend access key in x-access-key header
successResponse fieldPresent in sampleExample: true
selfIdResponse fieldPresent in sampleConnected account identity
selfUsernameResponse fieldPresent in sampleConnected account username
conversations[].idResponse fieldPresent in sampleConversation ID used for Read Message History
conversations[].participants[].idResponse fieldPresent in sampleParticipant ID; intended participant ID used as recipientId for replies
conversations[].participants[].nameResponse fieldPresent in sampleParticipant display name
conversations[].participants[].usernameResponse fieldPresent in sampleParticipant username
conversations[].participants[].profilePictureUrlResponse fieldPresent in sampleParticipant profile picture URL
conversations[].lastMessage.idResponse fieldPresent in sampleMost recent message ID
conversations[].lastMessage.textResponse fieldPresent in sampleMost recent message text
conversations[].lastMessage.from.idResponse fieldPresent in sampleSender ID for most recent message
conversations[].lastMessage.from.nameResponse fieldPresent in sampleSender name for most recent message
conversations[].lastMessage.timestampResponse fieldPresent in sampleMost recent message timestamp
conversations[].updatedTimeResponse fieldPresent in sampleConversation updated time
nextCursorResponse fieldPresent when another page is availableUse to continue pagination

Exact captured sample; POST/GET labelling conflict flagged privately and not resolved here.

Failure matrix for Instagram DM operations
Operation / conditionInput checkExpected handlingFailure check
List Conversationsplatform=instagram, accountId, x-access-key headerSample response labelled 202 in source; map conversations, participants, lastMessage, updatedTime, and nextCursorConfirm selfId/selfUsername match connected account; follow nextCursor when present
Read Message HistoryConversation ID from List Conversations, platform=instagram, accountIdLoad paginated messages with sender and timestamp; rebuild thread in orderConfirm conversation ID belongs to same accountId before rendering history
Send RepliesIntended participant ID as recipientIdResponse returns sent message ID for delivery trackingDo not mark reply as sent unless sent message ID is returned
24-hour window closedSend attempted more than 24 hours after user's last messageAPI surfaces failure clearly; platform rule, not client preferenceShow failure state; do not store a sent message ID
Authenticationx-access-key header on each requestAuthenticate request for connected accountInclude x-access-key on each request

No status codes invented; only captured 202 response label for List Conversations and described failure surfacing are retained.

Frequently asked questions

What can I do with the Instagram Messaging API?

With a connected Instagram account you can fetch DM threads, open the messages inside a chosen thread, and send a reply to the other participant.

What type of Instagram account do I connect?

The connection flow for Instagram expects a professional account.

How do I get the accountId for messaging requests?

After connecting, call /v1/connect/integrations and take the connected Instagram integration's id; that value is used as accountId.

How do I identify the person I should reply to?

Look at the participants returned for the thread. The other person's participant id is the value to pass as recipientId for a reply, separate from your own account identity.

Can I load more than one page of conversations?

Yes. When more results remain, the response carries nextCursor; pass it on to fetch the following page.

Can I load the messages inside a specific Instagram conversation?

Yes. Supply the thread's conversation ID to the Messages endpoint, along with platform=instagram and your accountId.

How do I authenticate Instagram Messaging API requests?

Include your access key on every request in the x-access-key header.

What can I build with the Instagram Messaging API?

It fits SaaS products and AI agents that need customer-message handling inside their own experience, such as an inbox, support workflow, or automation.

List Conversations response
{
    "success": true,
    "selfId": "17841411111111",
    "selfUsername": "yourbrand",
    "conversations": [
      {
        "id": "aWdfZG1fdGhyZWFkXzE",
        "participants": [
          {
            "id": "17841422222222",
            "name": "Jane Doe",
            "username": "jane_doe",
            "profilePictureUrl": "https://scontent.cdninstagram.com/..."
          },
          {
            "id": "17841411111111",
            "name": "Your Brand",
            "username": "yourbrand",
            "profilePictureUrl": "https://scontent.cdninstagram.com/..."
          }
        ],
        "lastMessage": {
          "id": "mid.aWdfbXNnXzk5OQ",
          "text": "An example comment.",
          "from": {
            "id": "17841422222222",
            "name": "Jane Doe"
          },
          "timestamp": "2026-08-05T16:40:00Z"
        },
        "updatedTime": "2026-08-05T16:40:00Z"
      }
    ],
    "nextCursor": "QVFIUl9..."
}