> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Payloads

> Detailed examples of webhook request and response payloads for all event types

## Request Payloads

These are the JSON payloads your webhook endpoint will receive for different events.

### Call Started Event

Triggered immediately when a call is initiated.

```json theme={null}
{
  "event_type": "call_started",
  "call_id": "4b30f5dc-7f86-4e4c-a3aa-15c01138559b",
  "call_sid": "f46cb9f4-f6ca-4d7d-abc9-02c226b95ec0",
  "agent_id": "cbaf9944-3e34-43b6-b3e8-6a905de16639",
  "workspace_id": "442a9db3-0fd4-47dc-b8cd-cc7eedfa272f",
  "custom_args_values": {
    "callee_name": "John",
    "order_value": "70000",
    "company_name": "Acme Corp"
  },
  "sub_status": "ACCEPTED",
  "agent_name": "Payment Reminder Agent",
  "version_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "version_slug": "v1",
  "version_description": "Initial version",
  "tool_call_logs": []
}
```

### Call Completed Event

Triggered when a call attempt finishes (completed, failed, or retry).

```json theme={null}
{
  "event_type": "call_completed",
  "call_duration": 15.733745,
  "agent_message_count": 3,
  "user_message_count": 2,
  "call_type": "outbound",
  "custom_args_values": {
    "callee_name": "John",
    "order_value": "70000",
    "company_name": "Acme Corp"
  },
  "to_number": "+919875436897",
  "from_number": "+919875436897",
  "bulk_list_id": null,
  "call_id": "4b30f5dc-7f86-4e4c-a3aa-15c01138559b",
  "call_sid": "f46cb9f4-f6ca-4d7d-abc9-02c226b95ec0",
  "agent_id": "cbaf9944-3e34-43b6-b3e8-6a905de16639",
  "workspace_id": "442a9db3-0fd4-47dc-b8cd-cc7eedfa272f",
  "status": "completed",
  "called_on": "2025-12-14T19:37:13.310707Z",
  "agent_name": "Payment Reminder Agent",
  "version_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "call_cost": 0.15,
  "overall_latency_seconds": 0.892345,
  "first_utterance_seconds": 0.456789,
  "transcript": [
    {
      "bot": "Hello abhishek, this is Caroline from Ringg AI. I'm calling to remind you about your upcoming payment of dads due on twelve. Let's ensure everything is on track!"
    },
    {
      "user": "Yes. Yes. Everything is on track. Thank you so much,"
    },
    {
      "user": "Bye."
    },
    {
      "bot": "Thank"
    },
    {
      "bot": "you for"
    }
  ],
  "retry_count": 0,
  "recording_url": null,
  "tool_call_logs": []
}

```

### Recording Completed Event

Triggered when call recording is processed and ready for download.

<Note>
  The `recording_url` is valid for 24 hours after the call. Download and store the recording within that window if you need to retain it.
</Note>

```json theme={null}
{
  "call_id": "4b30f5dc-7f86-4e4c-a3aa-15c01138559b",
  "event_type": "recording_completed",
  "recording_url": "https://aps1.media.plivo.com/v1/Account/MZYZHIMM/Recording/0f27f498-2f98-403e-8239-10e24b67b604.mp3",
  "recording_duration": 16.28,
  "call_sid": "f46cb9f4-f6ca-4d7d-abc9-02c226b95ec0",
  "custom_args_values": {
    "callee_name": "John",
    "order_value": "70000",
    "company_name": "Acme Corp"
  },
  "bulk_list_id": "f46cb9f4-f6ca-4d7d-abc9-02c226b95ec0",
  "agent_name": "Payment Reminder Agent",
  "version_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "call_cost": 0.15,
  "overall_latency_seconds": 0.892345,
  "first_utterance_seconds": 0.456789,
  "tool_call_logs": []
}

```

### Platform Analysis Event

Triggered when Ringg AI's built-in analysis completes.

