Skip to content

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.

Instagram DMs API endpoint overview
EndpointMethod and path as shown in sourceInputs present in source examplesPurpose
Connect Instagramcurl {{API_BASE_URL}}/v1/connect/instagram (method not explicitly stated in source)x-access-key headerReturn an authorization URL for the instagram_business_manage_messages scope
List integrationscurl {{API_BASE_URL}}/v1/connect/integrations (method not explicitly stated in source)x-access-key headerReturn connected accounts; use each id as accountId
List conversationsGET {{API_BASE_URL}}/v1/messagesplatform=instagram, accountId, limit; x-access-key headerList conversations newest activity first
Read conversationGET {{API_BASE_URL}}/v1/messages/:conversationIdplatform=instagram, accountId, limit; x-access-key headerReturn messages in one conversation
Send DM replyPOST {{API_BASE_URL}}/v1/messagesplatform, accountId, recipientId, text; x-access-key headerSend 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.

List conversations input contract
FieldType in examplePresent in source examplesMeaning
platformstringYesSet to instagram in this workflow
accountIdstringYesConnected Instagram account id from the integrations response
limitnumberYesMaximum conversations to return per page in the example
afterstringNoPass a previous nextCursor to fetch the next page
x-access-keystring headerYesAPI access key

Captured contract; presence reflects source examples, not source-declared requiredness or validation.

List conversations response field map
FieldType in exampleMeaning
successbooleanWhether the request succeeded
selfIdstringYour own account id; compare participant and sender ids against it
selfUsernamestringYour own username
conversationsarrayConversation objects, newest activity first
conversations[].idstringConversation id; use it in GET /v1/messages/:conversationId
conversations[].participantsarrayParticipant objects with id, name, username, and profilePictureUrl
conversations[].lastMessageobjectMost recent message with id, text, from, and timestamp
conversations[].lastMessage.fromobjectSender with id and name
conversations[].updatedTimestring timestampLast activity time for sorting or filtering
nextCursorstring or nullPass back as after for the next page; null means no further page in the example

Captured contract

Read conversation input contract
FieldType in examplePresent in source examplesMeaning
conversationIdstring path parameterYesConversation id from the list response
platformstringYesSet to instagram in this workflow
accountIdstringYesConnected Instagram account id
limitnumberYesMaximum messages to return per page in the example
afterstringNoPass a previous nextCursor to fetch older messages
x-access-keystring headerYesAPI access key

Captured contract; presence reflects source examples, not source-declared requiredness or validation.

Read conversation response field map
FieldType in exampleMeaning
successbooleanWhether the request succeeded
messagesarrayFlat list of messages in the conversation
messages[].idstringMessage id
messages[].textstringMessage text
messages[].fromobjectSender with id and name; compare from.id against selfId
messages[].timestampstring timestampWhen the message was sent
nextCursorstring or nullPass back as after for older messages; null in the example

Captured contract

Send DM reply input contract
FieldType in examplePresent in source examplesMeaning
platformstringYesSet to instagram in this workflow
accountIdstringYesConnected Instagram account id
recipientIdstringYesParticipant id that is not selfId
textstringYesReply text to send
x-access-keystring headerYesAPI access key
Content-Typestring headerYesapplication/json in the example

Captured contract; presence reflects source examples, not source-declared requiredness or validation.

Send DM reply response field map
FieldType in exampleMeaning
successbooleanWhether the send succeeded
messageIdstringId of the newly sent message

Captured contract

Failure and check matrix for Instagram DM calls
SituationWhere it appearsSource-stated behaviorOperational check or guidance
Missing or incorrect x-access-keyEvery endpointSource does not specify an error responseConfirm the header name and value from the Access Keys page; do not log the key
Personal Instagram accountConnect and DM callsPersonal accounts cannot manage DMs via API; this is a Meta limitUse an Instagram Business account or a Creator account
Incorrect accountIdGET /v1/messages, GET /v1/messages/:conversationId, POST /v1/messagesSource does not specify an error responseCopy the id from the integrations response exactly
Incorrect recipientIdPOST /v1/messagesSource does not specify an error responseUse the participant id that is not selfId
Send after the 24-hour windowPOST /v1/messagesSend fails when the recipient's last message is more than 24 hours oldReply while the conversation is warm; as guidance, do not retry a window rejection indefinitely as if transient
More results than limitGET /v1/messages and GET /v1/messages/:conversationIdResponse includes nextCursor for pagingPass nextCursor back as after until nextCursor is null
Polling too frequentlyPoll-read-reply workflowEach DM call spends 1 credit per captured claimSet 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.

API key header
-H "x-access-key: YOUR_API_KEY"
Get Instagram authorization URL
curl {{API_BASE_URL}}/v1/connect/instagram \
  -H "x-access-key: YOUR_API_KEY"
List connected integrations to retrieve accountId
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
List Instagram DM conversations
curl "{{API_BASE_URL}}/v1/messages?platform=instagram&accountId=your-ig-id&limit=20" \
  -H "x-access-key: YOUR_API_KEY"
List conversations response example
{
	"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..."
}
Read a conversation
curl "{{API_BASE_URL}}/v1/messages/aWdfZG1fdGhyZWFk?platform=instagram&accountId=your-ig-id&limit=25" \
  -H "x-access-key: YOUR_API_KEY"
Read conversation response example
{
	"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
}
Send a DM reply
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."
  }'
Send DM reply response example
{
	"success": true,
	"messageId": "bWlkLmJheg"
}