Skip to main content
POST
Register inbound call

Register-then-bridge flow

  1. Your telephony receives the inbound call and decides which agent should answer.
  2. Call this endpoint with the agent ID, the caller number and any variables the agent needs.
  3. Store the returned callId and bridge the live call to the returned sipUri (sip:{callId}@sip-reg.blackbox.dasha.ai).
  4. The agent answers as soon as the call arrives. Results arrive on the agent’s result webhook with the same callId.

Deadline

callDeadline is how long the registration stays valid. If the call is not bridged by then, it is canceled and reported through the result webhook. Default is 10 minutes, maximum 24 hours.

Response

The response includes the assigned callId, the sipUri to bridge to, and the stored settings. The call has status Registered until the audio arrives.

Query Parameters

agentId
string

Agent identifier

Body

Registration details: caller number, called number, variables, deadline

Registration of an inbound call that your telephony already holds. Registering creates the call record with its settings before the audio arrives, and returns the SIP destination to bridge the live call to. The agent starts as soon as the call reaches that destination.

fromNumber
string
required

Number of the original caller (E.164 recommended). Stored as the call endpoint and reported back on every webhook for this call.

Minimum string length: 1
toNumber
string | null

Number that received the inbound call. Optional, informational only.

additionalData
object | null

Data for variable interpolation in agent prompts. Values can be referenced in prompts using {{variableName}} syntax. Merged with the agent's AdditionalData.

callDeadline
string<date-time> | null

Time until which the registration stays valid. If the call has not been bridged to the SIP destination by then, the registration is canceled and reported through the result webhook. Defaults to 10 minutes after registration; cannot exceed 24 hours.

sipDomainId
string<uuid> | null

Identifier of one of your verified custom SIP domains (see /api/v1/sip-domains). When set, the returned SIP URI uses that domain instead of the shared Dasha domain. The domain must be Active.

Response

Call registered successfully

Response after registering an inbound call. Store the call ID: it is the correlation key on every webhook and call result for this call. Bridge the live call to the SIP URI to start the agent.

callId
string
required

Unique identifier for this call. Same value on the result webhook, in call results, and in the SIP URI user part.

Minimum string length: 1
sipUri
string
required

SIP destination to bridge the live call to, in the form sip:{callId}@{domain}.

Minimum string length: 1
orgId
string
required

Organization that owns this call.

Minimum string length: 1
agentId
string
required

Agent that will handle this call.

Minimum string length: 1
fromNumber
string
required

Number of the original caller, as supplied at registration.

Minimum string length: 1
status
enum<string>
required

Current status. A fresh registration is Registered; it becomes Running when the call reaches the SIP destination and Canceled if the deadline passes first.

Available options:
Unknown,
Created,
Pending,
Queued,
Completed,
Failed,
Canceled,
Running,
Registered
direction
enum<string>
required

Always Inbound for registered calls.

Available options:
Outbound,
Inbound
callDeadline
string<date-time>
required

Time until which the registration stays valid.

createdTime
string<date-time>
required

Timestamp when the call was registered.

sipDomainId
string<uuid> | null

Custom SIP domain used for the SIP URI, when one was requested. Null when the shared Dasha domain is used.

toNumber
string | null

Number that received the inbound call, as supplied at registration.

additionalData
object | null

Data for variable interpolation in agent prompts, as supplied at registration.