Real-time Call Events

The /events endpoint provides real-time Server-Sent Events (SSE) streaming for active calls, allowing you to monitor conversation flow, transcription updates, workflow transitions, and performance metrics as they happen.

Endpoint Overview

URL: GET /events
Protocol: Server-Sent Events (SSE)
Authentication: Bearer Token
Content-Type: text/event-stream

title: “Real-time Events Stream” description: “Complete guide to consuming Server-Sent Events from the /events API endpoint” icon: “bolt” # Add this line with your preferred icon

Real-time Call Events

Endpoint Overview

URL: GET /events
Protocol: Server-Sent Events (SSE)
Authentication: Bearer Token
Content-Type: text/event-stream

Request Parameters

Parameter	Type	Required	Description
`callId`	string	Yes	The unique identifier for the call to monitor

Authentication

Include your API token in the Authorization header:

Authorization: Bearer your_api_token

Connection Examples

cURL

curl 'https://atoms-api.smallest.ai/api/v1/events?callId=CALL-1758124225863-80752e' \
  -H 'Authorization: Bearer your_token' \
  -H 'Accept: text/event-stream'

JavaScript (Node.js)

const EventSource = require("eventsource");

const eventSource = new EventSource(
  "https://atoms-api.smallest.ai/api/v1/events?callId=CALL-1758124225863-80752e",
  {
    headers: {
      Authorization: "Bearer your_token",
    },
  }
);

eventSource.onmessage = function (event) {
  const data = JSON.parse(event.data);
  console.log("Event received:", data.event_type, data);
};

eventSource.onerror = function (error) {
  console.error("SSE Error:", error);
};

Event Types Reference

Connection Events

SSE Initialization

Sent when the SSE connection is established.

{
  "event_type": "sse_init",
  "event_time": "2025-09-17T15:51:44.234Z"
}

SSE Connection Close

Sent when the connection is terminated, with reason.

{
  "event_type": "sse_close",
  "event_time": "2025-09-17T15:51:44.234Z"
}

Call Lifecycle Events

Call Start

Indicates the beginning of a call session.

{
  "event_type": "call_start",
  "event_id": "CALL-1758124225863-80752e_1_1758124305194",
  "timestamp": 1758124305.194836,
  "observer_class": "generic_event_factory",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "telephony_id": "8671288e-654e-4a79-adde-5f4dc714e6ca"
}

Transcription Events

User Transcription (Final)

Final transcription of user speech.

{
  "event_type": "user_transcription",
  "event_id": "CALL-1758124225863-80752e_7_1758124311576",
  "timestamp": 1758124311.5769129,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "user_transcription_text": "Hello?"
}

User Interim Transcription

Partial transcription as user speaks (real-time).

{
  "event_type": "user_interim_transcription",
  "event_id": "CALL-1758124225863-80752e_16_1758124315037",
  "timestamp": 1758124315.0371158,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "interim_transcription_text": "Yes. You are."
}

Agent Workflow Events

Agent Node State

Indicates agent workflow state changes with complete context.

{
  "event_type": "agent_node_state",
  "event_id": "CALL-1758124225863-80752e_2_1758124312905",
  "timestamp": 1758124312.905344,
  "observer_class": "generic_event_factory",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "node_id": "10001",
  "node_name": "Start - Determine If Reached Owner or Gatekeeper",
  "node_type": "default",
  "context": {
    "user_response": "Hello?",
    "agent_response": "Hi, is this the business owner, or am I speaking with someone who handles business or funding questions for the owner?"
  }
}

Node Transitions (Hopping)

When the agent moves from one workflow node to another.

{
  "event_type": "hopping",
  "event_id": "CALL-1758124225863-80752e_3_1758124315508",
  "timestamp": 1758124315.5088089,
  "observer_class": "generic_event_factory",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "from_node_id": "10001",
  "to_node_id": "10002"
}

LLM Response Events

LLM Full Response End

