Skip to main content
For low-latency agents, open a WebSocket and Sentvia pushes your events the moment they happen — no webhook endpoint required.

​
Connect

wss://api.sentvia.ai/v1/realtime?token=sv_live_…
Authentication is the token query parameter (a WebSocket handshake can’t set headers), using the same API key as the REST API. 
const ws = new WebSocket(`wss://api.sentvia.ai/v1/realtime?token=${process.env.SENTVIA_KEY}`);

ws.onmessage = (e) => {
  const frame = JSON.parse(e.data);
  if (frame.event === "connected") return;        // handshake ack
  if (frame.event === "message.received") {
    console.log("New email:", frame.data.message.subject);
  }
};

​
Frames

The first frame acknowledges the connection: 
{ "event": "connected", "data": { "tenant_id": "…" } }
After that, every event is pushed as { event, data }, where data carries the same fields as the corresponding webhook payload: 
{
  "event": "message.received",
  "data": {
    "inbox_id": "…",
    "thread_id": "…",
    "message": { "id": "…", "from": "…", "subject": "…", "text": "…", "attachments": [] }
  }
}
The event names match webhooks: message.received, message.delivered, message.bounced, message.complained, message.rejected.
Realtime frames nest the payload under data; webhooks deliver the same fields flat alongside event. Read frame.data.* over the socket.

​
Reconnecting

If the socket drops, reconnect and resume. The stream is live-only (it doesn’t replay missed events), so for guaranteed delivery pair it with a webhook or reconcile with GET /messages on reconnect.

​
Realtime vs webhooks

Realtime (WebSocket)Webhooks
LatencyInstant pushInstant push
Needs a public URLNoYes
Guaranteed delivery / retriesNo (live-only)Yes (retried)
Best forInteractive agents, live UIsReliable server-side processing
Many apps use both — a webhook for durable processing and the WebSocket for a live view.