```json theme={null}
{
  "event_type": "platform_analysis_completed",
  "analysis_data": {
    "key_points": [
      "Reminder about upcoming payment due on the 12th for dad's payment.",
      "User acknowledged the reminder and stated everything is on track.",
      "No issues or new concerns were raised; conversation ended amicably."
    ],
    "action_items": [],
    "summary": "Agent reminded the customer about an upcoming payment due on the 12th for dad's payment. The customer confirmed that everything is on track and did not request any further assistance or information.",
    "classification": "payment_confirmed",
    "callback_requested": false,
    "callback_requested_time": null,
    "status": "analyzed",
    "call_disconnect_reason": "agent_hangup",
    "timezone": "Asia/Kolkata"
  },
  "call_type": "outbound",
  "custom_args_values": {
    "callee_name": "John",
    "order_value": "70000",
    "company_name": "Acme Corp"
  },
  "to_number": "+918882876897",
  "from_number": "+918035736726",
  "bulk_list_id": null,
  "call_id": "4b30f5dc-7f86-4e4c-a3aa-15c01138559b",
  "call_sid": "f46cb9f4-f6ca-4d7d-abc9-02c226b95ec0",
  "agent_id": "cbaf9944-3e34-43b6-b3e8-6a905de16639",
  "workspace_id": "442a9db3-0fd4-47dc-b8cd-cc7eedfa272f",
  "status": "completed",
  "called_on": "2025-12-14T19:37:13.310707Z",
  "agent_name": "Payment Reminder Agent",
  "version_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "call_cost": 0.15,
  "overall_latency_seconds": 0.892345,
  "first_utterance_seconds": 0.456789,
  "transcript": [
    {
      "bot": "Hello abhishek, this is Caroline from Ringg AI. I'm calling to remind you about your upcoming payment of dads due on twelve. Let's ensure everything is on track!"
    },
    {
      "user": "Yes. Yes. Everything is on track. Thank you so much,"
    },
    {
      "user": "Bye."
    },
    {
      "bot": "Thank"
    },
    {
      "bot": "you for"
    }
  ],
  "call_duration": 15.73,
  "agent_message_count": 3,
  "user_message_count": 2,
  "tool_call_logs": []
}

```

### Client Analysis Event

Triggered when your custom analysis completes based on your configured prompts.

```json theme={null}
{
  "event_type": "client_analysis_completed",
  "analysis_data": {
    "lead_quality": "high",
    "intent_score": 8.5,
    "next_action": "follow_up",
    "purchase_probability": 0.75,
    "customer_segment": "premium",
    "satisfaction_score": 9
  },
  "call_type": "outbound",
  "custom_args_values": {
    "due_date": "12",
    "due_amount": "dads",
    "callee_name": "abhishek",
    "transfer_to": "+917404156687",
    "mobile_number": "+918882876897"
  },
  "to_number": "+918882876897",
  "from_number": "+918035736726",
  "bulk_list_id": null,
  "call_id": "4b30f5dc-7f86-4e4c-a3aa-15c01138559b",
  "call_sid": "f46cb9f4-f6ca-4d7d-abc9-02c226b95ec0",
  "agent_id": "cbaf9944-3e34-43b6-b3e8-6a905de16639",
  "workspace_id": "442a9db3-0fd4-47dc-b8cd-cc7eedfa272f",
  "status": "completed",
  "called_on": "2025-12-14T19:37:13.310707Z",
  "agent_name": "Payment Reminder Agent",
  "version_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "call_cost": 0.15,
  "overall_latency_seconds": 0.892345,
  "first_utterance_seconds": 0.456789,
  "transcript": [
    {
      "bot": "Hello abhishek, this is Caroline from Ringg AI. I'm calling to remind you about your upcoming payment of dads due on twelve. Let's ensure everything is on track!"
    },
    {
      "user": "Yes. Yes. Everything is on track. Thank you so much,"
    },
    {
      "user": "Bye."
    },
    {
      "bot": "Thank"
    },
    {
      "bot": "you for"
    }
  ],
  "call_duration": 15.73,
  "agent_message_count": 3,
  "user_message_count": 2,
  "tool_call_logs": []
}

```

### All Processing Completed Event

Triggered once all post-call processing is finished — recording uploaded, transcript generated, and both platform and client analysis complete. This single consolidated event carries the full call dataset in one payload.

