Navigation
Resources HubUser Documentation

Resources

Conversations

List and inspect conversations and messages for a chatbot.

List Conversations

Returns a paginated list of all conversations for a given chatbot.

http
GET /api/dev/v1/chatbots/{chatbot_id}/conversations
Authorization: Bearer <api-key>

Query Parameters

Filters

statusstringoptional

Filter by conversation status. One of: ACTIVE, CLOSED, ARCHIVED, HANDOFF_PENDING, AGENT_ACTIVE.

channelstringoptional

Filter by channel (e.g. whatsapp, web, sms, api).

start_timestringoptional

Filter conversations created at or after this time (ISO 8601, e.g. 2026-01-01T00:00:00Z).

end_timestringoptional

Filter conversations created at or before this time (ISO 8601).

Pagination

limitintegeroptionaldefault: 50

Page size. Min 1, max 67.

cursorstringoptional

Pagination cursor from a previous response.

bash
curl -X GET "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/conversations?status=ACTIVE&channel=whatsapp&limit=25" \
  -H "Authorization: Bearer <your-api-key>"

Response - 200 OK

json
{
  "count": 1,
  "conversations": [
    {
      "id": "01JPQ...",
      "chatbot_id": "01JMXYZ...",
      "user_phone": "+255712345678",
      "contact_name": "John",
      "channel": "whatsapp",
      "status": "ACTIVE",
      "last_message_id": "01JRS...",
      "last_message_at": "2026-02-18T14:35:00Z",
      "last_message_preview": "Thanks for your help!",
      "unread_count": 2,
      "created_at": "2026-02-18T14:22:00Z",
      "updated_at": "2026-02-18T14:35:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6IjAxSlBRIn0="
}

Get Conversation

Retrieves a single conversation by ID.

http
GET /api/dev/v1/chatbots/{chatbot_id}/conversations/{conversation_id}
Authorization: Bearer <api-key>
bash
curl -X GET http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/conversations/<conversation-id> \
  -H "Authorization: Bearer <your-api-key>"

Response - 200 OK

json
{
  "id": "01JPQ...",
  "chatbot_id": "01JMXYZ...",
  "user_phone": "+255712345678",
  "contact_name": "John",
  "channel": "whatsapp",
  "status": "ACTIVE",
  "last_message_id": "01JRS...",
  "last_message_at": "2026-02-18T14:35:00Z",
  "last_message_preview": "Thanks for your help!",
  "unread_count": 2,
  "created_at": "2026-02-18T14:22:00Z",
  "updated_at": "2026-02-18T14:35:00Z"
}

Get Conversation Messages

Returns messages for a conversation, ordered oldest first.

http
GET /api/dev/v1/chatbots/{chatbot_id}/conversations/{conversation_id}/messages
Authorization: Bearer <api-key>

Query Parameters

Pagination

limitintegeroptionaldefault: 50

Page size. Min 1, max 67.

cursorstringoptional

Pagination cursor from a previous response.

bash
curl -X GET "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/conversations/<conversation-id>/messages?limit=25" \
  -H "Authorization: Bearer <your-api-key>"

Response - 200 OK

json
{
  "count": 2,
  "messages": [
    {
      "id": "01JRS...",
      "conversation_id": "01JPQ...",
      "message": { "text": "Hello, I need help with my order" },
      "response": { "text": "Hi! I'd be happy to help. What's your order number?" },
      "message_type": "text",
      "responder": "BOT",
      "received_at": "2026-02-18T14:22:05Z",
      "responded_at": "2026-02-18T14:22:06Z",
      "status": "delivered",
      "created_at": "2026-02-18T14:22:05Z"
    }
  ],
  "next_cursor": null
}

Conversation Object

ConversationRecord fields

idstring
Conversation ULID.
chatbot_idstring
Parent chatbot ID.
user_phonestring
User phone number (e.g. +255712345678 for WhatsApp).
contact_namestring | null
Contact display name, if available.
channelstring
Integration channel: whatsapp, web, sms, api.
statusstring
Conversation status: ACTIVE, CLOSED, ARCHIVED, HANDOFF_PENDING, AGENT_ACTIVE.
last_message_idstring | null
ID of the last message in the conversation.
last_message_atstring
Timestamp of the most recent message.
last_message_previewstring | null
Preview text of the last message.
unread_countinteger
Number of unread messages.
created_atstring
When the conversation was created.
updated_atstring | null
When the conversation was last updated.

Message Object

MessageRecord fields

idstring
Message ULID.
conversation_idstring
Parent conversation ID.
messageobject | null
User input payload.
responseobject | null
System response payload.
message_typestring
Message type (e.g. text, image, document).
responderstring
Who responded: BOT or HUMAN.
received_atstring
When the user message was received.
responded_atstring | null
When the response was sent.
statusstring
Message delivery status.
created_atstring
When the record was created.

Want to chat with your bot via API?

Use the Chat API to create sessions and send messages programmatically. Conversations created via the Chat API appear here with channel=api.

PreviousFlowsNextChat