Complete response generated by the language model.

{
  "event_type": "llm_full_response_end",
  "event_id": "CALL-1758124225863-80752e_12_1758124312905",
  "timestamp": 1758124312.905622,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "llm_text": "Hi, is this the business owner, or am I speaking with someone who handles business or funding questions for the owner?"
}

Text-to-Speech Events

TTS Completion

When text-to-speech generation finishes.

{
  "event_type": "tts_completed",
  "event_id": "CALL-1758124225863-80752e_5_1758124310717",
  "timestamp": 1758124310.717878,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "tts_latency": 5.713,
  "tts_text": " Hi, am I speaking with the business owner right now, or is this an assistant or gatekeeper?"
}

Performance Metrics

Turn Latency

Measures response time between user input and agent response.

{
  "event_type": "turn_latency",
  "event_id": "CALL-1758124225863-80752e_14_1758124313216",
  "timestamp": 1758124313.21611,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "turn_latency": 1.69
}

Service Metrics

Performance metrics for various processing components.

{
  "event_type": "metrics",
  "event_id": "CALL-1758124225863-80752e_2_1758124305004",
  "timestamp": 1758124305.0049212,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "metrics": [
    {
      "processor": "WavesTTSService#0",
      "model": "lightning-v2",
      "value": 0.0005438327789306641
    }
  ]
}

LLM Token Usage

Tracks token consumption and processing time for language model calls.

{
  "event_type": "metrics",
  "event_id": "CALL-1758124225863-80752e_39_1758124326438",
  "timestamp": 1758124326.438517,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "metrics": [
    {
      "processor": "AtomsConversationFlowAgentProcessor#0",
      "model": null,
      "value": {
        "prompt_tokens": 1292,
        "completion_tokens": 46,
        "total_tokens": 1338,
        "cache_read_input_tokens": null,
        "cache_creation_input_tokens": null
      }
    }
  ]
}

Common Event Fields

All events include these base fields:

Field	Type	Description
`event_type`	string	Type of event (see Event Types above)
`event_id`	string	Unique identifier for this specific event
`timestamp`	number	Unix timestamp with microsecond precision
`call_id`	string	The call this event belongs to

Connection Management

Connection Lifecycle

Establish Connection: Send GET request with valid call ID and auth token
Receive sse_init: Confirms connection establishment
Stream Events: Receive real-time events as they occur
Handle Disconnection: Connection closes when call ends or on error

Error Handling

Monitor for sse_close events which indicate connection termination:

{
  "event_type": "sse_close",
  "event_time": "2025-09-17T15:51:44.234Z"
}

Common error scenarios:

Call log not found: Invalid or non-existent call ID
Agent not found: Call ID valid but associated agent not accessible
Unauthorized: Invalid or expired authentication token
Error consuming events: Internal server error

Reconnection Strategy

Implement exponential backoff for reconnections:

let reconnectDelay = 1000; // Start with 1 second
const maxReconnectDelay = 30000; // Max 30 seconds

function reconnect() {
  setTimeout(() => {
    connectToEvents();
    reconnectDelay = Math.min(reconnectDelay * 2, maxReconnectDelay);
  }, reconnectDelay);
}

function onConnectionSuccess() {
  reconnectDelay = 1000; // Reset delay on successful connection
}

Real-world Usage Patterns

Live Call Dashboard

Monitor multiple calls simultaneously by establishing separate SSE connections for each active call.

Call Analytics

Process metrics events to build real-time performance dashboards showing:

Average response times
TTS processing latency
Token usage patterns
Conversation flow efficiency

Quality Monitoring

Track transcription accuracy and agent response appropriateness by monitoring:

user_transcription events for input quality
agent_node_state events for workflow adherence
llm_full_response_end events for response quality

Integration Webhooks

Combine SSE events with your existing webhook infrastructure to trigger actions based on real-time call events.

Troubleshooting

No Events Received:

