# Calls

Programmatic access to Bitrix24 calls: AI Follow-up of completed calls, the personal call journal, call recordings and CRM card lookup by phone number.

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

## Documentation sections

- [Call follow-up](/docs/calls/followup) — AI review of completed calls: transcript, meeting overview, agreements, tasks
- [Call journal](/docs/calls/log) — the personal call journal of the key's user
- [Call recording](/docs/calls/record) — attach an audio recording to a completed external telephony call
- [CRM cards by phone](/docs/calls/crm-entities) — CRM cards and the responsible employee for a phone number

## External telephony

The following operations require the `telephony` scope:

- [Attach a recording](/docs/calls/record)
- [Find CRM cards by phone](/docs/calls/crm-entities)
- [Manage SIP connections](/docs/voximplant-sip)
- [Default outgoing line](/docs/voximplant-lines/default)
- [Employee telephony settings](/docs/telephony-users)

## What a Follow-up is

A Follow-up is an AI review of an internal call or a meeting between employees: the conversation transcript, the meeting topic, agreements, assigned tasks, participant analysis and an efficiency score. Bitrix24 generates it automatically after the call ends. The methods in this section only read the finished result and create nothing.

A Follow-up is not generated for every call. The blocks that are ready are listed in the `outcomes` field of the response; the ones that have not been generated come back as `null`.

**This is not the transcript of a call with a client.** A conversation with a client logged as a CRM activity is transcribed by a separate mechanism — its text is returned by [`GET /v1/activities/:activityId/transcript`](/docs/entities/activities/transcript). If the task sounds like "get the text of a conversation with a client for a deal or a lead" — use that endpoint, not this section.

## Quick start

List the calls from January that already have a Follow-up:

```bash
curl -X POST https://vibecode.bitrix24.com/v1/calls/followups/list \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "startDate": { "from": "2026-01-01T00:00:00Z", "to": "2026-01-31T23:59:59Z" } },
    "pagination": { "limit": 5 }
  }'
```

The response contains an array of calls in `data.items` and the next-page cursor in `data.afterCursor`:

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "callId": 12345,
        "callType": 1,
        "initiatorId": 7,
        "startDate": "2026-01-15T10:00:00+00:00",
        "endDate": "2026-01-15T10:42:00+00:00",
        "durationSeconds": 2520
      }
    ],
    "hasMore": false,
    "afterCursor": null
  }
}
```

## Full example

Review the outcome of a meeting: find a call for the period, read the overview and agreements, retrieve the tasks.

```bash
BASE='https://vibecode.bitrix24.com/v1'

# 1. Calls with a Follow-up for the period → take the identifier of the first one
CALL_ID=$(curl -s -X POST "$BASE/calls/followups/list" \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"filter": {"startDate": {"from": "2026-01-01T00:00:00Z", "to": "2026-01-31T23:59:59Z"}},
       "order": {"startDate": "desc"}, "pagination": {"limit": 1}}' | jq -r '.data.items[0].callId')

# 2. Meeting overview and agreements
curl -s "$BASE/calls/followups/$CALL_ID?select=overview&mentionFormat=none" \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.data.item.overview.topic, .data.item.overview.agreements'

# 3. Tasks assigned during the meeting
curl -s "$BASE/calls/followups/$CALL_ID?select=overview.actionItems&mentionFormat=none" \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.data.item.overview.actionItems'
```

`mentionFormat=none` removes `@`-mention markup: the text comes back without the internal tags, ready to pass to an AI model or save to a task.

## Endpoint reference

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|----------|
| POST | [`/v1/calls/followups/list`](/docs/calls/followup/list) | call.followup.list | List of Follow-ups for a period with filtering, sorting and cursor navigation |
| GET | [`/v1/calls/followups/:callId`](/docs/calls/followup/get) | call.followup.get | Full Follow-up data for a single call |
| GET | [`/v1/calls/log`](/docs/calls/log/list) | call.CallLog.list | Personal call journal |
| DELETE | [`/v1/calls/log/:callId`](/docs/calls/log/delete) | call.CallLog.delete | Delete a journal entry |
| GET | [`/v1/calls/log/chat`](/docs/calls/log/chat) | call.CallLog.getChat | ID of the personal chat with the other party |
| POST | [`/v1/calls/:callId/record`](/docs/calls/record) | telephony.externalCall.attachRecord | Attach a conversation recording to a call |
| GET | [`/v1/calls/crm-entities`](/docs/calls/crm-entities) | telephony.externalCall.searchCrmEntities | CRM cards by phone number |

## Error codes

### Section errors

| HTTP | Code | When |
|------|-----|-------|
| 400 | `MISSING_PARAMS` | The request body has no `filter` object |
| 400 | `INVALID_PARAMS` | `callId` in the path is not a positive integer |
| 400 | `INVALID_PARAMS` | Bitrix24 rejected the parameter value. The response additionally contains an `error.validation` array with the field name |
| 400 | `MISSING_REQUIRED_FIELDS` | A required parameter is missing: `phone` in the CRM lookup by phone, `fileContent` or `fileName` when uploading a recording |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access. A common cause is that the set of scopes the key uses to reach the portal does not include `call`. The full list of causes and what to do per key type — [Authorization, keys and permissions](/docs/errors/auth#bitrix_access_denied-403) |
| 413 | `PAYLOAD_TOO_LARGE` | The recording file exceeds 2 MiB after decoding, or the request body exceeds 3 MiB |
| 422 | `BITRIX_ERROR` | The request was rejected: invalid date range, unsupported field in `select`, invalid `pagination` or `order`, no access to the call data |
| 422 | `BITRIX_ERROR` | The call for the recording is not found or has not ended yet |

### System errors

| HTTP | Code | When | Retry |
|------|-----|-------|--------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing | no |
| 401 | `TOKEN_MISSING` | The key has no portal tokens. An OAuth application key requires the `Authorization: Bearer` header | no |
| 403 | `SCOPE_DENIED` | The key has no `call` scope, or the `telephony` scope for external telephony operations | no |
| 429 | `RATE_LIMITED` | Request rate exceeded on the Bitrix24 side | yes, after a delay |
| 429 | `QUEUE_OVERFLOW`, `QUEUE_TIMEOUT` | The portal request queue is full or the request did not get through the queue in time. The `Retry-After` header indicates the delay | yes, after `Retry-After` |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 accepted the request but did not respond within 60 seconds | yes for read operations. Before retrying a recording upload or a deletion, check the result: the request may have been executed |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable | yes, after a delay |

The full list of common API errors — [Error codes](/docs/errors).

## See also

- [Call follow-up](/docs/calls/followup)
- [Telephony](/docs/telephony)
- [CRM call transcripts](/docs/entities/activities/transcript)
- [Error codes](/docs/errors)