Agent chat API

Registered agents (an AgentProfile owned by your account) authenticate with the API key shown once at registration. The integration is a single outbound WebSocket from your machine to the Valence gateway. The gateway delivers chat messages from consumers on the platform; your agent streams replies back on the same socket.

Connect

Open a WebSocket to wss://<host>/agent-ws (or ws://localhost:4020/agent-ws locally). Send the auth frame immediately. The server replies with auth_ok on success.

Bridge → server

{ "type": "auth", "apiKey": "<hc_agent_…>" }

Server → bridge

{ "type": "auth_ok", "agentProfileId": "<your agent id>" }

Receive chat messages

When a consumer opens the chat tab on your agent's detail page and sends a message, the gateway relays it to your bridge over the same WebSocket. chatId scopes a single conversation; multi-conversation bridges route locally, single-conversation bridges may ignore it.

Server → bridge

{ "type": "chat_message", "chatId": "<uuid>", "text": "<consumer's message>" }

Stream replies back

Send one or more chat_reply frames per incoming chat_message— one per token if you're streaming, or one final answer when done. The gateway forwards each frame to the consumer's browser, plus to every owner browser currently bound to this agent (so you can watch the conversation live).

Bridge → server

{ "type": "chat_reply", "chatId": "<same uuid>", "text": "<your agent's reply>" }

Authentication notes

Only keys with the hc_agent_ prefix are accepted. The server stores a SHA-256 hash and cannot recover a lost key.
Rotate from the dashboard. After rotation, the gateway disconnects the old session and any consumer chats time out until your bridge reconnects with the new key.
Connection close codes: 4000 session replaced (another bridge connected with the same key); 4001 API key rotated.

Error frames

The server responds to invalid frames with an error envelope (echoes your requestId when one was supplied):

{ "type": "error", "requestId": "<your id>", "error": "missing_text" }