Skip to Content
Sophon Docs
API Reference

SignalR

Real-time hubs — chat streaming, task status, approvals, voice, canvas, terminal, and node commands.

SignalR is Sophon's real-time transport. The Dashboard, Mobile, Desktop, and Sophon Node all connect to SignalR hubs for streaming, live status, and bidirectional commands. This page is the protocol reference.

Hubs

Sophon maps four hubs under /hubs/*:

HubPurpose
/hubs/chatChat streaming, task lifecycle, tool progress, session updates, approvals and questions, voice, and workflow runs
/hubs/canvasCanvas frames and canvas actions
/hubs/terminalInteractive terminal sessions
/hubs/nodeSophon Node command dispatch + heartbeats

There is no separate tasks, approvals, workflows or notifications hub. Task lifecycle, approval and question events, voice, and workflow run updates all ride /hubs/chat — a custom client only needs that one connection unless it drives the canvas, a terminal or a node.

A single client can connect to multiple hubs over one WebSocket (SignalR multiplexes).

Authentication

Same JWT bearer as REST. Pass via query string (SignalR's WebSocket limitation):

import { HubConnectionBuilder } from "@microsoft/signalr";

const connection = new HubConnectionBuilder()
  .withUrl("https://gw.example.com/hubs/chat", { accessTokenFactory: () => jwt })
  .withAutomaticReconnect()
  .build();

Chat hub

Hub methods take positional arguments — SignalR matches by arity, so pass them in order, not as one object:

// SendMessage(sessionId, text, agentId, effort?)
await connection.invoke(
  "SendMessage",
  "sess_abc",
  "What's on my calendar today?",
  "default"
);

// SendMessageWithAttachments(sessionId, text, agentId, documentIds, effort?)
await connection.invoke(
  "SendMessageWithAttachments",
  "sess_abc",
  "Summarize this",
  "default",
  ["doc_1"]
);

Since v2.2.0 the optional last string carries the message's effort: auto, low, medium, high, xhigh or max. It used to carry Thinking; the position and type are unchanged, and a v2.1 client's off, fast and full are read as low, medium and high. Any other value is refused with a caller-only TaskRejected whose errorCode is EFFORT_INVALID.

Server → client events. As of 1.11.0, task stream, status, lifecycle, and approval events are delivered to the session group rather than the whole user — see Session scoping.

EventPayloadMeaning
TaskQueued{taskId, sessionId, policyMode, pendingTaskCount, replacedActiveTask, droppedPendingTaskCount}Message accepted, background task queued (sent to the caller)
TaskRejected{taskId, sessionId, errorCode, error, policyMode, pendingTaskCount}The session's execution policy refused the message (sent to the caller)
TaskStarted{taskId, sessionId}Worker picked up the task
AgentStatus{taskId, sessionId, phase, description, isComplete, planMetadata}Progress checkpoint for the running turn
StreamChunk{taskId, sessionId, content, isComplete, modelId, providerId, providerName, inputTokens, outputTokens, costUsd, contextTokens, contextWindow, routing}Token stream (if streaming enabled). The usage fields and routing are set on a complete chunk only (see Usage and routing on turn events)
ToolProgress{taskId, sessionId, toolName, eventType, summary, data}Live progress from a running tool (e.g. browser screenshots)
ReceiveMessage{id, sender, content, timestamp, sessionId, channelType, proactive}Final agent message
TaskCompleted{taskId, sessionId, modelId, providerId, providerName, inputTokens, outputTokens, cacheReadTokens, reasoningTokens, costUsd, contextTokens, contextWindow, routing}Task done, with the turn's totals and route
TaskFailed{taskId, sessionId, error, …turn totals, routing}Task errored. routing.error says why when the route itself could not be served
TaskCancelled{taskId, sessionId, success, reason, …turn totals, stopCause}Task cancelled. The reply a CancelTask caller gets carries only taskId, success and sessionId. stopCause is user, timeout, shutdown, replaced or unknown
SessionModelRoutingChangedSessionModelRoutingStateThe chat's model routing changed (see Model routing)
AgentActivity{rootSessionId, childSessionId, kind, state, agentName, title, currentTool, lastLine, inputTokens, outputTokens, costUsd, seq, routing, …}Live state of one child agent, sent to the root session (see Child agents)
SessionUpdated{id, …}Session metadata changed — carries the session id plus whichever field changed (e.g. status, agentId)
SessionNotification{sessionId, kind, refId, success, excerpt, timestamp}User-wide activity event (see SessionNotification)
ApprovalRequired{id, toolName, description, risk, sessionId, agentId, channelType, parameters, previewContent, allowEdit, timeoutSeconds, escalationSessionId, graphRunId, graphNodeId, workflowId?, workflowRunId?, workflowNodeId?}An approval is waiting for a decision. The workflow* members are present only on a workflow's card (since v2.2.0)
ApprovalResolved{id, outcome, sessionId, escalationSessionId}That approval is no longer pending (see Approvals and questions)
InfoRequestRequired{id, question, options, questions, context, sessionId, timeoutSeconds, createdAt, escalationSessionId, graphRunId, graphNodeId, workflowId?, workflowRunId?, workflowNodeId?}The agent, or a workflow's Info request step, is asking a question
InfoRequestAnswered{id, answer, timedOut?, cancelled?, escalationSessionId, graphRunId, graphNodeId}That question is settled
VoiceUtteranceStarted{sessionId, utteranceId}A new speech-to-text utterance is open — sent only to the connection streaming the audio
VoiceInterimTranscript{sessionId, utteranceId, text}Live partial transcript — sent only to the connection streaming the audio
VoiceFinalTranscript{sessionId, utteranceId, text, confidence}Committed utterance — sent only to the connection streaming the audio

Voice replies (audio, status, fallback notices) go to the session's voice group instead, so every attached tab hears them — see Voice.

The hub carries more than the table above: session-list events (SessionCreated, SessionDeleted, SessionTitleUpdated, ChildSessionCreated), BudgetAlert, DocumentProgress, the workflow run events below, and the ClaudeCode stream events. The CLI coding agent adds ToolCallUpdate (a tool call started or finished), SessionWorkspaceChanged (the chat's folder binding changed) and SessionPermissionModeChanged (the chat's permission mode or standing rules changed). SubAgentStarted and SubAgentCompleted gain rootSessionId, kind and parentToolCallId, and SubAgentCompleted gains stopped (true only when a person stopped the child).

SessionModelOverrideChanged is gone in 2.1. Register SessionModelRoutingChanged instead. Custom clients should register a handler for every event above, a no-op at minimum, and accept members they do not know: new fields are added without a version bump.

Client → server methods:

MethodPurpose
SendMessageSubmit a user message
SendMessageWithAttachmentsSubmit a user message with document ids attached
CancelTaskCancel in-flight task
CancelPlanCancel an active plan
JoinSessionSubscribe to a session's events — the primary subscription mechanism (see Session scoping)
LeaveSessionStop receiving events for a session
RespondToApproval(approvalId, approved) — decide a pending approval
RespondToApprovalWithEdit(approvalId, editedPlanJson) — approve with modifications
RespondToInfoRequestV2(infoRequestId, answers) — answer a question; answers maps each wire question id (q1…qN) to the list of chosen values
VoiceStart(sessionId?, agentId) — open a voice session on a chat session; returns the session id it settled on (a new one if you passed none, or one you don't own)
VoiceMessage(sessionId, text) — submit an already-transcribed utterance as a voice turn
StreamAudioStream microphone audio for realtime transcription (see StreamAudio)
VoiceInterrupt(sessionId) — stop the current speech-to-text stream and silence the turn's reply. It does not cancel the task: the work keeps running and its reply still lands in the chat thread
VoiceEnd(sessionId) — end the voice session and leave its voice group
GetSessionModelRouting(sessionId) — the chat's SessionModelRoutingState
SetSessionModelRouting(sessionId, request) — replace the chat's routing layer; returns the new state
GetSessionActivity(sessionId, query) — one snapshot for a reload or a reconnect: recent tool calls, child agents, modelRouting, sessionUsage and more
StopChildAgent(rootSessionId, childSessionId) — stop one running child agent. Returns accepted, not_running or not_found; it never cancels the parent turn

The coding agent adds more methods (workspace binding, permission modes, approval rules, changes and rewind). Check the feature tokens below before calling any of them.

Model routing

GetSessionModelRouting(sessionId) and SetSessionModelRouting(sessionId, request) read and write the same state as REST GET|PUT /api/sessions/{id}/model-routing — see REST API for the request body and Model routing for what the modes mean. A refused write throws a HubException whose message starts with the code, for example seq_conflict: … or activity_child: ….

Neither method broadcasts by itself. Every change to a chat's routing, from any client, arrives as SessionModelRoutingChanged with the full SessionModelRoutingState: seq, the stored layer, effective (one row per role, always all five: orchestrator, executor, researcher, utility, vision), allowFallback, localOnly, autoProfile, gaps and backgroundNotice. Apply it by seq and drop any state older than the one you hold. A notice change is sent at the same seq.

Usage and routing on turn events

Turn events carry what the turn cost and which model answered. These fields are new in 2.1 and advertised by usage.v1 and modelRouting.v1.

  • TaskCompleted carries the turn's totals: inputTokens, outputTokens, cacheReadTokens, reasoningTokens, costUsd (null when no call was priced), contextTokens (the last call's prompt size, which is how full the context is) and contextWindow (null when the model's window is unknown). TaskFailed and TaskCancelled carry the same totals, nullable. Cost covers this session's own turns; child agents are not included.
  • A complete StreamChunk carries its own call's costUsd, contextTokens and contextWindow. A stream whose provider reported no usage reads as null, not $0.
  • routing on the final StreamChunk, TaskCompleted, TaskFailed and AgentActivity is the route the turn ran on, or null when no model ran:
FieldMeaning
roleorchestrator, executor, researcher, utility or vision
providerId, providerType, providerName, modelIdThe provider and the concrete model that answered
sourceThe scope that chose the route: task, session, agent, user, host, assistant, delegation, auto or default
routedBypinned, auto, default, or fallback when another provider answered
isLocalThe answering provider runs locally
warningsFor example contextUnverified, noToolSupport, smallContext; never null
failoverSet when the turn left its first route: {fromProviderId, fromProviderName, fromModelId, reason, attempts}. reason is rateLimited, overloaded, serverError, timeout, connectionFailed, contextOverflow, budgetExceeded or providerUnavailable
errorSet when the route could not be served: {code, message, providerId, modelId, reason}. code is pin_unavailable or no_candidate; message is fixed wording, never a provider's error text

Child agents

AgentActivity is the live state of one child agent (a sub-agent, a plan step, a delegated run or a coding agent), sent to the root session's group only, so a client watching the main chat sees every child without joining each one. It is advertised by agentActivity.v1.

FieldMeaning
rootSessionId, parentSessionId, childSessionId, parentToolCallIdWhere the child sits in the tree
kindsubagent, graphnode, delegate or coding
statequeued, running, waiting_approval, completed, failed or cancelled
stopRequested, stopReasonstopReason is user, parent or interrupted
agentId, agentName, title, depthWho is working and on what (depth 1 to 4)
currentTool, currentToolSummary, lastLine, toolCount, filesChangedWhat it is doing now
inputTokens, outputTokens, costUsdWhat it has used
graphRunId, nodeId, attemptSet for a plan step
startedAt, updatedAt, endedAt, seqseq rises from 1 per child
routingThe route the child's turn last ran on (see above), null until known

The stream is coalesced and may lag: updates are merged per window (250 ms, longer when a root has more than 16 live children), and a state change into or out of waiting_approval, a stop request or a terminal state is sent at once. Drop any event whose seq you have already seen. Nothing is sent after a terminal state. After a reconnect, rebuild the tree from GetSessionActivity or REST GET /api/sessions/{id}/agents.

Plan events

Plan progress rides AgentStatus: {sessionId, phase, description, isComplete, planMetadata}. 2.1 changes how a plan that stops is reported, so plans can be recovered.

  • A plan that pauses arrives as phase: "plan_interrupted". planMetadata.interruptReason is Shutdown (the Gateway stopped), TurnTimeLimit, BudgetExceeded or Recovery. A budget stop also carries costUsd and budgetUsd (the cap in force now) and, when the token limit tripped, tokensUsed and tokenBudget.
  • A budget stop is now plan_interrupted, not plan_failed. A client that treated it as a failure will miss the Continue with a new budget action.
  • A cancelled plan is still plan_failed, now with planMetadata.cancelCause: UserStop, Superseded (a newer message replaced the turn), HostShutdown, TurnTimeLimit, ContinuedAsRetry (a continuation took over its remaining steps) or Unspecified (no cause was recorded). When a continuation exists, continuationRunId names it.
  • A continuation run carries retryOfRunId on its events, and a step kept from the earlier run is marked carried: true.

Recovery itself is REST: POST /api/graph-runs/{id}/resume, /retry and /cancel (see REST API). Events are not replayed after a reconnect, so a client that reloads should read the newest events with GET /api/sessions/{id}/events?window=latest and the session's runs with GET /api/graph-runs?sessionId=…&kind=plan.

Feature tokens

GET /api/system/info (no sign-in needed) returns features, a list of the contract versions this Gateway serves. Check a token before you call a method or rely on a field that a 2.0 Gateway does not have.

TokenWhat it covers
modelRouting.v1GetSessionModelRouting, SetSessionModelRouting, SessionModelRoutingChanged, and routing on turn events
embeddings.v1The /api/models/embeddings/* routes
usage.v1Usage fields on turn events, stopCause, and sessionUsage in GetSessionActivity
agentActivity.v1AgentActivity and the extra SubAgentStarted/SubAgentCompleted fields
agentStop.v1StopChildAgent
sessionActivity.v1GetSessionActivity
toolCallUpdate.v1, toolCallHistory.v1, approvalToolCallId.v1Tool-call events and history
workspace.v1, codingTools.v1, projectInstructions.v1, permissionModes.v1, planMode.v1, todos.v1The coding agent's workspace, modes and plan tools
approvalPreview.v1, approvalV2.v1, toolGrants.v1, commandPrefixRules.v1, connectionElevation.v1Approval previews, standing rules and elevation
sessionChanges.v1, rewind.v1Edit history and rewind

Session scoping

As of 1.11.0, JoinSession(sessionId) is the primary subscription mechanism, and per-task events target the session group instead of broadcasting user-wide:

  • Clients are auto-joined to sessions they create — sending the first message on a new session subscribes you implicitly.
  • Ownership is validated on every join — a client can only join sessions owned by its user (and tenant). The Canvas (whiteboard) hub validates session ownership on join the same way.
  • Legacy clients that never call JoinSession fall back to user-wide events, so older integrations keep working unchanged.

This is what keeps multiple devices from interfering: a Dashboard tab watching one session never receives another session's stream chunks, and approvals shown in the CLI aren't disturbed by activity on other devices. Devices not joined to a session still learn about its activity via SessionNotification.

SessionNotification

SessionNotification is a lightweight, user-wide activity event — every connected device receives it, whether or not it has joined the session:

FieldMeaning
sessionIdThe session with activity
kindWhat happened — one of the seven kinds below
refIdID of the thing the event refers to (task, approval, or info request)
successOutcome flag, where the kind has one (e.g. false on taskFailed)
excerptShort content excerpt, when one is available
timestampWhen the event occurred
KindFires when
taskStartedA task begins running
taskCompletedA task finishes successfully
taskFailedA task errors
taskCancelledA task is cancelled
approvalPendingAn approval is waiting for a decision
infoRequestPendingThe agent is waiting on a user answer
heartbeatActionedA heartbeat run took action — see Heartbeat

The excerpt gives clients a short preview to render; full message content and detail still require JoinSession or REST. Clients use the event to update unread badges and pending-approval counters. The Desktop app's native notifications are driven by this event.

Voice

A voice session is opened with VoiceStart(sessionId?, agentId). It attaches your connection to the chat session's group and to its voice group, then returns the chat session id it settled on. Several connections can attach to the same voice session, which is why replies reach every open tab and survive a reconnect (reconnecting mints a new connection id, so the client re-invokes VoiceStart).

Server → client voice events. Transcript events are addressed to the one connection streaming the audio; everything else goes to the session's voice group:

EventPayloadMeaning
VoiceUtteranceStarted{sessionId, utteranceId}A new utterance is open (connection-addressed)
VoiceInterimTranscript{sessionId, utteranceId, text}Partial transcript; each interim replaces the previous one (connection-addressed)
VoiceFinalTranscript{sessionId, utteranceId, text, confidence}Committed utterance (connection-addressed)
VoiceStatus{sessionId, status}Session state: listening, thinking, speaking, idle, expired
VoiceAudioChunk{sessionId, audioBase64, chunkIndex, isLast}Synthesized reply audio, chunk by chunk
VoiceNativeTtsRequested{sessionId, text, language}No provider audio for this reply — speak it with the client's own speech synthesis
VoiceProviderFallback{sessionId, reason}Why provider speech isn't being used for this reply
VoiceTranscript{sessionId, text, isAgent}Transcript line for the voice UI — the user's own words, or the agent's reply
VoiceError{sessionId, error}Voice or transcription failure

Two VoiceStatus rules changed in 2.0 and matter to custom clients:

  • VoiceStatus is no longer sent when a speech-to-text stream opens. The producer was removed. A client that treated VoiceStatus{listening} from the speech-to-text path as "the mic is open" must stop; open the mic on its own action instead.
  • A VoiceStatus of listening after a turn means the reply is finished — that is the signal to re-arm the mic, together with playback having finished on the client side.

StreamAudio

StreamAudio(sessionId, audioChunks, mode) is a client-to-server streaming method for realtime speech-to-text. SignalR matches by positional arity, so all three parameters are always sent:

import { Subject } from "@microsoft/signalr";

const audioChunks = new Subject<string>();
await connection.send("StreamAudio", sessionId, audioChunks, "auto");

// feed base64-encoded PCM chunks as the mic produces them
audioChunks.next(base64Chunk);
// manual mode: end the utterance explicitly
audioChunks.complete();
  • Audio format — 16 kHz mono linear16 PCM, base64-encoded per chunk. This works over the standard SignalR JSON protocol; no binary transport is required.
  • mode: "auto" (the default for any unrecognised value) — hands-free. The end of the utterance is detected for you: natively where the provider supports it, otherwise by a server-side silence detector, so hands-free works with any active provider.
  • mode: "manual" — push-to-talk; the client ends the stream by completing it.
  • mode: "answer" (new in 2.0) — the server transcribes and returns the final transcript, but runs no agent turn and does not resolve the pending prompt. The client matches the transcript to an answer itself and then calls RespondToApproval or RespondToInfoRequestV2. Use it for a capture opened to answer an approval or a question, so answering never spawns a chat turn.

Mode matching is case-insensitive. The arity is unchanged, so a client that only ever sent "auto" or "manual" keeps working untouched.

Utterance ids

Every transcript now carries an utteranceId, announced first by VoiceUtteranceStarted. A client should accept a final transcript only for the most recently announced utterance and drop the rest — that is what keeps a slow transcription of something you said earlier from being taken as your answer to the next question.

This is advisory, not enforced: a client that ignores VoiceUtteranceStarted and forwards every final keeps working exactly as before. It also only applies to server-side speech-to-text — a client using its own browser recognition never sees an announcement, so it has nothing to match against.

In auto and manual modes the committed utterance enters the agent pipeline like a typed message; in answer mode it does not. See Voice for provider setup and per-user listening preferences.

Approvals and questions

Approval and question events ride this hub. They are sent to the request's session group, to the escalation root's session group when the request was raised in a child session, and to the user group when the request has no session.

ApprovalResolved tells every surface an approval is no longer pending — decided on a chat card, over REST, from a channel reply, by voice, in another tab, by timeout, or by a cancelled run — so an open card or a waiting voice prompt stops asking:

FieldMeaning
idThe approval
outcomeapproved | rejected | timed_out | cancelled
sessionIdThe session the approval belongs to
escalationSessionIdThe escalation root's session, when the approval was raised in a child session

cancelled is not a decision: it is written when the caller's own wait ends (the chat's Cancel, a cancelled plan or step) or when a graph run is cancelled while one of its approval gates is still pending. Before 2.0 that case was recorded and announced as timed_out. An approval that ends without a decision is still never treated as an approval.

InfoRequestAnswered gained the matching field: a cancelled question now carries cancelled: true with timedOut: false, so a client can tell a cancel from a real expiry. The caller-facing answer shape is unchanged.

Node hub (/hubs/node)

Bidirectional command channel between the Gateway and Sophon Nodes. Nodes connect as clients.

Gateway → Node (methods Nodes implement):

MethodPayload
ExecuteCommand{commandId, command, params} — Node runs it, returns result
RefreshScopes{scopes} — update permission scopes without reconnect
RevokeAccess{} — force disconnect

Node → Gateway:

MethodPayload
Heartbeat{nodeId, status, uptime} — every 30 s
CommandResult{commandId, ok, result, error?} — response to ExecuteCommand
ScopeChanged{scopes} — ack of RefreshScopes

See Sophon Node for command semantics and Node Protocol for field schemas.

Workflow runs

Workflow run events arrive on /hubs/chat, addressed to the user group of the user the run executes as (the workflow's owner) in the run's tenant, and also to the user who started the run when that is someone else. They never go to all clients or to an Admin group, so an Admin gets no live events for other users' runs; read those over REST. Filter by runId or workflowId.

EventPayloadMeaning
WorkflowRunUpdated{kind, runId, workflowId, rootRunId, parentRunId, run, node}New in 2.2. A stored run or step changed
WorkflowProgressstarted, completed / failed, run summary; each ends with runIdDeprecated since v2.2.0, removed in v2.3.0. Sent beside WorkflowRunUpdated, never instead

kind is runStarted, nodeUpdated or runCompleted. run is the run summary the run list routes return (status, trigger kind, counts, tokens, costUsd, a redacted error). node is null except on nodeUpdated, where it carries the step run: id, nodeId, nodeType, nodeLabel, iterationPath, attempt, sequence, status, skipReason, effect, carried, unresolvedExpressions, outputPreview (redacted, at most 500 characters), outputTruncated, outputBytes, tainted, error, timestamps, durationMs, approvalId, childRunId, model, inputTokens, outputTokens and costUsd. Events never carry the definition, inputs, resolved inputs, variables or a full output; fetch GET /api/workflow-runs/{runId} for those.

conn.on("WorkflowRunUpdated", (e) => {
  if (e.kind === "nodeUpdated") console.log(e.node.nodeId, e.node.status);
  if (e.kind === "runCompleted") console.log("Run", e.runId, e.run.status);
});

Events are sent from one bounded queue that drops the oldest when full, without throttling, and are not replayed after a reconnect. Refetch the run on reconnect, on a gap in a step's sequence, and on runCompleted. A run marked Interrupted by a restart sends no event.

Breaking in v2.2.0

WorkflowProgress now reaches only the run's user and the user who started it, gains runId, and is removed in v2.3.0. Register a WorkflowRunUpdated handler, a no-op at minimum.

Removed in v2.2.0: discussion events

Discussions were removed in v2.2.0. The Discussion* events (DiscussionStarted through DiscussionCancelled) are no longer sent, and the CancelDiscussion hub method is gone. Remove their handlers; the REST routes answer 410 (see REST API).

Groups

SignalR groups are the mechanism for user / tenant / session scoping. As of 1.11.0, all group names are tenant-qualified — session groups are scoped to the tenant that owns the session, and user groups are prefixed with the tenant ID. A shared Gateway hosting multiple tenants can never deliver one tenant's events to another tenant's connections. See Tenants & Multi-Tenancy.

GroupScope
User groupUser-wide events for one user in one tenant (SessionNotification, session list updates, workflow run events)
Session groupEvery event in one chat session — joined via JoinSession, ownership-validated
Voice groupVoice delivery for one chat session — joined by VoiceStart, left by VoiceEnd; this is why every attached tab hears the reply
Canvas groupCanvas frames for one session, on the canvas hub
Node groupCommand / heartbeat events for one node, on the node hub

Clients are auto-joined to their user group on connect and to session groups for sessions they create. Group names are server-internal — clients only ever pass IDs (sessionId, runId) to subscribe methods.

Reconnection

SignalR's withAutomaticReconnect() handles network blips. Reconnection retries with exponential backoff (0 ms, 2 s, 10 s, 30 s, then every 30 s).

On reconnect:

  • Subscriptions are re-established (groups rejoined)
  • Missed events are not replayed — use REST to catch up (e.g., GET /tasks/{id} for task state)
  • Streaming tasks that were in flight continue; the client sees a possibly-incomplete stream followed by TaskCompleted once the task finishes

Rejoining mid-task: after JoinSession, fetch the persisted message (GET /sessions/{id}/messages) and replace any partial stream buffer with it — appending renders duplicated text. Guard for staleness: the probe may discover the task already finished while you were reconnecting; in that case render the final message and don't re-arm any waiting or streaming state. The Dashboard and Mobile apps do this automatically.

Backpressure

Server buffers outgoing events per-connection (default: 100 events). Beyond that, the slowest consumer is dropped. This prevents a slow client from OOMing the Gateway.

The mobile app and Dashboard rarely hit this. Custom SignalR clients that can't keep up should either fan out to a queue or switch to polling REST.

Transport selection

Preference order:

  1. WebSockets — default; lowest latency, bidirectional
  2. Server-Sent Events — for browsers that block WebSockets
  3. Long polling — fallback for restrictive proxies

The Gateway also exposes a node-token command queue over plain HTTP (GET /api/nodes/me/commands), but the shipped Sophon Node connects over the hub — it does not fall back to polling.

Client examples

TypeScript (browser)

import { HubConnectionBuilder } from "@microsoft/signalr";

const conn = new HubConnectionBuilder()
  .withUrl("https://gw.example.com/hubs/chat", { accessTokenFactory: () => jwt })
  .withAutomaticReconnect()
  .build();

conn.on("StreamChunk", (c) => process.stdout.write(c.content));
conn.on("TaskCompleted", (c) => console.log("\nDone. Cost:", c.costUsd ?? "unknown"));

await conn.start();
await conn.invoke("SendMessage", sessionId, "hi", "default");

.NET / C#

var conn = new HubConnectionBuilder()
  .WithUrl("https://gw.example.com/hubs/chat", o => o.AccessTokenProvider = () => Task.FromResult(jwt))
  .WithAutomaticReconnect()
  .Build();

conn.On<StreamChunkEvent>("StreamChunk", c => Console.Write(c.Content));
await conn.StartAsync();
await conn.InvokeAsync("SendMessage", sessionId, "hi", "default");

Python (signalrcore)

from signalrcore.hub_connection_builder import HubConnectionBuilder

hub = (HubConnectionBuilder()
  .with_url(f"https://gw.example.com/hubs/chat?access_token={jwt}")
  .with_automatic_reconnect()
  .build())

hub.on("StreamChunk", lambda msg: print(msg[0]["content"], end=""))
hub.start()
hub.send("SendMessage", [sid, "hi", "default"])

Where to go next

  • REST API — everything SignalR doesn't stream
  • Node Protocol — the Node-specific hub contract
  • Webhooks — for consumers that prefer push over WebSockets
  • Voice — speech provider configuration and listening preferences behind StreamAudio