Verify the call is currently active or recently completed
Check that the call ID format is correct: CALL-XXXXXXXXX-XXXXXX
Ensure your authentication token has access to the specified call

Connection Drops:

Implement automatic reconnection with exponential backoff
Monitor network connectivity
Check for authentication token expiration

Missing Event Types:

Some events only occur during specific call phases
Workflow events depend on agent configuration
Metrics events vary by enabled services

High Event Volume:

Implement client-side filtering for relevant event types
Use batching to process multiple events together
Consider sampling for high-frequency metrics events

Request Parameters

Parameter	Type	Required	Description
`callId`	string	Yes	The unique identifier for the call to monitor

Authentication

Include your API token in the Authorization header:

Authorization: Bearer your_api_token

Connection Examples

cURL

curl 'https://atoms-api.smallest.ai/api/v1/events?callId=CALL-1758124225863-80752e' \
  -H 'Authorization: Bearer your_token' \
  -H 'Accept: text/event-stream'

JavaScript (Node.js)

const EventSource = require("eventsource");

const eventSource = new EventSource(
  "https://atoms-api.smallest.ai/api/v1/events?callId=CALL-1758124225863-80752e",
  {
    headers: {
      Authorization: "Bearer your_token",
    },
  }
);

eventSource.onmessage = function (event) {
  const data = JSON.parse(event.data);
  console.log("Event received:", data.event_type, data);
};

eventSource.onerror = function (error) {
  console.error("SSE Error:", error);
};

Event Types Reference

Connection Events

SSE Initialization

Sent when the SSE connection is established.

{
  "event_type": "sse_init",
  "event_time": "2025-09-17T15:51:44.234Z"
}

SSE Connection Close

Sent when the connection is terminated, with reason.

{
  "event_type": "sse_close",
  "event_time": "2025-09-17T15:51:44.234Z"
}

Call Lifecycle Events

Call Start

Indicates the beginning of a call session.

{
  "event_type": "call_start",
  "event_id": "CALL-1758124225863-80752e_1_1758124305194",
  "timestamp": 1758124305.194836,
  "observer_class": "generic_event_factory",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "telephony_id": "8671288e-654e-4a79-adde-5f4dc714e6ca"
}

Transcription Events

User Transcription (Final)

Final transcription of user speech.

{
  "event_type": "user_transcription",
  "event_id": "CALL-1758124225863-80752e_7_1758124311576",
  "timestamp": 1758124311.5769129,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "user_transcription_text": "Hello?"
}

User Interim Transcription

Partial transcription as user speaks (real-time).

{
  "event_type": "user_interim_transcription",
  "event_id": "CALL-1758124225863-80752e_16_1758124315037",
  "timestamp": 1758124315.0371158,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "interim_transcription_text": "Yes. You are."
}

Agent Workflow Events

Agent Node State

Indicates agent workflow state changes with complete context.

{
  "event_type": "agent_node_state",
  "event_id": "CALL-1758124225863-80752e_2_1758124312905",
  "timestamp": 1758124312.905344,
  "observer_class": "generic_event_factory",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "node_id": "10001",
  "node_name": "Start - Determine If Reached Owner or Gatekeeper",
  "node_type": "default",
  "context": {
    "user_response": "Hello?",
    "agent_response": "Hi, is this the business owner, or am I speaking with someone who handles business or funding questions for the owner?"
  }
}

Node Transitions (Hopping)

When the agent moves from one workflow node to another.

{
  "event_type": "hopping",
  "event_id": "CALL-1758124225863-80752e_3_1758124315508",
  "timestamp": 1758124315.5088089,
  "observer_class": "generic_event_factory",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "from_node_id": "10001",
  "to_node_id": "10002"
}

LLM Response Events

LLM Full Response End

Complete response generated by the language model.

