Status Update Event - Interactly API

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}")

Status Update Event Example

This is a complete example of a status-update webhook event 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,
            "analysis": {
                "summary": "",
                "successEvaluation": ""
            },
            "recording": {
                "s3Bucket": "",
                "path": ""
            },
            "assistantOverrides": {},
            "metadata": {}
        },
        "assistant": {
            "_id": "697769ef5e6d94d5ad83e01e",
            "name": "Mary Dental - main",
            "welcomeMessage": "Welcome to Apollo clinic!!",
            "welcomeMessageMode": "automatic",
            "welcomeMessageInterruptionsEnabled": false,
            "endCallMessage": "",
            "endCallToolDescription": "",
            "endCallPhrases": [
                "Goodbye",
                "Bye"
            ],
            "bargeInEnabled": true,
            "callForwardData": [],
            "assistantKnowledgeBaseIds": [],
            "assistantToolIds": [],
            "assistantProvider": "gemini",
            "assistantModel": "gemini-3-flash-preview",
            "assistantLLMUrl": "",
            "assistantSystemPrompt": "You here are a voice assistant for Apollo clinic clinic, located at 123 North Face Place, Anaheim, California. Your name is Rachel. The hours are 8 AM to 5PM daily, but they are closed on Sundays. Clinic phone number is 7706258801.\n\nThe practicing orthopedic doctor is Dr.Sam.\n\nToday's date is {{date}}.\nThis is your serial number {{serial_number}}, when they ask for serial number say {{serial_number}}\n\n\nYou are tasked with answering questions about the business, and booking appointments. If they wish to book an appointment, your goal is to gather necessary information from callers in a friendly and efficient manner like follows:\n\n1. Ask for their full name.\n2. Ask for their mobile number.\n3. Ask for their age.\n4. Ask for their place of birth.\n5. Ask for their body weight.\n6. Ask for the purpose of their appointment.\n7. Request their preferred date and time for the appointment.\n8. Then finally ask for their date of birth.\n9. Confirm the details(full name, purpose of appointment, and appointment time) with the caller, and then book the appointment.\n\nKnowledgebase:\nIf any questions are asked related to KB, try to answer them from the information in KB.\n- Keep all your responses short and simple by using casual language. Don't ramble too long.\n\nOnce the appointment is booked, do not forget to ask if they need assistance with anything else.\nIf nothing else from the user, then gracefully end the conversation by saying 'Goodbye'.",
            "assistantTemperature": 0,
            "assistantMaxTokens": 256,
            "assistantResponseSplitter": "",
            "assistantBackchannelingEnabled": false,
            "assistantAnalysis": {
                "summary": {
                    "enabled": true,
                    "prompt": "You are an expert note-taker. You will be given a transcript of a call. Summarize the call in 2-3 sentences. DO NOT return anything except the summary.",
                    "provider": "",
                    "model": "",
                    "timeoutInSecs": 30
                },
                "successEvaluation": {
                    "enabled": true,
                    "prompt": "You are an expert call evaluator. You will be given a transcript of a call and the system prompt of the AI participant. Determine if the call was successful based on the objectives inferred from the system prompt. DO NOT return anything except the result.",
                    "provider": "",
                    "model": "",
                    "rubric": "DescriptiveScale",
                    "timeoutInSecs": 30,
                    "rubricDescription": "A scale of Excellent, Good, Fair, Poor."
                },
                "structuredData": {
                    "enabled": true,
                    "prompt": "You are an expert data extractor. You will be given a transcript of a call. Extract structured data per the JSON Schema. DO NOT return anything except the structured data.",
                    "provider": "",
                    "model": "",
                    "schema": {
                        "type": "object",
                        "properties": {
                            "Name": {
                                "type": "string",
                                "description": "Name of the patient"
                            },
                            "phone number": {
                                "type": "string",
                                "description": "phone number of a patient"
                            },
                            "serial_number": {
                                "description": "this is the serial number",
                                "type": "number"
                            }
                        },
                        "required": [
                            "Name",
                            "phone number",
                            "serial_number"
                        ],
                        "additionalProperties": false,
                        "$defs": {}
                    },
                    "timeoutInSecs": 30
                },
                "guardrails": {
                    "enabled": false,
                    "prompt": "",
                    "provider": "",
                    "model": "",
                    "timeoutInSecs": 30,
                    "metrics": []
                },
                "phiRedaction": {
                    "enabled": true,
                    "prompt": "",
                    "provider": "",
                    "model": "",
                    "timeoutInSecs": 30
                },
                "callbackUrl": "http://127.0.0.1:8506/internal/v1/conversations/analysis"
            },
            "assistantServer": {
                "enabled": true,
                "url": "https://c368-202-53-12-234.ngrok-free.app/events",
                "timeoutSeconds": 20,
                "secret": "",
                "headers": {
                    "Authorization": "Bearer 69a0087e9f4ab593ca5b8f83"
                },
                "messages": [
                    "conversation-update",
                    "status-update",
                    "end-of-call-report"
                ]
            },
            "config": {
                "speech": {
                    "stt": {
                        "vendor": "deepgram",
                        "language": "en-US",
                        "languages": [
                            "en-US",
                            "hi"
                        ],
                        "profanityFilter": true,
                        "interim": true,
                        "hints": [],
                        "deepgramOptions": {
                            "model": "nova-3",
                            "punctuate": true,
                            "endpointing": 10,
                            "smart_format": true,
                            "numerals": true,
                            "no_delay": true,
                            "eagerEotThreshold": 0.5,
                            "eotThreshold": 0.7,
                            "eotTimeoutMs": 5000
                        }
                    },
                    "ttsData": [
                        {
                            "vendor": "eleven-labs",
                            "language": "en-US",
                            "voice": "EiyHck4gkzXTAtzLbssU",
                            "voiceName": "Nava (male)-cloned",
                            "default": true,
                            "config": {
                                "modelId": "eleven_flash_v2",
                                "modelName": "Eleven Flash v2",
                                "stability": 0.5,
                                "similarityBoost": 0.8,
                                "speakerBoost": true,
                                "applyTextNormalization": false,
                                "styleExaggeration": 0,
                                "optimizeStreamingLatency": 0,
                                "seed": null,
                                "speed": 1
                            }
                        }
                    ]
                }
            }
        },
        "phone": {
            "provider": {
                "name": ""
            }
        },
        "customer": {
            "number": "web-Ramesh Naik"
        },
        "analysis": {}
    }
}

Documentation Index

​When It’s Triggered

​Event Structure

​Key Fields

​Call Object

​Assistant Object

​Key Subobjects

​Phone Object

​Customer Object

​Example Payload

​Common Use Cases

​Call Tracking Dashboard

​Notification System

​Call Analytics

​Status Transition Flow

​Error Handling

​Status Update Event Example

When It’s Triggered

Event Structure

Key Fields

Call Object

Assistant Object

Key Subobjects

Phone Object

Customer Object

Example Payload

Common Use Cases

Call Tracking Dashboard

Notification System

Call Analytics

Status Transition Flow

Error Handling

Status Update Event Example