Real-Time APIs

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

---

The three hubs

Hub	URL	Use case
VoiceHub	wss://api.voisnap.ai/hubs/voice	Stream raw PCM audio for phone calls, PSTN, SIP
ChatHub	wss://api.voisnap.ai/hubs/chat	Real-time text chat exchange (web chat widget)
WebRtcHub	wss://api.voisnap.ai/hubs/webrtc	WebRTC signaling (SDP + ICE) for browser voice

---

When to use each

VoiceHub

Use VoiceHub when you're building a custom telephony integration or need direct PCM audio access. The standard phone channel (Twilio/Vonage/Telnyx) connects to VoiceHub automatically. 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.

WebRtcHub

Use WebRtcHub to embed browser voice calls into your web application. The user speaks directly via their microphone — no phone number required. Voisnap handles the WebRTC SDP negotiation and connects to the agent's audio pipeline.

---

Authentication

All three 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

All 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

All 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