Skip to main content

​
Request Payloads

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

​
Call Completed Event

Triggered when a call attempt finishes (completed, failed, or retry). 
{
  "event_type": "call_completed",
  "call_id": "adb64369-bb56-461e-a38a-9cc704e3210f",
  "call_sid": "CA1234567890abcdef123456789012345",
  "call_duration": 9.4,
  "call_type": "outbound",
  "status": "completed",
  "to_number": "+919875436897",
  "from_number": "+918035736726",
  "agent_id": "8e1ba144-884f-49be-97ad-137cebc56913",
  "workspace_id": "442a9db3-0fd4-47dc-b8cd-cc7eedfa272f",
  "custom_args_values": {
    "callee_name": "John",
    "order_value": "70000",
    "company_name": "Acme Corp"
  },
  "transcript": [
    {"bot": "Hello, how can I help you today?"},
    {"user": "I need information about my order"},
    {"bot": "I'd be happy to help you with that. Can you provide your order number?"},
    {"user": "Sure, it's ORDER-12345"}
  ],
  "retry_count": 0
}

​
Recording Completed Event

Triggered when call recording is processed and ready for download. 
{
  "event_type": "recording_completed",
  "call_id": "adb64369-bb56-461e-a38a-9cc704e3210f",
  "call_sid": "CA1234567890abcdef123456789012345",
  "recording_url": "https://recordings.ringg.ai/v1/recordings/8c92980b-f47c-4b8b-877f-6daa81ab1d9e.mp3",
  "recording_duration": 19.3,
  "custom_args_values": {
    "callee_name": "John",
    "order_value": "70000",
    "company_name": "Acme Corp"
  }
}

​
Platform Analysis Event

Triggered when Ringg AI’s built-in analysis completes. 
{
  "event_type": "platform_analysis_completed",
  "call_id": "adb64369-bb56-461e-a38a-9cc704e3210f",
  "call_sid": "CA1234567890abcdef123456789012345",
  "analysis_data": {
    "summary": "Concise summary of the conversation purpose and outcome",
    "classification": "One of the classification labels (e.g., 'qualified_lead', 'support_ticket_requested')",
    "key_points": [
      "Important takeaway 1",
      "Important takeaway 2"
    ],
    "action_items": [
      "Task or follow-up action 1",
      "Task or follow-up action 2"
    ],
    "callback_requested_time": "2023-10-27T14:30:00",
    "status": "analyzed",
    "call_disconnect_reason": "agent_hangup",
    "timezone": "Asia/Kolkata"
  },
  "call_id": "uuid-string",
  "agent_id": "uuid-string",
  "workspace_id": "uuid-string",
  "call_type": "inbound",
  "call_sid": "string",
  "to_number": "+1234567890",
  "from_number": "+1234567890",
  "custom_args_values": {
    "custom_field": "value"
  },
  "call_type": "outbound",
  "status": "completed",
  "agent_id": "8e1ba144-884f-49be-97ad-137cebc56913",
  "workspace_id": "442a9db3-0fd4-47dc-b8cd-cc7eedfa272f",
  "custom_args_values": {
    "callee_name": "John",
    "order_value": "70000",
    "company_name": "Acme Corp"
  },
  "transcript": [
    {
      "role": "assistant",
      "content": "Hello, how can I help you?"
    },
    {
      "role": "user",
      "content": "I need to schedule a demo."
    }
  ]
}

​
Client Analysis Event

Triggered when your custom analysis completes based on your configured prompts. 
{
  "event_type": "client_analysis_completed",
  "call_id": "adb64369-bb56-461e-a38a-9cc704e3210f",
  "call_sid": "CA1234567890abcdef123456789012345",
  "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",
  "status": "completed",
  "agent_id": "8e1ba144-884f-49be-97ad-137cebc56913",
  "workspace_id": "442a9db3-0fd4-47dc-b8cd-cc7eedfa272f",
  "custom_args_values": {
    "callee_name": "John",
    "order_value": "70000",
    "company_name": "Acme Corp"
  }
}

​
Implementation Examples

​
Node.js/Express

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_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;
  }
  
  // Always acknowledge receipt
  res.status(200).json({ received: true });
});

app.listen(3000);

​
Field Descriptions

​
Common Fields

FieldTypeDescription
event_typestringType of event: call_completed, recording_completed, platform_analysis_completed, client_analysis_completed
call_idstringUnique identifier for the call
call_sidstringTelephony provider’s call identifier (e.g., Twilio Call SID, Plivo Call UUID)
agent_idstringID of the AI agent that handled the call
workspace_idstringID of your workspace
custom_args_valuesobjectCustom data you provided when initiating the call

​
Call Completed Fields

FieldTypeDescription
call_durationnumberDuration of the call in seconds (call_completed only)
call_typestringDirection: inbound, outbound, or webcall
statusstringFinal call status: completed, failed, retry (call_completed only)
to_numberstringPhone number that received the call
from_numberstringPhone number that made the call
call_sidstringProvider call ID (e.g., from Twilio/Plivo)
transcriptarrayArray of conversation turns with role and content fields
custom_args_valuesobjectCustom data you provided when initiating the call
retry_countnumberNumber of retry attempts (0 for first attempt) (call_completed only)

​
Recording Fields

FieldTypeDescription
recording_urlstringURL of the call recording
recording_durationnumberDuration of the recording in seconds

​
Analysis Fields

FieldTypeDescription
analysis_dataobjectAnalysis results - structure varies by analysis type
summarystringConcise summary of conversation purpose and outcome (platform analysis)
classificationstringCall category label (e.g., ‘qualified_lead’) (platform analysis)
key_pointsarrayArray of important conversation takeaways (platform analysis)
action_itemsarrayArray of tasks or follow-up actions (platform analysis)
callback_requested_timestringISO 8601 timestamp when callback was requested (platform analysis)
statusstringAnalysis status, always ‘analyzed’ (platform analysis)
call_disconnect_reasonstringReason call ended: ‘agent_hangup’ or ‘user_hangup’ (platform analysis)
timezonestringTimezone used for the call (platform analysis)