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
callId path string yes callId from the POST /v1/calls/register response

Request fields (body)

Parameter Type Required Default Description
messages array yes — Array of conversation turns. Each item: {side, startTime, stopTime, message}. The array cannot be empty
messages[].side string yes — Side of the conversation: "User" — operator, "Client" — customer
messages[].startTime number yes — Turn start time in seconds from the beginning of the recording (≥ 0)
messages[].stopTime number yes — Turn end time in seconds (> 0)
messages[].message string yes — Turn text (non-empty string)
cost number no — Recognition cost
costCurrency string no — Cost 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
transcriptId number Internal 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
400 MISSING_PARAMS messages is missing, is not an array, or the array is empty
400 INVALID_MESSAGE_SHAPE Invalid 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
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY Invalid API key
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
401 KEY_INACTIVE The API key is inactive or revoked
403 SCOPE_DENIED The key is missing the telephony scope
422 BITRIX_ERROR Bitrix24 returned an error (text in error.message)
429 RATE_LIMITED Request limit exceeded
502 BITRIX_UNAVAILABLE Bitrix24 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