Call Lifecycle & Webhooks

This documents the v1 product. It is kept for integrations already running on it. If you are building something new, start with the Quickstart.

Voice Agents uses webhooks to notify your application about the state of every call in real-time. Whether a call connects, fails, or triggers a specific action (like creating an order), your configured callback URL receives an event payload.

Call Lifecycle

Every call progresses through a specific lifecycle. At each stage, an event is fired.

Lifecycle Events

These events track the normal progression of a successful call.

Event	Description
`call.initiate`	The call has been queued and is being dialed.
`call.in-progress`	The recipient picked up; the AI conversation has started.
`call.ended`	The phone connection has dropped.
`call.completed`	Call data (recording, transcript, duration) has been processed.
`call.timeout`	The call exceeded the maximum allowed duration.
`end-of-call`	AI analysis is complete — summary, success evaluation, and structured data are available.
`call.lifecycle-ended`	All processing is finished. This is the final event for this call.

Failure & Retry Events

If a call cannot be established, one of these events will fire. The system may automatically retry based on your campaign settings.

Event	Description
`call.failed`	The call could not be connected (general failure).
`call.busy`	The recipient’s line was busy.
`call.no-answer`	The recipient did not pick up.
`call.validation-failed`	Pre-call validation failed (e.g., invalid number).
`call.skip`	The call was skipped (e.g., DND number).

Other Events

Event	Description
`call.rescheduled`	A callback has been scheduled for a later time (lifecycle continues to the next attempt).
`call.aborted`	The call was manually cancelled via the abort API.

After all retry attempts are exhausted, call.lifecycle-ended is sent to signal that no further attempts will be made for this specific call task.

Webhook Payload Structure

Every webhook event shares a common envelope structure.

{
  "metadata": {
    "customer_id": "12345",
    "order_ref": "ORD-001"
  },
  "event": {
    "type": "call.completed",
    "data": {
      "call": {
        "id": "c_550e8400-e29b",
        "status": "completed",
        "startedAt": "2023-10-27T10:00:00Z",
        "endedAt": "2023-10-27T10:02:30Z",
        "durationSeconds": 150,
        "recordingUrl": "https://api.voice-agents.com/recordings/...",
        "detailUrl": "https://api.voice-agents.com/calls/..."
      }
    }
  }
}

Key Fields

metadata: The custom JSON object you passed when initiating the call. This is passed back in every event, allowing you to link calls to your internal records (e.g., userId, orderId).
event.type: The specific event name (e.g., call.in-progress, end-of-call).
event.data: The payload specific to the event.

Special Payloads

Some events contain additional data in event.data.

`end-of-call`

Contains the AI analysis, summary, and credit usage.

{
  "analysis": {
    "success": true,
    "summary": "Customer confirmed the appointment for Tuesday.",
    "insights": {
        "sentiment": "positive",
        "intent": "booking_confirmed"
    }
  },
  "credits": {
    "used": 2.5,
    "available": 105.0
  }
}

`call.lifecycle-ended`

Contains a report of all attempts.

{
  "report": {
    "reAttemptCount": 1,
    "rescheduledCount": 0,
    "finalStatus": "completed"
  }
}

Actions

Actions are special events triggered by the AI during the conversation when a specific task needs to be performed on your end, such as creating an order or sending a message.

`create_order`

Fires when the AI determines the customer wants to place an order and has provided all necessary details.

{
  "event": {
    "type": "action",
    "data": {
      "action": "create_order",
      "payload": {
        "phone": "+15550109988",
        "lineItems": [{ "variantId": "123", "quantity": 1 }],
        "shippingAddress": {
          "firstName": "Jane",
          "lastName": "Doe",
          "address1": "123 Main St",
          "city": "New York",
          "zip": "10001",
          "country": "US"
        },
        "paymentMode": "cod",
        "cartTotal": 150.00
      }
    }
  }
}

`send_whatsapp`

Fires when the AI cannot complete a task (like creating an order) due to missing info, and triggers a fallback message via WhatsApp.

