# Calls

Programmatic access to the AI Follow-up of completed Bitrix24 calls: conversation transcript, meeting overview, agreements, tasks and effectiveness score.

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

## 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, a review of the participants and an effectiveness 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 were generated are listed in the `outcomes` field of the response. The ones that were not come back as `null`.

**This is not the transcript of a call with a client.** A conversation with a client logged by 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 in 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 set 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 |

## 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 |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access: the key's webhook has no `call` permission on the portal side. Reconnect the key with the required permission |
| 422 | `METHOD_NOT_YET_AVAILABLE` | The `call 26.600.0` update has not been released on the portal yet |
| 422 | `BITRIX_ERROR` | The request was rejected: invalid date range, unsupported field in `select`, invalid `pagination` or `order`, no access to the call data |

### 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 | 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 suggests the delay | yes, after `Retry-After` |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 accepted the request but did not respond within 15 seconds | yes: the methods in this section only read data, so a retry is safe |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable | yes, after a delay |

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

## See also

- [Call follow-up](/docs/calls/followup)
- [Telephony](/docs/telephony)
- [Call transcript](/docs/entities/activities/transcript)
- [Errors](/docs/errors)