> ## 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.

# Receive Inbound Calls on Your Agent

> Route phone calls to your AI agent. Link phone numbers for automatic call routing and handle business hours.

Route incoming phone calls to your agent. Link a phone number to an agent, and calls to that number automatically connect to the agent.

**What you'll learn:** How to link phone numbers for inbound routing and test incoming calls.

***

## How inbound calls work

When a phone number is linked to an agent:

1. Caller dials the phone number
2. Call routes through your SIP provider
3. Agent answers and starts the conversation

***

## Link a phone number for inbound calls

<Tabs>
  <Tab title="Dashboard">
    1. Navigate to **Phone Numbers**
    2. Click on the phone number you want to use
    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"}}
    // Link phone number to agent for inbound calls
    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>

<Note>
  Each phone number can only be linked to one agent for inbound calls. Linking to a new agent automatically unlinks from the previous one.
</Note>

***

## Configure greeting

<Card title="Talk First" icon="message" href="/docs/advanced-features/talk-first">
  Configure the agent's first message when answering calls
</Card>

***

## Set business hours

Control when your agent accepts inbound calls:

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Agents** → Select agent → **Edit**
    2. Navigate to **Schedule** section
    3. Set your business hours and timezone
    4. Click **Save Agent**
  </Tab>

  <Tab title="API">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    await fetch(`https://blackbox.dasha.ai/api/v1/agents/${agentId}`, {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        schedule: {
          timezone: "America/New_York",
          mon: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
          tue: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
          wed: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
          thu: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
          fri: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }]
        }
      })
    });
    ```
  </Tab>
</Tabs>

**No schedule configured = 24/7 availability.**

<Card title="Scheduling & Availability" icon="clock" href="/docs/create/scheduling-availability">
  Complete guide to business hours, holidays, and timezone configuration
</Card>

***

## Test inbound calls

<Steps>
  <Step title="Verify setup">
    * Agent is enabled (`isEnabled: true`)
    * Phone number is linked for inbound
    * SIP credentials are valid (check registration status)
  </Step>

  <Step title="Make a test call">
    Call the phone number from your mobile phone
  </Step>

  <Step title="Verify connection">
    Agent should answer with configured greeting
  </Step>

  <Step title="Review in dashboard">
    Go to **Calls** → Verify call appears in history with transcript
  </Step>
</Steps>

***

## Check phone number status

Verify a phone number is correctly linked:

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

console.log('Phone:', phoneNumber.phoneNumber);
console.log('Inbound agent:', phoneNumber.incomingCallsAgentId || 'Not linked');
console.log('Registration:', phoneNumber.registrationStatus);
```

***

## Unlink a phone number

Stop routing calls to an agent:

<Tabs>
  <Tab title="Dashboard">
    1. Navigate to **Phone Numbers**
    2. Click on the phone number
    3. Clear the **Inbound Agent** dropdown (select "None")
    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?mode=inbound`,
      {
        method: 'DELETE',
        headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
      }
    );
    ```
  </Tab>
</Tabs>

After unlinking, calls to this number will not be answered.

***

## Troubleshooting

### Calls not reaching agent

| Symptom                 | Fix                                         |
| ----------------------- | ------------------------------------------- |
| Call goes to voicemail  | Verify phone number is linked to an agent   |
| "Number not in service" | Check SIP registration status is successful |
| Ring but no answer      | Verify agent is enabled                     |

### Agent not answering correctly

| Symptom             | Fix                                           |
| ------------------- | --------------------------------------------- |
| No greeting plays   | Set `firstMessage` in agent config            |
| Wrong agent answers | Check phone number is linked to correct agent |
| Agent unavailable   | Check business hours schedule                 |

### Registration issues

| Symptom                  | Fix                                              |
| ------------------------ | ------------------------------------------------ |
| Status: "Not registered" | Verify SIP credentials are correct               |
| Status: "Failed"         | Check server address and transport protocol      |
| Intermittent failures    | Enable registration if your provider requires it |

***

## What's next

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

  <Card title="Phone Numbers" icon="phone" href="/docs/deploy/phone-numbers">
    Add and manage phone numbers
  </Card>

  <Card title="Business Hours" icon="clock" href="/docs/create/scheduling-availability">
    Configure availability schedule
  </Card>

  <Card title="Call History" icon="list-check" href="/docs/monitor/call-history">
    Monitor inbound calls
  </Card>
</CardGroup>