Reason	Meaning
`missing_address`	Customer’s shipping address is incomplete.
`missing_first_name`	Customer’s name could not be determined.
`invalid_cart_data`	Cart data is malformed or missing.

{
  "event": {
    "type": "action",
    "data": {
      "action": "send_whatsapp",
      "reason": "missing_address"
    }
  }
}

Handling Webhooks

Here is an example of how to handle these events in a Node.js Express application.

app.post('/webhooks/voice-agent', (req, res) => {
  const { event, metadata } = req.body;

  console.log(`Received event: ${event.type} for Customer: ${metadata.customer_id}`);

  switch (event.type) {
    case 'call.in-progress':
      // Call connected, maybe update UI status
      break;

    case 'action':
      if (event.data.action === 'create_order') {
        // Handle order creation logic
        createOrder(event.data.payload);
      } else if (event.data.action === 'send_whatsapp') {
        // Handle WhatsApp fallback logic
        sendWhatsAppFallback(event.data.reason);
      }
      break;

    case 'end-of-call':
      // Save call summary and analysis
      saveCallAnalysis(event.data.call.id, event.data.analysis);
      break;

    case 'call.rescheduled':
      // Update next attempt time in your DB
      console.log(`Call rescheduled for later`);
      break;

    case 'call.failed':
    case 'call.busy':
    case 'call.no-answer':
      // Log failure reason
      console.log(`Call failed: ${event.type}`);
      break;
      
    default:
      console.log('Unhandled event:', event.type);
  }

  // Always acknowledge the webhook
  res.status(200).send('OK');
});

Security

To ensure that the webhooks you receive are genuinely from Voice Agents, you should verify the signature included in the headers. See Webhook Signature Verification for implementation details.

The same thing in v2

Most of the shape above survives — one event per state change, an envelope you acknowledge with 200, a signature you verify. The names changed, the retry and action machinery did not carry over, and the analysis is not built yet.

v1 event	v2	Notes
`call.initiate`	`call.queued`	Opt-in in v2; ask to have it enabled.
`call.in-progress`	`call.started`	Media is live.
`call.ended` + `call.completed`	`call.completed`	One terminal event, not two.
`call.timeout`	`call.failed`	Read `data.call.status` — it is `timeout`.
`call.failed` / `call.busy` / `call.no-answer`	`call.failed`	One event; the status distinguishes them.
`call.aborted`	`call.aborted`	Same meaning.
—	`call.voicemail`	New in v2, and it is billed.
`call.validation-failed`	—	v2 rejects a bad number at create time, with `400`.
`call.rescheduled`, `call.skip`, `call.lifecycle-ended`	—	v2 does not retry. One call object, one outcome. Retry from your own dialler.
`end-of-call` (summary, sentiment)	—	Post-call analysis is on the roadmap.
`action` (`create_order`, `send_whatsapp`)	—	Not in v2.

metadata works differently. v1 echoes your object back on every event. v2 hands you the call_id in the 202 response to POST /v2/calls — store that against your own record before the first event can arrive, and correlate on it. variables you pass at create are used in the prompt; they do not come back on the event. Full reference: v2 Webhooks.

Start

Developer guides

API v1 reference

Endpoints

Guides

Integrations

Use cases

Call Lifecycle & Webhooks

Call Lifecycle

Lifecycle Events

Failure & Retry Events

Other Events

Webhook Payload Structure

Key Fields

Special Payloads

`end-of-call`

`call.lifecycle-ended`

Actions

`create_order`

`send_whatsapp`

Handling Webhooks

Security

The same thing in v2

​Call Lifecycle

​Lifecycle Events

​Failure & Retry Events

​Other Events

​Webhook Payload Structure

​Key Fields

​Special Payloads

​end-of-call

​call.lifecycle-ended

​Actions

​create_order

​send_whatsapp

​Handling Webhooks

​Security

​The same thing in v2

Call Lifecycle

Lifecycle Events

Failure & Retry Events

Other Events

Webhook Payload Structure

Key Fields

Special Payloads

`end-of-call`

`call.lifecycle-ended`

Actions

`create_order`

`send_whatsapp`

Handling Webhooks

Security

The same thing in v2