{
  "event_type": "llm_full_response_end",
  "event_id": "CALL-1758124225863-80752e_12_1758124312905",
  "timestamp": 1758124312.905622,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "llm_text": "Hi, is this the business owner, or am I speaking with someone who handles business or funding questions for the owner?"
}

Text-to-Speech Events

TTS Completion

When text-to-speech generation finishes.

{
  "event_type": "tts_completed",
  "event_id": "CALL-1758124225863-80752e_5_1758124310717",
  "timestamp": 1758124310.717878,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "tts_latency": 5.713,
  "tts_text": " Hi, am I speaking with the business owner right now, or is this an assistant or gatekeeper?"
}

Performance Metrics

Turn Latency

Measures response time between user input and agent response.

{
  "event_type": "turn_latency",
  "event_id": "CALL-1758124225863-80752e_14_1758124313216",
  "timestamp": 1758124313.21611,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "turn_latency": 1.69
}

Service Metrics

Performance metrics for various processing components.

{
  "event_type": "metrics",
  "event_id": "CALL-1758124225863-80752e_2_1758124305004",
  "timestamp": 1758124305.0049212,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "metrics": [
    {
      "processor": "WavesTTSService#0",
      "model": "lightning-v2",
      "value": 0.0005438327789306641
    }
  ]
}

LLM Token Usage

Tracks token consumption and processing time for language model calls.

{
  "event_type": "metrics",
  "event_id": "CALL-1758124225863-80752e_39_1758124326438",
  "timestamp": 1758124326.438517,
  "observer_class": "EventObserver",
  "call_id": "CALL-1758124225863-80752e",
  "source": "orchestrator",
  "metrics": [
    {
      "processor": "AtomsConversationFlowAgentProcessor#0",
      "model": null,
      "value": {
        "prompt_tokens": 1292,
        "completion_tokens": 46,
        "total_tokens": 1338,
        "cache_read_input_tokens": null,
        "cache_creation_input_tokens": null
      }
    }
  ]
}

Common Event Fields

All events include these base fields:

Field	Type	Description
`event_type`	string	Type of event (see Event Types above)
`event_id`	string	Unique identifier for this specific event
`timestamp`	number	Unix timestamp with microsecond precision
`call_id`	string	The call this event belongs to

Connection Management

Connection Lifecycle

Establish Connection: Send GET request with valid call ID and auth token
Receive sse_init: Confirms connection establishment
Stream Events: Receive real-time events as they occur
Handle Disconnection: Connection closes when call ends or on error

Error Handling

Monitor for sse_close events which indicate connection termination:

{
  "event_type": "sse_close",
  "event_time": "2025-09-17T15:51:44.234Z"
}

Common error scenarios:

Call log not found: Invalid or non-existent call ID
Agent not found: Call ID valid but associated agent not accessible
Unauthorized: Invalid or expired authentication token
Error consuming events: Internal server error

Reconnection Strategy

Implement exponential backoff for reconnections:

let reconnectDelay = 1000; // Start with 1 second
const maxReconnectDelay = 30000; // Max 30 seconds

function reconnect() {
  setTimeout(() => {
    connectToEvents();
    reconnectDelay = Math.min(reconnectDelay * 2, maxReconnectDelay);
  }, reconnectDelay);
}

function onConnectionSuccess() {
  reconnectDelay = 1000; // Reset delay on successful connection
}

Real-world Usage Patterns

Live Call Dashboard

Monitor multiple calls simultaneously by establishing separate SSE connections for each active call.

Call Analytics

Process metrics events to build real-time performance dashboards showing:

Average response times
TTS processing latency
Token usage patterns
Conversation flow efficiency

Quality Monitoring

Track transcription accuracy and agent response appropriateness by monitoring:

user_transcription events for input quality
agent_node_state events for workflow adherence
llm_full_response_end events for response quality

Integration Webhooks

Combine SSE events with your existing webhook infrastructure to trigger actions based on real-time call events.

Troubleshooting

No Events Received:

