Skip to main content
connic

WebSocket

Open one socket, send JSON messages and stream each reply into your app while the agent writes it. Agent sessions keep the conversation going across messages and reconnects.

Modes
Sync
Set up in
Dashboard or connectors/*.yaml
Documentation
WebSocket docs
Publisher
By connic

Stream the reply while the agent writes it

Open the socket, send JSON and render each chunk as it arrives. Every message gets an ack, and the reply ends with the full text and token usage.

Streaming on
You get stream_start, then stream_chunk events with partial text, then stream_end with the full reply and token usage.
Streaming off
The reply arrives as one response event once the run finishes.
Guardrails first
An agent with output guardrails sends its reply as a single stream_chunk after the checks pass.
Matching replies
Give each message an id, and every event of its reply carries the same id.
chat.js
const ws = new WebSocket(
  "<websocket-url>?secret=<your-secret-key>"
);

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "message",
    id: "msg-001",
    payload: { message: "Where is my order ord_8812?" },
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === "stream_chunk") appendToChat(data.chunk);
};
events.json
{ "type": "ack", "id": "msg-001", "message_number": 1 }
{ "type": "stream_start", "id": "msg-001",
  "agent": "support-chat" }
{ "type": "stream_chunk", "id": "msg-001",
  "agent": "support-chat", "chunk": "Order ord_8812 " }
{ "type": "stream_chunk", "id": "msg-001",
  "agent": "support-chat", "chunk": "shipped on October 12." }
{ "type": "stream_end", "id": "msg-001",
  "agent": "support-chat",
  "full_response": "Order ord_8812 shipped on October 12.",
  "token_usage": { "input_tokens": 812, "output_tokens": 14,
    "total_tokens": 826 } }

Keep the conversation across messages

Each message starts its own agent run. A persistent session keyed by a conversation ID carries the history from one message to the next.

History follows the conversation
Set session.key to input.conversation_id and send that field with every message. Reconnect with the same ID, and the conversation continues.
One key per conversation
Without a key, every conversation of the agent shares one session.
One message at a time
A connection handles messages in the order they arrive. A message sent during a reply waits until every linked agent has answered.
Approvals hold the turn
An approval-gated tool pauses the reply until someone decides, and later messages wait. Keep approval.timeout short on chat agents.
agents/support-chat.yaml
session:
  key: input.conversation_id
  ttl: 86400
message.json
{
  "type": "message",
  "id": "msg-002",
  "payload": {
    "message": "Can you send it to my office instead?",
    "conversation_id": "conv_4821"
  }
}

Keep the socket next to your agents

Declare it as a YAML file in connectors/. Each deploy creates or updates it for its environment, and a rollback restores it. connic generates the URL and the secret, so neither appears in the file.

connectors/support-chat.yaml
type: websocket
name: Support chat
config:
  streaming: true
  max_messages_per_session: 500
agents:
  - support-chat
create: connectors/support-chat.yaml (websocket)

Decide who connects and for how long

Authentication is on by default, and each connection closes after an idle timeout or a message limit that you set.

A secret on connect
Pass it as a secret query parameter, as an X-Connic-Secret header or as the first JSON message. With a wrong secret, the socket closes before any run starts.
Your own caller checks
Turn off Require Authentication only when middleware checks each caller, for example with a signed token.
Connection limits
An idle connection closes after session_timeout, and a connection closes once it reaches max_messages_per_session. The history stays in the agent session, so the client reconnects and continues.
Connector settings
FieldDefaultAllowed values
streamingtruetrue, false
require_authtruetrue, false
session_timeout360060 to 86400 seconds
max_messages_per_session1001 to 10000

Where a WebSocket fits

Pick a setup to see what the client sends and what comes back over the socket.

Your web app streams the answer into the chat window while the agent writes it.

Web app chat
WebSocket
support-chat
Streamed reply in the chat
message.json
{
  "type": "message",
  "id": "msg-001",
  "payload": {
    "message": "Where is my order ord_8812?",
    "conversation_id": "conv_4821"
  }
}
events.json
{ "type": "ack", "id": "msg-001", "message_number": 1 }
{ "type": "stream_start", "id": "msg-001",
  "agent": "support-chat" }
{ "type": "stream_chunk", "id": "msg-001",
  "agent": "support-chat", "chunk": "Order ord_8812 " }
{ "type": "stream_chunk", "id": "msg-001",
  "agent": "support-chat", "chunk": "shipped on October 12." }
{ "type": "stream_end", "id": "msg-001",
  "agent": "support-chat",
  "full_response": "Order ord_8812 shipped on October 12.",
  "token_usage": { "input_tokens": 812, "output_tokens": 14,
    "total_tokens": 826 } }

Users upload a contract in your portal and ask about it, and the answer streams back with the file in context.

Customer portal
WebSocket
contract-reader
Answer in the portal
message.json
{
  "type": "message",
  "id": "msg-007",
  "payload": {
    "message": "Which notice period applies to this contract?",
    "conversation_id": "conv_9310",
    "files": [
      {
        "name": "service-agreement.pdf",
        "mime_type": "application/pdf",
        "data": "<base64-bytes>",
        "size": 284113
      }
    ]
  }
}
stream_end.json
{
  "type": "stream_end",
  "id": "msg-007",
  "agent": "contract-reader",
  "full_response": "Section 9: three months' notice to the end of a quarter.",
  "token_usage": { "input_tokens": 6120, "output_tokens": 22, "total_tokens": 6142 }
}

Your app shows the next setup step as one complete message, so the connector runs with streaming off.

Onboarding flow
WebSocket
onboarding-guide
Next step in the app
message.json
{
  "type": "message",
  "id": "msg-003",
  "payload": {
    "message": "I imported my contacts. What comes next?",
    "conversation_id": "onb_5520"
  }
}
events.json
{ "type": "ack", "id": "msg-003", "message_number": 3 }
{
  "type": "response",
  "id": "msg-003",
  "agent": "onboarding-guide",
  "response": "Next, create your first campaign. Pick a template to start from.",
  "token_usage": { "input_tokens": 930, "output_tokens": 16, "total_tokens": 946 }
}

Your CRM backend asks for a briefing on an account and shows the finished text in a sidebar.

CRM backend
WebSocket
account-briefing
Briefing in the CRM sidebar
briefing.py
import json

import websockets


async def brief(account_id: str) -> str:
    url = "<websocket-url>?secret=<your-secret-key>"
    async with websockets.connect(url) as ws:
        await ws.recv()  # connected
        await ws.send(json.dumps({"payload": {
            "message": "Brief me before my call.",
            "account_id": account_id,
        }}))
        while True:
            event = json.loads(await ws.recv())
            if event["type"] == "stream_end":
                return event.get("full_response", "")
stream_end.json
{
  "type": "stream_end",
  "id": "3f2b8c1e-6d4a-4e9b-9a7c-2d5e8f1b4c6a",
  "agent": "account-briefing",
  "full_response": "Example GmbH renewed in March and has two open tickets.",
  "token_usage": { "input_tokens": 1460, "output_tokens": 24, "total_tokens": 1484 }
}

WebSocket FAQ

Add a WebSocket connector to the agent, open the socket with its URL and secret, and send a JSON message. The reply arrives as stream_chunk events while the agent writes it, and a stream_end event carries the full text and token usage.

Yes, with a persistent session. Set session.key to a payload field such as input.conversation_id and send that field with every message. The history belongs to the conversation, so a reconnect with the same ID continues it.

With the connector secret, sent as a secret query parameter, as an X-Connic-Secret header or as the first JSON message. Turn off Require Authentication only when middleware checks each caller, for example with a signed token.

Yes. Add a files array to the payload with name, mime_type and base64-encoded data. Each message takes up to 10 files and 10 MiB combined, and every accepted file goes to the model with the message.

When one request should wait for the finished answer and you need neither a stream nor an open connection. A sync webhook returns the agent's output in the HTTP response and waits five minutes by default.