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

Telephony

Bitrix24 telephony management: registering external calls in CRM, automatic outbound calls and callbacks, attaching transcriptions, call statistics, managing application lines.

Scope: telephony | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Quick start | Full example | Endpoint reference | Error codes

Documentation sections

  • Calls in CRM — registering external calls, finishing, the call card for the operator, transcriptions
  • Outbound calls — callback and automatic calls with speech synthesis or an audio file
  • Lines — external application lines and the list of lines rented from Voximplant
  • Analytics and reference data — call statistics and the voice reference for speech synthesis

Quick start

1. Register a call

Terminal
curl -X POST https://vibecode.bitrix24.com/v1/calls/register \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "phoneNumber": "+12025550123",
    "type": 2,
    "crmCreate": true
  }'

Response (HTTP 201):

JSON
{
  "success": true,
  "data": {
    "CALL_ID": "externalCall.00b1e735843c558431be668e3687a58b.1777974304",
    "CRM_CREATED_LEAD": 1001069,
    "CRM_CREATED_ENTITIES": [{"ENTITY_TYPE": "LEAD", "ENTITY_ID": 1001069}],
    "CRM_ENTITY_TYPE": "LEAD",
    "CRM_ENTITY_ID": 1001069
  }
}

2. Finish the call

Terminal
curl -X POST https://vibecode.bitrix24.com/v1/calls/externalCall.00b1e735843c558431be668e3687a58b.1777974304/finish \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": 1, "duration": 120, "statusCode": "200"}'

3. Attach a transcription

Terminal
curl -X POST https://vibecode.bitrix24.com/v1/calls/externalCall.00b1e735843c558431be668e3687a58b.1777974304/transcription \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"side": "User", "startTime": 0, "stopTime": 3, "message": "Hello, how can I help you?"},
      {"side": "Client", "startTime": 4, "stopTime": 8, "message": "I have a question about my order"}
    ]
  }'

Response:

JSON
{ "success": true, "data": { "TRANSCRIPT_ID": 3 } }

Full example

A JavaScript script that handles an incoming call: register in CRM with automatic lead creation → show the card to the operator → finish → attach transcription → check statistics.

javascript
const KEY = process.env.VIBE_API_KEY
const BASE = 'https://vibecode.bitrix24.com/v1'

async function api(method, path, body) {
  const opts = { method, headers: { 'X-Api-Key': KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  if (res.status === 204) return null
  return res.json()
}

// 1. Register an external call and create a lead if the number is not in CRM yet
const reg = await api('POST', '/calls/register', {
  userId: 1,
  phoneNumber: '+12025550124',
  type: 2,
  crmCreate: true
})
const callId = reg.data.CALL_ID
console.log('Call registered:', callId)
console.log('Lead created:', reg.data.CRM_CREATED_LEAD)

// 2. Show the call card to the operator
await api('POST', `/calls/${callId}/show`, { userId: 1 })

// 3. Finish the call (duration 245 seconds, success)
const fin = await api('POST', `/calls/${callId}/finish`, {
  userId: 1,
  duration: 245,
  statusCode: '200'
})
console.log('CRM activity:', fin.data.CRM_ACTIVITY_ID)

// 4. Attach a transcription
await api('POST', `/calls/${callId}/transcription`, {
  messages: [
    { side: 'User', startTime: 0, stopTime: 4, message: 'Hello, this is Vibecode!' },
    { side: 'Client', startTime: 5, stopTime: 12, message: 'Hi, I would like to clarify the details of order 4521' },
    { side: 'User', startTime: 13, stopTime: 25, message: 'Of course, the order has shipped, tracking number 1234567890' }
  ]
})

// 5. Check today's statistics
const today = new Date().toISOString().slice(0, 10) + 'T00:00:00'
const stats = await api('GET', `/calls/statistics?filter[>CALL_START_DATE]=${today}`)
console.log(`Calls today: ${stats.total}`)

Endpoint reference

Method Path Bitrix24 method Description
POST /v1/calls/register telephony.externalcall.register Register an external call in CRM
POST /v1/calls/:callId/finish telephony.externalcall.finish Finish a call
POST /v1/calls/:callId/show telephony.externalcall.show Show the call card to the operator
POST /v1/calls/:callId/hide telephony.externalcall.hide Hide the call card
POST /v1/calls/:callId/transcription telephony.call.attachTranscription Attach a transcription
POST /v1/calls/callback voximplant.callback.start Callback (operator → client)
POST /v1/calls/auto-call voximplant.infocall.startwithtext Automatic call with speech synthesis
POST /v1/calls/auto-call-audio voximplant.infocall.startwithsound Automatic call with audio file playback
GET /v1/telephony-lines telephony.externalLine.get List of application lines
POST /v1/telephony-lines telephony.externalLine.add Add an application line
PATCH /v1/telephony-lines/:number telephony.externalLine.update Update a line
DELETE /v1/telephony-lines/:number telephony.externalLine.delete Delete a line
GET /v1/voximplant-lines voximplant.line.get List of Voximplant lines (rented and SIP)
GET /v1/calls/statistics voximplant.statistic.get Call statistics
GET /v1/calls/voices voximplant.tts.voices.get Speech synthesis voice reference

Error codes

Telephony errors

Code HTTP Description
MISSING_PARAMS 400 A required parameter is missing or failed validation. The exact message lists the required parameters and their format
INVALID_MESSAGE_SHAPE 400 For transcription only: invalid structure of one of the elements in the messages array
BITRIX_ERROR 422 Bitrix24 returned an error (the message from B24 is in the error.message field)
BITRIX_UNAVAILABLE 502 Bitrix24 is unavailable

System errors

Code HTTP Description
MISSING_API_KEY 401 The X-Api-Key header is missing
INVALID_API_KEY 401 Invalid API key
KEY_INACTIVE 401 The API key is inactive or revoked
TOKEN_MISSING 401 The API key has no Bitrix24 tokens configured
SCOPE_DENIED 403 The key lacks the telephony scope
RATE_LIMITED 429 Request limit exceeded

The full list of common API errors — Errors.


See also

  • Leads — created automatically with crmCreate: true in register
  • Contacts — linked to calls by phone number
  • Deals — calls appear in the timeline of the related deal