Events

Real-time event streaming for workspace activity and call observation.

The Platform API streams real-time events over two channels:

• Workspace SSE stream - server-sent events covering call lifecycle, surface activity, operator actions, and pipeline status

• Observer WebSocket - per-call observation events including transcripts, tool execution, and call forwarding

Workspace SSE Stream

Connect to the workspace event stream to receive real-time notifications about activity in your workspace. Events are delivered as server-sent events (SSE) with a typed event_type discriminator field.

Event Types

Call Events

Event Type	Description	Key Fields
call.started	A call has started	call_sid, direction, service_id, caller_id
call.ended	A call has ended	call_sid, direction, duration_seconds, completion_reason, escalated
call.escalated	A call was escalated to a human operator	call_sid, escalation_id, trigger, reason

Surface Events

Event Type	Description	Key Fields
surface.created	A new surface was created	surface_id, entity_id, channel, fields_count
surface.delivered	A surface was delivered to the recipient	surface_id, entity_id, channel, delivery_status
surface.updated	A surface was updated	surface_id
surface.archived	A surface was archived	surface_id
surface.reshaped	A surface was reshaped from an existing surface	surface_id, original_surface_id
surface.submitted	A surface was submitted by the recipient	surface_id, entity_id, submitted_at
surface.field_saved	A single field was saved on a surface	surface_id, entity_id, field_id
surface.opened	A surface was opened by the recipient	surface_id, entity_id
surface.pending_review	A surface is pending review	surface_id, entity_id
surface.review_approved	A surface review was approved	surface_id
surface.review_rejected	A surface review was rejected	surface_id, reason

Operator Events

Event Type	Description	Key Fields
operator.registered	A new operator was registered	operator_id, timestamp
operator.status_changed	An operator's status changed	operator_id, status
operator.profile_updated	An operator's profile was updated	operator_id, changes
operator.joined_call	An operator joined a call	call_sid, operator_id, mode
operator.left_call	An operator left a call	call_sid, operator_id
operator.mode_changed	An operator's mode changed during a call	call_sid, operator_id, mode
operator.wrap_up	A call entered wrap-up	call_sid, wrap_up_reason

Pipeline Events

Event Type	Description	Key Fields
pipeline.sync_completed	A data source sync completed	data_source_id, event_count, duration_ms
pipeline.error	A pipeline error occurred	data_source_id, error

Discriminated Unions in the SDK

The OpenAPI specification includes typed schemas for all event types as a discriminated union on the event_type field. SDK clients generated from the spec (such as the TypeScript SDK) receive full type safety when handling events:

// TypeScript SDK example - exhaustive event handling
switch (event.event_type) {
  case "call.started":
    console.log(`Call ${event.call_sid} started`);
    break;
  case "surface.created":
    console.log(`Surface ${event.surface_id} created for entity ${event.entity_id}`);
    break;
  // ... other event types
}

Observer Events

Observer events are delivered over the call observation WebSocket and provide real-time visibility into an active call. These events use a type discriminator field.

Event Type	Description	Key Fields
user_transcript	Caller speech transcription	transcript, state, speaker_id, speaker_role
agent_transcript	Agent speech output	transcript, action, interrupted, streaming
tool_call_started	A tool began executing	tool_name, tool_input
tool_call_completed	A tool finished executing	tool_name, output, succeeded, duration_ms, error
forward_call_resolved	A call forwarding target was resolved	target_number, location_name, result, error
speaker_muted	A speaker's mute state changed	muted