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
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):
{
"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
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
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:
{ "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.
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.