Conversations

List conversations

GET /v1/conversations

const { data, meta } = await kerabie.conversations.list({ status: 'WAITING', limit: 20 });

Query params

Param	Type	Description
`status`	`WAITING \| ACTIVE \| RESOLVED \| CLOSED`	Filter by status (`WAITING` is shown as New in the dashboard)
`channel`	`string`	Filter by channel, e.g. `WHATSAPP`
`assignedTo`	`number`	Filter by the user id of the assigned agent
`search`	`string`	Case-insensitive match on customer name, email, subject or message text (max 200 characters)
`page`	`number`	Page number (default 1)
`limit`	`number`	Results per page (default 20, maximum 100)

Response

{
  "data": [
    {
      "id": 101,
      "status": "ACTIVE",
      "channel": "WHATSAPP",
      "subject": null,
      "customer": { "id": 5, "name": "Chidi Okafor", "email": "chidi@palmex.com", "sessionId": "s_8f2c" },
      "assignedAgent": { "id": 7, "userId": 12, "user": { "fname": "Amara", "lname": "Osei", "email": "amara@kerabie.com", "avatar": null } },
      "lastMessage": "Please hurry.",
      "lastMessageAt": "2026-10-05T10:52:00.000Z",
      "tags": [{ "tag": "refund" }, { "tag": "vip" }],
      "aiHandling": false,
      "_count": { "messages": 1 },
      "createdAt": "2026-10-05T09:10:00.000Z",
      "updatedAt": "2026-10-05T10:52:00.000Z"
    }
  ],
  "meta": {
    "total": 43,
    "page": 1,
    "limit": 20,
    "pages": 3,
    "counts": { "all": 57, "WAITING": 4, "ACTIVE": 21, "RESOLVED": 12, "CLOSED": 20 }
  }
}

Field notes

tags holds the first three tags only; get a conversation returns all of them.
_count.messages is the number of unread messages.
aiHandling is true while the AI assistant is handling the conversation on its own: it is still open, the AI has replied, no human has, and it has not handed off.
meta.counts are organisation-wide totals per status and ignore the filters above, so they work as inbox tab counts.

Get a conversation

GET /v1/conversations/:id

const conversation = await kerabie.conversations.get(101);

Returns the conversation with its customer, assigned agent, all tags and the aiHandling flag. Responds 404 if the conversation does not exist in your organisation.

Previous conversations

GET /v1/conversations/:id/history

const { data } = await kerabie.conversations.getHistory(101, 5);

The same customer's other conversations in your organisation, newest first. limit defaults to 5 and is capped at 20. The conversation you ask about is never included. A conversation with no linked customer returns an empty list.

{
  "data": [
    {
      "id": 88,
      "status": "RESOLVED",
      "channel": "WHATSAPP",
      "subject": "Refund not received",
      "isTicket": false,
      "createdAt": "2026-09-28T09:00:00.000Z",
      "lastMessageAt": "2026-09-28T09:40:00.000Z",
      "handoffSummary": null
    }
  ]
}

Take over from the AI

POST /v1/conversations/:id/take-over

await kerabie.conversations.takeOver(101, { agentId: 7 });

Hands a conversation from the AI assistant to a person. It stops the AI from replying, sets the status to ACTIVE, and assigns the conversation to agentId if nobody holds it yet (an existing assignee is kept).

Body

Field	Type	Description
`agentId`	`number`	Required. The organisation team-member id to assign.

Errors

Status	When
`400`	`agentId` is missing or invalid, the team member is not in your organisation, or the AI is no longer handling the conversation (for example, someone already took over or it was resolved).
`404`	The conversation does not exist in your organisation.

Taking over is safe to race: only one caller succeeds, and the rest receive 400.

Resolve a conversation

POST /conversations/:id/resolve

Close a conversation

POST /conversations/:id/close

Assign to an agent

PATCH /conversations/:id

{ "agentId": 7 }

Send a message

POST /conversations/:id/messages

{
  "body": "Your order has shipped! Tracking: ABC123",
  "senderType": "bot"
}

senderType can be "agent" or "bot".

On this page