DialBots
Start free

Quickstart

From sign-up to your first API call

About ten minutes. You need a DialBots workspace; the trial credit pays for everything on this page.

1. Create an account

Sign up at app.dialbots.ai/signup with email and password or Google. You get free trial credit and no card is needed.

2. Create and test an agent

  1. Choose a template, or describe the job and let the panel draft the agent.
  2. Pick a voice and languages, and write the opening message.
  3. Press Test to talk to the draft from your browser. To hear it on a phone, verify your own number with a one-time code and use Call my phone.
  4. Publish. API calls always use the published version, and every publish is a numbered version you can roll back.

3. Create an API key

In the panel open Settings, then API keys. Give the key only the scopes it needs, for example calls:write and calls:read. The key starts with db_live_ and is shown once. Keep it on your server and never in a browser or mobile app.

Send it as Authorization: Bearer db_live_... (or in an X-Api-Key header). All requests go to https://api.dialbots.ai over HTTPS.

4. Place a call

On a trial workspace, use your own verified phone number as to.

curl -X POST https://api.dialbots.ai/v1/calls \
  -H "Authorization: Bearer db_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_UUID",
    "to": "+919800000000",
    "variables": { "first_name": "Asha", "appointment_at": "tomorrow 11 am" },
    "idempotency_key": "appointment-1042"
  }'

variables fill the placeholders in your agent’s instructions, such as {{contact.first_name}} or the appointment details. idempotency_key makes retries safe: sending the same key again returns the existing call (status 200) instead of dialling twice.

{
  "id": "6f1c0e1e-...",
  "status": "queued",
  "direction": "outbound",
  "agent_id": "AGENT_UUID",
  "to": "+919800000000",
  "is_test": false,
  "created_at": "2026-11-01T10:00:00+00:00"
}

The call object also carries transcript, summary, disposition, extracted fields, cost and duration_seconds once the call has finished.

5. Get notified when it ends

Register an HTTPS endpoint. The response contains the signing secret once, starting with whsec_.

curl -X POST https://api.dialbots.ai/v1/webhooks \
  -H "Authorization: Bearer db_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/dialbots", "events": ["call.completed", "call.failed"] }'

Verify the DialBots-Signature header on the raw body before you trust a request. The webhooks page has complete Python and Node.js code.

6. Read the result

The call.completed webhook carries the call object. You can also fetch it later:

curl https://api.dialbots.ai/v1/calls/CALL_UUID \
  -H "Authorization: Bearer db_live_YOUR_KEY"

Conventions

  • Lists return { "data": [...], "next_cursor": "..." }. Pass next_cursor back as cursor to get the next page.
  • Errors return { "error": { "type", "code", "message" } } with a matching HTTP status.
  • Scopes are checked per request. A key without the scope gets 403.
  • Phone numbers are in E.164 format, for example +919800000000.

Next