---
title: "Phone"
description: "A phone number for an agent. Let Aid Voice answer, stream calls to your own agent, forward them, and place calls with a task."
canonical_url: "https://www.agent-identity.dev/docs/phone"
markdown_url: "https://www.agent-identity.dev/docs/phone.md"
last_updated: "2018-10-20"
x_farming_labs_generated_preamble: true
agent:
  tokenBudget: 900
  task: "Understand what phone gives an agent and pick the page for the job at hand."
  outcome: "You know which of numbers, incoming calls, placing calls, Aid Voice, your own agent, access, call events or limits answers the question."
  appliesTo:
    package:
      - "@aid/api"
      - "@agentidentity/sdk"
  prerequisites:
    - "An organization with a verified owner. Numbers and outgoing calls are refused until the owner returns the emailed code."
  files:
    - "apps/api/src/services/phone.ts"
  sideEffects:
    - "Buying a number spends money with the carrier."
  verification:
    - description: "Read the agent's incoming call setting."
      expect: "GET /v1/identities/{id}/incoming-call-action returns the action the number uses."
  rollback:
    - "DELETE /v1/phone/numbers/{id} releases a number. It cannot be undone."
  failureModes:
    - symptom: "403 with code org.not_verified."
      resolution: "The owner has not returned the emailed code. Verify the owner, then retry."
---

# Phone
URL: /docs/phone
LLM index: /llms.txt
Description: A phone number for an agent. Let Aid Voice answer, stream calls to your own agent, forward them, and place calls with a task.
Related: /docs/phone/numbers, /docs/phone/incoming-calls, /docs/phone/placing-calls, /docs/phone/aid-voice

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Understand what phone gives an agent and pick the page for the job at hand.
Outcome: You know which of numbers, incoming calls, placing calls, Aid Voice, your own agent, access, call events or limits answers the question.

### Applies To

- Package: `@aid/api`, `@agentidentity/sdk`

### Prerequisites

- An organization with a verified owner. Numbers and outgoing calls are refused until the owner returns the emailed code.

### Files

- `apps/api/src/services/phone.ts`

### Side Effects

- Buying a number spends money with the carrier.

### Verification

- Read the agent's incoming call setting.
  - Expected: GET /v1/identities/{id}/incoming-call-action returns the action the number uses.

### Rollback

- DELETE /v1/phone/numbers/{id} releases a number. It cannot be undone.

### Failure Modes

- 403 with code org.not_verified. — Recovery: The owner has not returned the emailed code. Verify the owner, then retry.
<!-- farming-labs:agent-contract:end -->

# Phone

An agent can have a phone number of its own. People can call it, and it can call people. We provide the number, decide
what happens to each call, enforce who may call whom and how much, and keep the history, transcripts and follow-ups.

You choose who does the talking. **Aid Voice**, our built-in voice agent, needs no server at all. Or stream the call to
**your agent** over a WebSocket: you get what the caller says as text and send back what to say.

<Callout type="info">
  Calls only for now: one voice number per agent. Texts are not available yet.
</Callout>

## What happens to an incoming call

Each agent has one incoming call setting. New numbers answer with Aid Voice.

| Option | API value | What happens |
| --- | --- | --- |
| Aid Voice | `hosted_agent` | Our voice agent answers, with your standing instructions. The default for new numbers. |
| Your agent | `auto_accept` | We answer and stream the conversation to your `client_websocket_url`. |
| Your server | `webhook` | We ask your `incoming_call_webhook_url` first. Its reply decides. |
| Forward | `forward` | We send the call on to another phone number or a SIP address. |
| Decline | `auto_reject` | The call is refused, or goes to voicemail if you set that up. |

## Pages

| Page | Covers |
| --- | --- |
| [Numbers](/docs/phone/numbers) | Getting a number, attaching one you already own, moving and releasing it. |
| [Incoming calls](/docs/phone/incoming-calls) | The five options above, the voice, and voicemail. |
| [Placing calls](/docs/phone/placing-calls) | Calling out with Aid Voice and a task, or with your own agent. What happens at voicemail. |
| [Aid Voice](/docs/phone/aid-voice) | Instructions, greeting, voices, what it knows at the start of a call, its tools and follow-ups. |
| [Your agent](/docs/phone/your-agent) | The live call protocol for running your own agent: text mode, keypad presses, raw audio. |
| [Access](/docs/phone/access) | Who can reach the agent: allow and block rules, and allowlist mode. |
| [Calls and events](/docs/phone/calls-and-events) | The call record, transcripts, voicemail, and the `call.ended` event. |
| [Limits](/docs/phone/limits) | Calls, minutes, concurrency, numbers and call length per plan. |

## In one minute

```ts title="first-call.ts"
import { AgentClient } from "@agentidentity/sdk";

const org = new AgentClient({ baseUrl: "https://api.agent-identity.dev", apiKey: process.env.AID_ORG_KEY! });

// A number for the agent. It answers with Aid Voice straight away.
const number = await org.phone.provisionNumber({ identityId: agent.id, state: "NY" });

// Have Aid Voice call someone with a task.
const call = await org.phone.placeCall({
  identityId: agent.id,
  to: "+14155550100",
  mode: "hosted_agent",
  reason: "Confirm tomorrow's 9:30am appointment and ask if they need parking.",
});
```

When the call ends, a `call.ended` event carries the outcome, the transcript and any follow-ups Aid Voice recorded.
See [Calls and events](/docs/phone/calls-and-events).

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).