API reference

DialBots API

152 endpoints, generated from the OpenAPI description (version 0.1.0) when this site is built. Base URL: https://api.dialbots.ai.

Authentication

Send your API key as Authorization: Bearer db_live_... or in an X-Api-Key header. Keys carry scopes and a call to an endpoint outside the key’s scopes returns 403. See the quickstart.

Lists return { "data": [...], "next_cursor": "..." }. Errors return { "error": { "type", "code", "message" } }. Some actions, such as team management, API key management, buying phone numbers and connecting WhatsApp, are only available to signed-in users in the panel and are not listed here.

curl https://api.dialbots.ai/v1/calls?limit=10 \
  -H "Authorization: Bearer db_live_YOUR_KEY"

Calls

Place an outbound call with a published agent
POST/v1/calls
Request body (JSON)
- agent_id string (uuid), required
- to string, required
- from_number_id string (uuid) (nullable)
- contact_id string (uuid) (nullable)
- variables object
- idempotency_key string (nullable)
List calls (newest first)
GET/v1/calls
Query parameters
- limit integer
- cursor string (nullable)
- agent_id string (uuid) (nullable)
- campaign_id string (uuid) (nullable)
- status string (nullable)
- end_reason string (nullable)
- is_test boolean (nullable)
- direction string (nullable)
- disposition string (nullable)
- contact_id string (uuid) (nullable)
- q string (nullable)
  Contact name or phone contains
- from string (date) (nullable)
- to string (date) (nullable)
One call with transcript, cost, latency and a signed recording URL
GET/v1/calls/{call_id}
Path parameters
- call_id string (uuid), required
End a test call (anyone who may place calls) or a live call (admins) by closing its room
POST/v1/calls/{call_id}/hangup
Path parameters
- call_id string (uuid), required
Phone test of the DRAFT agent
POST/v1/agents/{agent_id}/test-call
Path parameters
- agent_id string (uuid), required
Request body (JSON)
- to string, required

Agents

Voice catalog (Gemini Live)
GET/v1/voices
Model presets with latency / cost / quality labels
GET/v1/model-presets
Starter templates for any industry
GET/v1/agent-templates
Create a draft agent from a template
POST/v1/agent-templates/{key}/create
Path parameters
- key string, required
Request body (JSON)
- name string (nullable)
- overrides object
Describe your agent: generate instructions with an LLM
POST/v1/agents/generate-instructions
Request body (JSON)
- description string, required
- languages string[] (nullable)
- industry string (nullable)
Create an agent (the row is the draft)
POST/v1/agents
Request body (JSON)
- name string, required
- instructions any
- opening_message any
- languages any
- voice_id any
- model_tier any
- max_duration_s any
- silence_timeout_s any
- voicemail_action any
- voicemail_message any
- ai_disclosure any
- transfer_number any
- tools any
- kb_ids any
- stt_vocabulary any
- pronunciations any
- extraction_schema any
- disposition_options any
- kb_fallback any
- transfer_fallback any
List agents
GET/v1/agents
Query parameters
- limit integer
- cursor string (nullable)
- status string
- q string (nullable)
Get an agent (draft + publish state)
GET/v1/agents/{agent_id}
Path parameters
- agent_id string (uuid), required
Edit the draft (never touches published versions)
PATCH/v1/agents/{agent_id}
Path parameters
- agent_id string (uuid), required
Request body (JSON)
- name string (nullable)
- instructions any
- opening_message any
- languages any
- voice_id any
- model_tier any
- max_duration_s any
- silence_timeout_s any
- voicemail_action any
- voicemail_message any
- ai_disclosure any
- transfer_number any
- tools any
- kb_ids any
- stt_vocabulary any
- pronunciations any
- extraction_schema any
- disposition_options any
- kb_fallback any
- transfer_fallback any
Alias of archive (agents are never hard-deleted)
DELETE/v1/agents/{agent_id}
Path parameters
- agent_id string (uuid), required
Publish the draft as a new immutable version
POST/v1/agents/{agent_id}/publish
Path parameters
- agent_id string (uuid), required
Request body (JSON)
- note string (nullable)
Published versions, newest first
GET/v1/agents/{agent_id}/versions
Path parameters
- agent_id string (uuid), required
Query parameters
- limit integer
- before integer (nullable)
One published version
GET/v1/agents/{agent_id}/versions/{version}
Path parameters
- agent_id string (uuid), required
- version integer, required
Copy an old version into the draft and publish it as a new version
POST/v1/agents/{agent_id}/rollback
Path parameters
- agent_id string (uuid), required
Request body (JSON)
- version integer, required
- note string (nullable)
Duplicate as a new draft
POST/v1/agents/{agent_id}/duplicate
Path parameters
- agent_id string (uuid), required
Archive (soft delete); published versions are kept
POST/v1/agents/{agent_id}/archive
Path parameters
- agent_id string (uuid), required
Restore an archived agent
POST/v1/agents/{agent_id}/restore
Path parameters
- agent_id string (uuid), required

