# Quickstart

Give your AI agent a phone — a verified U.S. caller ID — in about five minutes.

Private beta. U.S. numbers and U.S. destinations only. Phone numbers are E.164,
like `+19495550123`.

**Agents:** start at the [agent map](https://dialvalet.com/llms.txt). It is the
setup path in machine-readable form.

## Five minutes to a first call

Four things have to be true before DialValet can place a call: you are signed in,
the number you want to show is verified, you have prepaid credit, and you asked
for that specific call.

```sh
# 1. Install
npm install --global @dialvalet/cli

# 2. Sign up (phone OTP; no password)
dialvalet signup --phone +19495550123 --json
# STOP. Enter the SMS code, then:
dialvalet auth verify --verification-id otp_... --code 12345 --json

# 3. Verify the caller ID recipients will see (a second, different code)
dialvalet identities verify --phone +19495550123 --json
# STOP. Enter the caller-ID code, then:
dialvalet identities confirm --verification-id otp_... --code 12345 --json

# 4. Add prepaid credit, then open checkout_url and pay
dialvalet billing checkout --amount 5 --json
dialvalet balance --json

# 5. Place one explicit call. --confirm is required.
dialvalet calls create --to +19495550199 --objective "Ask if you are open Saturday" --confirm --json
dialvalet calls wait call_... --json
```

Every command takes `--json` and returns a `next_step` field. Full command list:
[CLI reference](CLI.md).

Or paste this into the agent you already use:

```text
Add DialValet so I can make U.S. calls from my verified caller ID. Follow the 5-minute setup at https://dialvalet.com/llms.txt
```

It will stop and ask you for each SMS code — that is expected. Never share a code
with anyone but the tool you are setting up.

While watching, the CLI streams transcript events. If the business offers an
alternative that the objective did not authorize, the call agent can request
guidance. The watcher emits `input_required`, prints exact answer commands, and
exits successfully so the originating agent can decide:

```sh
dialvalet calls answer call_... guide_... \
  --answer "Eight PM works; reserve it for two." --follow --json
```

`--follow` immediately resumes the transcript. An agent that notices an unrelated
mistake can also send a live correction:

```sh
dialvalet calls steer call_... --mode instruction \
  --text "Correct the requested day to Friday." --interrupt --follow --json
```

An interrupt stops queued speech, but it cannot retract words the recipient
already heard.

To let the live agent ring you into the call, add `--allow-transfer` to
`dialvalet calls create` (API and MCP: `allow_user_transfer: true`). The agent
will not ring you without it, and even with it rings only when the other party
needs you on the phone. Answer **+1 480-480-1077**. That number is
DialValet. The business keeps seeing your verified caller ID. If you do not
answer, the agent continues the call.

## Trust and acceptable use

- **Verified caller ID is not consent.** Proving you control the from-number does
  not mean the person you call agreed to be contacted, or to speak with an AI
  assistant. Only place lawful, one-to-one, user-directed calls you are allowed
  to make.
- **Not a dialer.** No telemarketing, campaigns, bulk or sequential dialing, or
  call-center workflows.
- **U.S. only.** U.S. numbers and U.S. destinations. International calling is
  not available.
- **Prepaid.** $0.12 per started connected minute. Checkout is $5–$100. No
  subscription and no automatic reload. Credit posts after payment settles — a
  checkout URL is not a payment.
- **No DialValet numbers.** Dedicated numbers and inbound forwarding are not
  available. Recipients see a number you already own and verified.
- **Private beta.** This page describes what exists now. Do not assume
  recordings, inbound service, or non-U.S. support.

DialValet does not add a fixed opening disclosure. Include any identity,
AI/artificial-voice, purpose, callback-number, recording, or opt-out notice that
applies to the call in the objective or context. Before dialing, the objective and
optional context are screened against the acceptable-use rules. Ordinary personal
calls and benign jokes between friends are allowed; harmful or prohibited uses are
not.

Full rules: [Terms of Service — acceptable use](https://dialvalet.com/terms#acceptable-use).

## Connect Cursor or Claude (MCP)

Point the client at `https://mcp.dialvalet.com/mcp`. Authorization runs phone
sign-in and asks you which scopes to grant:

`calls:read` · `calls:write` · `caller_identities:read` · `billing:read`

Approving a connection is not approval for any particular call. Your agent still
needs a direct instruction from you each time.

### Cursor

Save this as `.cursor/mcp.json` in a project, or in `~/.cursor/mcp.json`:

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

`dialvalet mcp config` prints the same JSON.

### Claude Code and other MCP clients

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

```sh
claude mcp add --transport http dialvalet https://mcp.dialvalet.com/mcp
grok mcp add --transport http dialvalet https://mcp.dialvalet.com/mcp
```

Tools after connect: `place_call`, `get_call`, `list_calls`, `cancel_call`,
`list_voices`, `set_default_voice`, `get_credit_balance`, `list_caller_ids`.

## In the browser

Sign up at [dialvalet.com/signup](https://dialvalet.com/signup) with your phone
number, then use the dashboard to verify a caller ID, add credit, and place
calls. The dashboard **Connect** page has the same paste-into-your-agent message
and the MCP snippets above.

## What a call costs

$0.12 per started connected minute, rounded up per minute. No charge for talk
time if nobody answers. Credit is prepaid, $5 to $100 per checkout, and nothing
renews.

## When something goes wrong

- **Checkout opened but the balance is still $0.** Credit posts after the payment
  settles. Re-check `dialvalet balance --json` shortly after paying.
- **Call rejected for caller ID.** Confirm the number with
  `dialvalet identities list --json`. It must be verified, not just typed in.
- **Call rejected for limits.** Defaults are 5 calls per day, 1 at a time, 20
  minutes maximum.
- **No structured result.** It is optional. Transcript turns exist only when a
  result was produced, and `GET /v1/calls/{id}/transcript` returns 404 otherwise.

More detail: [REST and MCP reference](API.md). Questions:
[contact@dialvalet.com](mailto:contact@dialvalet.com)