#Прикрепить транскрипцию

POST /v1/calls/:callId/transcription

Прикрепляет текстовую транскрипцию диалога к завершённому звонку в Битрикс24. Звонок должен быть предварительно завершён через `POST /v1/calls/:callId/finish`.

#Параметры

Параметр В Тип Обяз. Описание
callId path string да CALL_ID из ответа `POST /v1/calls/register`

#Поля запроса (body)

Параметр Тип Обяз. По умолч. Описание
messages array да — Массив реплик диалога. Каждый элемент: {side, startTime, stopTime, message}. Не может быть пустым
messages[].side string да — Сторона диалога: "User" — оператор, "Client" — клиент
messages[].startTime number да — Время начала реплики в секундах от начала записи (≥ 0)
messages[].stopTime number да — Время окончания реплики в секундах (> 0)
messages[].message string да — Текст реплики (непустая строка)
cost number нет — Стоимость распознавания
costCurrency string нет — Валюта стоимости (например "RUB")

#Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/calls/CALL_ID/transcription \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"side": "User", "startTime": 0, "stopTime": 3, "message": "Здравствуйте, чем могу помочь?"},
      {"side": "Client", "startTime": 4, "stopTime": 9, "message": "Здравствуйте, хотел уточнить статус заказа"}
    ]
  }'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/calls/CALL_ID/transcription \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"side": "User", "startTime": 0, "stopTime": 3, "message": "Здравствуйте, чем могу помочь?"},
      {"side": "Client", "startTime": 4, "stopTime": 9, "message": "Здравствуйте, хотел уточнить статус заказа"}
    ]
  }'

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

javascript 
const callId = 'externalCall.00b1e735843c558431be668e3687a58b.1777974304'

const res = await fetch(`https://vibecode.bitrix24.tech/v1/calls/${callId}/transcription`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [
      { side: 'User', startTime: 0, stopTime: 3, message: 'Здравствуйте, чем могу помочь?' },
      { side: 'Client', startTime: 4, stopTime: 9, message: 'Здравствуйте, хотел уточнить статус заказа' },
    ],
  }),
})

const { success, data } = await res.json()
console.log('ID транскрипции:', data.TRANSCRIPT_ID)

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

javascript 
const callId = 'externalCall.00b1e735843c558431be668e3687a58b.1777974304'

const res = await fetch(`https://vibecode.bitrix24.tech/v1/calls/${callId}/transcription`, {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: [
      { side: 'User', startTime: 0, stopTime: 3, message: 'Здравствуйте, чем могу помочь?' },
      { side: 'Client', startTime: 4, stopTime: 9, message: 'Здравствуйте, хотел уточнить статус заказа' },
    ],
  }),
})

const { success, data } = await res.json()

#Поля ответа

Поле Тип Описание
TRANSCRIPT_ID number Внутренний ID транскрипции на портале Битрикс24

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

HTTP 200 — транскрипция прикреплена:

JSON 
{
  "success": true,
  "data": {
    "TRANSCRIPT_ID": 3
  }
}

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

400 — не передан массив реплик:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: messages (non-empty array of {side, startTime, stopTime, message})"
  }
}

#Ошибки

HTTP Код Описание
400 MISSING_PARAMS Не передан messages или массив пустой
400 INVALID_MESSAGE_SHAPE Некорректная структура элемента messages[i]: неверный side, тип или диапазон startTime/stopTime, пустой message. В тексте ошибки — индекс некорректного элемента и нарушенное поле
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный API-ключ
401 TOKEN_MISSING Ключ не имеет настроенных токенов Битрикс24
401 KEY_INACTIVE API-ключ неактивен или отозван
403 SCOPE_DENIED Ключу не хватает скоупа telephony
422 BITRIX_ERROR Битрикс24 вернул ошибку (текст в error.message)
429 RATE_LIMITED Превышен лимит запросов
502 BITRIX_UNAVAILABLE Битрикс24 недоступен

Полный список общих ошибок API — Ошибки.

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

На незавершённом звонке Битрикс24 вернёт ошибку. Порядок операций: register → finish → transcription.

Вайбкод валидирует структуру messages локально. Каждый элемент проверяется до отправки в Битрикс24. Ошибка INVALID_MESSAGE_SHAPE содержит индекс некорректного элемента и точное описание нарушенного ограничения — это позволяет исправить конкретный элемент без повторной отправки всего массива.

TRANSCRIPT_ID используется только внутри портала. Внешних эндпоинтов для чтения транскрипций по этому ID нет.

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