Knowledge bases

Create a knowledge base
POST/v1/knowledge-bases
Request body (JSON)
- name string, required
- description string (nullable)
List knowledge bases
GET/v1/knowledge-bases
Query parameters
- limit integer
- cursor string (nullable)
Get a knowledge base
GET/v1/knowledge-bases/{kb_id}
Path parameters
- kb_id string (uuid), required
Rename / describe a knowledge base
PATCH/v1/knowledge-bases/{kb_id}
Path parameters
- kb_id string (uuid), required
Request body (JSON)
- name string (nullable)
- description string (nullable)
Delete a knowledge base and its documents
DELETE/v1/knowledge-bases/{kb_id}
Path parameters
- kb_id string (uuid), required
Add a text, FAQ or URL document (ingested in the background)
POST/v1/knowledge-bases/{kb_id}/documents
Path parameters
- kb_id string (uuid), required
Request body (JSON)
- kind string, required
- title string (nullable)
- text string (nullable)
- faqs FaqPair[] (nullable)
- url string (nullable)
List documents with ingest status
GET/v1/knowledge-bases/{kb_id}/documents
Path parameters
- kb_id string (uuid), required
Query parameters
- limit integer
- cursor string (nullable)
- status string (nullable)
Upload a pdf, docx, txt, md or csv file
POST/v1/knowledge-bases/{kb_id}/documents/file
Path parameters
- kb_id string (uuid), required
One document (with chunk count)
GET/v1/knowledge-bases/{kb_id}/documents/{doc_id}
Path parameters
- kb_id string (uuid), required
- doc_id string (uuid), required
Delete a document and its chunks
DELETE/v1/knowledge-bases/{kb_id}/documents/{doc_id}
Path parameters
- kb_id string (uuid), required
- doc_id string (uuid), required
Re-run ingestion (e.g. after a failure or a page change)
POST/v1/knowledge-bases/{kb_id}/documents/{doc_id}/reingest
Path parameters
- kb_id string (uuid), required
- doc_id string (uuid), required
Semantic search
POST/v1/knowledge-bases/{kb_id}/search
Path parameters
- kb_id string (uuid), required
Request body (JSON)
- query string, required
- k integer

Contacts

Create a contact
POST/v1/contacts
Request body (JSON)
- phone string, required
- name string (nullable)
- email string (nullable)
- whatsapp string (nullable)
- language string (nullable)
- timezone string (nullable)
- owner_user_id string (uuid) (nullable)
- source string (nullable)
- attributes object
- tags string[]
- dnd boolean
- consent object
List contacts (cursor pagination, search, filters)
GET/v1/contacts
Query parameters
- limit integer
- cursor string (nullable)
- q string (nullable)
  matches name, email, phone
