# Расшифровки звонков CRM

`GET /v1/activities/:activityId/transcript`

Возвращает готовую AI-расшифровку звонка клиента, зафиксированного в CRM как дело типа «Звонок» и обработанного на портале с помощью BitrixGPT. Метод только читает уже готовую расшифровку — генерацию не запускает.

Битрикс24 API: `crm.activity.call.getTranscript`
Скоуп: `crm`

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `activityId` (path) | number | да | ID дела-звонка. Список: [`GET /v1/activities`](/docs/entities/activities/list) |

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/activities/12345/transcript" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/activities/12345/transcript" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/activities/12345/transcript', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
if (data.transcription === null) {
  // расшифровки ещё нет — это не ошибка
} else {
  console.log(data.transcription)
}
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/activities/12345/transcript', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `transcription` | string \| null | Полный текст расшифровки. Значение `null` приходит со статусом `200`, когда расшифровки для звонка ещё нет — звонок не обработан или обработка не завершилась. Проверяйте `data.transcription === null` |

## Пример ответа

Расшифровка готова:

```json
{
  "success": true,
  "data": {
    "transcription": "Здравствуйте, чем могу помочь?"
  }
}
```

Расшифровки пока нет — `transcription` равно `null`, статус остаётся `200`:

```json
{
  "success": true,
  "data": {
    "transcription": null
  }
}
```

## Пример ответа при ошибке

403 — нет доступа к расшифровке:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "Доступ запрещён",
    "hint": "Access denied to this call transcript. Two possible causes: (1) the API key owner lacks read access to a CRM entity bound to this call activity, or (2) AI call processing is not enabled on this portal. Verify the user's CRM permissions, and confirm AI call processing (transcription) is turned on."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 403 | `BITRIX_ACCESS_DENIED` | Один код на два повода: нет прав на CRM-сущность, к которой привязан звонок, либо на портале выключена AI-обработка звонков. Поле `hint` называет оба |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `crm` |
| 400 | `INVALID_PARAMS` | `activityId` не положительное целое число |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |
| 404 | `ENTITY_NOT_FOUND` | Дело с таким `activityId` не найдено или не имеет CRM-привязок |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

- Расшифровка доступна, если у ключа есть права на чтение хотя бы одной CRM-сущности — сделки, лида, контакта или компании, к которой привязан звонок. Дополнительно на портале должна быть включена AI-обработка звонков (BitrixGPT).
- Расшифровка появляется не сразу: портал формирует её после завершения звонка. Пока обработка не закончена, `transcription` равно `null` со статусом `200`. Повторите запрос позже.

## Смотрите также

- [Получить дело](/docs/entities/activities/get)
- [Список дел](/docs/entities/activities/list)
- [Привязки дел](/docs/entities/activities/bindings)
- [Лимиты и оптимизация](/docs/optimization)