---
name: vr-add-phone-number
description: Add a phone number to a VoiceRun agent. Checks for unassigned numbers, purchases a new one if needed, and assigns it to an agent environment.
---

# Add a Phone Number to a VoiceRun Agent

You are helping the user add a phone number to their VoiceRun voice agent. This involves checking for available numbers, optionally purchasing a new one, and assigning it to an agent environment. Follow these steps:

## Step 1: Identify the agent and environment

Determine which agent and environment the phone number should be assigned to.

1. Ask the user for the **agent name** (or detect from the current project's `.voicerun/agent.lock`).
2. List the agent's environments to pick a target:

```bash
vr get environments <AGENT>
```

Ask the user which environment to assign the number to (e.g., `production`, `staging`). If the agent has no environments yet, guide them to deploy first:

```bash
vr deploy <ENVIRONMENT_NAME> -f .voicerun/values.<ENVIRONMENT_NAME>.yaml
```

Note: The `-f` flag specifying a values file is required for `vr deploy`.

## Step 2: Check for unassigned phone numbers

List all organization phone numbers and existing assignments to find numbers that are available.

```bash
vr get phonenumbers
```

Then check which numbers are already assigned to this agent:

```bash
vr get assignments <AGENT>
```

Compare the two lists. A phone number is **unassigned** if its ID does not appear in any assignment's PHONE NUMBER ID column.

- If there are unassigned numbers, present them to the user and ask if they'd like to use one of those.
- If all numbers are assigned (or there are no numbers at all), proceed to Step 3 to purchase a new one.

## Step 3: Purchase a new phone number (if needed)

If no unassigned numbers are available, purchase a new one. First, find the telephony provider:

```bash
vr get telephony
```

If no telephony provider exists, the user needs to create one first:

```bash
vr create telephony
```

Once a telephony provider is available, ask the user for an **area code** (optional) and purchase the number:

```bash
vr create phonenumber <TELEPHONY_ID> --purchase --area-code <AREA_CODE>
```

- `<TELEPHONY_ID>` — The ID of the telephony provider from `vr get telephony`.
- `--area-code` — Optional preferred area code (e.g., `415`, `212`). Omit to let the provider choose.
- `--friendly-name` — Optional display name (e.g., `"Support Line"`).

Note the returned **phone number ID** for the next step.

## Step 4: Assign the phone number to the agent environment

Create the assignment and configure it with the telephony provider:

```bash
vr create assignment <AGENT> <ENVIRONMENT> <PHONE_NUMBER_ID> --configure
```

- `<AGENT>` — Agent name or ID.
- `<ENVIRONMENT>` — Environment name or ID from Step 1.
- `<PHONE_NUMBER_ID>` — The ID of the phone number (from Step 2 or Step 3).
- `--configure` — Automatically configures the number with the telephony provider so it routes calls to this agent environment.

## Step 5: Verify the assignment

Confirm everything is set up correctly:

```bash
vr get assignments <AGENT>
```

The new assignment should appear in the table with the correct phone number ID and environment ID.

## Troubleshooting

- **"Agent not found"** — Check the agent name with `vr get agents`.
- **"Environment not found"** — List environments with `vr get environments <AGENT>`. The agent must be deployed first with `vr deploy`.
- **"Failed to purchase phone number"** — Verify the telephony provider is set up correctly with `vr describe telephony <ID>`. Check that credentials are valid.
- **"Failed to configure phone number"** — The telephony provider may not support automatic configuration. Check provider credentials and try again.
- **No telephony provider** — Create one with `vr create telephony`. You'll need credentials from your provider (Twilio or Telnyx).

Guide the user through this process step by step, running each command and presenting results before moving on.
