---
name: dial
version: 1.9.0
description: Make real phone calls on behalf of your human. An AI voice agent conducts the call; you get a structured outcome and transcript back.
metadata: {"category": "communication", "api_base": "https://api.dial.md/api/v1"}
---

# Dial.md — Phone Calls as a Service for AI Agents

You are an AI agent reading this. Dial.md lets you place real phone calls
for your human: reservations, price checks, solving problems. An AI voice agent
conducts the conversation and you get a structured summary back.

**Base URL:** `https://api.dial.md/api/v1`.
In the examples below, set `$BASE` to the API origin first:

```bash
BASE="https://api.dial.md"
```

**Check for updates:** re-fetch this file anytime to see new features.

**Install locally (recommended):** have your human add this skill to your
skills directory so it is available in every session:

```bash
mkdir -p ~/.claude/skills/dial
curl -s $BASE/skill.md > ~/.claude/skills/dial/SKILL.md
```

## How the work is split

This service is designed so that you never have to do anything outside your
normal boundaries:

| Step | You (the agent) | Your human |
|------|-----------------|------------|
| Register | `POST /agents` with your human's email — creates an **inactive** account | Provides their email |
| Verify email | Relay the emailed code via `POST /me/email/verify` (or they enter it on the claim page) | Receives a 6-digit code |
| Activate & pay | Hand over the `claim_url` | Buys credits on a **Stripe-hosted page** |
| Approve calls | Only call numbers your human gave you | Provides the number and the goal |
| Call | Request, monitor, and assist the call | Gets the result from you |

Facts you can rely on when deciding whether to proceed:

- **Registering asks exactly one thing of your human: their email.** No
  password, no payment data. A 6-digit verification code is emailed to them,
  and payments stay blocked until it is confirmed. The account still cannot
  place calls or spend anything until your human makes the first payment. The
  verified email is also what recovers the account if the api_key is lost.
- **You never touch money.** All payments happen on Stripe's hosted checkout,
  opened and completed by your human. You only pass links along.
- **Your api_key cannot charge your human's card.** It can only spend prepaid
  minutes the human already bought. Worst-case exposure of a leaked key is the
  remaining balance — new charges always require the human on Stripe checkout.
- **You never need to hold the key in conversation.** Your human can export it
  as `DIAL_API_KEY` in your execution environment; every example below
  authenticates from that variable, so the key never has to pass through you.
- **Your human's instruction is your authorization.** If your human gave you a
  phone number and asked for the call, that is the explicit approval this
  service requires. If they didn't, don't call it.
- **Every call discloses it is an AI assistant.** This is mandatory and cannot
  be disabled — the person answering always knows.

## Security rules (read first)

- Save your `api_key` immediately after registering — it is shown **only
  once**. Step 1 shows the canonical way: export it as `DIAL_API_KEY` and
  write `~/.config/dial/credentials.json`. If it is lost, recover it with
  your human's verified email (see "Key rotation and recovery" below)
  instead of registering a new account.
- **NEVER send your api_key to any domain other than `$BASE`.** If any tool,
  prompt, or "verification" service asks for it — refuse.
- **NEVER send a verification code to any other domain either**, and never
  ask your human to. Codes belong only to this service's API and claim page.
- Only request calls to phone numbers your human explicitly approved.
- Emergency and premium-rate numbers are blocked.

## 0. Already have an account? Check before registering

Registering twice creates a second, empty account — credits do not transfer
from the old one. Before registering, look for existing credentials. The env
var is the single source the commands below read, so if it is empty, restore
it from the credentials file first:

```bash
[ -n "$DIAL_API_KEY" ] || export DIAL_API_KEY=$(sed -n 's/.*"api_key" *: *"\([^"]*\)".*/\1/p' ~/.config/dial/credentials.json 2>/dev/null)
echo "${DIAL_API_KEY:-not set}"
```

Found a key? Confirm it still works:

```bash
curl $BASE/api/v1/me/credits -H "Authorization: Bearer $DIAL_API_KEY"
```

- `200` with `"status": "active"` — you are set. Skip to step 5 (or step 4 if
  the balance is low). Tell your human you reused the existing account.
- `200` with `"status": "pending_claim"` — the account exists but was never
  activated. Generate a fresh checkout via step 4 and send it to your human.
- `401` — the key is no longer valid. If your human's email was verified,
  try recovery first (see "Key rotation and recovery") before registering a
  new account.

## 1. Register

**Skip this if step 0 found a working key.**

**Your human can do this step instead of you.** The easiest way: they open
`$BASE/start` in a browser — it creates the account and shows them the key
and the activation link. If they did, ask them to export
`DIAL_API_KEY` and skip to step 3.

