Introduction to Voisnap's real-time SignalR hubs — VoiceHub and ChatHub — and when to use each.

Real-Time APIs

Voisnap exposes real-time WebSocket interfaces built on SignalR (ASP.NET Core's real-time library). Both hubs run over wss:// WebSocket connections.

Building a fully custom web widget? The @voisnap/widget-core package ships typed hub contracts, reference clients, and the Web-Audio PCM helpers — so you don't re-derive the protocol below by hand.

The hubs

Hub	URL	Use case
VoiceHub	`wss://api.voisnap.ai/hubs/voice`	Stream raw PCM audio for phone calls, PSTN, SIP, and browser-based voice widgets
ChatHub	`wss://api.voisnap.ai/hubs/chat`	Real-time text chat exchange (web chat widget)

When to use each

VoiceHub

Use VoiceHub when you're building a custom telephony integration, embedding the browser voice widget, or need direct PCM audio access. The standard phone channel (Twilio/Vonage/Telnyx) and the web voice widget both connect to VoiceHub. You'd use it directly only for custom SIP integrations or building your own audio pipeline.

ChatHub

Use ChatHub for text-based web chat embedded in a website or app. It handles turn-by-turn text messages, typing indicators, and session lifecycle without any audio.

Authentication

Both hubs require a JWT access token passed as a query parameter:

wss://api.voisnap.ai/hubs/voice?agentId=agt_01HXK8Z3MNPQRS&access_token=eyJhbGci...

:::warning API keys cannot be used for real-time hub connections — only JWT access tokens. Obtain a short-lived token via POST /api/v1/auth/login or the JS SDK's getAccessToken() helper. :::

Connection lifecycle

Both hubs follow the same lifecycle:

Client connects (WebSocket handshake)
         ↓
Hub authenticates token (401 if invalid)
         ↓
Hub emits SessionStarted
         ↓
Bidirectional exchange (audio/messages)
         ↓
Either party calls EndSession / disconnects
         ↓
Hub emits SessionEnded
         ↓
WebSocket closes

SignalR client libraries

Use the official SignalR client library for your platform:

# Browser / Node.js
npm install @microsoft/signalr

# Python
pip install signalrcore

# .NET
dotnet add package Microsoft.AspNetCore.SignalR.Client

Error codes

Both hubs can emit an Error event with a structured error:

{
  "code": "AGENT_NOT_FOUND",
  "message": "No agent with ID agt_01HXK8Z3MNPQRS found.",
  "recoverable": false
}

Code	Description
`AGENT_NOT_FOUND`	Agent ID does not exist
`AGENT_INACTIVE`	Agent is not activated
`AUTH_FAILED`	JWT is invalid or expired
`STT_PROVIDER_TIMEOUT`	Speech-to-text did not respond in time
`LLM_PROVIDER_ERROR`	LLM request failed
`SESSION_LIMIT_REACHED`	Max concurrent sessions for your plan
`RECONNECT_FAILED`	Could not reconnect within retry window

Real-Time Overview