Receive Inbound Calls on Your Agent

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:

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

Link a phone number for inbound calls

Dashboard
API

Navigate to Phone Numbers
Click on the phone number you want to use
Select an agent from the Inbound Agent dropdown
Click Save

// 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' }
  }
);

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

Route a whole SIP domain to an agent

If you run your own PBX or carrier trunk, you do not need phone numbers or SIP credentials in BlackBox. Point your telephony at a hostname you own and let one agent answer everything sent to it.

Add and verify the domain

Go to Phone Numbers → SIP Domains, add your hostname (for example calls.yourcompany.com), create the DNS records shown in the domain details, and click Verify. The DNS setup is described in Register Call → Use your own domain.

Choose the agent

Dashboard
API

Open the domain details and pick an agent under Inbound routing.

await fetch(`https://blackbox.dasha.ai/api/v1/sip-domains/${domainId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ defaultAgentId: agentId })
});

Send calls to the domain

Configure your PBX or carrier to send calls to sip:<anything>@calls.yourcompany.com, for example sip:+14155550100@calls.yourcompany.com. The agent answers, and the caller number from the SIP From header becomes the call endpoint.

Registered calls (sip:{callId}@calls.yourcompany.com) always keep the agent they were registered with. The domain agent only handles user parts that are not a registered call id. A domain without an agent rejects such calls with SIP 404.

Configure greeting

Talk First

Configure the agent’s first message when answering calls

Set business hours

Control when your agent accepts inbound calls:

Dashboard
API

Go to Agents → Select agent → Edit
Navigate to Schedule section
Set your business hours and timezone
Click Save Agent

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 } }]
    }
  })
});

No schedule configured = 24/7 availability.

Scheduling & Availability

Complete guide to business hours, holidays, and timezone configuration

Test inbound calls

Verify setup

Agent is enabled (isEnabled: true)
Phone number is linked for inbound
SIP credentials are valid (check registration status)

Make a test call

Call the phone number from your mobile phone

Verify connection

Agent should answer with configured greeting

Review in dashboard

Go to Calls → Verify call appears in history with transcript

Check phone number status

Verify a phone number is correctly linked:

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:

Dashboard
API

Navigate to Phone Numbers
Click on the phone number
Clear the Inbound Agent dropdown (select “None”)
Click Save

await fetch(
  `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/agent-link?mode=inbound`,
  {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }
);

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

Outbound Calls

Make calls via API

Phone Numbers

Add and manage phone numbers

Business Hours

Configure availability schedule

Call History

Monitor inbound calls

Introduction

Create

Test

Deploy

Monitor

Advanced Features

Troubleshooting

How inbound calls work

Link a phone number for inbound calls

Route a whole SIP domain to an agent

Configure greeting

Talk First

Set business hours

Scheduling & Availability

Test inbound calls

Check phone number status

Unlink a phone number

Troubleshooting

Calls not reaching agent

Agent not answering correctly

Registration issues

What’s next

Outbound Calls

Phone Numbers

Business Hours

Call History

​How inbound calls work

​Link a phone number for inbound calls

​Route a whole SIP domain to an agent

​Configure greeting

Talk First

​Set business hours

Scheduling & Availability

​Test inbound calls

​Check phone number status

​Unlink a phone number

​Troubleshooting

​Calls not reaching agent

​Agent not answering correctly

​Registration issues

​What’s next

Outbound Calls

Phone Numbers

Business Hours

Call History

How inbound calls work

Link a phone number for inbound calls

Route a whole SIP domain to an agent

Configure greeting

Set business hours

Test inbound calls

Check phone number status

Unlink a phone number

Troubleshooting

Calls not reaching agent

Agent not answering correctly

Registration issues

What’s next