For AI agents: markdown of this page — /docs-content-en/telephony/outbound.md documentation index — /llms.txt

Outbound calls

Initiate outbound calls through the Voximplant infrastructure: a callback that connects an operator and a client, automated informational calls with speech synthesis or with playback of an audio file.

Bitrix24 API: voximplant.callback.start, voximplant.infocall.* Scope: telephony

Initiate a callback

POST /v1/calls/callback

Initiates a callback: Bitrix24 first calls the operator line (fromLine), and once it is answered, connects the operator to the client (toNumber). Used for outbound calls from CRM without dialing the number manually.

Request fields (body)

Parameter Type Required Default Description
fromLine string yes — Operator line ID. List of lines — GET /v1/voximplant-lines
toNumber string yes — Client phone number in international format

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/calls/callback \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromLine": "YOUR_LINE_ID",
    "toNumber": "+12025550123"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/calls/callback \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fromLine": "YOUR_LINE_ID",
    "toNumber": "+12025550124"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calls/callback', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fromLine: 'YOUR_LINE_ID',
    toNumber: '+12025550125',
  }),
})

const { success, data } = await res.json()
const callId = data.callId

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calls/callback', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fromLine: 'YOUR_LINE_ID',
    toNumber: '+12025550126',
  }),
})

const { success, data } = await res.json()
const callId = data.callId

Response fields

Field Type Description
result boolean true when the call is initiated successfully
callId string Identifier of the initiated call with the callback. prefix

Response example

HTTP 200 — call initiated:

JSON 
{
  "success": true,
  "data": {
    "result": true,
    "callId": "callback.e7804636435209e12c9cef1ec1bcead1.1777974876"
  }
}

Error response example

400 — required parameters not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: fromLine (string), toNumber (string)"
  }
}

Errors

HTTP Code Description
400 MISSING_PARAMS fromLine or toNumber not provided
401 MISSING_API_KEY X-Api-Key header not provided
401 INVALID_API_KEY Invalid API key
401 TOKEN_MISSING The key has no configured Bitrix24 tokens
401 KEY_INACTIVE API key is inactive or revoked
403 SCOPE_DENIED The key lacks the telephony scope
422 BITRIX_ERROR Bitrix24 returned an error (message in error.message)
429 RATE_LIMITED Request limit exceeded
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable

Full list of common API errors — Errors.

Known specifics

Connection order. Bitrix24 first calls the operator line. The client is called only after the operator has answered. If the operator does not answer, the client is not disturbed.

callId prefix. Callback identifiers start with callback. — unlike registered calls (externalCall.) and informational ones (infocall.).

Record in statistics. After the call ends, it appears in the statistics with CALL_TYPE: "4".

Real charges. Each invocation initiates a call to the operator's number and draws on your Bitrix24 account balance.

See also