Real-Time Events

Talkif uses Server-Sent Events (SSE) to push updates to the dashboard in real-time. No polling — all changes appear instantly.

Event types

Event	Description
`call-created`	New call initiated — payload is the full call object
`call-status`	Call status changed — minimal payload (call ID, status, direction, phones)
`call-ended`	Call reached terminal state — includes `end_reason`
`call-recording-status`	Call recording status changed
`balance-updated`	Credit balance changed
`payment-required`	Payment action needed (e.g. insufficient balance)
`notification`	New notification
`campaign-status-changed`	Campaign state changed
`campaign-progress`	Campaign progress updated
`schedule-status-changed`	Schedule state changed
`schedule-executed`	Scheduled call executed
`data-export-status`	Data export status changed

Call event payloads

call-created events carry the full call response object. call-status carries a minimal status update with the call ID, status, direction, source, and phone numbers.

call-ended includes additional fields for diagnostics:

Field	Type	Description
`end_reason`	`string \| null`	Why the call ended — see end reasons
`failure_code`	`string \| null`	Technical failure category (only when call failed)
`failure_reason`	`string \| null`	Human-readable failure description
`duration`	`number`	Call duration in seconds
`cost`	`number`	Call cost in USD
`recording_url`	`string \| null`	Recording URL (if recorded)

Call stream events

Subscribe to a specific call to receive real-time stream events. These require an explicit subscription via POST /calls/{callId}/subscribe.

Event	Description
`call-transcript`	New transcript segment
`call-interim`	Interim (partial) transcript
`call-tts`	Text-to-speech audio generated
`call-tts-word`	TTS word timing marker
`call-speech`	Speech audio segment
`call-turn`	Conversation turn completed
`call-node-transition`	Flow node transition
`call-recording`	Recording status update
`call-error`	Error during the call

Unsubscribe with POST /calls/{callId}/unsubscribe when no longer needed.

Connecting

SSE connections use ticket-based authentication:

Request a ticket: POST /api/v1/auth/sse-ticket
Connect: GET /api/v1/sse/connect?ticket={ticket}

The ticket is single-use. On connection, you receive a connected event with your clientId — use this for subscription management. The server sends a keep-alive every 15 seconds.

The server may also send shutdown (with reconnect: true) during graceful restarts, and lag-warning if your client falls behind.

What updates live

Call status — ringing, in-progress, completed, failed
Active call count — current number of concurrent calls
Credit balance — updates in real-time during calls
Notifications — appear instantly in the notification panel
Campaign progress — contact completion and state changes

The dashboard maintains a persistent SSE connection. If the connection drops, it automatically reconnects.