Realtime (WebSocket)

For low-latency agents, open a WebSocket and SentFromAI pushes your events the moment they happen — no webhook endpoint required.

Connect

wss://api.sentfrom.ai/v1/realtime?token=sf_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.sentfrom.ai/v1/realtime?token=${process.env.SENTFROMAI_API_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);
  }
};

import json, os, websockets, asyncio

async def main():
    url = f"wss://api.sentfrom.ai/v1/realtime?token={os.environ['SENTFROMAI_API_KEY']}"
    async with websockets.connect(url) as ws:
        async for raw in ws:
            frame = json.loads(raw)
            if frame["event"] == "message.received":
                print("New email:", frame["data"]["message"]["subject"])

asyncio.run(main())

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
Latency	Instant push	Instant push
Needs a public URL	No	Yes
Guaranteed delivery / retries	No (live-only)	Yes (retried)
Best for	Interactive agents, live UIs	Reliable server-side processing

Many apps use both — a webhook for durable processing and the WebSocket for a live view.

Get started

Core concepts

Guides

Examples

Agent frameworks

DNS guides

Troubleshooting

Realtime (WebSocket)

Connect

Frames

Reconnecting

Realtime vs webhooks

​Connect

​Frames

​Reconnecting

​Realtime vs webhooks

Connect

Frames

Reconnecting

Realtime vs webhooks