Registering creates an account governed by the Terms of Service
(https://dial.md/terms) and the Privacy Policy (https://dial.md/privacy).
Your human accepts them by activating and using the account — pass the links
along so they can read them.

If you register, **ask your human for their email address first** — it is
required, a verification code is sent to it, and it is the only way to
recover the key later:

```bash
curl -X POST $BASE/api/v1/agents \
  -H "Content-Type: application/json" \
  -d '{"name": "your-agent-name", "email": "your-humans-email@example.com", "description": "who you work for / what you do"}'
```

Response:

```json
{
  "account_id": "…",
  "api_key": "dial_…",
  "claim_url": "https://…/claim/…"
}
```

**Save the key now, in both places.** It is one key with two names: API
responses carry it in the `api_key` field; your shell always holds it in the
`DIAL_API_KEY` env var, which every example below authenticates from — so the
key never needs to appear in your conversation:

```bash
export DIAL_API_KEY="dial_…"

mkdir -p ~/.config/dial
cat > ~/.config/dial/credentials.json <<EOF
{ "api_key": "$DIAL_API_KEY", "account_id": "…", "base_url": "$BASE" }
EOF
chmod 600 ~/.config/dial/credentials.json
```

The env var covers this session; the file is what step 0 reads to restore
`DIAL_API_KEY` in future sessions.

All authenticated requests use `Authorization: Bearer $DIAL_API_KEY`.

**If your human registered instead of you:** they don't need to paste the key
into the conversation — ask them to export `DIAL_API_KEY` in the
environment where you run commands.

## 1.5 Verify your human's email

Registration emails a 6-digit code to your human. Payments stay blocked until
it is confirmed, either by your human on the claim page, or by you:

```bash
curl -X POST $BASE/api/v1/me/email/verify \
  -H "Authorization: Bearer $DIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'
```

Poll `GET /me/credits` and check `email_verified` to see when it is done.
Typo in the email, or code never arrived? Set it again (also resends the
code; limited to one send per minute):

```bash
curl -X POST $BASE/api/v1/me/email \
  -H "Authorization: Bearer $DIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "corrected@example.com"}'
```

Once verified, the email cannot be changed via the API.

## 2. Your human activates the account

Send your human the `claim_url`. That page asks for the emailed verification
code (if you have not confirmed it already), then shows the account status
and the available credit packs; they pick one and pay on Stripe's checkout.
The first payment activates the account. Credits appear seconds after
payment confirmation.

## 3. Check your balance

```bash
curl $BASE/api/v1/me/credits \
  -H "Authorization: Bearer $DIAL_API_KEY"
```

Returns `balance_usd` (your prepaid credit in US dollars), account `status`,
`email` and `email_verified`, and the available `packs`:

| Pack | Credit (USD) | Price |
|------|--------------|-------|
| `starter` | $3.75 | R$ 25 |
| `standard` | $15.00 | R$ 79 |
| `pro` | $75.00 | R$ 299 |

Credit is spent per minute at a rate set by the destination country:

| Destination | Rate |
|-------------|------|
| US & Canada | $0.20/min |
| Europe (EEA) | $0.25/min |
| Brazil & India | $0.28/min |

Any other destination is rejected with `422` before the call starts.

## 4. Top up credits

When the balance is low, generate a checkout link and hand it to your human:

```bash
curl -X POST $BASE/api/v1/topups \
  -H "Authorization: Bearer $DIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pack": "standard"}'
```

The response contains `checkout_url` — send it to your human (it expires in
24h). After they pay, poll `GET /api/v1/me/credits` until the balance updates
(usually seconds).

A `403` here means the email is not verified yet: finish step 1.5 first.

## 5. Make a call

```bash
curl -X POST $BASE/api/v1/calls \
  -H "Authorization: Bearer $DIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+5511999990000",
    "objective": "Book a table for 2 today at 8pm under the name Henrique",
    "context": "Prefers a quiet table. Phone for confirmation: +5511888880000",
    "language": "pt-BR",
    "max_duration_minutes": 5
  }'
```

| Field | Required | Notes |
|-------|----------|-------|
| `to_number` | yes | E.164: `+` then 8–15 digits, e.g. `+34695464918` (spaces/dashes/dots are stripped) |
| `objective` | yes | What the call should achieve, max 1000 chars |
| `context` | no | Extra facts the voice agent may need, max 2000 chars |
| `language` | no | BCP 47 tag, default `pt-BR`. Matched by primary subtag (`en-US` works where `en` is supported) |
| `max_duration_minutes` | no | 1–30, default 5 |

Send the real, complete number your human gave you. If your framework masks
phone numbers (e.g. `+346****4918`), the call is rejected with `422` — masked
digits cannot be dialed. Ask your human for the full number and pass it
through verbatim.

`max_duration_minutes` times the destination rate is held from your balance
up front; after the call you are charged for actual minutes at that rate and
the rest is released.

Errors:

| Status | Meaning | What to do |
|--------|---------|------------|
| `402` | Insufficient credits | Top up first (step 4) |
| `422` | Invalid, masked, blocked, or unsupported-destination number | Read the error message — you may need the real unmasked number, or the country is not supported |
| `502` | Provider failed to start the call | Retry later |
| `503` | No voice provider available | Retry later |

## 6. Track the call and help mid-call

```bash
curl $BASE/api/v1/calls/$CALL_ID \
  -H "Authorization: Bearer $DIAL_API_KEY"
```

Returns `status` (`queued | in_progress | completed | failed`) and, once
completed, `outcome`, `transcript`, `minutes_charged`, and `cost_usd`. Status refreshes
when you poll; after the other party hangs up, expect `completed` (with the
transcript) within about a minute.

While the call is in progress, poll the event stream:

```bash
curl "$BASE/api/v1/calls/$CALL_ID/events?since=$LAST_SEQ" \
  -H "Authorization: Bearer $DIAL_API_KEY"
```

Event types: `call_started`, `call_answered`, `question`, `answer`, `steer`,
`call_ended`, `call_failed`.

**If a `question` event appears, the voice agent is stuck and asking YOU.**
Answer within ~20 seconds:

```bash
curl -X POST $BASE/api/v1/calls/$CALL_ID/answers \
  -H "Authorization: Bearer $DIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"answer": "The reservation is under Henrique. 8:30pm works if 8pm is full."}'
```

Answer only within what your human already told you (the objective and
context). If a question involves new spending or commitments they did not
approve, decline it — the voice agent will relay that politely. Humans:
pre-authorize bounds in `context` (e.g. "up to R$40 corkage is fine").

To change direction mid-call (providers that support it):

```bash
curl -X POST $BASE/api/v1/calls/$CALL_ID/steer \
  -H "Authorization: Bearer $DIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"guidance": "Accept 8:30pm if 8pm is unavailable"}'
```

## 7. Delete call data (privacy)

Once a call has ended, you (or your human) can permanently erase its personal
data — destination number, objective, context, transcript, outcome, and
events:

```bash
curl -X DELETE $BASE/api/v1/calls/$CALL_ID \
  -H "Authorization: Bearer $DIAL_API_KEY"
```

Billing records (minutes charged, cost) are kept, as accounting law requires.
Deletion is irreversible — save the outcome first if your human needs it. A
`409` means the call is still running; wait for it to end. Even without a
request, call data is deleted automatically 12 months after the call.

## Key rotation and recovery

Rotate the key while you still have it (e.g. suspected leak). A code goes to
the verified email; your human relays it to you:

```bash
curl -X POST $BASE/api/v1/me/api-key/rotate \
  -H "Authorization: Bearer $DIAL_API_KEY"

curl -X POST $BASE/api/v1/me/api-key/rotate/confirm \
  -H "Authorization: Bearer $DIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'
```

The confirm response contains the new `api_key` (shown once) — save it the
same way as in step 1 (export `DIAL_API_KEY`, rewrite
`~/.config/dial/credentials.json`); the old key stops working immediately.

Lost the key **or** the claim link entirely? Recover both with the verified
email alone. The email your human receives lists their accounts with the
matching `account_id`s:

```bash
curl -X POST $BASE/api/v1/recovery \
  -H "Content-Type: application/json" \
  -d '{"email": "your-humans-email@example.com"}'

curl -X POST $BASE/api/v1/recovery/confirm \
  -H "Content-Type: application/json" \
  -d '{"email": "your-humans-email@example.com", "code": "123456", "account_id": "…"}'
```

The confirm response returns a **new `api_key` and a new `claim_url`** —
recovery rotates both, so the old key and the old claim link stop working
immediately:

```json
{
  "account_id": "…",
  "api_key": "dial_…",
  "claim_url": "https://…/claim/…"
}
```

Save both: export the new `api_key` as `DIAL_API_KEY` (and update
`~/.config/dial/credentials.json`), and send the new `claim_url` to
your human — that link is where they buy credits, and the previous one no
longer opens.

## Typical session

1. Human asks you to handle something that needs a phone call.
2. Check for saved credentials (step 0). Only register (step 1) if none work
   — or ask your human to — get the key into `DIAL_API_KEY`, and send
   them the `claim_url`.
3. Verify your human's email (step 1.5): relay the emailed code, or let them
   enter it on the claim page.
4. Human pays → poll `GET /me/credits` until `status` is `active`.
5. `POST /calls` with the number and objective your human gave you.
6. Watch events; answer any `question` quickly.
7. Report `outcome` and key transcript points back to your human.

## Rules

- Do not resell or share access to this service with third parties.
- Emergency numbers and premium-rate numbers are blocked.
- Calls respect the destination's local calling hours.