- tag string (nullable)
- list_id string (uuid) (nullable)
- dnd boolean (nullable)
- source string (nullable)
- owner_user_id string (uuid) (nullable)
- created_after string (date-time) (nullable)
- created_before string (date-time) (nullable)
- attr string (nullable)
  custom attribute filter key:value
Get a contact
GET/v1/contacts/{contact_id}
Path parameters
- contact_id string (uuid), required
Update a contact
PATCH/v1/contacts/{contact_id}
Path parameters
- contact_id string (uuid), required
Request body (JSON)
- phone string (nullable)
- name string (nullable)
- email string (nullable)
- whatsapp string (nullable)
- language string (nullable)
- timezone string (nullable)
- owner_user_id string (uuid) (nullable)
- source string (nullable)
- attributes object (nullable)
- tags string[] (nullable)
- dnd boolean (nullable)
- consent object (nullable)
Delete a contact
DELETE/v1/contacts/{contact_id}
Path parameters
- contact_id string (uuid), required
Bulk tag / untag / delete (max 1000 ids)
POST/v1/contacts/bulk
Request body (JSON)
- action string, required
- contact_ids string (uuid)[], required
- tags string[]
Timeline (notes, calls, messages, dispositions)
GET/v1/contacts/{contact_id}/notes
Path parameters
- contact_id string (uuid), required
Query parameters
- limit integer
- cursor string (nullable)
- kind string (nullable)
Add a note
POST/v1/contacts/{contact_id}/notes
Path parameters
- contact_id string (uuid), required
Request body (JSON)
- body string, required
- kind string
List tags
GET/v1/tags
Delete a tag (removes it from contacts)
DELETE/v1/tags/{tag_id}
Path parameters
- tag_id string (uuid), required
Create a contact list
POST/v1/lists
Request body (JSON)
- name string, required
- description string (nullable)
List contact lists
GET/v1/lists
Rename a list
PATCH/v1/lists/{list_id}
Path parameters
- list_id string (uuid), required
Request body (JSON)
- name string, required
- description string (nullable)
Delete a list (contacts stay)
DELETE/v1/lists/{list_id}
Path parameters
- list_id string (uuid), required
Add contacts to a list
POST/v1/lists/{list_id}/members
Path parameters
- list_id string (uuid), required
Request body (JSON)
- contact_ids string (uuid)[], required
Contacts in a list
GET/v1/lists/{list_id}/members
Path parameters
- list_id string (uuid), required
Query parameters
- limit integer
- cursor string (nullable)
Remove a contact from a list
DELETE/v1/lists/{list_id}/members/{contact_id}
Path parameters
- list_id string (uuid), required
- contact_id string (uuid), required
Define a custom contact field
POST/v1/custom-fields
Request body (JSON)
- key string, required
- label string, required
- type string, required
- options string[]
- required boolean
List custom field definitions
GET/v1/custom-fields
Delete a field definition (values stay on contacts)
DELETE/v1/custom-fields/{field_id}
Path parameters
- field_id string (uuid), required
Add a number to the workspace do-not-call list
POST/v1/dnd
Request body (JSON)
- phone string, required
- reason string (nullable)
Workspace do-not-call list
GET/v1/dnd
Query parameters
- limit integer
- cursor string (nullable)
Remove a do-not-call entry
DELETE/v1/dnd/{entry_id}
Path parameters
- entry_id string (uuid), required

Contact imports and exports

Upload a CSV; returns headers, sample rows and a suggested mapping
POST/v1/contacts/imports
Recent import jobs (resume a wizard after a refresh)
GET/v1/contacts/imports
Query parameters
- status string (nullable)
- limit integer
Map columns and start the background import
POST/v1/contacts/imports/{import_id}/start
Path parameters
- import_id string (uuid), required
Request body (JSON)
- mapping object, required
  target -> CSV header. Targets: phone (required), name, email, whatsapp, language, timezone, source, tags, or attributes.<custom_field_key>
