Status Update Event

The status-update event is triggered whenever a call status changes occur, such as when a call transitions between queued, ongoing, finished, or forwarded states.

This event provides real-time visibility into call progression and is essential for tracking call lifecycle in your systems.

When It’s Triggered

Status update events are sent when the call moves through these states:

Status	Description	Timing
`queued`	The call has been initiated and is waiting to start	Call initiation
`ongoing`	The call has started and conversation is active	Call pickup/answer
`finished`	The call has ended successfully	Call termination
`forwarded`	The call has been forwarded to another destination	Call forwarding

Event Structure

{
    "message": {
        "timestamp": 1772702480032,
        "type": "status-update",
        "call": { /* Call Object */ },
        "assistant": { /* Assistant Object */ },
        "phone": { /* Phone Object */ },
        "customer": { /* Customer Object */ },
        "analysis": { /* Empty during status updates */ }
    }
}

Key Fields

Field	Type	Description
`message.type`	string	Always “status-update” for this event
`message.timestamp`	number	Unix timestamp when status change occurred (milliseconds)
`call.status`	string	New call status: “queued”, “ongoing”, “finished”, “forwarded”
`call.phoneCallStatus`	string	Detailed phone system status
`call.phoneCallStatusReason`	string	Human-readable explanation of the status

Call Object

The call object contains comprehensive information about the call session.

Field	Type	Description
`id`	string	Unique call identifier (e.g., “WC-82015760-c3bd-427d-a23b-ba9b07e4ab85”)
`teamId`	string	Organization/team identifier
`assistantId`	string	ID of the assistant handling this call
`callType`	string	Type of call: “web”, “phone”, etc.
`direction`	string	Call direction: “inbound” or “outbound”
`startAt`	string	ISO timestamp when call started
`endAt`	string	ISO timestamp when call ended (only in end-of-call-report)
`userNumber`	string	User’s phone number or identifier
`assistantNumber`	string	Assistant’s number or identifier
`status`	string	Current call status: “queued”, “ongoing”, “finished”, “forwarded”
`phoneCallStatus`	string	Detailed phone status: “in-progress”, “completed”, etc.
`phoneCallStatusReason`	string	Human-readable status reason
`callEndTriggerBy`	string	What triggered call end: “bot”, “user”, “system”
`assistantCallDuration`	number	Duration of call in milliseconds
`analysis`	analysis-object	Call analysis results
`recording`	object	Recording information with S3 bucket and path
`assistantOverrides`	object	Dynamic variables and validation overrides
`metadata`	object	Custom metadata associated with the call
`cost`	object	Cost breakdown (only in end-of-call-report)
`metrics`	object	Detailed call metrics (only in end-of-call-report)

Assistant Object

The assistant object contains the configuration and settings of the assistant handling the call.

In some webhook events, the assistant object may be truncated for brevity. The full assistant configuration is typically included in status-update events.

Field	Type	Description
`_id`	string	Unique assistant identifier
`name`	string	Display name of the assistant
`welcomeMessage`	string	Message played when call starts
`welcomeMessageMode`	string	How welcome message is triggered: “automatic”, “manual”
`welcomeMessageInterruptionsEnabled`	boolean	Whether users can interrupt welcome message
`endCallMessage`	string	Message played when call ends
`endCallPhrases`	array	Phrases that trigger call termination
`bargeInEnabled`	boolean	Whether users can interrupt assistant responses
`assistantProvider`	string	LLM provider: “openai”, “anthropic”, “gemini”, etc.
`assistantModel`	string	Specific model being used
`assistantSystemPrompt`	string	System prompt defining assistant behavior
`assistantTemperature`	number	LLM creativity setting (0.0 to 1.0)
`assistantMaxTokens`	number	Maximum tokens per response
`assistantAnalysis`	object	Configuration for call analysis features
`assistantServer`	object	Webhook configuration for this assistant
`config`	object	Speech-to-text and text-to-speech configurations

Key Subobjects

