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

# Connect Phone Numbers to Your Agents

> Add phone numbers for inbound and outbound calls. Connect via Twilio integration or manually configure SIP credentials from any provider.

Connect phone numbers to receive inbound calls and make outbound calls. Use the Twilio integration for automatic setup, or manually configure SIP credentials from any provider.

**What you'll learn:** How to add phone numbers via Twilio or manual SIP configuration, link numbers to agents, and manage your telephony setup.

***

## Two ways to add phone numbers

| Method                     | Setup time   | Best for                                           |
| -------------------------- | ------------ | -------------------------------------------------- |
| **Twilio integration**     | 2 minutes    | Quick setup, automatic SIP trunk configuration     |
| **Manual SIP credentials** | 5-10 minutes | Any SIP provider (Telnyx, Bandwidth, Vonage, etc.) |

***

## Option 1: Twilio integration

Connect your Twilio account and import phone numbers with automatic SIP trunk configuration.

### Step 1: Create Twilio provider

<Tabs>
  <Tab title="Dashboard">
    1. Navigate to **Phone Numbers** in the sidebar
    2. Click **Add Provider** → **Twilio**
    3. Enter your Twilio **Account SID** and **Auth Token**
    4. Click **Connect**
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch('https://blackbox.dasha.ai/api/v1/providers/twilio', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: 'My Twilio Account',
        accountSid: 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        authToken: 'your-auth-token'
      })
    });

    const provider = await response.json();
    console.log('Provider created:', provider.id);
    ```
  </Tab>
</Tabs>

This automatically:

* Creates a SIP trunk in your Twilio account
* Generates SIP credentials for authentication
* Stores everything securely in your organization

### Step 2: Import phone numbers

<Tabs>
  <Tab title="Dashboard">
    1. In your Twilio provider, click **Import Numbers**
    2. Select the phone numbers you want to use
    3. Click **Import Selected**
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    // First, list available numbers
    const available = await fetch(
      `https://blackbox.dasha.ai/api/v1/providers/twilio/${providerId}/available-numbers`,
      { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
    ).then(r => r.json());

    console.log('Available numbers:', available);

    // Import selected numbers
    const result = await fetch(
      `https://blackbox.dasha.ai/api/v1/providers/twilio/${providerId}/import-numbers`,
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          phoneNumberSids: ['PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx']
        })
      }
    ).then(r => r.json());

    console.log(`Imported: ${result.successCount}, Failed: ${result.failedCount}`);
    ```
  </Tab>
</Tabs>

### Step 3: Link to agent

See [Link phone numbers to agents](#link-phone-numbers-to-agents) below.

***

## Option 2: Manual SIP credentials

Configure SIP credentials from any provider (Telnyx, Bandwidth, Vonage, or others).

### Step 1: Create SIP credentials

<Tabs>
  <Tab title="Dashboard">
    1. Navigate to **Phone Numbers** → **Credentials** tab
    2. Click **Add Credentials**
    3. Enter your SIP provider details:
       * **Server**: SIP server address (e.g., `sip.telnyx.com`)
       * **Auth User**: Your SIP username
       * **Password**: Your SIP password
       * **Transport**: UDP, TCP, or TLS
    4. Click **Save**
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch('https://blackbox.dasha.ai/api/v1/sip-credentials', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        server: 'sip.telnyx.com',
        authUser: 'your-username',
        authPassword: 'your-password',
        transport: 'udp',
        description: 'Telnyx Production Trunk'
      })
    });

    const credentials = await response.json();
    console.log('Credentials ID:', credentials.id);
    ```
  </Tab>
</Tabs>

### Step 2: Add phone numbers

