Skip to main content
POST
/
api
/
v1
/
engine
/
triggers
/
chat
Trigger a chat intent
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tenant_id: '01935-tttt-tttt-tttt-tttttttttttt',
    intent_name: 'order_status',
    conversation_id: '01935-aaaa-bbbb-cccc-dddddddddddd',
    context: {page_url: 'https://acme.com/orders'},
    variables: {order_number: '4567'}
  })
};

fetch('{protocol}://{host}/api/v1/engine/triggers/chat', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "blocks": [
    {
      "type": "<string>",
      "id": "<string>",
      "payload": {},
      "meta": {}
    }
  ],
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "expected_input": {},
  "metadata": {},
  "token_usage": {
    "prompt_tokens": 1,
    "completion_tokens": 1,
    "total_tokens": 1,
    "model": "<string>",
    "cost_micros": 1,
    "cost_usd": 123
  }
}

Authorizations

​
Authorization
string
header
required

Deploy-wide server-to-server bearer token (ENGINE_API_TOKEN), validated by the engine_api firewall. Authenticates the Engine API, Knowledge base, and Conversions surfaces. The tenant_id rides in the request body and is trusted in V1 — keep this token strictly server-side.

Headers

​
Idempotency-Key
string

Make the call safe to retry. A repeat with the same key returns the cached response (24h TTL); reusing the key with a different payload returns 409 idempotency_conflict.

Body

application/json
​
tenant_id
string<uuid>
required
​
intent_name
string
required

Intent to start; must match a published flow.

​
conversation_id
string<uuid> | null

Attach to an existing conversation, or omit to create one.

​
context
object

Free-form context merged into the execution.

​
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"]
}

Response

Execution envelope

The standard execution envelope returned by every Engine API call that touches an execution — trigger and resume share one parser. Keys are snake_case (the public Chat API uses the camelCase ChatReply shape).

​
execution_id
string<uuid>
required
​
status
enum<string>
required
Available options:
waiting_input,
waiting_time,
completed,
failed,
aborted
​
blocks
object[]
required
​
conversation_id
string<uuid> | null
​
expected_input
object

What to send to /resume next; null when the execution is terminal.

​
metadata
object

metadata.wait_token binds future /resume calls to this exact pause.

​
token_usage
object

Token usage for the turn that produced these blocks, or null.