Instagram DMs API: How to Manage Instagram DMs With an API
The Instagram DMs API lets a developer list conversations, read message history, and reply programmatically instead of handling every direct message by hand. This guide follows the exact list, read, and reply flow, including the account connection step, the fields returned for each conversation and message, and the 24-hour window that controls whether a reply can be sent.
What you need
You need an API access key and an eligible Instagram account before you can call the messaging endpoints. The access key is sent on every request in the x-access-key header, so store it like a password and never commit it to source control. The Instagram account must be an Instagram Business account or a Creator account. Personal accounts cannot manage DMs through this API, which is a Meta limit rather than a restriction added by the API layer. If you connect a personal account, the DM workflow is not available for that account type, so check account type before building automation around it.
Step 1: Get your API key
Create an account, open the dashboard, and copy your access key from the Access Keys page. Every request in the examples that follow uses that key in the x-access-key header, as shown in the API key header example. Treat the key as a credential: rotate it if it leaks, scope server-side calls to a trusted backend, and log failures without printing the full header value. If a request does not succeed, confirming the header name and value is a sensible first check, though the source does not specify a particular error response for authentication failures.
Step 2: Connect your Instagram account
Connecting the Instagram account uses an OAuth flow that requests the instagram_business_manage_messages scope from Meta. That scope is what allows reading and sending messages on behalf of the connected account. Call the connect endpoint to obtain an authorization URL, open that URL, authorize the app, and then confirm the link by listing integrations. The integrations response includes an id for each connected account, and that id is the accountId you pass to every DM call below. If you prefer a graphical flow, the same connection can be completed from the dashboard, but the accountId still comes from the integrations response.
The one Meta rule you can't ignore: the 24-hour window
Meta only allows a business to message a user within 24 hours of that user's last message to the business. When someone sends a DM, the clock starts, and a reply sent through the API after that period is rejected. This 24-hour window exists to prevent cold messaging, and it applies to sends only. Reading conversations and message history is not limited by the window, so you can inspect an older thread at any time, but you cannot use the API to reopen a stale conversation with a new outbound message. Design automation to reply promptly while the conversation is still warm, and surface a clear failure state when a send is attempted outside the window.
Step 3: List your conversations
List your conversations by calling GET /v1/messages with platform set to instagram, your accountId, and a limit, as shown in the source examples. The response returns conversations newest activity first, along with selfId and selfUsername so your code can tell which side of a thread belongs to your brand. Each conversation carries its participants, its lastMessage, and an updatedTime you can sort or filter on. When there are more conversations than the limit you requested, the response includes a nextCursor. Pass that value back as the after parameter on the next request to page through the rest of the inbox, and stop when nextCursor is null or absent.
Step 4: Read a conversation
Take a conversation id from the list response and call GET /v1/messages/:conversationId with the same platform, accountId, and limit parameters shown in the examples. The response is a flat list of messages, each with an id, text, a from object, and a timestamp. Compare each message's from.id against the selfId from the list response to know who said what when rendering the thread. Older messages page in with the after cursor exactly as conversations do, using the nextCursor returned in the response. Check the field map in the tables below before building your renderer, because participant and sender shapes differ between the conversation list and the message list.
Step 5: Send a DM reply
To reply, POST to /v1/messages with platform, accountId, recipientId, and text in the JSON body, as shown in the send example. The recipientId is the participant's id from the conversation, specifically the one that is not selfId. A successful send returns success set to true and a messageId for the new message. If the recipient's last message is more than 24 hours old, the send fails because of the 24-hour window, so build your logic to check recency before attempting the POST and to handle the rejection gracefully. As operational guidance, waiting longer will not make a conversation that is outside the window eligible again, so do not treat a window rejection as a transient error to retry indefinitely.
Putting it together
A basic Instagram DM auto responder is three calls in sequence. Poll GET /v1/messages for new activity, read the relevant thread with GET /v1/messages/:conversationId to get context, then POST a reply to /v1/messages. Each of those calls spends 1 credit, so choose a polling cadence that fits your credit budget instead of polling as fast as possible. Before writing code, you can also try the free Instagram DM inbox, which exposes the same list, read, and reply flow behind a simple interface. Work through one conversation end to end, verify that selfId, recipientId, and nextCursor behave as documented in the tables, and only then wire the flow into your own application.
What's next
That is the full DM loop: list conversations, read a thread, and send a reply, all on Instagram Business and Creator accounts. The 24-hour window is the rule that trips people up most often, and it comes from Meta rather than from the API layer. Full endpoint details live on the Instagram DMs API page, and the general API documentation covers authentication and pagination in more depth. If you also handle public engagement, the guide to managing Instagram comments with an API follows the same pattern on a different endpoint.
| Endpoint | Method and path as shown in source | Inputs present in source examples | Purpose |
|---|---|---|---|
| Connect Instagram | curl {{API_BASE_URL}}/v1/connect/instagram (method not explicitly stated in source) | x-access-key header | Return an authorization URL for the instagram_business_manage_messages scope |
| List integrations | curl {{API_BASE_URL}}/v1/connect/integrations (method not explicitly stated in source) | x-access-key header | Return connected accounts; use each id as accountId |
| List conversations | GET {{API_BASE_URL}}/v1/messages | platform=instagram, accountId, limit; x-access-key header | List conversations newest activity first |
| Read conversation | GET {{API_BASE_URL}}/v1/messages/:conversationId | platform=instagram, accountId, limit; x-access-key header | Return messages in one conversation |
| Send DM reply | POST {{API_BASE_URL}}/v1/messages | platform, accountId, recipientId, text; x-access-key header | Send a reply and return messageId |
Captured contract; origin shown as {{API_BASE_URL}}. Connect endpoints are shown in source as curl without an explicit -X/method, so no method is asserted for them here.
| Field | Type in example | Present in source examples | Meaning |
|---|---|---|---|
| platform | string | Yes | Set to instagram in this workflow |
| accountId | string | Yes | Connected Instagram account id from the integrations response |
| limit | number | Yes | Maximum conversations to return per page in the example |
| after | string | No | Pass a previous nextCursor to fetch the next page |
| x-access-key | string header | Yes | API access key |
Captured contract; presence reflects source examples, not source-declared requiredness or validation.
| Field | Type in example | Meaning |
|---|---|---|
| success | boolean | Whether the request succeeded |
| selfId | string | Your own account id; compare participant and sender ids against it |
| selfUsername | string | Your own username |
| conversations | array | Conversation objects, newest activity first |
| conversations[].id | string | Conversation id; use it in GET /v1/messages/:conversationId |
| conversations[].participants | array | Participant objects with id, name, username, and profilePictureUrl |
| conversations[].lastMessage | object | Most recent message with id, text, from, and timestamp |
| conversations[].lastMessage.from | object | Sender with id and name |
| conversations[].updatedTime | string timestamp | Last activity time for sorting or filtering |
| nextCursor | string or null | Pass back as after for the next page; null means no further page in the example |
Captured contract
| Field | Type in example | Present in source examples | Meaning |
|---|---|---|---|
| conversationId | string path parameter | Yes | Conversation id from the list response |
| platform | string | Yes | Set to instagram in this workflow |
| accountId | string | Yes | Connected Instagram account id |
| limit | number | Yes | Maximum messages to return per page in the example |
| after | string | No | Pass a previous nextCursor to fetch older messages |
| x-access-key | string header | Yes | API access key |
Captured contract; presence reflects source examples, not source-declared requiredness or validation.
| Field | Type in example | Meaning |
|---|---|---|
| success | boolean | Whether the request succeeded |
| messages | array | Flat list of messages in the conversation |
| messages[].id | string | Message id |
| messages[].text | string | Message text |
| messages[].from | object | Sender with id and name; compare from.id against selfId |
| messages[].timestamp | string timestamp | When the message was sent |
| nextCursor | string or null | Pass back as after for older messages; null in the example |
Captured contract
| Field | Type in example | Present in source examples | Meaning |
|---|---|---|---|
| platform | string | Yes | Set to instagram in this workflow |
| accountId | string | Yes | Connected Instagram account id |
| recipientId | string | Yes | Participant id that is not selfId |
| text | string | Yes | Reply text to send |
| x-access-key | string header | Yes | API access key |
| Content-Type | string header | Yes | application/json in the example |
Captured contract; presence reflects source examples, not source-declared requiredness or validation.
| Field | Type in example | Meaning |
|---|---|---|
| success | boolean | Whether the send succeeded |
| messageId | string | Id of the newly sent message |
Captured contract
| Situation | Where it appears | Source-stated behavior | Operational check or guidance |
|---|---|---|---|
| Missing or incorrect x-access-key | Every endpoint | Source does not specify an error response | Confirm the header name and value from the Access Keys page; do not log the key |
| Personal Instagram account | Connect and DM calls | Personal accounts cannot manage DMs via API; this is a Meta limit | Use an Instagram Business account or a Creator account |
| Incorrect accountId | GET /v1/messages, GET /v1/messages/:conversationId, POST /v1/messages | Source does not specify an error response | Copy the id from the integrations response exactly |
| Incorrect recipientId | POST /v1/messages | Source does not specify an error response | Use the participant id that is not selfId |
| Send after the 24-hour window | POST /v1/messages | Send fails when the recipient's last message is more than 24 hours old | Reply while the conversation is warm; as guidance, do not retry a window rejection indefinitely as if transient |
| More results than limit | GET /v1/messages and GET /v1/messages/:conversationId | Response includes nextCursor for paging | Pass nextCursor back as after until nextCursor is null |
| Polling too frequently | Poll-read-reply workflow | Each DM call spends 1 credit per captured claim | Set a polling cadence that fits your credit budget |
Captured contract for source-stated behavior; guidance column is editorial and not a source-stated status/error contract. No runtime test evidence supplied.
-H "x-access-key: YOUR_API_KEY"curl {{API_BASE_URL}}/v1/connect/instagram \
-H "x-access-key: YOUR_API_KEY"curl {{API_BASE_URL}}/v1/connect/integrations \
-H "x-access-key: YOUR_API_KEY"curl "{{API_BASE_URL}}/v1/messages?platform=instagram&accountId=your-ig-id&limit=20" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"selfId": "17841400000000000",
"selfUsername": "yourbrand",
"conversations": [
{
"id": "aWdfZG1fdGhyZWFk",
"participants": [
{
"id": "17841400000000000",
"name": "Your Brand",
"username": "yourbrand",
"profilePictureUrl": "https://.../you.jpg"
},
{
"id": "9876543210",
"name": "Dana Lee",
"username": "danalee",
"profilePictureUrl": "https://.../dana.jpg"
}
],
"lastMessage": {
"id": "bWlkLmZvbw",
"text": "An example comment.",
"from": { "id": "9876543210", "name": "Dana Lee" },
"timestamp": "2026-08-06T14:22:10Z"
},
"updatedTime": "2026-08-06T14:22:10Z"
}
],
"nextCursor": "QVFIUmxk..."
}curl "{{API_BASE_URL}}/v1/messages/aWdfZG1fdGhyZWFk?platform=instagram&accountId=your-ig-id&limit=25" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"messages": [
{
"id": "bWlkLmZvbw",
"text": "An example comment.",
"from": { "id": "9876543210", "name": "Dana Lee" },
"timestamp": "2026-08-06T14:22:10Z"
},
{
"id": "bWlkLmJhcg",
"text": "An example comment.",
"from": { "id": "17841400000000000", "name": "Your Brand" },
"timestamp": "2026-08-06T14:19:02Z"
}
],
"nextCursor": null
}curl -X POST {{API_BASE_URL}}/v1/messages \
-H "x-access-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"platform": "instagram",
"accountId": "your-ig-id",
"recipientId": "9876543210",
"text": "An example comment."
}'{
"success": true,
"messageId": "bWlkLmJheg"
}