Guides

Inbox and approvals

List conversations, read messages, and approve or edit the drafts the AI holds for a person.

The inbox endpoints let you build an agent screen: list conversations, read their messages, and approve the replies the AI drafted. Approving is how a draft leaves the system while a channel is in review mode, which is the default for every new channel.

Conversations

curl "https://api.getengageai.app/conversations?limit=25" -H "Authorization: Bearer $ENGAGE_API_KEY"

{
  "items": [
    {
      "id": "c2d1…",
      "contactName": "Jamie Chen",
      "status": "OPEN",
      "lastMessageAt": "2026-10-16T22:40:12.000Z",
      "lastMessagePreview": "do the trailhead boots come in a UK 11?",
      "unreadCount": 1,
      "providerKey": "whatsapp_cloud"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Filter with status and assigneeId. Paginate with cursor as described in conventions.

`status`	Meaning
`OPEN`	Active. The AI handles it according to the channel's reply mode. Conversations with a draft waiting for approval are usually here.
`AWAITING_HUMAN`	The agent worklist. The AI escalated, or a person took over. Automation is paused.
`RESOLVED` / `CLOSED`	Finished. A new message from the customer reopens it.
`PENDING`, `SNOOZED`, `SPAM`	Reserved for agent workflows.

To fetch the worklist:

curl "https://api.getengageai.app/conversations?status=AWAITING_HUMAN" -H "Authorization: Bearer $ENGAGE_API_KEY"

One customer is one contact across platforms, so someone who wrote on WhatsApp last week and Telegram today keeps the same history.

Messages

curl https://api.getengageai.app/conversations/$CONVERSATION_ID/messages -H "Authorization: Bearer $ENGAGE_API_KEY"

{
  "items": [
    {
      "id": "m-001",
      "conversationId": "c2d1…",
      "direction": "INBOUND",
      "senderType": "CONTACT",
      "text": "do the trailhead boots come in a UK 11?",
      "contentType": "TEXT",
      "status": "RECEIVED",
      "createdAt": "2026-10-16T22:40:12.000Z"
    },
    {
      "id": "m-002",
      "conversationId": "c2d1…",
      "direction": "OUTBOUND",
      "senderType": "AI",
      "text": "Yes, the Trailhead Mid GTX goes up to a UK 13, so an 11 is in the range.",
      "contentType": "TEXT",
      "status": "DRAFT",
      "createdAt": "2026-10-16T22:40:15.000Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Field	Values
`direction`	`INBOUND` from the customer, `OUTBOUND` to them.
`senderType`	`CONTACT`, `AI`, `HUMAN_AGENT` or `SYSTEM`.
`status`	Inbound: `RECEIVED`. Outbound: `DRAFT` → `QUEUED` → `SENDING` → `SENT` → `DELIVERED` → `READ`, or `FAILED` / `DEAD_LETTERED`.

DELIVERED and READ only appear on platforms that report them, such as WhatsApp. DEAD_LETTERED means delivery was retried and gave up; the reason is recorded.

Approve a draft

A message with status: "DRAFT" is a reply the AI wrote and is holding for a person. Approve it to send it:

curl -X POST https://api.getengageai.app/conversations/messages/$MESSAGE_ID/approve \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{ "status": "queued" }

To change the wording first, send it as editedText:

curl -X POST https://api.getengageai.app/conversations/messages/$MESSAGE_ID/approve \
  -H "Authorization: Bearer $ENGAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "editedText": "Yes, the Trailhead Mid GTX comes in UK 4 to 13, so an 11 is available." }'

An approved draft goes through the same delivery pipeline as an automatic reply: the same rate limits, retries and records.
The edit is stored next to the AI's original. The difference between what the AI wrote and what a person sent is the best signal for improving replies.
editedText can be up to 8,000 characters, but the platform's own limit still applies (4,096 on WhatsApp).
WhatsApp's 24-hour window still applies. A draft approved more than 24 hours after the customer's last message cannot be sent as free text.

Building an agent screen

Worklist: GET /conversations?status=AWAITING_HUMAN, newest first.
Drafts to review: conversations with outbound messages in DRAFT. Show each draft next to the customer's message, with an edit box.
Approve: POST /conversations/messages/{id}/approve, with editedText if it was changed.
Watch delivery: re-read the messages and show SENT, DELIVERED or FAILED.

Find a customer with GET /search?types=CONTACT.