[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-chats\u002Ffiles\u002Ftranscribe":3,"docs-tabs-chats\u002Ffiles\u002Ftranscribe":6},{"content":4,"lastmod":5},"\n## Transcribe an audio file\n\n`POST \u002Fv1\u002Fchats\u002Ffiles\u002F:fileId\u002Ftranscribe`\n\nStarts 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.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `fileId` (path) | number | yes | Chat file ID. Get it: `files[].id` in [Load a chat](\u002Fdocs\u002Fchats\u002Fmessages\u002Fload) or in the [message history in the v2 mode](\u002Fdocs\u002Fchats\u002Fmessages\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|---------|\n| `messageId` | number | yes | ID of the message the file is attached to. Get it: `messages[].id` in [Load a chat](\u002Fdocs\u002Fchats\u002Fmessages\u002Fload) or in the [message history in the v2 mode](\u002Fdocs\u002Fchats\u002Fmessages\u002Flist) |\n| `requestId` | string | no | Attempt identifier in UUID format, generated by the app. Sent only together with `contentVersion` and only when [transcription settings](\u002Fdocs\u002Fchats\u002Ffiles\u002Ftranscribe-transcription-config) were retrieved successfully |\n| `contentVersion` | string | no | Expected file version from the file metadata: 1–128 visible ASCII characters, without spaces. Sent only together with `requestId` |\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Ffiles\u002F7701\u002Ftranscribe \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"messageId\": 1003}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Ffiles\u002F7701\u002Ftranscribe \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"messageId\": 1003}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Ffiles\u002F7701\u002Ftranscribe', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ messageId: 1003 }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('State:', data.status, data.transcriptText)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002Ffiles\u002F7701\u002Ftranscribe', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ messageId: 1003 }),\n})\n\nconst { success, data } = await res.json()\nconsole.log('State:', data.status, data.transcriptText)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data.fileId` | number | File ID |\n| `data.status` | string | Transcription state: `Pending` — the job is running, `Success` — the text is ready, `Error` — the transcription failed |\n| `data.transcriptText` | string\\|null | The transcript text. `null` while there is no text |\n| `data.chatId` | number | ID of the message's chat |\n| `data.messageId` | number | Message ID |\n| `data.contentVersion` | string | File version from the request |\n| `data.revision` | string | Job revision as a decimal string |\n| `data.operationId` | string | Transcription job ID |\n| `data.errorCode` | string\\|null | Transcription error code |\n| `data.retryable` | boolean | Whether the attempt can be retried |\n| `data.pendingForMs` | number\\|null | How many more milliseconds the job stays in the `Pending` state, from `0` to `300000`. `null` for a final result |\n\nThe fields from `data.chatId` to `data.pendingForMs` are returned only in response to a call with `requestId` and `contentVersion`.\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"fileId\": 7701,\n    \"status\": \"Pending\",\n    \"transcriptText\": null\n  }\n}\n```\n\n## Error response example\n\n422 — the file is neither audio nor video:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"FILE_NOT_TRANSCRIBABLE\",\n    \"b24Code\": \"FILE_NOT_TRANSCRIBABLE\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_PARAMS` | `fileId` is not a positive integer, `messageId` is missing or is not a positive integer, the body is not a JSON object, or an extra body field or a query parameter was sent. Checked before any call to Bitrix24 |\n| 400 | `INVALID_PARAMS` | `requestId` is not a UUID, `contentVersion` is not 1–128 visible ASCII characters, or one of these fields was sent without the other. Checked before any call to Bitrix24 |\n| 404 | `ENTITY_NOT_FOUND` | Bitrix24 returned a \"not found\" error. The Bitrix24 code is in `error.b24Code` |\n| 422 | `BITRIX_ERROR` | `error.b24Code` = `100` — there is no file with this `fileId` |\n| 422 | `BITRIX_ERROR` | `error.b24Code` = `FILE_NOT_TRANSCRIBABLE` — the file is neither audio nor video |\n| 422 | `BITRIX_ERROR` | `error.b24Code` = `FILE_SIZE_EXCEEDED` — the file is larger than 25 MB |\n| 422 | `BITRIX_ERROR` | `error.b24Code` = `TRANSCRIPTION_NOT_ACTIVE` — transcription is turned off in the Bitrix24 account |\n| 422 | `BITRIX_ERROR` | `error.b24Code` = `LIMIT_IS_EXCEEDED_BAAS` — the AI request limit is used up |\n| 422 | `BITRIX_ERROR` | `error.b24Code` = `TRANSCRIPTION_SERVICE_ERROR` — the transcription service failed |\n| 422 | `BITRIX_ERROR` | `error.b24Code` = `FILE_ACCESS_ERROR` — no access to the file |\n| 422 | `BITRIX_ERROR` | Another Bitrix24 refusal. The Bitrix24 code is in `error.b24Code` |\n| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only. Checked before any call to Bitrix24 |\n| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |\n\nThe full list of general API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**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.\n\n**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.\n\n**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.\n\n**No automatic retries.** The call reaches Bitrix24 exactly once and does not retry the request on its own.\n\n## See also\n\n- [Get transcription settings](\u002Fdocs\u002Fchats\u002Ffiles\u002Ftranscribe-transcription-config)\n- [Chat files](\u002Fdocs\u002Fchats\u002Ffiles)\n- [Load a chat](\u002Fdocs\u002Fchats\u002Fmessages\u002Fload)\n- [Save files to Drive](\u002Fdocs\u002Fchats\u002Ffiles\u002Fsave)\n","2026-11-05",{},1794739537536]