- on_duplicate string
- list_id string (uuid) (nullable)
- tags string[]
  tags applied to every imported contact
- default_region string (nullable)
Progress and per-row errors
GET/v1/contacts/imports/{import_id}
Path parameters
- import_id string (uuid), required
Dry run: check every row with this mapping, change nothing
POST/v1/contacts/imports/{import_id}/validate
Path parameters
- import_id string (uuid), required
Request body (JSON)
- mapping object, required
  target -> CSV header. Targets: phone (required), name, email, whatsapp, language, timezone, source, tags, or attributes.<custom_field_key>
- on_duplicate string
- list_id string (uuid) (nullable)
- tags string[]
  tags applied to every imported contact
- default_region string (nullable)
Row-level errors as a CSV (row, column, error + the original columns)
GET/v1/contacts/imports/{import_id}/errors.csv
Path parameters
- import_id string (uuid), required
Continue a failed or stalled import where it stopped
POST/v1/contacts/imports/{import_id}/resume
Path parameters
- import_id string (uuid), required
Start a contacts CSV export (runs in the background)
POST/v1/contacts/exports
Request body (JSON)
- q string (nullable)
- tag string (nullable)
- list_id string (uuid) (nullable)
- dnd boolean (nullable)
- source string (nullable)
- owner_user_id string (uuid) (nullable)
- created_after string (date-time) (nullable)
- created_before string (date-time) (nullable)
Recent export jobs
GET/v1/contacts/exports
Query parameters
- limit integer
Export progress
GET/v1/contacts/exports/{job_id}
Path parameters
- job_id string (uuid), required
The finished CSV
GET/v1/contacts/exports/{job_id}/download
Path parameters
- job_id string (uuid), required

Campaigns

Create a draft campaign (optionally with its audience)
POST/v1/campaigns
Request body (JSON)
- name string, required
- agent_id string (uuid), required
- agent_version integer (nullable)
  pin a published version; omit to always use the latest
- from_number_id string (uuid) (nullable)
- audience Audience (nullable)
- schedule object (nullable)
- daily_limit integer (nullable)
- concurrency integer (nullable)
- daily_spend_limit number | string (nullable)
- retry object (nullable)
- voice_config object (nullable)
  {whatsapp_fallback: {after_attempts, template, variables?, language?}}: after N unanswered attempts the approved template is sent on WhatsApp
