Real-time events

Polling GET /calls/{callId} every second tells you a call ended about a second late and costs you a request a second per call. The event stream tells you the moment it happens, and gives you what polling can’t: the transcript as it’s spoken, each function call and agent transition as it occurs. It’s the same feed the dashboard runs on, exposed over a WebSocket you authenticate with an API key.

What you can subscribe to

Connecting

Open a WebSocket to wss://api.talkif.ai/api/v1/ws/events with your API key as a Bearer token in the Authorization header. The key needs the calls scope. Then send subscribe frames — one with no call_id for the account stream, one per call for conversation streams.

{ "type": "subscribe" }
{ "type": "subscribe", "call_id": "018f4e9e-…", "replay": true }
{ "type": "unsubscribe", "call_id": "018f4e9e-…" }
{ "type": "ping" }

Every server frame is an envelope:

{
  "v": 1,
  "type": "transcript",
  "call_id": "018f4e9e-…",
  "seq": 42,
  "ts": 1757700000123,
  "data": { "role": "user", "content": "I'd like to book a cleaning.", "timestamp": 12.4, "turnNumber": 3 }
}

• seq is per connection and monotonic. A gap means this connection dropped droppable frames under backpressure — not that something happened out of order globally.
• Control frames use the same envelope: subscribed / unsubscribed (with the call_id, if any) confirm your subscribe frames; pong answers ping.

import WebSocket from "ws";
const ws = new WebSocket("wss://api.talkif.ai/api/v1/ws/events", {
  headers: { Authorization: `Bearer ${process.env.TALKIF_API_KEY}` },
});
ws.on("open", () => ws.send(JSON.stringify({ type: "subscribe" })));
ws.on("message", (raw) => {
  const frame = JSON.parse(raw.toString());
  if (frame.type === "call.ended") {
    const { callId, endReason, duration, cost } = frame.data;
    // update your CRM: callId, endReason, duration, cost
  }
});

Joining late: replay

Subscribing to a call with "replay": true streams the call’s history first — every event so far, in order — then continues live. A consumer that connects halfway through a call, or restarts, still gets the whole transcript. Live events that arrive during the replay may appear twice; if that matters, de-duplicate on the event’s own identity (turn number, timestamp) rather than on seq.

Keeping the connection healthy

Design for reconnection from the start: one long-lived connection per service instance, subscribe on open, re-subscribe after any close. Don’t open a connection per call.

Next