DialogBot Developer Docs
Integrate DialogBot's voice AI into your dental practice management software. Manage calls, appointments, recall campaigns, and analytics — all via a simple REST API.
Overview
The DialogBot REST API lets you programmatically manage every aspect of your dental practice voice AI — from call routing and appointment booking to recall campaigns and analytics.
api.dialogbot.ca/v1Bearer token (API key)JSON (application/json)Authentication
All API requests must include your API key as a Bearer token in the Authorization header. You can generate and manage API keys from your DialogBot dashboard.
Authorization: Bearer db_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKeep your API key secret. Never expose it in client-side code or public repositories. Use environment variables in your backend.
API Key types
db_live_...For production use. Affects real patient data and calls.
db_test_...For development and testing. No real calls are made.
Quickstart
Make your first API call in under 2 minutes. This example retrieves a list of recent patient calls from your practice.
1. Install the DialogBot SDK (optional)
npm install @dialogbot/node2. Fetch recent calls
import DialogBot from '@dialogbot/node';
const client = new DialogBot({
apiKey: process.env.DIALOGBOT_API_KEY,
});
const calls = await client.calls.list({
limit: 10,
status: 'completed',
});
console.log(calls.data);3. Example response
{
"data": [
{
"id": "call_01HXYZ",
"patient_phone": "+14165550100",
"direction": "inbound",
"status": "completed",
"duration_seconds": 94,
"intent": "appointment_booking",
"appointment_booked": true,
"created_at": "2025-05-10T14:32:00Z"
}
],
"meta": {
"total": 1482,
"page": 1,
"per_page": 10
}
}Calls
Retrieve and manage patient call records. All inbound and outbound calls handled by DialogBot are logged and accessible via this endpoint.
/callsList all calls/calls/{id}Retrieve a call/calls/{id}/transcriptGet call transcript/calls/{id}/recordingGet call recording URL/calls/outboundInitiate an outbound callList calls — query parameters
limitintegerNumber of results (default: 20, max: 100)pageintegerPage number for paginationstatusstringFilter by status: completed, missed, in_progressdirectionstringFilter by direction: inbound, outboundfromISO 8601Start date filtertoISO 8601End date filterAppointments
Create, update, and cancel appointments. DialogBot syncs with your practice management software in real time — changes made via the API are reflected immediately.
/appointmentsList appointments/appointments/{id}Retrieve an appointment/appointmentsCreate an appointment/appointments/{id}Update an appointment/appointments/{id}Cancel an appointmentCreate appointment — request body
{
"patient_phone": "+14165550100",
"patient_name": "Maria Santos",
"appointment_type": "cleaning",
"provider_id": "prov_01HXYZ",
"start_time": "2025-06-15T10:00:00-04:00",
"duration_minutes": 60,
"notes": "Patient requested morning slot"
}Recall Campaigns
Create and manage automated recall campaigns. DialogBot will proactively call patients overdue for cleanings, check-ups, or follow-up treatments.
/recall/campaignsList recall campaigns/recall/campaignsCreate a campaign/recall/campaigns/{id}/resultsGet campaign results/recall/campaigns/{id}Update a campaign/recall/campaigns/{id}/pausePause a campaign/recall/campaigns/{id}/resumeResume a campaignCreate campaign — request body
{
"name": "June Hygiene Recall",
"type": "hygiene_recall",
"patient_list": ["pat_01", "pat_02"],
"script_id": "script_cleaning_en",
"schedule": {
"start_date": "2025-06-01",
"call_window": { "from": "09:00", "to": "17:00" },
"timezone": "America/Toronto",
"max_attempts": 3
}
}Analytics
Pull call volume, booking rates, recall success metrics, and ROI data for your practice or across multiple locations.
/analytics/callsCall volume & outcomes summary/analytics/bookingsAppointment booking metrics/analytics/recallRecall campaign performance/analytics/roiRevenue recovery estimateCall analytics — example response
{
"period": "2025-05-01/2025-05-31",
"total_calls": 842,
"answered": 798,
"missed": 44,
"answer_rate": 0.948,
"appointments_booked": 312,
"booking_conversion_rate": 0.391,
"avg_call_duration_seconds": 87,
"top_intents": [
{ "intent": "appointment_booking", "count": 312 },
{ "intent": "general_inquiry", "count": 241 },
{ "intent": "emergency_triage", "count": 89 }
]
}Webhooks
Receive real-time event notifications when calls complete, appointments are booked, or recall campaigns reach milestones. Register webhook endpoints from your dashboard.
call.completedA patient call has ended
call.missedAn inbound call was not answered
appointment.bookedA new appointment was created
appointment.cancelledAn appointment was cancelled
recall.attempt.completedA recall call attempt finished
recall.campaign.finishedA recall campaign has ended
Webhook payload example — appointment.booked
{
"event": "appointment.booked",
"created_at": "2025-05-10T14:32:00Z",
"data": {
"appointment_id": "appt_01HXYZ",
"patient_phone": "+14165550100",
"patient_name": "Maria Santos",
"appointment_type": "cleaning",
"start_time": "2025-06-15T10:00:00-04:00",
"booked_via": "voice_ai",
"call_id": "call_01HABC"
}
}Error Codes
DialogBot uses standard HTTP status codes. All error responses include a machine-readable code and a human-readable message.
bad_requestInvalid request body or missing required fieldsunauthorizedMissing or invalid API keyforbiddenAPI key does not have permission for this actionnot_foundThe requested resource does not existconflictAppointment slot is no longer availableunprocessableRequest is valid but cannot be processedrate_limitedToo many requests — retry after the Retry-After headerserver_errorAn unexpected error occurred on our endPHIPA & PIPEDA
All data accessed via the DialogBot API is subject to Ontario's Personal Health Information Protection Act (PHIPA) and Canada's federal PIPEDA. Here's what that means for your integration.
All patient data is stored and processed on Canadian servers. API responses never route through non-Canadian infrastructure.
DialogBot logs patient consent for outbound calls. Your integration must not initiate recall calls without a valid consent record.
Every API call that reads or modifies patient data is logged with your API key ID, timestamp, and IP address for PHIPA audit purposes.
Only request the patient fields your integration needs. Avoid storing full call transcripts unless required for your use case.
SDKs & Libraries
Official DialogBot SDKs are available for the most common backend languages used in dental practice integrations.
@dialogbot/nodedialogbot-pythondialogbot/dialogbot-phpNeed help with your integration?
Our Ontario-based developer support team is available Monday–Friday, 9am–6pm ET.