List campaigns (newest first)
GET/v1/campaigns
Query parameters
- limit integer
- cursor string (nullable)
- status string (nullable)
One campaign with its screening counts
GET/v1/campaigns/{campaign_id}
Path parameters
- campaign_id string (uuid), required
Edit a draft; a live campaign accepts schedule, limits, lines and retries
PATCH/v1/campaigns/{campaign_id}
Path parameters
- campaign_id string (uuid), required
Request body (JSON)
- name string (nullable)
- agent_id string (uuid) (nullable)
- agent_version integer (nullable)
- from_number_id string (uuid) (nullable)
- schedule object (nullable)
- daily_limit integer (nullable)
- concurrency integer (nullable)
- daily_spend_limit number | string (nullable)
- retry object (nullable)
- voice_config object (nullable)
Delete a draft campaign
DELETE/v1/campaigns/{campaign_id}
Path parameters
- campaign_id string (uuid), required
Replace the audience of a draft (screened, deduplicated on E.164)
PUT/v1/campaigns/{campaign_id}/audience
Path parameters
- campaign_id string (uuid), required
Request body (JSON)
- list_id string (uuid) (nullable)
- filter object (nullable)
- contact_ids string (uuid)[] (nullable)
- skip_called_within_days integer (nullable)
Add contacts to a draft, paused or running campaign
POST/v1/campaigns/{campaign_id}/contacts
Path parameters
- campaign_id string (uuid), required
Request body (JSON)
- list_id string (uuid) (nullable)
- filter object (nullable)
- contact_ids string (uuid)[] (nullable)
- skip_called_within_days integer (nullable)
Counts per screening reason
GET/v1/campaigns/{campaign_id}/screening
Path parameters
- campaign_id string (uuid), required
Start now, or schedule with start_at (402 trial_campaigns_locked during the trial)
POST/v1/campaigns/{campaign_id}/start
Path parameters
- campaign_id string (uuid), required
Pause (reversible; calls in progress finish)
POST/v1/campaigns/{campaign_id}/pause
Path parameters
- campaign_id string (uuid), required
Resume a paused campaign
POST/v1/campaigns/{campaign_id}/resume
Path parameters
- campaign_id string (uuid), required
Cancel (cannot be resumed; calls in progress finish)
POST/v1/campaigns/{campaign_id}/cancel
Path parameters
- campaign_id string (uuid), required
Copy a campaign's settings and contacts into a new draft
POST/v1/campaigns/{campaign_id}/duplicate
Path parameters
- campaign_id string (uuid), required
Live progress, lines in use, dialer state, ETA, end-reason breakdown
GET/v1/campaigns/{campaign_id}/progress
Path parameters
- campaign_id string (uuid), required
Cost range and duration before starting
GET/v1/campaigns/{campaign_id}/estimate
Path parameters
- campaign_id string (uuid), required
Per-contact status, attempts, last end reason (filters: status, end_reason, attempts, outcome)
GET/v1/campaigns/{campaign_id}/targets
Path parameters
- campaign_id string (uuid), required
Query parameters
- limit integer
- cursor string (nullable)
- status string (nullable)
- end_reason string (nullable)
- attempts integer (nullable)
- outcome string (nullable)
- skip_reason string (nullable)
Results as CSV (streamed)
GET/v1/campaigns/{campaign_id}/export.csv
Path parameters
- campaign_id string (uuid), required

Phone numbers

Phone numbers this workspace can call from
GET/v1/phone-numbers
Choose the agent that answers inbound calls (empty = none)
PATCH/v1/phone-numbers/{number_id}
Path parameters
- number_id string (uuid), required
Request body (JSON)
- inbound_agent_id string (uuid) (nullable)
Calling-account status for buying numbers
GET/v1/numbers/account
Set up the calling account (idempotent)
POST/v1/numbers/account
Identity-verification steps, fields, uploads and status for this workspace's country
GET/v1/numbers/kyc
Refresh identity-verification status
GET/v1/numbers/account/kyc
Submit one identity-verification step (register, pan, aadhaar, gst, final)
POST/v1/numbers/account/kyc/{step}
Path parameters
- step string, required
Kinds of numbers on offer
GET/v1/numbers/types
Numbers available to buy
GET/v1/numbers/inventory
Query parameters
- type integer, required
- months integer
- number string (nullable)
- page integer
- per_page integer
Price a number (locks it briefly)
POST/v1/numbers/quote
Request body (JSON)
- did_id integer, required
- number string, required
- months integer
- lines integer
Buy a quoted number from the wallet
POST/v1/numbers/purchase
Request body (JSON)
- quote_id string, required

Wallet

Wallet balance in the workspace currency
GET/v1/wallet
Set the low-balance alert threshold (empty = off)
PATCH/v1/wallet
Request body (JSON)
- low_balance_threshold number | string (nullable)
Ledger (newest first)
GET/v1/wallet/transactions
Query parameters
- limit integer
- cursor string (nullable)
- source string (nullable)

Analytics

