API reference: Messages

Messages. Ask the agent and get its answer.

Send a visitor's message to a chatbot and receive the answer, its sources and suggested follow-ups. Each message counts as one AI reply.

Do you ship to Belgium?
Yes. Next-day to Belgium, free over €50.
Source: Shipping
How much is shipping to Belgium?
threadId 3f0c…channel: api

By , AI EngineerUpdated

How a message is handled

  • The chatbot answers from its knowledge, exactly as in the chat widget. The conversation appears in your inbox with the channel api.
  • Without threadId a new conversation starts (201). With it, the conversation continues (200).
  • If the visitor asks for a person, or the agent decides your team should help, the conversation is handed over: conversation.mode becomes human and your team is notified. While a person handles it, message.answer is null and the message waits for your team.
  • When the plan has no AI replies left, the answer is a short neutral notice and nothing is charged.
  • The request waits for the answer, usually a few seconds. Use a client timeout of at least 30 seconds and an Idempotency-Key, so a retry does not send the message twice.

Send a message

POST/chatbots/{chatbotId}/messages

Sends the visitor's message and returns the chatbot's answer.

Permission: conversations:write

Path parameters

chatbotId
string (uuid)required

The chatbot. Listed by GET /chatbots.

Body (JSON)

message
stringrequired

The visitor's message, 1 to 2,000 characters.

threadId
string (uuid)

Continue this conversation. It must be a conversation started through the API.

Request
curl -X POST https://get-api.simplyboost.io/api/v1/chatbots/CHATBOT_ID/messages \
  -H "Authorization: Bearer $SIMPLYBOOST_TOKEN" \
  -H "Idempotency-Key: 7f9c2b1e-q1" \
  -H "Content-Type: application/json" \
  -d '{"message": "Do you ship to Belgium?"}'

Response 201 Created (new conversation) or 200 OK (continued)

{
  "ok": true,
  "data": {
    "conversation": {
    "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:30:04+00:00",
    "ticketCode": null,
    "ticketNumber": null,
    "priority": null,
    "tags": [],
    "assignee": null
  },
    "message": {
      "question": { "text": "Do you ship to Belgium?" },
      "answer": { "text": "Yes. Next-day to Belgium, free over €50." },
      "sources": [{ "title": "Shipping", "url": "https://yourshop.com/shipping", "type": "website" }],
      "suggestedQuestions": ["How much is shipping to Belgium?"],
      "attachments": []
    }
  },
  "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.message.question.text
string

The message as it was received.

data.message.answer
object | null

{ "text": … }, the chatbot's answer in Markdown. null when a person is handling the conversation.

data.message.sources[]
object[]

Knowledge the answer used: title, url (null for files and text) and type.

data.message.suggestedQuestions
string[]

Up to two follow-ups the visitor might ask next. Can be empty.

data.message.attachments
object[]

Cards such as products or a booking picker, when the chatbot shows one. Usually empty.

Errors

StatusCodeWhen
400validation_errormessage is missing, empty or over 2,000 characters, or threadId is not a UUID.
404not_foundNo such chatbot, or threadId is not an API conversation of this chatbot.
409idempotency_key_reusedThe Idempotency-Key was used with a different body.

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