```json theme={null}
{
  "event_type": "all_processing_completed",
  "call_id": "4b30f5dc-7f86-4e4c-a3aa-15c01138559b",
  "call_sid": "f46cb9f4-f6ca-4d7d-abc9-02c226b95ec0",
  "agent_id": "cbaf9944-3e34-43b6-b3e8-6a905de16639",
  "workspace_id": "442a9db3-0fd4-47dc-b8cd-cc7eedfa272f",
  "status": "completed",
  "sub_status": "ACCEPTED",
  "call_type": "outbound",
  "call_duration": 15.73,
  "called_on": "2025-12-14T19:37:13.310707Z",
  "created_at": "2025-12-14T19:37:13.315211Z",
  "to_number": "+918882876897",
  "from_number": "+918035736726",
  "custom_args_values": {
    "callee_name": "John",
    "order_value": "70000",
    "company_name": "Acme Corp"
  },
  "bulk_list_id": null,
  "agent_name": "Payment Reminder Agent",
  "version_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "version_slug": "v1",
  "version_description": "Initial version",
  "call_cost": 0.15,
  "agent_message_count": 3,
  "user_message_count": 2,
  "overall_latency_seconds": 0.892345,
  "first_utterance_seconds": 0.456789,
  "transcript": [
    {
      "bot": "Hello abhishek, this is Caroline from Ringg AI. I'm calling to remind you about your upcoming payment of dads due on twelve. Let's ensure everything is on track!"
    },
    {
      "user": "Yes. Yes. Everything is on track. Thank you so much,"
    },
    {
      "user": "Bye."
    },
    {
      "bot": "Thank you for confirming. Have a great day!"
    }
  ],
  "recording_url": "https://storage.googleapis.com/calling_agent_call_recordings/vobiz/6b382cad-a8d7-4489.mp3",
  "platform_analysis": {
    "key_points": [
      "Reminder about upcoming payment due on the 12th for dad's payment.",
      "User acknowledged the reminder and stated everything is on track.",
      "No issues or new concerns were raised; conversation ended amicably."
    ],
    "action_items": [],
    "summary": "Agent reminded the customer about an upcoming payment due on the 12th. The customer confirmed that everything is on track.",
    "classification": "payment_confirmed",
    "callback_requested": false,
    "callback_requested_time": null,
    "status": "analyzed",
    "call_disconnect_reason": "agent_hangup",
    "timezone": "Asia/Kolkata"
  },
  "platform_analysis_status": "success",
  "client_analysis": {
    "lead_quality": "high",
    "intent_score": 8.5,
    "next_action": "follow_up",
    "purchase_probability": 0.75
  },
  "client_analysis_status": "success",
  "tool_call_logs": []
}
```

## Implementation Examples

### Node.js/Express

```javascript theme={null}
const express = require('express');
const app = express();

app.use(express.json());

// Handle all webhook events
app.post('/webhooks/:eventType', (req, res) => {
  const eventData = req.body;
  const eventType = req.params.eventType;
  
  console.log(`Received ${eventData.event_type} for call ${eventData.call_id}`);
  
  // Process based on event type
  switch(eventData.event_type) {
    case 'call_started':
      // Log call initiation
      console.log(`Call started for agent: ${eventData.agent_name}`);
      break;

    case 'call_completed':
      // Store transcript, update call status
      console.log(`Call duration: ${eventData.call_duration}s`);
      break;
      
    case 'recording_completed':
      // Download and store recording
      console.log(`Recording: ${eventData.recording_url}`);
      break;
      
    case 'platform_analysis_completed':
      // Process AI insights
      console.log(`Classification: ${eventData.analysis_data.classification}`);
      break;
      
    case 'client_analysis_completed':
      // Handle custom analysis
      console.log(`Lead quality: ${eventData.analysis_data.lead_quality}`);
      break;

    case 'all_processing_completed':
      // All data ready — transcript, recording, and both analyses
      console.log(`Recording: ${eventData.recording_url}`);
      console.log(`Classification: ${eventData.platform_analysis.classification}`);
      console.log(`Client analysis: ${JSON.stringify(eventData.client_analysis)}`);
      break;
  }
  
  // Always acknowledge receipt
  res.status(200).json({ received: true });
});

app.listen(3000);
```

## Field Descriptions

### Common Fields