Verify the call is currently active or recently completed
Check that the call ID format is correct: CALL-XXXXXXXXX-XXXXXX
Ensure your authentication token has access to the specified call

Connection Drops:

Implement automatic reconnection with exponential backoff
Monitor network connectivity
Check for authentication token expiration

Missing Event Types:

Some events only occur during specific call phases
Workflow events depend on agent configuration
Metrics events vary by enabled services

High Event Volume:

Implement client-side filtering for relevant event types
Use batching to process multiple events together
Consider sampling for high-frequency metrics events

Get Started

Deep Dive

​Real-time Call Events

​Endpoint Overview

​Real-time Call Events

​Endpoint Overview

​Request Parameters

​Authentication

​Connection Examples

​cURL

​JavaScript (Node.js)

​Event Types Reference

​Connection Events

​SSE Initialization

​SSE Connection Close

​Call Lifecycle Events

​Call Start

​Transcription Events

​User Transcription (Final)

​User Interim Transcription

​Agent Workflow Events

​Agent Node State

​Node Transitions (Hopping)

​LLM Response Events

​LLM Full Response End

​Text-to-Speech Events

​TTS Completion

​Performance Metrics

​Turn Latency

​Service Metrics

​LLM Token Usage

​Common Event Fields

​Connection Management

​Connection Lifecycle

​Error Handling

​Reconnection Strategy

​Real-world Usage Patterns

​Live Call Dashboard

​Call Analytics

​Quality Monitoring

​Integration Webhooks

​Troubleshooting

​Request Parameters

​Authentication

​Connection Examples

​cURL

​JavaScript (Node.js)

​Event Types Reference

​Connection Events

​SSE Initialization

​SSE Connection Close

​Call Lifecycle Events

​Call Start

​Transcription Events

​User Transcription (Final)

​User Interim Transcription

​Agent Workflow Events

​Agent Node State

​Node Transitions (Hopping)

​LLM Response Events

​LLM Full Response End

​Text-to-Speech Events

​TTS Completion

​Performance Metrics

​Turn Latency

​Service Metrics

​LLM Token Usage

​Common Event Fields

​Connection Management

​Connection Lifecycle

​Error Handling

​Reconnection Strategy

​Real-world Usage Patterns

​Live Call Dashboard

​Call Analytics

​Quality Monitoring

​Integration Webhooks

​Troubleshooting

Real-time Call Events

Endpoint Overview

Real-time Call Events

Endpoint Overview

Request Parameters

Authentication

Connection Examples

cURL

JavaScript (Node.js)

Event Types Reference

Connection Events

SSE Initialization

SSE Connection Close

Call Lifecycle Events

Call Start

Transcription Events

User Transcription (Final)

User Interim Transcription

Agent Workflow Events

Agent Node State

Node Transitions (Hopping)

LLM Response Events

LLM Full Response End

Text-to-Speech Events

TTS Completion

Performance Metrics

Turn Latency

Service Metrics

LLM Token Usage

Common Event Fields

Connection Management

Connection Lifecycle

Error Handling

Reconnection Strategy

Real-world Usage Patterns

Live Call Dashboard

Call Analytics

Quality Monitoring

Integration Webhooks

Troubleshooting

Request Parameters

Authentication

Connection Examples

cURL

JavaScript (Node.js)

Event Types Reference

Connection Events

SSE Initialization

SSE Connection Close

Call Lifecycle Events

Call Start

Transcription Events

User Transcription (Final)

User Interim Transcription

Agent Workflow Events

Agent Node State

Node Transitions (Hopping)

LLM Response Events

LLM Full Response End

Text-to-Speech Events

TTS Completion

Performance Metrics

Turn Latency

Service Metrics

LLM Token Usage

Common Event Fields

Connection Management

Connection Lifecycle

Error Handling

Reconnection Strategy

Real-world Usage Patterns

Live Call Dashboard

Call Analytics

Quality Monitoring

Integration Webhooks

Troubleshooting