Transcribe an audio file

POST /v1/chats/files/:fileId/transcribe

Starts speech-to-text transcription of an audio or video file attached to a message — for example, a voice message or a video note. The transcription is done by CoPilot, the artificial intelligence (AI) of your Bitrix24 account. The call queues a job, and the text appears once the job finishes.

Parameters

Request fields (body)

Examples

curl — personal key

curl -X POST https://vibecode.bitrix24.com/v1/chats/files/7701/transcribe \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messageId": 1003}'

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/chats/files/7701/transcribe \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messageId": 1003}'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/files/7701/transcribe', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ messageId: 1003 }),
})

const { success, data } = await res.json()
console.log('State:', data.status, data.transcriptText)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/files/7701/transcribe', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ messageId: 1003 }),
})

const { success, data } = await res.json()
console.log('State:', data.status, data.transcriptText)

Response fields

The fields from data.chatId to data.pendingForMs are returned only in response to a call with requestId and contentVersion.

Response example

{
  "success": true,
  "data": {
    "fileId": 7701,
    "status": "Pending",
    "transcriptText": null
  }
}

Error response example

422 — the file is neither audio nor video:

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "FILE_NOT_TRANSCRIBABLE",
    "b24Code": "FILE_NOT_TRANSCRIBABLE"
  }
}

Errors

The full list of general API errors — Errors.

Known specifics

Counts against the AI request limit of your Bitrix24 account. A repeated call for the same file does not queue a new job: while the transcription runs, it returns Pending, afterwards Success with the text.

The call may add the user as a member. If the message's chat can be joined without an invitation — for example, a comment chat, a collab or a task chat — the call adds the current user as a member, just as opening the chat in the Bitrix24 interface does.

An attempt with the same requestId. A repeat with the same requestId within 24 hours does not queue a new job. A new manual attempt sends a new UUID: it joins the running job and, once the repeat window expires, may consume the AI request limit again.

No automatic retries. The call reaches Bitrix24 exactly once and does not retry the request on its own.

See also

• Get transcription settings
• Chat files
• Load a chat
• Save files to Drive