Conversations

Read Instagram and Messenger direct messages, check the 24 hour reply window, and reply or mark conversations done.

Method	Path	Scope
`GET`	`/conversations`	`inbox:read`
`GET`	`/conversations/{id}`	`inbox:read`
`POST`	`/conversations/{id}/reply`	`inbox:write`
`POST`	`/conversations/{id}/resolve`	`inbox:write`

Direct messages exist for Instagram and Facebook Pages (Messenger). Threads has no direct messages.

24 hour window, replies written by you

Meta only allows a reply within 24 hours of the customer's last message. After that reply fails with 422 reply_window_closed and nothing is sent. IMMA AI never writes or sends a reply on its own: your agent or a person writes the text. Never send promotional content outside the window.

List conversations

GET /conversations?status=&platform=&account_id=&limit=&cursor=

Query	Description
`status`	`open` or `done`
`platform`	`instagram` or `facebook_page`
`account_id`	One account
`limit`	1 to 100, default 20
`cursor`	From the previous page

{
  "data": [
    {
      "id": "conv_01J...",
      "platform": "instagram",
      "account_id": "acc_01J...",
      "participant_name": "Sari",
      "participant_handle": "sari.k",
      "last_message_preview": "How much for 2 kg?",
      "last_message_at": "2026-10-04T08:12:40.000Z",
      "unread_count": 1,
      "status": "open",
      "can_reply": true,
      "hours_remaining": 23
    }
  ],
  "cursor": { "next": "2026-10-04T08:12:40.000Z|conv_01J...", "has_more": false }
}

Most recent first. can_reply is false once the window has closed, and hours_remaining is then 0.

Get a conversation

GET /conversations/{id} returns the conversation and its last 50 messages, oldest first. Like in the dashboard, opening a conversation marks it as read, so unread_count is 0 in the response.

{
  "conversation": {
    "id": "conv_01J...",
    "platform": "instagram",
    "account_id": "acc_01J...",
    "participant_name": "Sari",
    "participant_handle": "sari.k",
    "last_message_preview": "How much for 2 kg?",
    "last_message_at": "2026-10-04T08:12:40.000Z",
    "unread_count": 0,
    "status": "open",
    "can_reply": true,
    "hours_remaining": 23
  },
  "messages": [
    { "id": "msg_01J...", "direction": "in", "text": "How much for 2 kg?", "sent_at": "2026-10-04T08:12:40.000Z" }
  ]
}

direction is in for the customer and out for your business. Over MCP, text and names written by the customer are wrapped in <untrusted_user_content> tags.

Reply

POST /conversations/{id}/reply with { "text": "..." }, 1 to 1000 characters.

curl -X POST https://api.getimma.com/v1/conversations/conv_01J.../reply \
  -H "Authorization: Bearer imma_live_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2d8e1f40-3a5c-4b97-8e16-7c0d9a1b2e34" \
  -d '{ "text": "2 kg is Rp 340,000. Want me to reserve one?" }'

{ "ok": true, "reply_id": "aWdfZG06MTc4NDEz..." }

reply_id is the id the platform gave the message, or null. A successful reply also marks the conversation done. Reopen it with resolve if you want to keep it in the open list.

Mark done or reopen

POST /conversations/{id}/resolve with { "status": "done" } (the default) or { "status": "open" }.

{ "ok": true, "status": "done" }

Webhook

Subscribe to message.received to be told when a customer writes. See Webhooks.

Errors

Status	Code	Cause
404	`not_found`	Unknown conversation
422	`reply_window_closed`	More than 24 hours since the customer's last message. `hours_remaining` is `0`
422	`reconnect_required`	The account must be reconnected
502	`platform_unavailable`	The platform did not answer