Dialro API Documentation

Complete REST API for integrating Dialro with your systems. Manage AI agents, phone numbers, retrieve call data, set up webhooks, and define function calling schemas.

Introduction

The Dialro API allows developers to integrate AI voice agent functionality into their own systems. Common use cases:

• Sync call data to your CRM (HubSpot, Salesforce, custom)
• Trigger workflows when calls end (send email, update database)
• Manage AI agent configuration programmatically
• Let AI agents call your internal APIs (function calling)
• Monitor usage and billing in real-time

Authentication

All API requests require an API key. Get your API key from the Dashboard → Settings → API Keys.

curl https://api.dialro.com/api/v1/calls \
  -H "x-api-key: dkl_your_api_key_here"

API keys are prefixed with dkl_. Keep them secret. You can have multiple keys per tenant (e.g., one for production, one for testing). Keys can be revoked anytime from the dashboard.

Base URL

Environment	Base URL
Production	https://api.dialro.com/api/v1
Development	https://dialro-worker-dev.dialro.workers.dev/api/v1

Rate Limits

Plan	Limit
Starter	60 requests/minute
Business	300 requests/minute
Enterprise	Custom

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

AI Agents

Manage AI agent configuration per tenant.

List Agents

GET /api/v1/agents

curl https://api.dialro.com/api/v1/agents \
  -H "x-api-key: dkl_your_key"

{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Klinik Sehat Receptionist",
      "systemPrompt": "Anda adalah resepsionis klinik...",
      "voiceId": "Puck",
      "greetingText": "Halo, selamat datang di Klinik Sehat",
      "language": "id",
      "maxCallDurationMinutes": 10,
      "toolsEnabled": ["search_kb", "create_booking"],
      "isActive": true
    }
  ]
}

Create Agent

POST /api/v1/agents

Field	Type	Required	Description
name	string	Yes	Agent display name
systemPrompt	string	Yes	AI instructions/persona
voiceId	string	No	Voice: Puck, Charon, Kore, Fenrir, Aoede
greetingText	string	No	Opening greeting
language	string	No	Default: "id" (Bahasa Indonesia)
maxCallDurationMinutes	int	No	Max call duration (default: 10)
escalationNumber	string	No	Phone number for human escalation

Update Agent

PATCH /api/v1/agents/:id

Delete Agent

DELETE /api/v1/agents/:id

Phone Numbers

Manage WhatsApp Business phone numbers linked to your tenant.

List Phone Numbers

GET /api/v1/phone-numbers

{
  "phoneNumbers": [
    {
      "id": "pn_xyz789",
      "displayNumber": "+6289502159000",
      "label": "Klinik Sehat",
      "isActive": true,
      "agentId": "agent_abc123"
    }
  ]
}

Assign Agent to Phone Number

POST /api/v1/phone-numbers/:id/assign-agent
Content-Type: application/json

{ "agentId": "agent_abc123" }

Calls

Retrieve call history and details.

List Calls

GET /api/v1/calls?limit=50&offset=0&status=ended

Param	Type	Description
limit	int	Max 100 (default: 50)
offset	int	Pagination offset
status	string	Filter: ringing, answered, ended, dropped, failed
from	ISO date	Filter calls after this date
to	ISO date	Filter calls before this date

Get Call Detail

GET /api/v1/calls/:id

{
  "id": "call_xxx",
  "phoneNumberId": "pn_xyz789",
  "agentId": "agent_abc123",
  "callerNumber": "+628123456789",
  "calleeNumber": "+6289502159000",
  "direction": "inbound",
  "status": "ended",
  "startedAt": "2026-06-28T10:00:00Z",
  "endedAt": "2026-06-28T10:03:30Z",
  "durationSeconds": 210,
  "talkTimeSeconds": 195,
  "hangupReason": "normal",
  "transcriptSummary": "Customer asked about clinic hours and booked appointment for Tuesday.",
  "aiCostIdr": 1500,
  "metadata": {}
}

Credits & Billing

Get Credit Balance

GET /api/v1/credits

{
  "balanceMinutes": 2850,
  "lifetimePurchasedMinutes": 3000,
  "lifetimeUsedMinutes": 150
}

List Credit Transactions

GET /api/v1/credits/transactions?limit=20

Webhooks

Register webhook URLs to receive real-time call events on your server.

Register Webhook

POST /api/v1/webhooks
Content-Type: application/json

{
  "url": "https://your-system.com/webhooks/dialro",
  "events": ["call.started", "call.ended", "call.transcript"],
  "secret": "your_webhook_secret_for_verification"
}

List Webhooks

GET /api/v1/webhooks

Delete Webhook

DELETE /api/v1/webhooks/:id

Webhook Event Types

Event	Description	Payload
call.started	Inbound call received	callId, phoneNumberId, callerNumber, did
call.answered	AI agent answered	callId, agentId, startedAt
call.ended	Call completed	callId, durationSeconds, hangupReason
call.transcript	Transcript available	callId, transcriptSummary
credits.low	Credits below threshold	balanceMinutes, threshold
function.called	AI invoked a function	callId, functionName, parameters, result

Webhook Payload Format

POST https://your-system.com/webhooks/dialro
Content-Type: application/json
X-Dialro-Signature: sha256=abc123...

{
  "event": "call.ended",
  "timestamp": "2026-06-28T10:03:30Z",
  "data": {
    "callId": "call_xxx",
    "phoneNumberId": "pn_xyz789",
    "callerNumber": "+628123456789",
    "calleeNumber": "+6289502159000",
    "durationSeconds": 210,
    "talkTimeSeconds": 195,
    "hangupReason": "normal",
    "hangupInitiator": "caller",
    "transcriptSummary": "Customer booked appointment for Tuesday 2pm.",
    "aiCostIdr": 1500
  }
}

Webhook Signature Verification

Verify the X-Dialro-Signature header using HMAC-SHA256:

import hmac, hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Function Calling

Define custom functions that your AI agent can call during a call. When the AI decides to call a function, Dialro sends an HTTP request to your specified endpoint.

Create Function

POST /api/v1/agents/:id/functions
Content-Type: application/json

{
  "name": "check_appointment",
  "description": "Check if a phone number has an upcoming appointment",
  "endpoint": "https://your-api.com/appointments/check",
  "method": "GET",
  "parameters": {
    "type": "object",
    "properties": {
      "phone": {
        "type": "string",
        "description": "Customer phone number in E.164 format"
      }
    },
    "required": ["phone"]
  }
}

How It Works

1. Customer calls your WhatsApp number
2. AI agent answers and converses naturally
3. Customer asks: "Apakah saya ada janji besok?"
4. AI decides to call check_appointment function
5. Dialro sends HTTP request to your endpoint with parameters
6. Your endpoint returns: { "hasAppointment": true, "date": "2026-06-29", "time": "14:00" }
7. AI tells customer: "Iya, Anda ada janji besok jam 2 siang"

Function Request Format

When AI calls a function, Dialro sends this to your endpoint:

POST https://your-api.com/appointments/check
Content-Type: application/json
X-Dialro-Signature: sha256=...

{
  "callId": "call_xxx",
  "functionName": "check_appointment",
  "parameters": {
    "phone": "+628123456789"
  }
}

Function Response

Your endpoint should return JSON within 5 seconds:

{
  "hasAppointment": true,
  "date": "2026-06-29",
  "time": "14:00",
  "doctor": "Dr. Sari"
}

List Functions

GET /api/v1/agents/:id/functions

Delete Function

DELETE /api/v1/agents/:id/functions/:name

---

Need help? Email [email protected] or visit our dashboard.