Conversations | Developer API | Sarufi

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

Parameters

limitintegeroptionaldefault: 50

Page size. Min 1, max 100.

cursorstringoptional

Pagination cursor from a previous response.

bash

curl -X GET "https://beta-api.sarufi.io/api/dev/v1/chatbots/<chatbot-id>/conversations?limit=25" \
  -H "Authorization: Bearer <your-api-key>"

Response — 200 OK

json

{
  "items": [
    {
      "id": "01JPQ...",
      "chatbot_id": "01JMXYZ...",
      "user_id": "+255712345678",
      "channel": "whatsapp",
      "started_at": "2026-02-18T14:22:00Z",
      "last_message_at": "2026-02-18T14:35:00Z",
      "message_count": 8,
      "status": "active"
    }
  ],
  "next_cursor": "eyJpZCI6IjAxSlBRIn0=",
  "total": 1240
}

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_id": "+255712345678",
  "channel": "whatsapp",
  "current_state": "awaiting_order",
  "session_data": {
    "user_name": "John",
    "order_id": null
  },
  "started_at": "2026-02-18T14:22:00Z",
  "last_message_at": "2026-02-18T14:35:00Z",
  "message_count": 8,
  "status": "active"
}

Get Conversation Messages

Returns all messages exchanged in a specific conversation, ordered chronologically.

http

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

bash

curl -X GET https://beta-api.sarufi.io/api/dev/v1/chatbots/<chatbot-id>/conversations/<conversation-id>/messages \
  -H "Authorization: Bearer <your-api-key>"

Response — 200 OK

json

{
  "items": [
    {
      "id": "01JRS...",
      "conversation_id": "01JPQ...",
      "role": "user",
      "content": "Hello, I need help with my order",
      "type": "text",
      "timestamp": "2026-02-18T14:22:05Z"
    },
    {
      "id": "01JRT...",
      "conversation_id": "01JPQ...",
      "role": "bot",
      "content": "Hi! I'd be happy to help. What's your order number?",
      "type": "text",
      "timestamp": "2026-02-18T14:22:06Z"
    }
  ],
  "total": 8
}

Conversation Object

ConversationRecord fields

idstring

Conversation ULID.

chatbot_idstring

Parent chatbot ID.

user_idstring

User identifier (e.g. phone number for WhatsApp).

channelstring

Integration channel: whatsapp, web, rest-api, sms.

current_statestring

Name of the current flow state the user is in.

session_dataobject

Key-value session variables collected during the conversation.

started_atstring

When the conversation began.

last_message_atstring

Timestamp of the most recent message.

message_countinteger

Total number of messages exchanged.

statusstring

active or completed.

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.