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.
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);
};{ "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.
session:
key: input.conversation_id
ttl: 86400{
"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.
type: websocket
name: Support chat
config:
streaming: true
max_messages_per_session: 500
agents:
- support-chatDecide 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.
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.
{
"type": "message",
"id": "msg-001",
"payload": {
"message": "Where is my order ord_8812?",
"conversation_id": "conv_4821"
}
}{ "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.
{
"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
}
]
}
}{
"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.
{
"type": "message",
"id": "msg-003",
"payload": {
"message": "I imported my contacts. What comes next?",
"conversation_id": "onb_5520"
}
}{ "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.
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", ""){
"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
More connectors
Cron Scheduler
Run an agent on any cron expression. connic hosts the scheduler for daily digests, hourly health checks, and weekly audits.
Inbound
Google Pub/Sub
Run an agent on every message a Pub/Sub push subscription delivers, checked with Google's signed token, and publish results to a topic.
Inbound · Outbound
Jira
Run an agent on new issues, issue updates and comments in Jira Cloud. It comments back or creates a new issue.
Inbound · Outbound
Outlook (Microsoft 365)
Run an agent on new email in a Microsoft 365 mailbox and reply in the same thread. connic signs in with your own Entra ID app. Attachments included.
Inbound · Outbound
PostgreSQL
Use LISTEN/NOTIFY to trigger an agent from new rows, without polling or a CDC pipeline.
Inbound
Telnyx Messaging
Receive and send SMS/MMS, WhatsApp, and RCS messages through your Telnyx account. Connect agents to customer conversations and notifications.
Inbound · Outbound