Skip to main content
POST
/
api
/
v1
/
calls
Create call
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    endpoint: '<string>',
    additionalData: {},
    priority: 1,
    callDeadline: null,
    timezone: null,
    overrideOutboundConfig: {phoneNumber: null, credentialsId: null, displayName: null}
  })
};

fetch('https://blackbox.dasha.ai/api/v1/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "endpoint": "<string>",
  "callId": "<string>",
  "orgId": "<string>",
  "agentId": "<string>",
  "createdTime": "2023-11-07T05:31:56Z",
  "status": "Unknown",
  "nextScheduleTime": "2023-11-07T05:31:56Z",
  "additionalData": {},
  "priority": 123,
  "callDeadline": "2023-11-07T05:31:56Z",
  "timezone": "<string>",
  "overrideOutboundConfig": {
    "phoneNumber": null,
    "credentialsId": null,
    "displayName": null
  }
}

​
Call Scheduling

Calls are scheduled based on:
  • Deadline: Target time for call completion (ISO 8601 format)
  • Timezone: Timezone for scheduling (default: UTC)
  • Priority: Call priority level (affects queue ordering)

​
Required Fields

  • Agent ID (query parameter)
  • Destination endpoint (phone number or SIP URI)
  • Call deadline

​
Response

The response includes the created call with assigned call ID and calculated next schedule time.

Query Parameters

​
agentId
string

Agent identifier

Body

Call configuration

Configuration for enqueueing an outbound call. Specifies the destination endpoint, scheduling parameters, and optional SIP configuration overrides for making automated calls to customers or external phone numbers.

​
endpoint
string
required

Phone number or SIP endpoint to call. The format depends on your SIP configuration and the type of call being made.

Minimum string length: 1
​
additionalData
object

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

​
priority
integer<int32> | null
default:1

Call priority for queue ordering. Higher priority calls are attempted before lower priority calls when multiple calls are queued. Useful for prioritizing urgent calls or VIP customers.

​
callDeadline
string<date-time> | null

Deadline for completing the call attempt. If the call has not been successfully connected by this time, it will be marked as canceled. When not specified, defaults to current time plus 1 day, giving the system 24 hours to complete the call.

​
timezone
string | null

Timezone identifier for call scheduling (e.g., "America/New_York", "Europe/London"). Used to interpret scheduled call times in the recipient's local timezone. When not specified, the agent's timezone is used.

​
overrideOutboundConfig
object

Override SIP configuration for this specific call. Allows using different outbound SIP settings, caller ID, or trunk configuration than the agent's default configuration. Useful for routing calls through specific carriers or presenting different caller IDs.

Response

Call created successfully

Response after successfully enqueueing a call. Contains all call parameters from the request plus system-assigned identifiers, status, and scheduling information for tracking the call's lifecycle.

​
endpoint
string
required

Phone number or SIP endpoint to call. The format depends on your SIP configuration and the type of call being made.

Minimum string length: 1
​
callId
string
required

Unique identifier for this call. Use this ID to query call status, retrieve call details, or cancel the call before it completes.

Minimum string length: 1
​
orgId
string
required

Organization that owns this call. Used for access control and resource tracking.

Minimum string length: 1
​
agentId
string
required

Agent that will handle this call. References the agent configuration used for the conversation logic, voice settings, and tool availability.

Minimum string length: 1
​
createdTime
string<date-time>
required

Timestamp when the call was enqueued and entered the system.

​
status
enum<string>
required

Current status of the call. Possible values: Created (just enqueued), Pending (waiting to be processed), Queued (in call queue), Running (call in progress), Completed (successfully finished), Failed (error occurred), Canceled (manually canceled).

Available options:
Unknown,
Created,
Pending,
Queued,
Completed,
Failed,
Canceled,
Running
​
nextScheduleTime
string<date-time>
required

Next scheduled time when the system will attempt to initiate this call. For immediate calls, this is typically very close to the creation time. For scheduled calls or retries, this reflects the next planned attempt.

​
additionalData
object

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

​
priority
integer<int32> | null

Call priority for queue ordering. Higher priority calls are attempted before lower priority calls when multiple calls are queued. Useful for prioritizing urgent calls or VIP customers.

​
callDeadline
string<date-time> | null

Deadline for completing the call attempt. If the call has not been successfully connected by this time, it will be marked as canceled. When not specified, defaults to current time plus 1 day, giving the system 24 hours to complete the call.

​
timezone
string | null

Timezone identifier for call scheduling (e.g., "America/New_York", "Europe/London"). Used to interpret scheduled call times in the recipient's local timezone. When not specified, the agent's timezone is used.

​
overrideOutboundConfig
object

Override SIP configuration for this specific call. Allows using different outbound SIP settings, caller ID, or trunk configuration than the agent's default configuration. Useful for routing calls through specific carriers or presenting different caller IDs.