Skip to content
EN
Open app

For AI assistants: this page as plain markdown is at https://docs.voicelogica.ai/raw/outbound-calls/api.md, and https://docs.voicelogica.ai/llms.txt lists the docs by topic, one file each, small enough to read whole. Read those rather than this HTML page.

API

5 min read
Copy as Markdown
View as MarkdownOpen the raw .md file.md

One outbound call from your system — a CRM event, a form, a missed-call callback. A list on a schedule is Campaigns, not this endpoint.

The agent’s Outgoing settings still apply. This request picks the number, the agent, and optional extra context for this call.

  1. Plan includes Allow Outbound Calls.
  2. API key with the Calls group.
  3. A trunk (or VoIP phone) to dial from — Your own carrier / Voice Logica numbers.
  4. The agent id — from the agent URL on My Agents, or Copy on a campaign row.
POST https://api.voicelogica.ai/api/v1/phones/calls/initiate-call
x-api-key: YOUR_API_KEY
Content-Type: application/json

Resellers: optional x-company-id to act on a subsidiary. Without it, the key’s own company is used.

Send destinationNumber and agentId. Send sipTrunkId or voipPhoneId unless the company already has an outbound route / default trunk that can carry the call — if neither is sent and no trunk can be resolved, the API returns that no active SIP trunk or VoIP phone was specified.

Trunk (usual):

Terminal window
curl -X POST https://api.voicelogica.ai/api/v1/phones/calls/initiate-call \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sipTrunkId": "your_sip_trunk_id",
"destinationNumber": "+14155552671",
"agentId": "your_agent_id"
}'

VoIP phone id still works — the server resolves it to a trunk.

Success is { "callId": "..." }. If the destination is outside 09:00–21:00 local time, you may get "scheduled": true plus scheduleTime and reason. Open Calls and listen.

destinationNumber in E.164 (+14155552671).

Required for an AI outbound call

FieldWhat it does
destinationNumberNumber to call.
agentIdAgent that talks. Required for AI outbound; optional only for isInternalCall.

Call source — send one, or rely on the company outbound default

FieldWhat it does
sipTrunkIdTrunk from Telephony → Trunks. Prefer this.
voipPhoneIdLegacy line id. Resolved to a trunk.
callerIdE.164 or SIP URI shown to the recipient. Must be a number that trunk is allowed to present.

This call only

FieldWhat it does
contextForAiAppended to the system prompt for this call.
dynamicVariablesString key/value pairs the prompt can use ({{customer_name}}).
superVariablesTyped values: { placeholder, value, type } — text / number / boolean / date / time.
metadataYour tracking. Stored on the call. Keys starting scenario_ are stripped.
emailAddressWhere to send the summary / recording.
welcomeMessageOverrideSpoken instead of the agent greeting.
isWelcomeMessageAIGeneratedAI writes the greeting for this call.
scheduledAtISO date. Call later instead of now.
maxRetriesTotal calls, the first one included: 1–3, default 3. 3 = the first call plus up to 2 retries; 0 or 1 = no retry. Retries follow a busy line, no answer, voicemail or a failed call.
retryDelayMinutesMinutes between those calls: 30–1440, default 30.
additionalPhoneNumbersExtra numbers on the same request.

Do not send fromNumber. The public contract is sipTrunkId / voipPhoneId.

Inbound is never restricted.

  • Time (on) — 09:00–21:00 in your company’s country time (Greek time for a company in Greece). Outside that, the call is scheduled for the next allowed time. Bypass: overrideTimeRestriction: true.
  • Day (on) — weekends / holidays may be blocked by destination country. Bypass: overrideDayRestriction: true.
  • Anti-harassment (on unless you send useAntiHarassmentProtection: false) — per number per day: max 3 calls that went through and 3 failed, 1 hour between calls that went through, no duplicate active/scheduled call. The day resets at midnight UTC. Campaign Allowed test numbers bypass this. Full rules: Call limits and calling hours.

Bypassing time or day rules can break local law. Keep anti-harassment on for anyone who has not asked for the calls.

The body is { "error": "<code>", "reason": "<message>" }.

CodeMeaning
call_already_in_progressA live or scheduled call to this number already exists.
agent_not_found / voip_phone_not_foundBad id.
daily_call_limit_reached3 successful calls to this number today (anti-harassment).
failed_call_limit_reached3 failed attempts today.
cooldown_period_activeWait 1 hour after a successful call to this number.
call_already_scheduled / failed_to_schedule_callSchedule conflict.
callee_opted_outThis number asked not to be called again.
insufficient_credits / no_seconds_available / no_channels_available / no_concurrent_calls_availablePlan / credits.
maximum_authentication_attempts_exceededPhone deactivated after repeated auth failures.

402 is billing. 400 is a bad request or a protection. 500 is the calls server — retry later.

const response = await fetch('https://api.voicelogica.ai/api/v1/phones/calls/initiate-call', {
method: 'POST',
headers: { 'x-api-key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
body: JSON.stringify({
destinationNumber: '+14155552671',
agentId: 'your_agent_id',
sipTrunkId: 'your_sip_trunk_id',
contextForAi: 'Customer asked about order ORD123',
dynamicVariables: { customer_name: 'Ada', order_id: 'ORD123' },
useAntiHarassmentProtection: true,
}),
});
const result = await response.json();
if (result.callId) console.log(result.callId);
else console.error(result.error, result.reason);

Schedule + retries:

{
"destinationNumber": "+14155552671",
"agentId": "your_agent_id",
"sipTrunkId": "your_sip_trunk_id",
"scheduledAt": "2026-09-16T14:30:00Z",
"maxRetries": 2,
"retryDelayMinutes": 120
}

scheduledAt is converted to the destination country’s zone. Protections still apply unless you override them.

  • 400 “no active SIP trunk” — send sipTrunkId, or add a trunk with numbers and an outbound default.
  • scheduled: true when you expected now — destination local time is outside 09:00–21:00.
  • Agent talks over “hello” — Outgoing Who speaks first, not this payload.
  • Call missing on Calls — wrong company (x-company-id), or the request never returned a callId.
Why doesn't fromNumber work anymore in the initiate-call API?

fromNumber is not part of the public request body. Send sipTrunkId (the trunk id from Telephony → Trunks) or voipPhoneId instead.

Why did my initiate-call request return scheduled: true instead of calling now?

The call fell outside the allowed calling hours or days (09:00–21:00 in your company’s country time), so it was scheduled for the next allowed time. Wait for that window, or send overrideTimeRestriction / overrideDayRestriction only if you are allowed to call outside it.

Write developers@voicelogica.ai — extra test credits and help on the integration.