← HomeРусский

Trigger Call API

Start an outbound AI call programmatically from any CRM or external system. The call is queued and placed during the organization's business hours.

Endpoint

POST https://your-host/api/public/trigger-call

Headers

HeaderValue
AuthorizationBearer YOUR_API_KEY — a key issued in your account
Content-Typeapplication/json

Request body

FieldTypeDescription
phonestring, requiredA number in any format: +79991234567, 89991234567, 8 (999) 123-45-67. Normalized to E.164.
campaignstring, ≤64The calling campaign to queue the call in — identified by its trigger_key (not the numeric id). The campaign decides which agent calls and with which script. You may omit the field only if the key is already bound to a campaign in your account; otherwise the request is rejected with 422.
payloadobject, optionalAny JSON object with context. It is passed to the voice agent's prompt in the <client_context> block. Limit 5 KB; strings longer than 200 characters are truncated.
external_refstring, optional, ≤128The entity ID in your CRM (e.g. LEAD_42). Used for deduplication and to update exactly this lead after the call.
external_systemstring, optional, ≤32CRM name (bitrix, amocrm, custom). Determines how the lead is updated back.

Minimal request

{
  "phone": "+79991234567",
  "campaign": "reactivation"
}

Full request

{
  "phone": "+79991234567",
  "campaign": "reactivation",
  "payload": {
    "name": "John",
    "stage": "Price negotiation",
    "product": "CRM Pro",
    "deal_amount": 240000
  },
  "external_ref": "LEAD_42",
  "external_system": "bitrix"
}

curl

curl -X POST 'https://your-host/api/public/trigger-call' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+79991234567","campaign":"reactivation","payload":{"name":"John","stage":"Price negotiation","product":"CRM Pro","deal_amount":240000},"external_ref":"LEAD_42","external_system":"bitrix"}'

Responses

CodeWhen
202The call is queued. Body: {"queued":true,"call_list_entry_id":N}
400Invalid number, payload too large (>5 KB), malformed JSON.
401The key is missing, revoked, or doesn't match the sk_live_… format.
403The key lacks the trigger_call scope, or the key is bound to one campaign while campaign names another: the binding is strict and can't be overridden by the request body.
404Your organization has no campaign with this campaign key (or it is archived). The response is the same for a non-existent key and for another organization's campaign key.
409Duplicate within the same campaign. With external_ref — there is already an active entry with the same ref. Without it — there is an active entry for the same phone number.
422There is nowhere to queue the call: campaign is not provided and the key isn't bound to a campaign. There is no fallback “default” campaign — otherwise the customer could get a call from the wrong agent.
429Rate limit exceeded: 60 requests per minute or 1000 per day per key. The Retry-After header tells you how long to wait.

Setting up a Bitrix24 automation rule

In Bitrix24, an “outgoing webhook” from a pipeline automation rule sends a POST with a templated body to our URL. This is the simplest route — no apps to install.

  1. In Bitrix24, open CRM → Pipelines → Automation rules on the stage you need.
  2. Add the “HTTP notification” rule or a similar “webhook” one.
  3. Method: POST. URL: https://your-host/api/public/trigger-call
  4. Headers:
    • Authorization: Bearer YOUR_API_KEY
    • Content-Type: application/json
  5. Body — JSON with Bitrix placeholders. Take the campaign value from the campaign's “Integration” tab — it is the campaign's trigger_key, not its numeric id:
{
  "phone": "{{=Document:PHONE}}",
  "campaign": "reactivation",
  "payload": {
    "name": "{{=Document:NAME}}",
    "stage": "{{=Document:STAGE_ID}}",
    "title": "{{=Document:TITLE}}"
  },
  "external_ref": "LEAD_{{=Document:ID}}",
  "external_system": "bitrix"
}

Once set up: when a lead moves to this stage, the rule calls our endpoint and we queue the call. The AI agent gets the context from payload in its system prompt, and after a successful call the result goes back into the same lead (instead of creating a duplicate) — thanks to external_ref.

amoCRM, Kommo and other CRMs

The endpoint is provider-neutral. Set up a webhook on a pipeline stage or an automation trigger with the same headers and body. The external_system field tells our backend how to talk to your CRM's API when updating the lead back.

Deduplication and idempotency

Deduplication applies within a single campaign. The same number can be in a reactivation campaign and a callback campaign at the same time — those are different conversations with different agents.

When the call actually goes out

The call is queued instantly. It is actually dialed when:

Call statuses and outcomes

When a call ends, the number in the call list gets an operational status and a business outcome. They mean different things and shouldn't be confused.

Status (what happened at the telephony level)

Outcome (business result)

Important: voicemail and silence are no longer marked as “Completed”. If AMD detected an answering machine, the status is no_answer and the outcome is voicemail. This means the lead can be called back, rather than counted as if a conversation took place.

Calling settings

Settings are configured per campaign on the “Settings” tab of the /campaigns/{id} page. So reactivation can call rarely and gently, while callback requests are handled often and persistently — all within the same account:

Changes apply on the fly — the worker loop picks up new values within a minute, no restart needed.

Security