Send message

POST 
/v1/sessions/:session_id/messages

Sends the end user's next message and starts a task that answers it. One task runs at a time per session: while a task is still running, a new message is refused with session_busy — wait for the task's end event, or stop it first. The reply is kept in the message list and streams on GET /v1/sessions/{session_id}/events: open it with Last-Event-ID set to the returned last_event_id to receive the task from its first frame. Or set stream: true to receive the task on this request: the response is then 200 with the task's own frames, as the event stream sends them, ending with its end frame — or, like any event stream, after 10 minutes (a refused message still answers with its error); an asset still being made when the task ends is reported later on the event stream. A response that ends without the end frame — dropped, or at its time limit — does not stop the task: continue on the event stream with the last frame's id, or retry with the same Idempotency-Key to receive the same task again from its first frame. Needs a spendable balance on the project's billing account. A voice session does not take text messages. A message the user sends by acting on an a2ui surface carries the renderer's action in a2ui_action.

Request

Responses

200

With stream: true: the task's frames as server-sent events, from its first frame through its end frame.

202

Successful Response

401

Authentication failed: the credential is missing, malformed, expired, or revoked.

• invalid_token — The access token is invalid.
• project_disabled — This project is not active.
• token_expired — The access token has expired.
• user_disabled — This user is not active.

404

The requested resource does not exist, or is not visible to the caller.

• session_not_found — Session not found
• file_not_found — The requested file was not found.
• file_expired — The requested file has expired.

409

The request conflicts with the current state of the resource.

• session_busy — This session is already running a task; wait for it to finish before starting another.
• idempotency_conflict — This Idempotency-Key belongs to a different request.
• idempotency_in_progress — The first request with this Idempotency-Key is still in progress. Retry it with the same key shortly.
• session_not_taskable — This session does not accept tasks.

413

The request body is larger than the allowed limit.

• file_too_large — The file exceeds the maximum allowed size.
• payload_too_large — The request body is too large.

422

A request value failed validation; the details array names each offending field.

• unsupported_media_type — The media type is not supported.
• validation_failed — The request payload failed validation.

429

Either too many requests (a Retry-After header says when to retry) or the billing account is out of credits (no Retry-After — top up to continue); the code field tells the two apart.

• insufficient_credits — The billing account has insufficient credits.
• rate_limited — Too many requests. Please slow down.

500

An unexpected server-side error occurred.

• internal — An unexpected error occurred.

503

The service is temporarily unavailable; retry after a short delay.

• service_unavailable — Live updates are at capacity right now. Please retry shortly.