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

Use your own domain

Registered calls can use a hostname you own instead of sip-reg.blackbox.dasha.ai, so the URI you hand to your telephony or your customers reads sip:{callId}@calls.yourcompany.com. DNS sends the call directly to Dasha; you do not need a SIP proxy in the path.

Add the domain

Dashboard
API

Go to Phone Numbers → SIP Domains, click Add Domain and enter the hostname, for example calls.yourcompany.com.

const domain = await fetch('https://blackbox.dasha.ai/api/v1/sip-domains', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ domain: 'calls.yourcompany.com' })
}).then(r => r.json());

console.log(domain.status); // PendingVerification
console.log(domain.dns);    // records to create, see below

Create the DNS records

The domain details list two kinds of records. Create them at your DNS provider.

Purpose	Type	Name	Value
Prove ownership	`TXT`	`_dasha-verify.calls.yourcompany.com`	`dasha-domain-verification=<token>`
Route calls to Dasha	`CNAME`	`calls.yourcompany.com`	`sip.us.dasha.ai`

SIP phones and PBXs resolve the host with A records, which the CNAME provides. Use a dedicated hostname for the domain: a CNAME cannot share its name with other records, so calls.yourcompany.com must not carry any other record. The TXT record lives at _dasha-verify.calls.yourcompany.com, which is fine next to the CNAME.

Verify

Dashboard
API

Click Verify on the domain. It becomes Active when the TXT record is found. The details also show whether the routing records already point at Dasha.

const verified = await fetch(
  `https://blackbox.dasha.ai/api/v1/sip-domains/${domain.id}/verify`,
  { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());

console.log(verified.status);                 // Active, or PendingVerification with lastError
console.log(verified.routingRecordsDetected); // true when the domain already resolves to Dasha

DNS changes can take a few minutes to propagate; verify again if the record is not found yet.

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',
      sipDomainId: domain.id
    })
  }
).then(r => r.json());

console.log(registration.sipUri);
// sip:6f1c2c9e-…@calls.yourcompany.com

Custom SIP domains are enabled per organization. A hostname can belong to one organization only, and ownership is proven by the TXT record, so any hostname you control works. Names starting with sip under dasha.ai are reserved by the Dasha platform and fail verification.

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

Use your own domain

Check a registered call

​When to use it

​How it works

​Register a call

​Bridge the call

​Receive the result

Webhook Events

​Use your own domain

​Check a registered call

When to use it

How it works

Register a call

Bridge the call

Receive the result

Use your own domain

Check a registered call