Conversation Update Event

The conversation-update event is triggered whenever a message occurs during the call - both user messages (from speech-to-text) and assistant messages (generated responses).

Each event includes the complete conversation history from the start of the call, not just the latest message. This ensures you never miss context even if some events are lost.

When It’s Triggered

This event is sent for:

User Messages: When user speech is transcribed by STT
Assistant Messages: When the assistant generates and speaks a response
Welcome Messages: When the assistant plays the initial greeting

Event Structure

{
    "message": {
        "timestamp": 1772702480281,
        "type": "conversation-update",
        "call": { /* Call Object */ },
        "assistant": { /* Assistant Object */ },
        "messages": [ /* Array of Message Objects */ ],
        "phone": { /* Phone Object */ },
        "customer": { /* Customer Object */ },
        "analysis": { /* Empty during conversation */ }
    }
}

Key Fields

Field	Type	Description
`message.type`	string	Always “conversation-update” for this event
`message.timestamp`	number	Unix timestamp when message was processed
`messages`	array	Complete conversation history up to this point
`call.status`	string	Current call status (usually “ongoing”)

Messages Object

The messages array contains the conversation history between the user and assistant.

Each conversation-update event includes all messages from the start of the call up to that point, not just the latest message. This ensures that if any individual event is missed, you still have the complete conversation context.

Message Structure

Field	Type	Description
`messageId`	string	Unique message identifier
`role`	string	Message sender: “user” or “assistant”
`text`	string	Transcribed or generated message content
`timestamp`	number	Unix timestamp in milliseconds
`metrics`	object	Performance metrics for this message
`skippedAssistantMessages`	array	Assistant messages that were skipped due to interruptions

Message Metrics

Each message includes detailed performance metrics:

Timeline Metrics

totalElapsedTimeMs: Total time since call start
offsetFromPreviousTurnMs: Time gap from previous message

Audio Metrics

totalAudioReceivedMs: Total audio duration received
audioDelayPerTurnMs: Audio processing delay for this turn
delayedPacketsPerTurnCount: Count of delayed network packets

Speech-to-Text (STT) Metrics

timestampMs: When transcription was completed
startOffsetMs/endOffsetMs: Audio segment boundaries
confidence: Transcription confidence score (0.0 to 1.0)
vadMs: Voice activity detection duration

Text-to-Speech (TTS) Metrics

audioDurationMs: Duration of generated audio
generationTimeMs: Time to generate audio
queueLatencyMs: Processing queue delay
isCachePlaying: Whether audio was served from cache

LLM Metrics

responseLatencyMs: Time for LLM to generate response
queueLatencyMs: Processing queue delay

Message Types

Welcome Messages: Have messageId starting with “welcome-”
User Messages: Have messageId starting with “user-”
Assistant Messages: Have complex messageId with user reference and timestamp

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

Message Flow Pattern

Events are triggered in this typical sequence:

Welcome Message → conversation-update with assistant greeting
User Speaks → conversation-update with transcribed user message
Assistant Responds → conversation-update with assistant reply
User Replies → conversation-update with new user message
Cycle Continues until call ends

Messages may be interrupted or skipped if users barge in while the assistant is speaking. Check the skippedAssistantMessages field for interrupted responses.

Example Payload

{
  "message": {
    "timestamp": 1772702480281,
    "type": "conversation-update",
    "call": {
      "id": "WC-82015760-c3bd-427d-a23b-ba9b07e4ab85",
      "status": "ongoing"
    },
    "messages": [
      {
        "messageId": "welcome-1",
        "role": "assistant",
        "text": "Welcome to Apollo clinic!!",
        "timestamp": 1772702480279,
        "metrics": {
          "tts": {
            "audioDurationMs": 1442,
            "generationTimeMs": 7,
            "isCachePlaying": true
          }
        }
      }
    ]
  }
}

Common Use Cases

Real-Time Conversation Display

