API reference: Conversations

Conversations. Every chat, on every channel.

List and read conversations from all channels (website, WhatsApp, Instagram and the API) with their messages.

Sanne de Vries web
Can I change my delivery address?
human
Visitor 4821 api
Do you ship to Belgium?
ai
Tom Jansen whatsapp
Thanks, that's all.
resolved

By , AI EngineerUpdated

List conversations

GET/chatbots/{chatbotId}/conversations

The chatbot's conversations, most recent activity first.

Permission: conversations:read

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

Query parameters

limit
integer

Items per page, 1 to 100. Default 20.

cursor
string

meta.pagination.nextCursor from the previous page.

channel
string

Only this channel: web, api, whatsapp or instagram.

Request
curl https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/conversations?channel=api \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN"

Response 200 OK

{
  "ok": true,
  "data": {
    "conversations": [
      {
        "threadId": "3f0c9a52-6d1e-4b0a-9c51-0f3e2c7d8a14",
        "chatbotId": "f45268b2-1980-470d-865d-5048a89aedce",
        "channel": "api",
        "mode": "ai",
        "escalated": false,
        "resolved": false,
        "startedAt": "2026-10-07T09:30:00+00:00",
        "lastMessageAt": "2026-10-07T09:31:40+00:00",
        "ticketCode": null,
        "ticketNumber": null,
        "priority": null,
        "tags": [],
        "assignee": null,
        "messageCount": 4
      }
    ]
  },
  "meta": {
    "requestId": "req_…",
    "pagination": { "limit": 20, "hasMore": true, "nextCursor": "MjAyNi0xMC0wN1Qw…" }
  }
}

Response fields

data.conversations[].threadId
string

The conversation's ID.

data.conversations[].chatbotId
string

The chatbot it belongs to.

data.conversations[].channel
string

Where it happens: web, api, whatsapp or instagram.

data.conversations[].mode
string

Who answers: ai (the chatbot) or human (your team).

data.conversations[].escalated
boolean

True while a handover to your team is open.

data.conversations[].resolved
boolean

True once it was marked resolved.

data.conversations[].startedAt
string (date-time)

When it started.

data.conversations[].lastMessageAt
string (date-time)

When the last message was sent.

data.conversations[].ticketCode
string | null

The ticket's code, such as SB-7K4Q9M: what to show your team and the visitor, and what they quote. Random and unique across all accounts. null until the conversation is a ticket.

data.conversations[].ticketNumber
integer | null

The ticket's number in your account, in the order tickets opened. Use it to sort; show ticketCode instead. null until the conversation is a ticket.

data.conversations[].priority
string | null

low, normal, high or urgent, as set by your team. null when not set.

data.conversations[].tags
string[]

The conversation's tags.

data.conversations[].assignee
object | null

The teammate it is assigned to: id and name. null when unassigned.

data.conversations[].messageCount
integer

Number of messages.

meta.pagination
object

limit, hasMore (true when there is another page) and nextCursor (null on the last page).

Errors

StatusCodeWhen
404not_foundNo such chatbot, or this token may not see it.
400validation_errorlimit or cursor is not valid.

Get a conversation with its messages

GET/chatbots/{chatbotId}/conversations/{threadId}

One conversation with all its messages, oldest first. For long conversations, page through them with the next endpoint.

Permission: conversations:read

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

threadId
string (uuid)required

The conversation, from conversation.threadId.

Request
curl https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/conversations/THREAD_ID \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN"

Response 200 OK

{
  "ok": true,
  "data": {
    "conversation": {
      "threadId": "3f0c9a52-6d1e-4b0a-9c51-0f3e2c7d8a14",
      "channel": "api",
      "mode": "ai",
      …,
      "messageCount": 2,
      "messages": [
        { "id": "…", "role": "user", "text": "Do you ship to Belgium?", "createdAt": "2026-10-07T09:30:00+00:00" },
        { "id": "…", "role": "assistant", "text": "Yes. Next-day to Belgium, free over €50.", "createdAt": "2026-10-07T09:30:04+00:00" }
      ]
    }
  },
  "meta": { "requestId": "req_7c1e4b2a9f0d4e6c8b3a5d7f9e1c2b4a" }
}

Response fields

data.conversation.threadId
string

The conversation's ID.

data.conversation.chatbotId
string

The chatbot it belongs to.

data.conversation.channel
string

Where it happens: web, api, whatsapp or instagram.

data.conversation.mode
string

Who answers: ai (the chatbot) or human (your team).

data.conversation.escalated
boolean

True while a handover to your team is open.

data.conversation.resolved
boolean

True once it was marked resolved.

data.conversation.startedAt
string (date-time)

When it started.

data.conversation.lastMessageAt
string (date-time)

When the last message was sent.

data.conversation.ticketCode
string | null

The ticket's code, such as SB-7K4Q9M: what to show your team and the visitor, and what they quote. Random and unique across all accounts. null until the conversation is a ticket.

data.conversation.ticketNumber
integer | null

The ticket's number in your account, in the order tickets opened. Use it to sort; show ticketCode instead. null until the conversation is a ticket.

data.conversation.priority
string | null

low, normal, high or urgent, as set by your team. null when not set.

data.conversation.tags
string[]

The conversation's tags.

data.conversation.assignee
object | null

The teammate it is assigned to: id and name. null when unassigned.

data.conversation.messageCount
integer

Number of messages.

data.conversation.messages[].id
string

The message's ID.

data.conversation.messages[].role
string

user (the visitor), assistant (the chatbot) or agent (a person on your team).

data.conversation.messages[].text
string

The message text.

data.conversation.messages[].createdAt
string (date-time)

When it was sent.

Errors

StatusCodeWhen
404not_foundNo such chatbot or conversation, or this token may not see it.

List a conversation's messages

GET/chatbots/{chatbotId}/conversations/{threadId}/messages

The conversation's messages, newest first, a page at a time.

Permission: conversations:read

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

threadId
string (uuid)required

The conversation, from conversation.threadId.

Query parameters

limit
integer

Items per page, 1 to 100. Default 20.

cursor
string

meta.pagination.nextCursor from the previous page.

Request
curl https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/conversations/THREAD_ID/messages?limit=50 \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN"

Response 200 OK

{
  "ok": true,
  "data": {
    "messages": [
      { "id": "…", "role": "assistant", "text": "Yes. Next-day to Belgium, free over €50.", "createdAt": "2026-10-07T09:30:04+00:00" },
      { "id": "…", "role": "user", "text": "Do you ship to Belgium?", "createdAt": "2026-10-07T09:30:00+00:00" }
    ]
  },
  "meta": { "requestId": "req_…", "pagination": { "limit": 50, "hasMore": false, "nextCursor": null } }
}

Response fields

data.messages[].id
string

The message's ID.

data.messages[].role
string

user (the visitor), assistant (the chatbot) or agent (a person on your team).

data.messages[].text
string

The message text.

data.messages[].createdAt
string (date-time)

When it was sent.

meta.pagination
object

limit, hasMore (true when there is another page) and nextCursor (null on the last page).

Errors

StatusCodeWhen
404not_foundNo such chatbot or conversation, or this token may not see it.
400validation_errorlimit or cursor is not valid.

Try SimplyBoost with your own content

Start a 7-day free trial with 100 AI replies. Add your website, install the widget and see how the agent answers your customers. Larger team? Custom plans above 4,000 AI replies come with a dedicated account manager and white-label.

See pricing
  • 7 days, 100 AI replies
  • From €39 a month
  • Hosted in Europe