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.
curl "{{API_BASE_URL}}/v1/messages?platform=instagram&accountId=acc_ig_biz_789&limit=20" \
-H "x-access-key: your-api-key"curl "{{API_BASE_URL}}/v1/messages?platform=instagram&accountId=acc_ig_biz_789&limit=20" \
-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.
| Field | Location | Requiredness / condition | Notes |
|---|---|---|---|
| platform | Query parameter | Required in sample | Value: instagram |
| accountId | Query parameter | Required in sample | Example: acc_ig_biz_789; connected Instagram integration id |
| limit | Query parameter | Present in sample | Example: 20 |
| x-access-key | Header | Required for authentication | Send access key in x-access-key header |
| success | Response field | Present in sample | Example: true |
| selfId | Response field | Present in sample | Connected account identity |
| selfUsername | Response field | Present in sample | Connected account username |
| conversations[].id | Response field | Present in sample | Conversation ID used for Read Message History |
| conversations[].participants[].id | Response field | Present in sample | Participant ID; intended participant ID used as recipientId for replies |
| conversations[].participants[].name | Response field | Present in sample | Participant display name |
| conversations[].participants[].username | Response field | Present in sample | Participant username |
| conversations[].participants[].profilePictureUrl | Response field | Present in sample | Participant profile picture URL |
| conversations[].lastMessage.id | Response field | Present in sample | Most recent message ID |
| conversations[].lastMessage.text | Response field | Present in sample | Most recent message text |
| conversations[].lastMessage.from.id | Response field | Present in sample | Sender ID for most recent message |
| conversations[].lastMessage.from.name | Response field | Present in sample | Sender name for most recent message |
| conversations[].lastMessage.timestamp | Response field | Present in sample | Most recent message timestamp |
| conversations[].updatedTime | Response field | Present in sample | Conversation updated time |
| nextCursor | Response field | Present when another page is available | Use to continue pagination |
Exact captured sample; POST/GET labelling conflict flagged privately and not resolved here.
| Operation / condition | Input check | Expected handling | Failure check |
|---|---|---|---|
| List Conversations | platform=instagram, accountId, x-access-key header | Sample response labelled 202 in source; map conversations, participants, lastMessage, updatedTime, and nextCursor | Confirm selfId/selfUsername match connected account; follow nextCursor when present |
| Read Message History | Conversation ID from List Conversations, platform=instagram, accountId | Load paginated messages with sender and timestamp; rebuild thread in order | Confirm conversation ID belongs to same accountId before rendering history |
| Send Replies | Intended participant ID as recipientId | Response returns sent message ID for delivery tracking | Do not mark reply as sent unless sent message ID is returned |
| 24-hour window closed | Send attempted more than 24 hours after user's last message | API surfaces failure clearly; platform rule, not client preference | Show failure state; do not store a sent message ID |
| Authentication | x-access-key header on each request | Authenticate request for connected account | Include 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.
{
"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..."
}