Calls, answer rate, duration, minutes, spend, outcome and end-reason counts
GET/v1/analytics/summary
Query parameters
- from string (date) (nullable)
- to string (date) (nullable)
- agent_id string (uuid) (nullable)
- campaign_id string (uuid) (nullable)
- include_tests boolean
One metric per day (workspace timezone) or per hour
GET/v1/analytics/series
Query parameters
- metric "calls" | "answered" | "spend" | "minutes"
- interval "day" | "hour"
- from string (date) (nullable)
- to string (date) (nullable)
- agent_id string (uuid) (nullable)
- campaign_id string (uuid) (nullable)
- include_tests boolean
Usage and spend grouped by agent, campaign or phone number
GET/v1/usage
Query parameters
- group_by "agent" | "campaign" | "number"
- from string (date) (nullable)
- to string (date) (nullable)
- agent_id string (uuid) (nullable)
- campaign_id string (uuid) (nullable)
- include_tests boolean

Webhooks

Create an endpoint (signing secret shown once)
POST/v1/webhooks
Request body (JSON)
- url string, required
- events string[], required
- description string (nullable)
List endpoints
GET/v1/webhooks
Get an endpoint
GET/v1/webhooks/{ep_id}
Path parameters
- ep_id string (uuid), required
Update an endpoint
PATCH/v1/webhooks/{ep_id}
Path parameters
- ep_id string (uuid), required
Request body (JSON)
- url string (nullable)
- events string[] (nullable)
- description string (nullable)
- active boolean (nullable)
Delete an endpoint
DELETE/v1/webhooks/{ep_id}
Path parameters
- ep_id string (uuid), required
Rotate the signing secret (shown once)
POST/v1/webhooks/{ep_id}/rotate-secret
Path parameters
- ep_id string (uuid), required
Send a signed test ping now (not retried)
POST/v1/webhooks/{ep_id}/test
Path parameters
- ep_id string (uuid), required
Delivery log (cursor paginated)
GET/v1/webhooks/{ep_id}/deliveries
Path parameters
- ep_id string (uuid), required
Query parameters
- limit integer
- cursor string (nullable)
- status string (nullable)
Queue a delivery again
POST/v1/webhooks/deliveries/{delivery_id}/redeliver
Path parameters
- delivery_id string (uuid), required

Workspace

Active workspace
GET/v1/workspace
Edit workspace name / timezone
PATCH/v1/workspace
Request body (JSON)
- name string (nullable)
- timezone string (nullable)
List members
GET/v1/workspace/members
Change a member's role
PATCH/v1/workspace/members/{user_id}
Path parameters
- user_id string (uuid), required
Request body (JSON)
- role string, required
Remove a member
DELETE/v1/workspace/members/{user_id}
Path parameters
- user_id string (uuid), required
Invite someone by email
POST/v1/workspace/invites
Request body (JSON)
- email string (email), required
- role string
Pending invites
GET/v1/workspace/invites
Revoke an invite
DELETE/v1/workspace/invites/{invite_id}
Path parameters
- invite_id string (uuid), required

WhatsApp numbers

WhatsApp numbers of the workspace
GET/v1/whatsapp/accounts
One WhatsApp number
GET/v1/whatsapp/accounts/{account_id}
Path parameters
- account_id string (uuid), required
Rename a number (display label in DialBots only)
PATCH/v1/whatsapp/accounts/{account_id}
Path parameters
- account_id string (uuid), required
Request body (JSON)
- display_name string (nullable)
Disconnect a number (templates and history are kept)
DELETE/v1/whatsapp/accounts/{account_id}
Path parameters
- account_id string (uuid), required
Everything the Facebook JS SDK needs to launch Embedded Signup
GET/v1/whatsapp/connect/config
Query parameters
- mode "new" | "coexistence"
Finish Embedded Signup: exchange the code, subscribe the app, register the number
POST/v1/whatsapp/connect
Request body (JSON)
- code string, required
- waba_id string, required
- phone_number_id string, required
- mode "new" | "coexistence"
- business_id string (nullable)
- redirect_uri string (nullable)
Connect a number through AiSensy (templates only)
POST/v1/whatsapp/accounts/aisensy
Request body (JSON)
- api_key string, required
- display_name string, required
- display_phone string (nullable)
Re-read quality rating, messaging limit and status from Meta
POST/v1/whatsapp/accounts/{account_id}/refresh
Path parameters
- account_id string (uuid), required
Bot settings of a number
GET/v1/whatsapp/accounts/{account_id}/bot
Path parameters
- account_id string (uuid), required
Bind the number to an agent and set the bot's behaviour
PUT/v1/whatsapp/accounts/{account_id}/bot
Path parameters
- account_id string (uuid), required
Request body (JSON)
- enabled boolean (nullable)
- agent_id string (uuid) (nullable)
- settings object (nullable)

