Register Inbound Calls and Bridge Them to Your Agent

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 instead when a phone number should always route to the same agent.

How it works

Your telephony receives the inbound call.
You register the call: POST /api/v1/calls/register?agentId=….
BlackBox creates the call record and returns callId and sipUri (sip:{callId}@sip-reg.blackbox.dasha.ai).
You store callId and bridge the live call to sipUri.
BlackBox recognizes the registered call and starts the agent with your variables.
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

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:

{
  "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.

Twilio (TwiML)
Asterisk
FreeSWITCH

<Response>
  <Dial>
    <Sip>sip:6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c@sip-reg.blackbox.dasha.ai</Sip>
  </Dial>
</Response>

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.

<action application="bridge" data="sofia/external/6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c@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".

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

Webhook Events

Complete webhook payload reference

Check a registered call

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

Introduction

Create

Test

Deploy

Monitor

Advanced Features

Troubleshooting

Register Inbound Calls and Bridge Them to Your Agent

When to use it

How it works

Register a call

Bridge the call

Receive the result

Webhook Events

Check a registered call

​When to use it

​How it works

​Register a call

​Bridge the call

​Receive the result

Webhook Events

​Check a registered call

When to use it

How it works

Register a call

Bridge the call

Receive the result

Check a registered call