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).

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 "https://beta-api.sarufi.io/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 https://beta-api.sarufi.io/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 "https://beta-api.sarufi.io/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.
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.

Conversations are read-only

The API does not support sending messages to users directly. Conversations are created automatically when users interact through an active integration channel.

PreviousFlowsNextIntegrations