def handle_conversation_update(event_data):
    call_id = event_data["message"]["call"]["id"]
    messages = event_data["message"]["messages"]

    # Update conversation display
    for message in messages:
        display_message(
            call_id=call_id,
            role=message["role"],
            text=message["text"],
            timestamp=message["timestamp"]
        )

    # Scroll to latest message
    scroll_to_latest(call_id)

Live Transcription Storage

const storeConversation = (eventData) => {
  const { call, messages } = eventData.message;

  // Store each message with full context
  messages.forEach(message => {
    db.conversations.upsert({
      call_id: call.id,
      message_id: message.messageId,
      role: message.role,
      text: message.text,
      timestamp: message.timestamp,
      confidence: message.metrics?.stt?.confidence,
      created_at: new Date()
    });
  });

  // Update call status
  db.calls.update(call.id, {
    last_message_at: new Date(),
    message_count: messages.length,
    status: call.status
  });
};

Sentiment Analysis Pipeline

def analyze_conversation_sentiment(event_data):
    messages = event_data["message"]["messages"]
    call_id = event_data["message"]["call"]["id"]

    # Analyze only user messages for sentiment
    user_messages = [msg for msg in messages if msg["role"] == "user"]

    if user_messages:
        latest_user_message = user_messages[-1]

        # Run sentiment analysis
        sentiment = sentiment_analyzer.analyze(latest_user_message["text"])

        # Store sentiment data
        store_sentiment(
            call_id=call_id,
            message_id=latest_user_message["messageId"],
            sentiment=sentiment,
            confidence=sentiment.confidence
        )

        # Trigger alerts for negative sentiment
        if sentiment.label == "negative" and sentiment.confidence > 0.8:
            alert_supervisor(call_id, "Negative sentiment detected")

Message Metrics Tracking

def track_message_performance(event_data):
    messages = event_data["message"]["messages"]

    for message in messages:
        if message["role"] == "assistant" and "metrics" in message:
            metrics = message["metrics"]

            # Track TTS performance
            if "tts" in metrics:
                track_metric("tts_generation_time",
                           metrics["tts"]["generationTimeMs"])
                track_metric("tts_audio_duration",
                           metrics["tts"]["audioDurationMs"])

            # Track LLM performance
            if "llm" in metrics:
                track_metric("llm_response_time",
                           metrics["llm"]["responseLatencyMs"])

        elif message["role"] == "user" and "metrics" in message:
            # Track STT confidence
            stt_metrics = message["metrics"].get("stt", {})
            if "confidence" in stt_metrics:
                track_metric("stt_confidence", stt_metrics["confidence"])

Message Interruptions

When users interrupt assistant responses, the skippedAssistantMessages field contains messages that were cut off:

def handle_interruptions(event_data):
    messages = event_data["message"]["messages"]

    for message in messages:
        if message["role"] == "user" and "skippedAssistantMessages" in message:
            skipped = message["skippedAssistantMessages"]

            if skipped:
                # Log interrupted responses for analysis
                for skipped_msg in skipped:
                    log_interruption(
                        call_id=event_data["message"]["call"]["id"],
                        interrupted_text=skipped_msg.get("text", ""),
                        interruption_time=message["timestamp"]
                    )

Performance Considerations

Since conversation-update events can contain large message arrays:

Incremental Processing: Only process new messages since your last update
Message Deduplication: Use messageId to avoid processing duplicates
Efficient Storage: Consider storing messages individually rather than entire payloads
Pagination: For long conversations, implement message pagination in your UI

def process_incremental_messages(event_data, last_seen_message_id=None):
    messages = event_data["message"]["messages"]

    if last_seen_message_id:
        # Find index of last seen message
        last_index = -1
        for i, msg in enumerate(messages):
            if msg["messageId"] == last_seen_message_id:
                last_index = i
                break

        # Process only new messages
        new_messages = messages[last_index + 1:] if last_index >= 0 else messages
    else:
        new_messages = messages

    # Process new messages
    for message in new_messages:
        process_single_message(message)

    # Return latest message ID for next call
    return messages[-1]["messageId"] if messages else None