Agents
Agents (WebSocket)
Stream audio between your application and a hosted Line voice agent over a single bidirectional WebSocket. Use this for web apps, mobile apps, or to bridge your own telephony provider into a Line agent.
All messages are JSON text frames. Audio is exchanged as base64-encoded payloads inside those messages, not as binary frames.
Basic Usage:
- Connect to
wss://api.cartesia.ai/agents/stream/{agent_id}with anAuthorization: Bearer <ACCESS_TOKEN>header (oraccess_tokenquery parameter in the browser). Generate an agent access token via the/access-tokenendpoint. - Send a
startevent as the first message — the server closes the connection if any other event arrives first. - Wait for the server’s
ack, which echoes the resolved config and returns astream_idif you didn’t provide one. - Stream user audio as
media_inputevents (base64-encoded, in the format declared instart.config.input_format). - Receive agent audio as
media_outputevents. Handleclear(interrupt) andtransfer_call(telephony handoff) events as they arrive. - Send standard WebSocket ping frames every 60–90 seconds to avoid the 180-second inactivity timeout.
For a higher-level walkthrough and a runnable browser example, see the WebSocket API guide.
WSS