Initiate an outbound call from your AI agent to a destination number. The AI agent will handle the conversation according to its configured system prompt and capabilities.

Required Fields:

• destinationNumber: Phone number to call in E.164 format (e.g., +306912345678)
• agentId: ID of the AI agent that will handle the call
• sipTrunkId: SIP trunk to dial out from (get from POST /phones/sip-trunks/query)

Optional Features:

• contextForAi: Additional context appended to the agent's system prompt for this specific call (e.g., customer details, call purpose)
• dynamicVariables: Key-value pairs accessible to the agent during the call (e.g., customer name, order ID)
• callerId: Override the caller ID shown to the recipient
• scheduledAt: Schedule the call for a future date/time instead of immediate execution
• maxRetries: Total dial attempts including the first call (0-3, default: 3). 0 or 1 = no automatic retries
• retryDelayMinutes: Minutes between those calls (30-1440, default 30). A retry follows a busy line, no answer, voicemail or a failed call

Protection Settings:

• useAntiHarassmentProtection: (default: true) Prevents excessive outbound calling with daily limits and cooldown periods. Set false to skip.
• overrideTimeRestriction: (default: false) Bypass 9 AM - 9 PM local time restrictions
• overrideDayRestriction: (default: false) Bypass weekend/holiday restrictions

Response:

• callId: Unique identifier for tracking this call
• scheduled: True if call was scheduled for later due to time restrictions
• scheduleTime: The date/time when the call is scheduled (if scheduled)
• error: Error code if call initiation failed
• reason: Human-readable message explaining the error or scheduling reason

HTTP Status Codes:

• 200 OK: Call initiated successfully or scheduled for later
• 400 Bad Request: Validation errors (fix the request)
• 402 Payment Required: Billing/subscription issues (upgrade plan or add credits)
• 403 Forbidden: callee_opted_out - permanent, never retry
• 409 Conflict: call_already_in_progress - a call to this number is already live or scheduled
• 429 Too Many Requests: anti-harassment limits - retry after Retry-After
• 500 Internal Server Error: Server-side issues (retry later or contact support)

Refusals and retry semantics: every refusal has details.retryable. When it is true, details.retryAfterSeconds (also sent as the Retry-After header) and usually details.nextAllowedAt say when a retry can succeed. Do not retry sooner, and never retry when retryable is false: re-submitting the same call in a loop only repeats the refusal.

• callee_opted_out (403) - The callee asked to never be called again. Permanent (retryable: false, permanent: true): remove the number from your list.
• call_already_in_progress (409) - Only one outbound call per number at a time. details.liveCallId / liveCallStatus identify the call that is already live or scheduled: follow that call instead of re-submitting. When it is scheduled (alreadyScheduled: true, scheduledAt, retryable: false) your request is already covered: mark the number as done on your side, because that call is placed automatically and any re-submission is refused again. Also returned for an identical request (same number + agent) within 60s.
• daily_call_limit_reached (429) - Anti-harassment: max 3 outbound calls per number per day. nextAllowedAt is the start of the next day (UTC).
• failed_call_limit_reached (429) - Max 3 failed attempts per number per day. Retry the next day.
• cooldown_period_active (429) - Anti-harassment: 1 hour between connected outbound calls to the same number. nextAllowedAt is the last call + 1 hour.

Validation (400 - fix the request):

• agent_not_found - Invalid agent ID. Check agent exists and is accessible.
• SIP trunk not found or offline. Check sipTrunkId and trunk status.
• distributor_not_found - Configuration issue. Contact support.

Billing Issues (402 - Upgrade plan or add credits):

• insufficient_credits - No credits/minutes in plan. Add credits or upgrade.
• no_seconds_available - No seconds remaining. Upgrade plan.
• no_channels_available - Channel limit reached in plan. Upgrade plan.
• no_concurrent_calls_available - All concurrent slots in use. Upgrade plan or wait.

Server Issues (500 - Retry or contact support):

• internal_error - Unexpected server error. Retry or contact support.
• server_unavailable - Calls server unavailable. Retry in a few minutes.

Note: All error responses include both error (code) and reason (detailed message) fields.

For detailed examples and use cases, see: https://docs.voicelogica.ai/outbound-calls/api

{
  "sipTrunkId": "your_sip_trunk_id",
  "destinationNumber": "+302103009090",
  "agentId": "your_agent_id",
  "contextForAi": "Customer John Doe has an outstanding invoice from last month",
  "dynamicVariables": {
    "customer_name": "John Doe",
    "order_id": "ORD123"
  },
  "overrideTimeRestriction": true,
  "overrideDayRestriction": true,
  "retryDelayMinutes": 120,
  "maxRetries": 3
}

{
  "callId": "call_123456789"
}