> ## 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.
# Make Outbound Calls via API
> Schedule outbound calls through the API. Link phone numbers for caller ID, set priorities, and run campaigns at scale.
Make your agent call customers. Link a phone number for caller ID, then schedule calls via API with priority ordering and custom data.
**What you'll learn:** How to set up outbound calling, schedule calls via API, and monitor call status.
***
## Prerequisites
Before making outbound calls:
1. **Agent configured** and enabled
2. **Phone number added** with valid SIP credentials
3. **Phone number linked** to agent for outbound
Complete guide to adding phone numbers and SIP credentials
***
## Link a phone number for outbound calls
Set the caller ID your agent uses when making calls:
1. Go to **Agents** → Select agent → **Edit**
2. Find **Outbound Phone Number** section
3. Select a phone number from the dropdown
4. Click **Save Agent**
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Link phone number to agent for outbound calls
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' }
}
);
```
Each agent can have one outbound phone number. Linking a new number replaces the previous one.
***
## Schedule a call
### Quick test from dashboard
Test your agent before running campaigns:
1. Go to your agent's page
2. Click **Test Call**
3. Enter the target phone number
4. Click **Call** — starts immediately
### Schedule via API
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch(
'https://blackbox.dasha.ai/api/v1/calls?agentId=YOUR_AGENT_ID',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
endpoint: '+15551234567',
priority: 5,
additionalData: {
customerId: 'cust_123',
campaignId: 'spring_promo'
}
})
}
);
const call = await response.json();
console.log('Call scheduled:', call.callId);
```
***
## Schedule bulk calls
Schedule multiple calls in one request:
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch(
'https://blackbox.dasha.ai/api/v1/calls/bulk?agentId=YOUR_AGENT_ID',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
calls: [
{ endpoint: '+15551234567', priority: 5, additionalData: { name: 'John' } },
{ endpoint: '+15559876543', priority: 5, additionalData: { name: 'Jane' } },
{ endpoint: '+15555555555', priority: 5, additionalData: { name: 'Bob' } }
]
})
}
);
const result = await response.json();
console.log(`Scheduled: ${result.successCount}, Failed: ${result.failedCount}`);
```
***
## Monitor call status
### Check individual call
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const call = await fetch(
`https://blackbox.dasha.ai/api/v1/calls/${callId}`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());
console.log('Status:', call.status);
// Created → Queued → Pending → InProgress → Completed/Failed
```
### View queue
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const queue = await fetch(
`https://blackbox.dasha.ai/api/v1/calls/queue/list?agentId=${agentId}`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());
console.log(`Calls in queue: ${queue.totalCount}`);
queue.items.forEach(call => {
console.log(` ${call.endpoint} - Priority ${call.priority}`);
});
```
### Receive webhooks
Configure webhooks for real-time status updates:
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// When scheduling the call
{
endpoint: '+15551234567',
completedWebHook: 'https://your-server.com/call-completed',
failedWebHook: 'https://your-server.com/call-failed'
}
```
Complete webhook payload reference
***
## Cancel a scheduled call
Cancel calls that haven't started yet:
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
await fetch(
`https://blackbox.dasha.ai/api/v1/calls/${callId}`,
{
method: 'DELETE',
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}
);
```
Only calls in **Created**, **Queued**, or **Pending** status can be canceled. Calls already **InProgress** cannot be canceled via API.
***
## Call lifecycle
```
Created → Queued → Pending → InProgress → Completed
↘ Failed
```
| Status | Description |
| -------------- | ------------------------------------ |
| **Created** | Call record created, not yet queued |
| **Queued** | Waiting in queue based on priority |
| **Pending** | About to be dialed |
| **InProgress** | Call connected, agent speaking |
| **Completed** | Call finished successfully |
| **Failed** | Call failed (busy, no answer, error) |
***
## Troubleshooting
### Calls not scheduling
| Symptom | Fix |
| -------------------- | ------------------------------------------------ |
| 400 Bad Request | Verify phone number format (E.164: +15551234567) |
| 404 Agent Not Found | Check agentId is correct |
| "No outbound config" | Link a phone number to the agent for outbound |
### Calls stuck in queue
| Symptom | Fix |
| ------------------------- | ---------------------------------- |
| Calls not processing | Check agent is enabled |
| Slow queue processing | Check business hours schedule |
| Hitting concurrency limit | Upgrade plan or reduce call volume |
### Low answer rates
| Symptom | Fix |
| ----------------- | ------------------------------------------ |
| Many "No Answer" | Call during optimal hours (10am-4pm local) |
| Calls marked spam | Use local area code numbers |
| Quick hang-ups | Improve greeting, reduce agent latency |
***
## What's next
Add phone numbers for caller ID
Configure display names
Monitor call results
Handle call completion events