> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiceaiwrapper.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone number tools

> Connect one of your free phone numbers to an agent.

## connect\_phone\_number

Connect one of the organization's free phone numbers to an agent, so calls to that number go to the agent.

A number is **free** when it is active, not connected to another agent, and not used by an inbound campaign. Buying, porting or adding numbers happens in the VoiceAIWrapper app.

This changes live call routing, so the AI app confirms the number and the agent with you first.

**Scope:** `agents.write` · **Hints:** destructive

### Inputs

**agent\_id** `string` *required*

The `agent_id` from `list_agents`.

**phone\_number** `string`

The number to connect, as listed, for example `+14155550100`. Formatting is ignored. Leave it out to get the list of free numbers.

### Returns

**agent** `object`

The agent: `id`, `name`, `url`.

**direction** `string`

`inbound` (answers calls) or `outbound` (makes calls).

**connected** `boolean`

`false` when no number was given: pick one of `free_numbers`.

**phone\_number** `string`

The connected number, in E.164.

**free\_numbers** `object[]`

Only when no number was given: each free number's `phone_number` and `label`.

```json Listing free numbers theme={null}
{
  "agent": { "id": "VmF3TmF0aXZlQWdlbnRUeXBlOng3azJt", "name": "Lakeside Dental Receptionist", "url": "https://dashboard.voiceaiwrapper.app/en/..." },
  "direction": "inbound",
  "connected": false,
  "free_numbers": [
    { "phone_number": "+14155550100", "label": "Main line" },
    { "phone_number": "+14155550123", "label": null }
  ]
}
```

### Inbound and outbound agents

* **Inbound agent:** calls to the number go to the agent from now on.
* **Outbound agent:** the number becomes the agent's, and calls *to* it go to the agent. The number an outbound agent calls *from* is picked by its campaign. Choose this number when you set up the campaign in the VoiceAIWrapper app.

### When there are no free numbers

The tool answers that there is no free number. Connect or buy one in the VoiceAIWrapper app, then ask again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.