# DialValet — agent documentation map

DialValet gives a personal AI agent a phone. It places one user-directed outbound
U.S. call that shows a phone number the account owner has verified, then returns a
short structured outcome. It is in private beta.

## Endpoints

- Website: https://dialvalet.com
- REST API: https://api.dialvalet.com/v1
- Remote MCP: https://mcp.dialvalet.com/mcp
- CLI: `npm install --global @dialvalet/cli` (0.1.4), then `dialvalet --help`

## Facts

- U.S. phone numbers and U.S. destinations only.
- Accounts authenticate with a phone one-time code. There is no password.
- The number shown to the recipient must be verified separately from account
  sign-in. Verification proves the owner controls that number.
- $0.12 per started connected minute, charged as ceil(connected_seconds / 60). A
  call nobody answers has no talk-time charge.
- Prepaid credit only: a one-time Stripe Checkout from $5 to $100. No
  subscription, no automatic reload, no per-call card charge. Credit posts after
  the payment settles, so a checkout URL is not a payment.
- Default account limits: 5 calls per day, 1 call at a time, 20 minutes maximum
  per call.
- No audio recordings. An optional encrypted structured result, which can include
  speaker-labeled transcript turns, is kept up to 30 days and the owner can delete
  it sooner.
- Dedicated numbers and inbound call forwarding are not available.

## Start here

- [Documentation index](https://dialvalet.com/docs/INDEX.md)
- [Quickstart](https://dialvalet.com/docs/QUICKSTART.md)
- [CLI reference](https://dialvalet.com/docs/CLI.md)
- [REST and MCP reference](https://dialvalet.com/docs/API.md)
- [OpenAPI contract](https://dialvalet.com/openapi.yaml)
- [Expanded agent brief](https://dialvalet.com/llms-full.txt)
- [Terms](https://dialvalet.com/terms) · [Privacy](https://dialvalet.com/privacy)

## Agent interface summary

CLI: `dialvalet signup --phone +1... --json`, then stop and ask the account holder
for the SMS code, then `dialvalet auth verify --verification-id ... --code ...
--json`. Verify a caller ID with `identities verify` and `identities confirm`, add
credit with `billing checkout --amount 5`, then place a call with `calls create
--to +1... --objective "..." --confirm`. Optional `--voice` overrides the account
default (`voices` / `voices set`). Always pass `--json` and follow each
command's `next_step` field.

MCP: point the client at https://mcp.dialvalet.com/mcp. Authorization runs phone
one-time-code sign-in and a scope-selection page. Scopes are `calls:read`,
`calls:write`, `caller_identities:read`, and `billing:read`. Tools are
`place_call`, `get_call`, `list_calls`, `cancel_call`, `list_voices`,
`set_default_voice`, `get_credit_balance`, and `list_caller_ids`. `place_call`
accepts an optional `voice`; otherwise the account default, then `marin`, is used.
Portuguese voices `bossa` and `tempo` speak Brazilian Portuguese.

REST: Bearer API key, or the browser session cookie on routes that accept it. See
the [REST and MCP reference](https://dialvalet.com/docs/API.md) and the
[OpenAPI contract](https://dialvalet.com/openapi.yaml).

## Rules for agents

- If a CLI `--json` result includes `cli_update`, run `cli_update.command` and
  retry before doing anything else.
- Never request, guess, intercept, or invent a one-time code. Ask the account
  holder each time and pause until they answer.
- Place a call only after a direct instruction naming that destination and that
  objective. The CLI requires `--confirm`.
- A connected OAuth grant or a stored API key is not authorization for a specific
  call.
- Do not print or paste an API key, one-time code, or payment detail into a
  prompt, log, ticket, or transcript.
- A call ID is not proof that anyone answered. Watch `calls wait` or poll the call
  for a terminal status.
- A verified caller ID is not consent from the person being called. Only request
  calls the account owner is legally allowed to make.