WhatsApp inbox

Conversations, newest message first
GET/v1/whatsapp/conversations
Query parameters
- filter string
- q string (nullable)
- account_id string (uuid) (nullable)
- contact_id string (uuid) (nullable)
- cursor string (nullable)
- limit integer
One conversation
GET/v1/whatsapp/conversations/{conv_id}
Path parameters
- conv_id string (uuid), required
Messages, newest first (page back with next_cursor, then reverse for display)
GET/v1/whatsapp/conversations/{conv_id}/messages
Path parameters
- conv_id string (uuid), required
Query parameters
- cursor string (nullable)
- limit integer
Send a text (24-hour window only), media or template message
POST/v1/whatsapp/conversations/{conv_id}/messages
Path parameters
- conv_id string (uuid), required
Request body (JSON)
- text string (nullable)
- template TemplateRef (nullable)
- media MediaRef (nullable)
- reply_to string (nullable)
Send to a phone or contact (starts the conversation if needed)
POST/v1/whatsapp/messages
Request body (JSON)
- text string (nullable)
- template TemplateRef (nullable)
- media MediaRef (nullable)
- reply_to string (nullable)
- to string (nullable)
- contact_id string (uuid) (nullable)
- account_id string (uuid) (nullable)
Assign to a member (null to unassign)
POST/v1/whatsapp/conversations/{conv_id}/assign
Path parameters
- conv_id string (uuid), required
Request body (JSON)
- user_id string (uuid) (nullable), required
Take over from the AI (to=human) or give the conversation back (to=ai)
POST/v1/whatsapp/conversations/{conv_id}/handover
Path parameters
- conv_id string (uuid), required
Request body (JSON)
- to "human" | "ai", required
- reason string (nullable)
Mark the conversation read
POST/v1/whatsapp/conversations/{conv_id}/read
Path parameters
- conv_id string (uuid), required
Download a customer's media (proxied from Meta; the token never leaves the server)
GET/v1/whatsapp/messages/{message_id}/media
Path parameters
- message_id string (uuid), required

WhatsApp templates

Templates of the workspace
GET/v1/whatsapp/templates
Query parameters
- account_id string (uuid) (nullable)
- status string (nullable)
- category string (nullable)
- language string (nullable)
- limit integer
Create a template and submit it for review (AiSensy: register an API campaign name)
POST/v1/whatsapp/templates
Request body (JSON)
- account_id string (uuid), required
- name string, required
- language string, required
- category "marketing" | "utility" | "authentication", required
- components object[], required
Pull templates and their review status from Meta
POST/v1/whatsapp/templates/sync
Request body (JSON)
- account_id string (uuid), required
One template
GET/v1/whatsapp/templates/{template_id}
Path parameters
- template_id string (uuid), required
Delete a template (all its languages are removed at Meta)
DELETE/v1/whatsapp/templates/{template_id}
Path parameters
- template_id string (uuid), required

WhatsApp calling

