# How do I give an AI agent its own phone number?

*2026-10-21 · By Naol Ketema, founder of Agent Identity*

**Short answer:** Create the agent, then provision a number for it with one call (org.phone.provisionNumber in the Agent Identity SDK). The number answers with Aid Voice, a built-in voice agent, straight away, and you can switch it to your own agent, your server, forwarding or decline. Each agent holds one voice number; calls are live, texts (SMS) are not available yet.

## What it means for an agent to have a phone number

A phone number for an agent is a real number that belongs to one agent identity, not to a person or a shared line. People can call it, the agent can call people from it, and every call is recorded against that agent: who called, when, how long, the transcript, and what happened next.

That matters for the same reason an agent should have its own email address. If five agents share one number, you cannot tell which one made a call, you cannot block a caller for one agent only, and you cannot shut one agent down without cutting off the rest.

On Agent Identity, an agent can hold one voice number. The platform provides the number, decides what happens to each call based on your setting, enforces who may call whom and how much, and keeps the history, transcripts and follow-ups.

## What you need first

- An organization and an agent. The agent is the identity the number attaches to.
- An org key. Buying, moving and releasing numbers needs the org key, because it spends money. An agent key cannot do it.
- A verified owner. Only an organization whose owner has verified their email can buy a number or place a call.
- Room on your plan. Free includes 2 numbers, Builder 3, Team 20.

## Step by step

- Step 1: create a client with your org key.
- Step 2: call provisionNumber with the agent's id. The state field is an optional two-letter US state, such as NY.
- Step 3: read number.number for the E.164 number. It answers calls with Aid Voice immediately.
- Step 4: optionally give Aid Voice standing instructions and a greeting, or switch the incoming call setting to your own agent.

```ts
import { AgentClient } from "@agentidentity/sdk";

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

const number = await org.phone.provisionNumber({ identityId: agentId, state: "NY" });
console.log(number.number); // +1212...

await org.phone.setHostedAgentConfig(agentId, {
  instructions: "You answer for Blue Harbor Dental. Be warm and brief. Never quote prices.",
  greeting: "Thanks for calling Blue Harbor Dental, how can I help?",
});
```

Over plain HTTP it is a POST to /v1/phone/numbers with identity_id and state. To start the number on a different setting, pass incoming_call_action when you provision it, with the WebSocket or webhook address that setting needs.

```bash
curl -sS -X POST https://api.agent-identity.dev/v1/phone/numbers \
  -H "authorization: Bearer $AID_ORG_KEY" -H 'content-type: application/json' \
  -d '{"identity_id":"'$AID_AGENT'","state":"NY"}'
```

## Choose what happens when it rings

Each agent has one incoming call setting. New numbers use Aid Voice. The five options:

- Aid Voice (hosted_agent): the built-in voice agent answers with your instructions. No server needed.
- Your agent (auto_accept): the call is answered and streamed to your WebSocket as text. You send back what to say.
- Your server (webhook): your HTTPS endpoint is asked first and its reply decides whether to answer.
- Forward (forward): the call goes 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.

Blocked callers never reach any of these. They are refused before the call connects.

## Attach, move or release a number

- Attach a number that is already in the carrier account by passing it as number to provisionNumber. Nothing is bought. listCarrierNumbers shows numbers no agent has yet.
- Move a number to another agent with assignNumber(number.id, otherAgent.id). It fails with 409 if that agent already has a number.
- Detach it but keep it with assignNumber(number.id, null).
- Release it back to the carrier with releaseNumber(number.id). This cannot be undone.

## What you get for every call

Each call on the number becomes a record on the agent: direction, the two numbers, status, who ran it (Aid Voice or your agent), the outcome for Aid Voice calls, the hangup reason, the duration and timestamps. listCalls returns the history newest first, and listTranscript returns both sides of the conversation.

Calls also write to the same event log as email: call.started, call.answered, call.ended, call.missed and others. Your code can wait on call.ended, or receive it by webhook, instead of polling the call list. The call.ended event carries the whole story in one payload: outcome, transcript and any follow-ups Aid Voice recorded.

## Limits and what is not there yet

- One voice number per agent.
- Calls only. Texts (SMS) are not available yet, so do not plan an SMS flow on it today.
- Outgoing calls on the hosted service go to +1 numbers (the US and Canada).
- Plan limits cover numbers, outgoing calls and minutes per rolling 24 hours, calls live at once, and call length. The longest call is 10 minutes on Free, 20 on Builder and 40 on Team.

If all you need is one human support line that rings a desk phone, a regular business phone service is simpler. A number on the agent makes sense when software answers or places the calls and you want each agent's calls, transcripts and access rules kept separate.

## FAQ

### Can an AI agent send and receive text messages on this number?

Not yet. Agent Identity phone numbers handle voice calls only today; texts are not available.

### Can one agent have more than one phone number?

No. An agent holds one voice number. If you need separate numbers, create separate agents, which also keeps their history and access rules apart.

### Who answers the number by default?

Aid Voice, the built-in voice agent. It works with no instructions saved, and you can add standing instructions, a greeting and a voice at any time.

### Can I move a number from one agent to another?

Yes, with assignNumber and an org key. The move fails with 409 if the other agent already has a number.

---
Docs: https://www.agent-identity.dev/docs · All guides: https://www.agent-identity.dev/guides · llms.txt: https://www.agent-identity.dev/llms.txt