Skip to content
engage-ai

API reference

Inbox

Conversations, messages, and approving AI drafts

For concepts and a walkthrough, read Inbox and approvals.

List conversations

GET/conversations

Filter on status=AWAITING_HUMAN for the agent worklist: threads the AI escalated or where a draft is waiting for approval.

Auth
Session token or API key

Query parameters

  • statusenum

    AWAITING_HUMAN is the agent worklist: the AI escalated or held a draft.

    One of OPEN, PENDING, AWAITING_HUMAN, SNOOZED, RESOLVED, CLOSED, SPAM

  • assigneeIdstring (uuid)
  • cursorstring
  • limitinteger

    Max 100

Response fields 200
  • itemsConversationSummary[]required
  • nextCursorstring | nullrequired

    Opaque. Pass back verbatim as cursor. Null means the end.

  • hasMorebooleanrequired

ConversationSummary

  • idstring (uuid)required
  • contactNamestring | nullrequired
  • statusstringrequired
  • lastMessageAtstring (date-time) | nullrequired
  • lastMessagePreviewstring | nullrequired
  • unreadCountintegerrequired

    Min -9007199254740991

  • providerKeystringrequired

    Which platform this thread is on.

Responses

  • 200A page of conversations, most recent first.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
curl "https://api.getengageai.app/conversations" \
  -H "Authorization: Bearer $ENGAGE_API_KEY"
Response · 200
{
  "items": [
    {
      "id": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
      "contactName": "Jamie Chen",
      "status": "string",
      "lastMessageAt": "2026-10-16T09:30:00.000Z",
      "lastMessagePreview": "do the trailhead boots come in a UK 11?",
      "unreadCount": 0,
      "providerKey": "telegram_bot"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

List messages in a conversation

GET/conversations/{id}/messages

Includes AI drafts awaiting approval, which carry status DRAFT.

Auth
Session token or API key

Path parameters

  • idstring (uuid)required

Query parameters

  • cursorstring
  • limitinteger

    Max 100

Response fields 200
  • itemsMessage[]required
  • nextCursorstring | nullrequired

    Opaque. Pass back verbatim as cursor. Null means the end.

  • hasMorebooleanrequired

Message

  • idstring (uuid)required
  • conversationIdstring (uuid)required
  • directionenumrequired

    One of INBOUND, OUTBOUND

  • senderTypeenumrequired

    AI plus status DRAFT is a reply waiting for approval.

    One of CONTACT, AI, HUMAN_AGENT, SYSTEM

  • textstring | nullrequired
  • contentTypestringrequired
  • contentobjectrequired

    Normalised, platform-neutral content.

  • statusenumrequired

    One of PENDING, DRAFT, QUEUED, SENDING, SENT, DELIVERED, READ, FAILED, DEAD_LETTERED, RECEIVED

  • externalMessageIdstring | nullrequired
  • createdAtstring (date-time)required

Responses

  • 200A page of messages, most recent first.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
curl "https://api.getengageai.app/conversations/$ID/messages" \
  -H "Authorization: Bearer $ENGAGE_API_KEY"
Response · 200
{
  "items": [
    {
      "id": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
      "conversationId": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
      "direction": "INBOUND",
      "senderType": "CONTACT",
      "text": "Yes — the Trailhead Mid GTX goes up to a UK 13, so an 11 is in the range.",
      "contentType": "string",
      "content": {},
      "status": "PENDING",
      "externalMessageId": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e6f4a91",
      "createdAt": "2026-10-16T09:30:00.000Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

Approve an AI draft and release it for delivery

POST/conversations/messages/{messageId}/approve

Releases a held draft into the same delivery pipeline an auto-sent reply uses, so there is exactly one send path regardless of who authorised it. An edit is recorded against the generation that produced the draft.

Auth
Session token or API key
Body
application/json

Path parameters

  • messageIdstring (uuid)required

Request body

  • editedTextstring

    Supply when the agent changed the draft before approving. The edit is recorded against the generation that produced it — the delta between what the model wrote and what a human was willing to send is the best evaluation signal the product has.

    Max 8000 characters

Response fields 201
  • status"queued"required

Responses

  • 201Queued for delivery.
  • 401Missing, malformed, revoked or expired API key.
  • 404Not found, or not visible to this organization.
  • 422Request failed validation.
  • 429Rate limited.
  • 500Unexpected error. The correlationId ties it to our logs.
Request
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."
  }'
Response · 201
{
  "status": "queued"
}