Skip to main content
Retrieves call metrics and analytics data after a call has completed.
All endpoints should pass in the userId query parameter. You can find your userId in the sa.dialgen.ai dashboard.
  • Endpoint: GET /api/v1/call/get-metric
  • Method: GET
  • Query Parameters:
    • callId (string, required): The call identifier.
    • userId (string, required): The user identifier.
    • agentId (string, required): The agent identifier.
    • contactId (string, required): The contact identifier.
  • Example Response: 
    {
  "success": true,
  "callData": {
    "id": "call_123",
    "contactId": "contact_123",
    "agentId": "agent_456",
    "status": "COMPLETED",
    "startTime": "2024-01-15T10:00:00.000Z",
    "endTime": "2024-01-15T10:03:00.000Z",
    "duration": 180,
    "phoneNumber": "+1234567890",
    "contactName": "John Doe",
    "transcription": { "...": "..." },
    "summary": "Demo call completed successfully...",
    "metricJson": {
      "intent": "SALES_INQUIRY",
      "sentiment": "positive",
      "confidence": 0.95,
      "keyPoints": ["Interested in pricing", "Wants demo"],
      "customerSatisfaction": 5
    }
  },
  "metricSchema": { "...": "..." }
}
    • callData.summary: The freeform text summary of the call.
    • callData.metricJson: A JSON object containing all default and custom metrics.
    • metricSchema: The schema definition for metricJson.

​
Webhooks

For a fully automated workflow, you can provide a webhook URL when creating a batch.
  • onCallComplete: If provided in the options.webhooks object during batch creation, our system will POST the final call details (including transcription, summary, and recording URL) to this endpoint after each call is completed. This saves you from needing to poll for status.

​
Metrics System

The get-metric endpoint returns a metricJson object. This object contains standard Dialgen metrics (if enabled in your agent) and any custom metrics you have defined. Default Dialgen Metrics:
  • intent: The primary purpose or goal of the caller.
  • sentiment: Overall emotional tone (positive/neutral/negative).
  • confidence: AI confidence score (0-1).
  • keyPoints: List of important points mentioned.
  • actionItems: Follow-up tasks or actions agreed upon.
  • callStatus: HUMAN_ESCALATION, SUCCESS, RESCHEDULE, etc.
  • selfEvaluation: Agent’s performance evaluation.
Custom Metrics: You can define custom metrics (string, number, boolean, array) in the agent configuration, and they will also appear in the metricJson object.

​
Best Practices

​
Working with Contact IDs

When to provide Contact IDs:
  • ✅ Recommended: Always provide contact IDs if you’re maintaining your own contact database
  • ✅ Use Case: Re-running campaigns on the same contacts (preserves call history)
  • ✅ Use Case: Following up with contacts from previous batches
  • ✅ Benefit: Complete call history and analytics across multiple campaigns
When NOT to provide Contact IDs:
  • ❌ First Campaign: When calling a contact for the first time
  • ❌ Unknown Contacts: When you don’t have existing contact records
  • ❌ Fresh Start: When you want to create entirely new contact records
Example Workflow: 
// First campaign - no IDs
const firstBatch = {
  agentId: "agent_123",
  userId: "user_456",
  contacts: [
    { phoneNumber: "+15551234567", name: "Jane Doe" }
  ]
};

// After first campaign, retrieve contact IDs from status endpoint
// Second campaign - with IDs (preserves history)
const secondBatch = {
  agentId: "agent_123",
  userId: "user_456",
  contacts: [
    {
      id: "contact_789",  // From previous campaign
      phoneNumber: "+15551234567",
      name: "Jane Doe",
      metadata: { "follow_up": true }
    }
  ]
};

​
Rate Limiting & Throttling

  • Default Rate: 10 calls per second (adjustable via maxCallsPerSecond)
  • Recommended: Start with lower rates (5-10 CPS) and scale up based on your telephony provider’s limits
  • Twilio Limits: Check your Twilio account’s concurrent call limits

​
Retry Strategy

  • No Answer: Default 1-hour delay before retry (configurable)
  • Busy Signal: Default 5-minute delay before retry (configurable)
  • Max Attempts: Default 3 attempts (configurable, max 5)
  • Tip: Adjust retry delays based on your use case (e.g., shorter delays for time-sensitive campaigns)

​
Webhook Best Practices

  • Idempotency: Your webhook endpoints should be idempotent (handle duplicate calls gracefully)
  • Authentication: Secure your webhook endpoints with authentication tokens
  • Timeout: Respond to webhook calls within 5 seconds to avoid retries
  • Retry Logic: We retry failed webhook calls up to 3 times with exponential backoff

​
Error Handling

The API uses standard HTTP status codes for errors.
  • 400 Bad Request: Missing or invalid fields/parameters.
  • 401 Unauthorized: Missing or invalid API key.
  • 404 Not Found: The requested user, agent, or call was not found.
  • 409 Conflict: A call is already in progress for this contact.
  • 500 Internal Server Error: An unexpected server error occurred.
  • 502 Bad Gateway: The internal backend service failed to process the request.