An Instagram DM API for answering customers

Conversations and messages

GET /v1/accounts/{id}/conversations lists the account’s conversations with the other person, the last message and the unread count. GET /v1/accounts/{id}/conversations/{conversation_id}/messages returns a conversation’s messages, newest first, each marked incoming or outgoing. Both pages with next_cursor.

Attachment URLs from Instagram are signed and expire, so use them right away rather than storing them.

Send a reply

POST /v1/accounts/{id}/conversations/{conversation_id}/messages with text (up to 1,000 characters), an attachment_url pointing at a public file, or both. Add an Idempotency-Key header so a retry never sends the same message twice.

curl https://api.postpeg.com/v1/accounts/acc_mfz20b5n1s8f4j7xv2p9r6hu1c/conversations/aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6MTc4/messages \
  -H "Authorization: Bearer $POSTPEG_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-sunday-hours" \
  -d '{
    "text": "We are! 9 to 3 on Sundays."
  }'

{
  "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZB",
  "conversation_id": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6MTc4"
}

The 24-hour window

Instagram lets a business reply only within 24 hours of the person’s last message. Outside that window Instagram refuses, and postpeg passes its reason back:

{
  "type": "https://postpeg.com/errors/upstream_error",
  "title": "Upstream error",
  "status": 502,
  "detail": "The platform refused the request: …",
  "code": "upstream_error",
  "request_id": "8f14e45f-ceea-467a-9575-1f2a5c3e6b0d"
}

Show the time since the last incoming message in your inbox, and your users will know which conversations they can still answer.

Building a DM inbox

List conversations and sort them by updated_at, with unread_count as the badge. Opening one fetches its messages; show incoming ones on one side and outgoing on the other. When your user answers, send it with an Idempotency-Key made from the message they’re answering, so a double click or a retried request never sends it twice. Keep the time of the person’s last incoming message next to the reply box: once it’s more than 24 hours old, Instagram won’t accept a reply, and your user should know before they type one.

Replies only

Messages are for answering people who wrote to the account first. Cold outreach and bulk messages aren’t allowed, by Instagram or by postpeg’s acceptable use policy. Direct messages are available on Instagram today; the messages docs cover every field.