Skip to main content
POST
/
api
/
public
/
v1
/
chat
/
messages
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({text: 'I\'d like to check my order', intentName: 'order_status'})
};

fetch('{protocol}://{host}/api/public/v1/chat/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "reply": {
    "executionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "blocks": [
      {
        "type": "<string>",
        "id": "<string>",
        "payload": {},
        "meta": {}
      }
    ],
    "expectedInput": {},
    "waitToken": "<string>",
    "waitExpiresAt": "2023-11-07T05:31:56Z",
    "tokenUsage": {
      "prompt_tokens": 1,
      "completion_tokens": 1,
      "total_tokens": 1,
      "model": "<string>",
      "cost_micros": 1,
      "cost_usd": 123
    }
  }
}

Authorizations

​
Authorization
string
header
required

Token issued by POST /api/public/v1/chat/sessions. Lifetime 1h.

Body

application/json

New execution. The user's free-text message becomes part of the flow context.

​
text
string
required

User's verbatim message.

Required string length: 1 - 4000
​
intentName
string
required

Which intent to trigger. Must be one of the names returned in the session's intents array.

​
context
object

Free-form key/value bag merged into the execution context (page URL, referrer, A/B variant, …). Avoid PII.

​
variables
object

Optional conversation variables merged into the conversation row and surfaced to the flow as untrusted input. Constraints (rejected with a 422 validation_failed on the chat surface, 422 invalid_input on the Engine API):

  • at most 50 keys;
  • at most 4096 bytes total when JSON-encoded;
  • keys are snake_case matching ^[a-z][a-z0-9_]{0,63}$;
  • values are scalar, null, or arrays nested at most 4 levels deep (plain objects/maps as values are rejected).
Example:
{
  "cart_total": 129,
  "page_path": "/pricing",
  "tags": ["returning", "vip"]
}
​
tokenUsage
object

Client-reported LLM token usage for the reply this message turn produces, when that reply was generated by the integrator's own model. The server prices the counts from the tenant's model price table and attaches the result to the turn's agent message; the priced tokenUsage is echoed on the reply.

Response

Flow processed the message

​
reply
object
required