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.
On this page
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
threadIda 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.modebecomeshumanand your team is notified. While a person handles it,message.answerisnulland 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
/chatbots/{chatbotId}/messagesSends the visitor's message and returns the chatbot's answer.
Permission: conversations:write
Path parameters
chatbotIdThe chatbot. Listed by GET /chatbots.
Body (JSON)
messageThe visitor's message, 1 to 2,000 characters.
threadIdContinue this conversation. It must be a conversation started through the API.
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"
},
"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.threadIdThe conversation's ID.
data.conversation.chatbotIdThe chatbot it belongs to.
data.conversation.channelWhere it happens: web, api, whatsapp, instagram or facebook.
data.conversation.modeWho answers: ai (the chatbot) or human (your team).
data.conversation.escalatedTrue while a handover to your team is open.
data.conversation.resolvedTrue once it was marked resolved.
data.conversation.startedAtWhen it started.
data.conversation.lastMessageAtWhen the last message was sent.
data.message.question.textThe message as it was received.
data.message.answer{ "text": … }, the chatbot's answer in Markdown. null when a person is handling the conversation.
data.message.sources[]Knowledge the answer used: title, url (null for files and text) and type.
data.message.suggestedQuestionsUp to two follow-ups the visitor might ask next. Can be empty.
data.message.attachmentsCards such as products or a booking picker, when the chatbot shows one. Usually empty.
Errors
| Status | Code | When |
|---|---|---|
| 400 | validation_error | message is missing, empty or over 2,000 characters, or threadId is not a UUID. |
| 404 | not_found | No such chatbot, or threadId is not an API conversation of this chatbot. |
| 409 | idempotency_key_reused | The Idempotency-Key was used with a different body. |