Calling settings of a number (live from WhatsApp, cached copy if WhatsApp is unreachable)
GET/v1/whatsapp/accounts/{account_id}/calling
Path parameters
- account_id string (uuid), required
Change calling settings (enable, call button, callback requests, hours); saved to WhatsApp at once
PUT/v1/whatsapp/accounts/{account_id}/calling
Path parameters
- account_id string (uuid), required
Request body (JSON)
- enabled boolean (nullable)
- call_icon_visibility "DEFAULT" | "DISABLE_ALL" (nullable)
- restrict_to_user_countries string[] (nullable)
- callback_permission boolean (nullable)
- call_hours HoursIn (nullable)
Call permission per contact: none / temporary (expiry) / permanent / declined
GET/v1/whatsapp/accounts/{account_id}/calling/permissions
Path parameters
- account_id string (uuid), required
Query parameters
- contact_id string (uuid) (nullable)
- status string (nullable)
- limit integer
Ask a customer for permission to call them on WhatsApp
POST/v1/whatsapp/accounts/{account_id}/calling/permission-requests
Path parameters
- account_id string (uuid), required
Request body (JSON)
- contact_id string (uuid) (nullable)
- phone string (nullable)
- template object (nullable)
- body_text string (nullable)
Webhook-derived activity: call connected / ended, permission replies, account updates
GET/v1/whatsapp/accounts/{account_id}/calling/events
Path parameters
- account_id string (uuid), required
Query parameters
- event string (nullable)
- cursor string (nullable)
- limit integer
WhatsApp call log: one row per call id (wacid), folded from its webhook events
GET/v1/whatsapp/accounts/{account_id}/calling/calls
Path parameters
- account_id string (uuid), required
Query parameters
- limit integer
Is calling available for this number, and why not
GET/v1/whatsapp/accounts/{account_id}/calling/status
Path parameters
- account_id string (uuid), required

Test chat

Text chat with the DRAFT (or a published version) of an agent
POST/v1/agents/{agent_id}/test-chat
Path parameters
- agent_id string (uuid), required
Request body (JSON)
- messages ChatMessage[]
- version integer (nullable)
- execute_tools boolean
Browser voice test of the DRAFT (or a version) of an agent
POST/v1/agents/{agent_id}/web-call
Path parameters
- agent_id string (uuid), required
Request body (JSON)
- version integer (nullable)

DialBots API

Authentication

Calls

Place an outbound call with a published agent

Request body (JSON)

List calls (newest first)

Query parameters

One call with transcript, cost, latency and a signed recording URL

Path parameters

End a test call (anyone who may place calls) or a live call (admins) by closing its room

Path parameters

Phone test of the DRAFT agent

Path parameters

Request body (JSON)

Agents

Voice catalog (Gemini Live)

Model presets with latency / cost / quality labels

Starter templates for any industry

Create a draft agent from a template

Path parameters

Request body (JSON)

Describe your agent: generate instructions with an LLM

Request body (JSON)

Create an agent (the row is the draft)

Request body (JSON)

List agents

Query parameters

Get an agent (draft + publish state)

Path parameters

Edit the draft (never touches published versions)

Path parameters

Request body (JSON)

Alias of archive (agents are never hard-deleted)

Path parameters

Publish the draft as a new immutable version

Path parameters

Request body (JSON)

Published versions, newest first

Path parameters

Query parameters

One published version

Path parameters

Copy an old version into the draft and publish it as a new version

Path parameters

Request body (JSON)

Duplicate as a new draft

Path parameters

Archive (soft delete); published versions are kept

Path parameters

Restore an archived agent

Path parameters

Knowledge bases

Create a knowledge base

Request body (JSON)

List knowledge bases

Query parameters

Get a knowledge base

Path parameters

Rename / describe a knowledge base

Path parameters

Request body (JSON)

Delete a knowledge base and its documents

Path parameters

Add a text, FAQ or URL document (ingested in the background)

Path parameters

Request body (JSON)

List documents with ingest status

Path parameters

Query parameters

Upload a pdf, docx, txt, md or csv file

Path parameters

One document (with chunk count)

Path parameters

Delete a document and its chunks

Path parameters

Re-run ingestion (e.g. after a failure or a page change)

Path parameters

Semantic search

Path parameters

Request body (JSON)