| Field                     | Type   | Description                                                                                                                                                    |
| ------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_type`              | string | Type of event: `call_started`, `call_completed`, `recording_completed`, `platform_analysis_completed`, `client_analysis_completed`, `all_processing_completed` |
| `call_id`                 | string | Unique identifier for the call                                                                                                                                 |
| `call_sid`                | string | Telephony provider's call identifier (e.g., Twilio Call SID, Plivo Call UUID)                                                                                  |
| `agent_id`                | string | ID of the AI agent that handled the call                                                                                                                       |
| `workspace_id`            | string | ID of your workspace                                                                                                                                           |
| `custom_args_values`      | object | Custom data you provided when initiating the call                                                                                                              |
| `agent_name`              | string | Display name of the AI agent that handled the call                                                                                                             |
| `version_id`              | string | UUID of the agent version used for this call                                                                                                                   |
| `call_cost`               | number | Cost of the call in credits (null if not yet calculated)                                                                                                       |
| `overall_latency_seconds` | number | Total response latency in seconds (sum of median latencies across all metrics)                                                                                 |
| `first_utterance_seconds` | number | Time to first AI response (TTS) in seconds                                                                                                                     |
| `tool_call_logs`          | array  | Tool execution logs (pre-call, on-call) for the call                                                                                                           |

### Call Started Fields

| Field                 | Type   | Description                                 |
| --------------------- | ------ | ------------------------------------------- |
| `sub_status`          | string | Current call sub-status (e.g., `ACCEPTED`)  |
| `version_slug`        | string | Slug of the agent version used              |
| `version_description` | string | Description of the agent version (nullable) |

### Call Completed Fields

| Field                | Type   | Description                                                              |
| -------------------- | ------ | ------------------------------------------------------------------------ |
| `call_duration`      | number | Duration of the call in seconds (call\_completed only)                   |
| `call_type`          | string | Direction: `inbound`, `outbound`, or `webcall`                           |
| `status`             | string | Final call status: `completed`, `failed`, `retry` (call\_completed only) |
| `to_number`          | string | Phone number that received the call                                      |
| `from_number`        | string | Phone number that made the call                                          |
| `call_sid`           | string | Provider call ID (e.g., from Twilio/Plivo)                               |
| `transcript`         | array  | Array of conversation turns with `role` and `content` fields             |
| `custom_args_values` | object | Custom data you provided when initiating the call                        |
| `retry_count`        | number | Number of retry attempts (0 for first attempt) (call\_completed only)    |

### Recording Fields

| Field                | Type   | Description                                                   |
| -------------------- | ------ | ------------------------------------------------------------- |
| `recording_url`      | string | URL of the call recording (valid for 24 hours after the call) |
| `recording_duration` | number | Duration of the recording in seconds                          |

### Analysis Fields

| Field                     | Type   | Description                                                              |
| ------------------------- | ------ | ------------------------------------------------------------------------ |
| `analysis_data`           | object | Analysis results - structure varies by analysis type                     |
| `summary`                 | string | Concise summary of conversation purpose and outcome (platform analysis)  |
| `classification`          | string | Call category label (e.g., 'qualified\_lead') (platform analysis)        |
| `key_points`              | array  | Array of important conversation takeaways (platform analysis)            |
| `action_items`            | array  | Array of tasks or follow-up actions (platform analysis)                  |
| `callback_requested_time` | string | ISO 8601 timestamp when callback was requested (platform analysis)       |
| `status`                  | string | Analysis status, always 'analyzed' (platform analysis)                   |
| `call_disconnect_reason`  | string | Reason call ended: 'agent\_hangup' or 'user\_hangup' (platform analysis) |
| `timezone`                | string | Timezone used for the call (platform analysis)                           |

### All Processing Completed Fields

This event combines all data from the call lifecycle into a single payload. It includes every common field plus:

| Field                      | Type   | Description                                                                                  |
| -------------------------- | ------ | -------------------------------------------------------------------------------------------- |
| `call_duration`            | number | Duration of the call in seconds                                                              |
| `call_type`                | string | Direction: `inbound`, `outbound`, or `webcall`                                               |
| `status`                   | string | Final call status: `completed`, `failed`, `error`, `cancelled`, `forwarded`                  |
| `sub_status`               | string | Detailed call sub-status (e.g., `ACCEPTED`, `VOICEMAIL_DETECTED`)                            |
| `to_number`                | string | Phone number that received the call                                                          |
| `from_number`              | string | Phone number that made the call                                                              |
| `called_on`                | string | ISO 8601 timestamp when the call was initiated (UTC)                                         |
| `created_at`               | string | ISO 8601 timestamp when the call record was created (UTC)                                    |
| `transcript`               | array  | Full conversation transcript with `bot`/`user` content, `message_id`, and `timestamp`        |
| `recording_url`            | string | URL of the call recording (valid for 24 hours after the call)                                |
| `platform_analysis`        | object | Ringg AI's built-in analysis (same structure as `platform_analysis_completed.analysis_data`) |
| `platform_analysis_status` | string | Status: `success`, `failed`, `not_enabled`, `cancelled`                                      |
| `client_analysis`          | object | Your custom analysis results (same structure as `client_analysis_completed.analysis_data`)   |
| `client_analysis_status`   | string | Status: `success`, `failed`, `not_enabled`, `cancelled`                                      |
| `version_slug`             | string | Slug of the agent version used                                                               |
| `version_description`      | string | Description of the agent version (nullable)                                                  |