Conversations

List Conversations

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

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

Filter Parameters

Parameter	Type	Description
status	string	Filter by conversation status. One of: ACTIVE, CLOSED, ARCHIVED, HANDOFF_PENDING, AGENT_ACTIVE.
channel	string	Filter by channel (e.g. whatsapp, web, sms, api).
start_time	string	Filter conversations created at or after this time (ISO 8601, e.g. 2026-01-01T00:00:00Z).
end_time	string	Filter conversations created at or before this time (ISO 8601).

Pagination Parameters

Parameter	Type	Default	Description
limit	integer	50	Page size. Min 1, max 67.
cursor	string	-	Pagination cursor from a previous response.

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

Response - 200 OK

{
  "count": 1,
  "conversations": [
    {
      "id": "01JPQ...",
      "chatbot_id": "01JMXYZ...",
      "user_phone": "+255712345678",
      "contact_name": "Lorem Ipsum",
      "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.

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

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

Response - 200 OK - returns a single ConversationRecord (same shape as the list items above).

---

Get Conversation Messages

Returns messages for a conversation, ordered oldest first.

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

Pagination Parameters

Parameter	Type	Default	Description
limit	integer	50	Page size. Min 1, max 67.
cursor	string	-	Pagination cursor from a previous response.

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

Response - 200 OK

The wrapper carries count, total, page, limit, pages, next_cursor and messages. Each entry in messages is one stored turn. The response.messages array holds the same shapes as the Chat API send-message response.

{
  "count": 1,
  "total": 1,
  "page": 1,
  "limit": 25,
  "pages": 1,
  "next_cursor": null,
  "messages": [
    {
      "id": "01K5M2Q8Z7C3V9R1T4Y6W0B2NF",
      "conversation_id": "01K5M2Q8Z7C3V9R1T4Y6W0B2NE",
      "message": { "text": "hi" },
      "response": {
        "messages": [
          { "type": "TEXT", "text": "Lorem ipsum dolor sit amet, welcome!" },
          {
            "type": "BUTTONS",
            "text": "Choose an option.",
            "buttons": [
              { "id": "view_products", "title": "Products" },
              { "id": "support_menu", "title": "Support" }
            ]
          }
        ]
      },
      "message_type": "text",
      "responder": "BOT",
      "received_at": "2026-09-22T10:40:01+00:00",
      "responded_at": "2026-09-22T10:40:02+00:00",
      "status": "delivered",
      "created_at": "2026-09-22T10:40:01+00:00",
      "media": null
    }
  ]
}

---

Conversation Object

Field	Type	Description
id	string	Conversation ULID.
chatbot_id	string	Parent chatbot ID.
user_phone	string	User phone number (e.g. +255712345678 for WhatsApp).
contact_name	string | null	Contact display name, if available.
channel	string	Integration channel: whatsapp, web, sms, api.
status	string	Conversation status: ACTIVE, CLOSED, ARCHIVED, HANDOFF_PENDING, AGENT_ACTIVE.
last_message_id	string | null	ID of the last message in the conversation.
last_message_at	string	Timestamp of the most recent message.
last_message_preview	string | null	Preview text of the last message.
unread_count	integer	Number of unread messages.
created_at	string	When the conversation was created.
updated_at	string | null	When the conversation was last updated.

---

Message Object

Field	Type	Description
id	string	ULID of the turn.
conversation_id	string	Parent conversation ID.
message	object | null	What the user sent.
response	object | null	What the bot replied. Its messages array holds the same shapes as the Chat API send-message response.
message_type	string	Type of the user's message.
responder	string	Who responded: BOT or HUMAN.
received_at	string	ISO 8601. When the user message was received.
responded_at	string | null	ISO 8601. When the response was sent.
status	string	Message status. Includes the WhatsApp delivery tick once one arrives.
created_at	string	ISO 8601. When the record was created.
media	object | null	Media the user sent: type, url, mime_type, caption, filename, transcript. Never describes bot messages.

Older history rows

Rows recorded before 2026-09-22 may contain combined bot messages. See History of combined messages for how they are returned.

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.