> ## 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.
# Register Inbound Calls and Bridge Them to Your Agent
> Keep your own inbound call flow. Register a call with the agent and variables it needs, receive a call ID and SIP destination, and bridge the live call to it.
Register an inbound call that your telephony already holds, then bridge it to the SIP destination BlackBox returns. The agent answers with the variables you registered, and the call ID you stored is the correlation key on every webhook and result.
**What you'll learn:** When to use registration instead of linked phone numbers, how the register-then-bridge flow works, and how to handle results.
***
## When to use it
Use **Register Call** when:
* Your telephony (PBX, SIP provider, contact-center platform) receives the call first.
* You decide per call which agent should answer and which variables it needs.
* You need one call ID shared between your system and BlackBox for the complete call lifecycle.
Use [Inbound Calls](/docs/deploy/inbound-calls) instead when a phone number should always route to the same agent.
***
## How it works
1. Your telephony receives the inbound call.
2. You register the call: `POST /api/v1/calls/register?agentId=…`.
3. BlackBox creates the call record and returns `callId` and `sipUri` (`sip:{callId}@sip-reg.blackbox.dasha.ai`).
4. You store `callId` and bridge the live call to `sipUri`.
5. BlackBox recognizes the registered call and starts the agent with your variables.
6. The result reaches the agent's result webhook with the same `callId`.
The registration stays valid until `callDeadline` (default 10 minutes, maximum 24 hours). If the call is not bridged by then, it is canceled and reported through the result webhook with `status: "Canceled"`.
***
## Register a call
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const registration = await fetch(
`https://blackbox.dasha.ai/api/v1/calls/register?agentId=${agentId}`,
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
fromNumber: '+14155550100',
toNumber: '+14155550200',
additionalData: {
customerName: 'Jane Doe',
accountId: 'acct_123'
},
callDeadline: new Date(Date.now() + 5 * 60 * 1000).toISOString()
})
}
).then(r => r.json());
console.log('Call ID:', registration.callId);
console.log('Bridge to:', registration.sipUri);
// sip:6f1c2c9e-…@sip-reg.blackbox.dasha.ai
```
Response:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"callId": "6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c",
"sipUri": "sip:6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c@sip-reg.blackbox.dasha.ai",
"orgId": "org_abc",
"agentId": "agent_123",
"fromNumber": "+14155550100",
"toNumber": "+14155550200",
"additionalData": { "customerName": "Jane Doe", "accountId": "acct_123" },
"status": "Registered",
"direction": "Inbound",
"callDeadline": "2026-09-04T10:15:00Z",
"createdTime": "2026-09-04T10:10:00Z"
}
```
| Field | Required | Description |
| ---------------- | -------- | --------------------------------------------------------------------------------------------- |
| `fromNumber` | Yes | Number of the original caller. Reported as the call endpoint. |
| `toNumber` | No | Number that received the call. Informational. |
| `additionalData` | No | Variables for prompts, referenced as `{{variableName}}`. Merged with the agent's own data. |
| `callDeadline` | No | ISO 8601 time until which the registration stays valid. Default 10 minutes, maximum 24 hours. |
***
## Bridge the call
Point your telephony at `sipUri`. Any system that can transfer or bridge a live call to a SIP URI works.
```xml theme={"theme":{"light":"github-light","dark":"github-dark"}}
sip:6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c@sip-reg.blackbox.dasha.ai
```
```
exten => _X.,1,Dial(PJSIP/6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c@blackbox-register)
```
Define `blackbox-register` as a PJSIP endpoint whose contact is `sip:sip-reg.blackbox.dasha.ai`.
```
```
Bridge each registration exactly once. A second INVITE for the same call ID is rejected with SIP `410 Gone`.
BlackBox answers the INVITE with a SIP status when it cannot take the call:
| SIP status | Meaning |
| --------------- | ----------------------------------------------------- |
| `404 Not Found` | The user part of the URI is not a registered call ID. |
| `410 Gone` | The registration expired or was already used. |
| `603 Decline` | The agent is disabled or no longer exists. |
| `486 Busy Here` | Your organization has no free concurrency slot. |
***
## Receive the result
Configure a result webhook on the agent. The payload carries the same `callId`, your `additionalData` as `callAdditionalData`, the transcript, the recording URL and `callType: "InboundAudio"`.
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
app.post('/blackbox/result', (req, res) => {
const { callId, status, result, transcription, recordingUrl } = req.body;
// callId is the value you stored at registration
res.sendStatus(200);
});
```
Complete webhook payload reference
***
## Check a registered 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(call.status); // Registered → Running → Completed
console.log(call.direction); // Inbound
```
To cancel a registration before it is bridged, delete the call: `DELETE /api/v1/calls/{callId}`.