# 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](#quick-start) | [Full example](#full-example) | [Endpoint reference](#endpoint-reference) | [Error codes](#error-codes)

## Documentation sections

- [Calls in CRM](/docs/telephony/crm) — registering external calls, finishing, the call card for the operator, transcriptions
- [Outbound calls](/docs/telephony/outbound) — callback and automatic calls with speech synthesis or an audio file
- [Lines](/docs/telephony/lines) — external application lines and the list of lines rented from Voximplant
- [Analytics and reference data](/docs/telephony/analytics) — call statistics and the voice reference for speech synthesis

---

## Quick start

### 1. Register a call

```bash
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

```bash
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

```bash
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](/docs/telephony/crm/register) | telephony.externalcall.register | Register an external call in CRM |
| POST | [/v1/calls/:callId/finish](/docs/telephony/crm/finish) | telephony.externalcall.finish | Finish a call |
| POST | [/v1/calls/:callId/show](/docs/telephony/crm/show) | telephony.externalcall.show | Show the call card to the operator |
| POST | [/v1/calls/:callId/hide](/docs/telephony/crm/hide) | telephony.externalcall.hide | Hide the call card |
| POST | [/v1/calls/:callId/transcription](/docs/telephony/crm/transcription) | telephony.call.attachTranscription | Attach a transcription |
| POST | [/v1/calls/callback](/docs/telephony/outbound/callback) | voximplant.callback.start | Callback (operator → client) |
| POST | [/v1/calls/auto-call](/docs/telephony/outbound/auto-call) | voximplant.infocall.startwithtext | Automatic call with speech synthesis |
| POST | [/v1/calls/auto-call-audio](/docs/telephony/outbound/auto-call-audio) | voximplant.infocall.startwithsound | Automatic call with audio file playback |
| GET | [/v1/telephony-lines](/docs/telephony/lines/list) | telephony.externalLine.get | List of application lines |
| POST | [/v1/telephony-lines](/docs/telephony/lines/create) | telephony.externalLine.add | Add an application line |
| PATCH | [/v1/telephony-lines/:number](/docs/telephony/lines/update) | telephony.externalLine.update | Update a line |
| DELETE | [/v1/telephony-lines/:number](/docs/telephony/lines/delete) | telephony.externalLine.delete | Delete a line |
| GET | [/v1/voximplant-lines](/docs/telephony/lines/voximplant) | voximplant.line.get | List of Voximplant lines (rented and SIP) |
| GET | [/v1/calls/statistics](/docs/telephony/analytics/statistics) | voximplant.statistic.get | Call statistics |
| GET | [/v1/calls/voices](/docs/telephony/analytics/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](/docs/errors).

---

## See also

- [Leads](/docs/entities/leads) — created automatically with `crmCreate: true` in register
- [Contacts](/docs/entities/contacts) — linked to calls by phone number
- [Deals](/docs/entities/deals) — calls appear in the timeline of the related deal