# 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.

Setup path for agents: this file. Human walkthrough:
https://dialvalet.com/docs/QUICKSTART.md

## 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.2.0), 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. It is not consent
  from the person being called.
- $0.15 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.
- First call free: $1.00 credit (about 6 minutes) once your caller ID number is
  verified, one per number. The caller-ID confirm response reports it in
  `free_credit`.
- Default account limits: 5 calls per day, 1 call at a time, 20 minutes maximum
  per call. Without an explicit maximum duration, a call defaults to the longest
  the available balance covers.
- 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.
- A phone handoff is off unless the call is placed with `--allow-transfer`
  (API and MCP: `allow_user_transfer: true`). The live agent still rings the user only
  when the other party needs them on the call. The user's phone shows
  +1 480-480-1077 (+14804801077). That is DialValet, not the business. The
  business keeps seeing the verified caller ID. Answer that number to take over.
- Not a dialer: no telemarketing, campaigns, bulk dialing, or call-center use.

## Setup path (CLI, about five minutes)

Do these in order. Always pass `--json` and follow each command's `next_step`.
Never request, guess, intercept, or invent a one-time code — ask the account
holder and wait.

1. Install: `npm install --global @dialvalet/cli`
2. Sign up: `dialvalet signup --phone +1... --json`, then
   `dialvalet auth verify --verification-id ... --code ... --json`
3. Verify caller ID (different code than sign-in):
   `dialvalet identities verify --phone +1... --json`, then
   `dialvalet identities confirm --verification-id ... --code ... --json`
4. Prepaid credit: if step 3 returned `free_credit.granted: true`, the $1.00
   credit already covers a first call of about 6 minutes; check
   `dialvalet balance --json` and go to step 5 even if `next_step` suggests
   checkout. Otherwise, or for more credit:
   `dialvalet billing checkout --amount 5 --json`. Open `checkout_url` for the
   human. Wait until they confirm payment settled, then
   `dialvalet balance --json`
5. First call — only after the human names that destination and objective:
   `dialvalet calls create --to +1... --objective "..." --confirm --json`, then
   `dialvalet calls wait call_... --json`

Optional after that: `voices` / `voices set` to change the account default
(`marin` if skipped). `--voice` overrides one call.

`calls wait --json` streams newline-delimited transcript events. If it emits
`input_required`, it exits successfully with one plain-text question and an
`answer_command` template. Supply a plain-text answer with `--follow` to answer
the live agent and resume watching. Use `calls steer <call_id> --mode
instruction|context|say --text "..."
[--interrupt] [--follow] --json` to correct or inform the live agent.

## MCP alternative

Point the client at https://mcp.dialvalet.com/mcp. Authorization runs phone
one-time-code sign-in and a scope-selection page.

Copy-paste configs:

Cursor (`.cursor/mcp.json` or `~/.cursor/mcp.json`):

```json
{"mcpServers":{"dialvalet":{"url":"https://mcp.dialvalet.com/mcp"}}}
```

Claude Code and other HTTP MCP clients:

```json
{"mcpServers":{"dialvalet":{"type":"http","url":"https://mcp.dialvalet.com/mcp"}}}
```

`dialvalet mcp config` prints the Cursor JSON. Claude Code:
`claude mcp add --transport http dialvalet https://mcp.dialvalet.com/mcp`

Scopes: `calls:read`, `calls:write`, `caller_identities:read`, `billing:read`.
Tools: `place_call`, `get_call`, `list_calls`, `cancel_call`, `list_voices`,
`set_default_voice`, `get_credit_balance`, `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.

A connected grant is not per-call permission. Still require a direct user
instruction before `place_call`.

## Docs

- [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)
- [Documentation index](https://dialvalet.com/docs/INDEX.md)
- [Expanded agent brief](https://dialvalet.com/llms-full.txt)
- [Terms](https://dialvalet.com/terms) · [Privacy](https://dialvalet.com/privacy)

REST: Bearer API key, or the browser session cookie on routes that accept it.

## 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.
- When `calls wait` yields `input_required`, answer only from the objective,
  context, and authorized user preferences; do not invent consent for a new
  commitment.
- A verified caller ID is not consent from the person being called. Only request
  lawful, one-to-one, user-directed calls. No telemarketing, campaigns, bulk
  dialing, impersonation, or call-center workflows.
- Do not promise dedicated numbers, inbound forwarding, recordings, or non-U.S.
  calling. Those are not available.
- DialValet does not inject a fixed opening disclosure. Include any identity,
  AI/artificial-voice, purpose, callback-number, recording, or opt-out notice
  required for that specific call in the objective or context.
- Add `--allow-transfer` (`allow_user_transfer: true`) only when the user
  explicitly asked to be called in if the live call needs them. Do not set it
  otherwise. Tell the user to answer +1 480-480-1077 (+14804801077). Without it
  the live agent cannot ring them.
- Objectives and optional context are safety-screened before dialing. Benign jokes
  between friends are allowed; fraud, harmful deception, harassment, credential
  theft, prohibited high-stakes activity, illegal harm, and safety evasion are not.