Chat API

Use the Chat API when you want text-only assistant turns over HTTP.

The chat transport uses Server-Sent Events with the simplified event shape below. Voice sessions use a different protocol (Pipecat RTVI) over a WebSocket — see Voice WebSocket for that surface.

Send a message

POST /sessions/{session_id}/messages

Request body:

{
  "text": "Can you help me continue where we left off?"
}

text is required and must be between 1 and 8000 characters.

Response stream

The response is a Server-Sent Events stream.

event: turn_start
data: {"turn_id":"...","model":"..."}

event: token
data: {"text":"Hello"}

event: turn_end
data: {"turn_id":"...","latency_ms":842,"prompt_tokens":120,"completion_tokens":56}

Possible events:

Event	Payload	Meaning
turn_start	turn_id, model	Assistant turn started.
token	text	Streamed text chunk.
tool_call	call_id, name, arguments_partial	Tool invocation started; arguments_partial is the streaming-JSON arguments string at this point.
tool_result	call_id, name, arguments, result, latency_ms	Tool returned. result is what the assistant sees.
guard	kind, action, detail, replacement	A guard fired (e.g. no-go zone). action is block / redirect / escalate; replacement is set when action == "redirect".
turn_end	turn_id, latency_ms, prompt_tokens, completion_tokens	Assistant turn completed.
error	detail, error_kind	Turn failed.

Example client

const response = await fetch(`https://api.hyponema.ai/sessions/${sessionId}/messages`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.HYPONEMA_API_KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({ text: "What should we do next?" }),
})

if (!response.body) {
  throw new Error("Missing SSE body")
}

for await (const chunk of response.body) {
  process.stdout.write(Buffer.from(chunk).toString("utf8"))
}

Your production client should parse SSE event boundaries rather than printing raw chunks.