For AI agents: markdown of this page — /docs-content-en/telephony/crm/transcription.md documentation index — /llms.txt

Attach a transcription

POST /v1/calls/:callId/transcription

Attaches a text transcription of the conversation to a finished call in Bitrix24. The call must first be finished via POST /v1/calls/:callId/finish.

Parameters

Parameter In Type Required Description
ParametercallId Inpath Typestring Requiredyes DescriptioncallId from the POST /v1/calls/register response

Request fields (body)

Parameter Type Required Default Description
Parametermessages Typearray Requiredyes Default— DescriptionArray of conversation turns. Each item: {side, startTime, stopTime, message}. The array cannot be empty
Parametermessages[].side Typestring Requiredyes Default— DescriptionSide of the conversation: "User" — operator, "Client" — customer
Parametermessages[].startTime Typenumber Requiredyes Default— DescriptionTurn start time in seconds from the beginning of the recording (≥ 0)
Parametermessages[].stopTime Typenumber Requiredyes Default— DescriptionTurn end time in seconds (> 0)
Parametermessages[].message Typestring Requiredyes Default— DescriptionTurn text (non-empty string)
Parametercost Typenumber Requiredno Default— DescriptionRecognition cost
ParametercostCurrency Typestring Requiredno Default— DescriptionCost currency (e.g. "USD")

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/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": "Hello, how can I help you?"},
      {"side": "Client", "startTime": 4, "stopTime": 9, "message": "Hello, I wanted to check my order status"}
    ]
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/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": "Hello, how can I help you?"},
      {"side": "Client", "startTime": 4, "stopTime": 9, "message": "Hello, I wanted to check my order status"}
    ]
  }'

JavaScript — personal key

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

const res = await fetch(`https://vibecode.bitrix24.com/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: 'Hello, how can I help you?' },
      { side: 'Client', startTime: 4, stopTime: 9, message: 'Hello, I wanted to check my order status' },
    ],
  }),
})

const { success, data } = await res.json()
console.log('Transcription ID:', data.transcriptId)

JavaScript — OAuth application

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

const res = await fetch(`https://vibecode.bitrix24.com/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: 'Hello, how can I help you?' },
      { side: 'Client', startTime: 4, stopTime: 9, message: 'Hello, I wanted to check my order status' },
    ],
  }),
})

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

Response fields

Field Type Description
FieldtranscriptId Typenumber DescriptionInternal transcription ID in the Bitrix24 account

Response example

HTTP 200 — the transcription is attached:

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

Error response example

400 — the messages array is missing:

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

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS Descriptionmessages is missing, is not an array, or the array is empty
HTTP400 CodeINVALID_MESSAGE_SHAPE DescriptionInvalid structure of a messages[i] item: wrong side, wrong type or range of startTime/stopTime, empty message. The error text contains the index of the invalid item and the violated field
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized — no such key exists on the platform
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP401 CodeKEY_INACTIVE DescriptionThe API key is inactive or revoked
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the telephony scope
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error (text in error.message)
HTTP429 CodeRATE_LIMITED DescriptionRequest limit exceeded
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable

Full list of common API errors — Errors.

Known specifics

On an unfinished call, Bitrix24 returns an error. Operation order: register → finish → transcription.

Vibecode validates the messages structure locally. Each item is checked before being sent to Bitrix24. The INVALID_MESSAGE_SHAPE error contains the index of the invalid item and an exact description of the violated constraint — this lets you fix the specific item without resending the whole array.

transcriptId is used only inside the Bitrix24 account. There are no external endpoints for reading transcriptions by this ID.

See also