<Tabs>
  <Tab title="Dashboard">
    1. Navigate to **Phone Numbers** → **Numbers** tab
    2. Click **Add Number**
    3. Enter the phone number and select credentials
    4. Enable **Registration** if your provider requires it
    5. Click **Save**
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch('https://blackbox.dasha.ai/api/v1/sip-phone-numbers', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        phoneNumber: '+14155551234',
        credentialsId: 'your-credentials-id',
        displayName: 'Support Line',
        registration: true
      })
    });

    const phoneNumber = await response.json();
    console.log('Phone number ID:', phoneNumber.id);
    ```
  </Tab>
</Tabs>

### Step 3: Link to agent

See [Link phone numbers to agents](#link-phone-numbers-to-agents) below.

***

## Link phone numbers to agents

After adding phone numbers, link them to agents for inbound routing or outbound calling.

### For inbound calls

Link a phone number to an agent so incoming calls route to that agent:

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Phone Numbers** → **Numbers** tab
    2. Click on a phone number
    3. Select an agent from the **Inbound Agent** dropdown
    4. Click **Save**
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    await fetch(
      `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/agent-link?agentId=${agentId}&mode=inbound`,
      {
        method: 'PUT',
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      }
    );
    ```
  </Tab>
</Tabs>

### For outbound calls

Set a phone number as an agent's outbound caller ID:

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Agents** → Select agent → **Edit**
    2. In the **Outbound Phone Number** section, select a number
    3. Click **Save Agent**
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    await fetch(
      `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/agent-link?agentId=${agentId}&mode=replaceOutbound`,
      {
        method: 'PUT',
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      }
    );
    ```
  </Tab>
</Tabs>

***

## SIP credentials reference

| Field          | Required | Description                                                            |
| -------------- | -------- | ---------------------------------------------------------------------- |
| `server`       | Yes      | SIP server hostname with optional port (e.g., `sip.provider.com:5060`) |
| `authUser`     | No       | Authentication username                                                |
| `authPassword` | No       | Authentication password                                                |
| `domain`       | No       | SIP domain for authentication realm                                    |
| `transport`    | No       | Protocol: `udp` (default), `tcp`, or `tls`                             |
| `description`  | No       | Human-readable label                                                   |
| `cpsLimit`     | No       | Max calls per second through this trunk                                |
| `cpsKey`       | No       | Shared rate limit key across multiple credentials                      |

***

## Phone number reference

| Field           | Required | Description                              |
| --------------- | -------- | ---------------------------------------- |
| `phoneNumber`   | Yes      | Phone number (E.164 format recommended)  |
| `credentialsId` | Yes      | SIP credentials to use for this number   |
| `displayName`   | No       | Caller ID display name                   |
| `description`   | No       | Human-readable label                     |
| `registration`  | No       | Enable SIP registration (default: false) |

***

## Check what's using a phone number

Before modifying or deleting, see which agents use a phone number:

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const affected = await fetch(
  `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/affected-agents`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

console.log('Inbound agent:', affected.inboundAgent);
console.log('Outbound agents:', affected.outboundAgents);
```

***

## Troubleshooting

### Registration failing

| Symptom                       | Fix                                                                  |
| ----------------------------- | -------------------------------------------------------------------- |
| Status shows "Not registered" | Check credentials are correct; verify provider requires registration |
| 401 Unauthorized              | Verify `authUser` and `authPassword` match provider exactly          |
| Timeout errors                | Check `server` address and port; try different `transport`           |

### Inbound calls not connecting

| Symptom               | Fix                                                      |
| --------------------- | -------------------------------------------------------- |
| Calls go to voicemail | Verify phone number is linked to an agent                |
| 404 Not Found         | Check the phone number exists and registration succeeded |
| Agent doesn't answer  | Verify agent is enabled and has valid configuration      |

### Outbound calls failing

| Symptom               | Fix                                                |
| --------------------- | -------------------------------------------------- |
| "No outbound config"  | Link a phone number to the agent for outbound      |
| Authentication errors | Verify SIP credentials are correct                 |
| Invalid caller ID     | Ensure phone number is verified with your provider |

***

## Next steps

<CardGroup cols={2}>
  <Card title="Inbound Calls" icon="phone-arrow-down-left" href="/docs/deploy/inbound-calls">
    Handle incoming calls
  </Card>

  <Card title="Outbound Calls" icon="phone-arrow-up-right" href="/docs/deploy/outbound-calls">
    Make outbound calls via API
  </Card>

  <Card title="Caller ID" icon="id-card" href="/docs/deploy/caller-id">
    Configure display names
  </Card>

  <Card title="SIP Configuration" icon="network-wired" href="/docs/deploy/sip-configuration">
    Advanced SIP settings
  </Card>
</CardGroup>