Observer Events

Real-time event types delivered over the observer WebSocket connection during a voice session.

The observer WebSocket delivers real-time events during a voice session. Each event has a type field that identifies it. Clients can use this field as a discriminator to handle events with type safety.

Event Types

Channel Email Events

Email delivery status events are published to the workspace SSE stream when email is sent through a use case channel. These events let you track delivery outcomes in real time.

Event Type	Description	Fields
channel.email_delivered	Email successfully delivered	email_id, to_address, from_address
channel.email_bounced	Email bounced	email_id, to_address, from_address, bounce_type, bounce_subtype
channel.email_complained	Recipient filed a spam complaint	email_id, to_address, from_address
channel.email_rejected	Email rejected before delivery	email_id, to_address, from_address
channel.email_delayed	Delivery delayed, retrying	email_id, to_address, from_address
channel.email_opened	Recipient opened the email	email_id, to_address
channel.email_clicked	Recipient clicked a link	email_id, to_address

The to_address field is marked as PHI and subject to data access controls.

Channel email events are emitted automatically when the platform receives delivery status updates from the email provider. No additional configuration is required beyond creating a use case with an email channel.

The observer stream includes 20 event types grouped by category.

Session Lifecycle

Event Type	Description	Key Fields
session_info	Session metadata sent on connect	call_sid, service_id, workspace_id, current_state, direction, duration_seconds
session_start	Marks the beginning of a session	call_sid, session_id, service_id, workspace_id, initial_state, mode
session_end	Marks the end of a session	call_sid, session_id, duration_s, turns, completion_reason, final_state, has_recording

Transcripts

Event Type	Description	Key Fields
user_transcript	Caller speech, finalized	text, is_final, confidence
agent_transcript	Agent speech, finalized	text, state, filler_type (optional)
agent_transcript_delta	Incremental agent speech token	delta

State and Navigation

Event Type	Description	Key Fields
state_transition	Agent moved between context graph states	previous_state, next_state, transition_type, annotation

Tools

Event Type	Description	Key Fields
tool_call_started	A tool call began	tool_name, tool_call_id, parameters
tool_call_completed	A tool call finished	tool_name, tool_call_id, result

Latency and Timing

Event Type	Description	Key Fields
latency	End-to-end latency breakdown	e2e_ttfb_ms, engine_ms, nav_ms, render_ms, audio_ttfb_ms, continuation, is_greeting
nav_timing	Navigation and render timing detail	nav_ms, render_ms, total_ms, input_tokens, output_tokens, model, state, retry_attempts, used_fallback, selected_action

Emotion and Empathy

Event Type	Description	Key Fields
emotion	Caller emotion analysis	dominant, valence, arousal, trend, coherence, scores, speaker (acoustics)
compound_emotion	Blended emotion scores for a turn	compounds (list of name/score pairs), turn_index
empathy_classified	Empathy tier selection	tier, tier_name, should_pause, suppress_filler, filler_type, empathy_baseline

Barge-In and Participants

Event Type	Description	Key Fields
barge_in	Caller interrupted the agent	interrupted_text, discarded_texts, total_barge_ins
participant_joined	A participant entered the conference	participant_id, participant_role, conference_sid
participant_left	A participant left the conference	participant_id, participant_role, conference_sid

Call Control

Event Type	Description	Key Fields
forward_call_resolved	Call forwarding completed	forward_number, result
speaker_muted	Speaker mute state changed	muted

Voice Context

Event Type	Description	Key Fields
voice_context_applied	Voice parameters updated	tts_emotion, tts_speed, tts_volume, filler_enabled, emotion_detection_enabled, reasoning

Common Fields

All observer events inherit these base fields:

Field	Type	Description
type	string	Event type discriminator
timestamp	string	ISO 8601 timestamp
call_id	string	Call identifier

Participant Roles

The participant_joined and participant_left events use a participant_role field with these values:

Role	Description
caller	The end user on the call
agent	The AI voice agent
operator	A human operator who joined via escalation

Empathy Tiers

The empathy_classified event includes a tier_name field with these values:

Tier Name	Description
FUNCTIONAL	Standard conversational tone
LIGHT_TOUCH	Brief acknowledgment of caller emotion
FULL_EMPATHY	Extended empathetic response
HOLD_SPACE	Pause and hold space for the caller

Emotion Trends

The emotion event includes a trend field indicating the direction of the caller's emotional state:

Trend	Description
improving	Caller emotion is trending more positive
stable	Caller emotion is not changing significantly
deteriorating	Caller emotion is trending more negative

Handling Unknown Events

New event types may be added in future releases. Clients should ignore event types they do not recognize rather than treating them as errors. This ensures forward compatibility as the observer stream is extended.