لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/telephony.md فهرس التوثيق — /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 and finishing external calls, the call card for the operator, transcriptions
  • Outbound calls — callback and automatic calls with speech synthesis or an audio file
  • Lines — the application's external 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 it in CRM with automatic lead creation → show the card to the operator → finish → attach a 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.crmActivityId)

// 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
MethodPOST Path/v1/calls/register Bitrix24 methodtelephony.externalcall.register DescriptionRegister an external call in CRM
MethodPOST Path/v1/calls/:callId/finish Bitrix24 methodtelephony.externalcall.finish DescriptionFinish a call
MethodPOST Path/v1/calls/:callId/show Bitrix24 methodtelephony.externalcall.show DescriptionShow the call card to the operator
MethodPOST Path/v1/calls/:callId/hide Bitrix24 methodtelephony.externalcall.hide DescriptionHide the call card
MethodPOST Path/v1/calls/:callId/transcription Bitrix24 methodtelephony.call.attachTranscription DescriptionAttach a transcription
MethodPOST Path/v1/calls/callback Bitrix24 methodvoximplant.callback.start DescriptionCallback (operator → client)
MethodPOST Path/v1/calls/auto-call Bitrix24 methodvoximplant.infocall.startwithtext DescriptionAutomatic call with speech synthesis
MethodPOST Path/v1/calls/auto-call-audio Bitrix24 methodvoximplant.infocall.startwithsound DescriptionAutomatic call with audio file playback
MethodGET Path/v1/telephony-lines Bitrix24 methodtelephony.externalLine.get DescriptionList of application lines
MethodPOST Path/v1/telephony-lines Bitrix24 methodtelephony.externalLine.add DescriptionAdd an application line
MethodPATCH Path/v1/telephony-lines/:number Bitrix24 methodtelephony.externalLine.update DescriptionUpdate a line
MethodDELETE Path/v1/telephony-lines/:number Bitrix24 methodtelephony.externalLine.delete DescriptionDelete a line
MethodGET Path/v1/telephony-lines/fields Bitrix24 method— DescriptionField schema of an application line
MethodGET Path/v1/voximplant-lines Bitrix24 methodvoximplant.line.get DescriptionList of Voximplant lines (rented and SIP)
MethodGET Path/v1/calls/statistics Bitrix24 methodvoximplant.statistic.get DescriptionCall statistics
MethodGET Path/v1/calls/voices Bitrix24 methodvoximplant.tts.voices.get DescriptionSpeech synthesis voice reference

Error codes

Telephony errors

Code HTTP Description
CodeMISSING_PARAMS HTTP400 DescriptionA required parameter is missing or failed validation. The exact message lists the required parameters and their format
CodeINVALID_MESSAGE_SHAPE HTTP400 DescriptionFor transcription only: invalid structure of one of the elements in the messages array
CodeBITRIX_ERROR HTTP422 DescriptionBitrix24 returned an error. Its text is in the error.message field
CodeBITRIX_UNAVAILABLE HTTP502 DescriptionBitrix24 is unavailable
CodeUNSUPPORTED_FILTER HTTP400 DescriptionA filter parameter was passed, but this endpoint does not support one. The error text names what to use instead
CodeINVALID_FILTER HTTP400 DescriptionAn ambiguous filter envelope: bracket and JSON forms mixed, or a bracket condition deeper than two levels. Pass the whole filter in a single form

System errors

Code HTTP Description
CodeMISSING_API_KEY HTTP401 DescriptionThe X-Api-Key header is missing
CodeINVALID_API_KEY HTTP401 DescriptionThe key is not recognized — no such key exists on the platform
CodeKEY_INACTIVE HTTP401 DescriptionThe API key is inactive or revoked
CodeTOKEN_MISSING HTTP401 DescriptionThe API key has no Bitrix24 tokens configured
CodeSCOPE_DENIED HTTP403 DescriptionThe key lacks the telephony scope
CodeRATE_LIMITED HTTP429 DescriptionRequest limit exceeded

The full list of common API errors — Errors.

See also