assistantAnalysis: Contains settings for summary generation, success evaluation, and structured data extraction
assistantServer: The webhook configuration that triggered this event
config.speech: STT/TTS vendor settings, voice configuration, and language options

Phone Object

The phone object contains telephony provider information.

Field	Type	Description
`provider.name`	string	Name of the telephony provider (may be empty for web calls)

For web-based calls, the phone provider name is typically empty since no traditional telephony service is used.

Customer Object

The customer object contains information about the person interacting with the assistant.

Field	Type	Description
`number`	string	Customer’s identifier or phone number

For web calls, the customer number typically follows the format “web-” instead of a traditional phone number.

The analysis object is typically empty in status-update events since analysis is performed after the call completes.

Example Payload

{
  "message": {
    "timestamp": 1772702480032,
    "type": "status-update",
    "call": {
      "id": "WC-82015760-c3bd-427d-a23b-ba9b07e4ab85",
      "teamId": "67c0231ae6880fe48ef929ee",
      "assistantId": "697769ef5e6d94d5ad83e01e",
      "callType": "web",
      "direction": "inbound",
      "startAt": "2026-03-05T09:21:19.627Z",
      "userNumber": "web-Ramesh Naik",
      "assistantNumber": "697769ef5e6d94d5ad83e01e",
      "status": "queued",
      "phoneCallStatus": "in-progress",
      "phoneCallStatusReason": "Call is in progress",
      "callEndTriggerBy": "",
      "assistantCallDuration": 0
    },
    "assistant": {
      "_id": "697769ef5e6d94d5ad83e01e",
      "name": "Mary Dental - main",
      "welcomeMessage": "Welcome to Apollo clinic!!"
    }
  }
}

Common Use Cases

Call Tracking Dashboard

def handle_status_update(event_data):
    call = event_data["message"]["call"]
    call_id = call["id"]
    new_status = call["status"]

    # Update call tracking database
    db.calls.update_one(
        {"call_id": call_id},
        {
            "$set": {
                "status": new_status,
                "last_updated": datetime.utcnow(),
                "duration": call.get("assistantCallDuration", 0)
            }
        }
    )

    # Send real-time updates to dashboard
    emit_to_dashboard(call_id, new_status)

Notification System

def send_status_notifications(event_data):
    call = event_data["message"]["call"]
    status = call["status"]
    assistant_name = event_data["message"]["assistant"]["name"]

    if status == "queued":
        notify_agents(f"New call queued for {assistant_name}")
    elif status == "ongoing":
        notify_agents(f"Call started with {assistant_name}")
    elif status == "finished":
        notify_agents(f"Call completed - Duration: {call['assistantCallDuration']}ms")

Call Analytics

const handleStatusUpdate = (eventData) => {
  const { call, timestamp } = eventData.message;

  // Track call lifecycle timing
  analytics.track('call_status_change', {
    call_id: call.id,
    status: call.status,
    assistant_id: call.assistantId,
    call_type: call.callType,
    direction: call.direction,
    timestamp: timestamp
  });

  // Calculate metrics
  if (call.status === 'finished') {
    const duration = call.assistantCallDuration;
    analytics.track('call_completed', {
      call_id: call.id,
      duration_ms: duration,
      end_trigger: call.callEndTriggerBy
    });
  }
};

Status Transition Flow

Error Handling

Always handle missing fields gracefully, as different statuses may include different data:

def safe_status_handler(event_data):
    try:
        call = event_data["message"]["call"]
        status = call.get("status", "unknown")

        # Duration only available for finished calls
        duration = call.get("assistantCallDuration")
        if duration is not None:
            duration_seconds = duration / 1000

        # End trigger only relevant for finished calls
        end_trigger = call.get("callEndTriggerBy", "")

        process_status_update(call["id"], status, duration, end_trigger)

    except KeyError as e:
        logger.error(f"Missing required field: {e}")
    except Exception as e:
        logger.error(f"Status update processing failed: {e}")