Send a message

One endpoint. You send a message, you wait, you get the assistant’s reply back in the response.

POST /api/v1/agents/:id/messages

:id is the assistant’s id, from the address bar of its page in Toldo.

Request

Header	Value
Authorization	Bearer mb_live_… — the scheme is case-insensitive, the key is not
Content-Type	application/json

curl -X POST "https://YOUR-TOLDO/api/v1/agents/agt_7f2c9d41b8e05a63/messages" \
  -H "Authorization: Bearer mb_live_…" \
  -H "content-type: application/json" \
  -d '{
    "message": "When are you open on Sundays?",
    "conversation_id": "customer-42",
    "user_name": "Priya"
  }'

Field	Type	Required	Rules
message	string	yes	1–8,000 characters, trimmed
conversation_id	string	no	Your own id. 1–120 characters of A–Z a–z 0–9 _ . : -
user_name	string	no	Up to 80 characters. Who is writing, if you know

Anything else in the body is ignored.

Response

{
  "conversation_id": "customer-42",
  "reply": "On Sundays we're open 8am to 4pm. The kitchen closes at 3.",
  "needs_human": false
}

Field	Meaning
conversation_id	The conversation this message belongs to — the one you sent, or a new one
reply	What the assistant said. Plain text: no Markdown, no headings, no tables
needs_human	true when the assistant handed this conversation over to a person

The reply is written as plain text because this channel is a program, not a chat window. Do not expect Markdown to render.

Conversation continuity

Send the same conversation_id again and the assistant picks up where it left off, with the history of that conversation in front of it. Use an id that is stable and meaningful in your own system: a customer id, a ticket number, a session id.

Leave conversation_id out and you get a one-off question. A fresh id comes back in the response, so you can decide after the fact to continue the conversation you just started.

# first message — no id sent
# → {"conversation_id":"k7q3nv8d2f5h…","reply":"…","needs_human":false}

# second message — reuse what came back
-d '{"message":"And on public holidays?","conversation_id":"k7q3nv8d2f5h…"}'

Acting on needs_human

needs_human: true means the assistant flagged the conversation for the owner. The reply still contains something to show the person — whatever the owner wrote as their hand-over message — but this is the signal to route the thread to a human in your own system, not to keep asking.

What happens on the other side

The conversation appears in the owner’s Conversations tab like any other, labelled as coming from their own software, with the same turn-by-turn notes. Details the assistant collects land in their Collected list. It is not a separate, lesser kind of conversation.

Next: Errors and limits.