> ## Documentation Index > Fetch the complete documentation index at: https://docs.talqui.chat/llms.txt > Use this file to discover all available pages before exploring further. # Transcribe message > Transcreve o áudio de uma mensagem (`messageKey: 'audio'` ou `'voice'`) e grava o resultado em `messageValue.transcription`. Roda de forma **síncrona**: a resposta já traz a mensagem transcrita. Use o `POST` no mesmo path quando a transcrição puder ser processada em segundo plano — ele devolve 202 e o resultado chega pelo socket. Se a mensagem já possui `messageValue.transcription`, o endpoint devolve a mensagem imediatamente, sem rodar o motor novamente. O motor é escolhido pela env `MESSAGE_TRANSCRIBE_ENGINE` (`whisper` na nossa infra, ou `litellm-audio` / `litellm-chat` via LiteLLM). Em ambos os casos um evento `service:transcribe:processed` é emitido no socket do tenant. ## OpenAPI ````yaml /api/services-api.yaml put /v1/tenants/{tenantID}/messages/{messageID}/transcribe openapi: 3.0.3 info: description: >- Talqui is an omnichannel customer service platform that unifies conversations from WhatsApp, Instagram, Telegram, and many other channels into a single attendant panel, alongside a broader ecosystem of plugins and integrations. This API gives developers programmatic access to Talqui's services layer, exposing the operations needed to read and manage tenants, conversations, plugins, and related resources that power that platform. Authentication is available on behalf of an Operator (the default for this API), a Plugin Connection, or a Plugin — see the [Talqui authentication guide](https://docs.talqui.chat/guides/introduction/authentication/) for how each token is obtained and when to use it. Need help or have questions not covered here? Reach out to support@talqui.com. license: name: ISC url: https://opensource.org/license/isc-license-txt title: Talqui - Services API version: 0.65.0 servers: - description: Production url: https://services-api.talqui.chat security: [] tags: - name: Tenants - name: Settings - name: Analytics - name: Campaigns - name: Campaigns models - name: Contacts - name: Handoff links - name: Inboxes - name: Messages - name: Notifications - name: Sessions - name: Operators - name: Plugins - name: Setup - name: Uploads paths: /v1/tenants/{tenantID}/messages/{messageID}/transcribe: put: tags: - Messages summary: Transcribe message description: >- Transcreve o áudio de uma mensagem (`messageKey: 'audio'` ou `'voice'`) e grava o resultado em `messageValue.transcription`. Roda de forma **síncrona**: a resposta já traz a mensagem transcrita. Use o `POST` no mesmo path quando a transcrição puder ser processada em segundo plano — ele devolve 202 e o resultado chega pelo socket. Se a mensagem já possui `messageValue.transcription`, o endpoint devolve a mensagem imediatamente, sem rodar o motor novamente. O motor é escolhido pela env `MESSAGE_TRANSCRIBE_ENGINE` (`whisper` na nossa infra, ou `litellm-audio` / `litellm-chat` via LiteLLM). Em ambos os casos um evento `service:transcribe:processed` é emitido no socket do tenant. operationId: TranscribeMessageController parameters: - in: path name: tenantID required: true schema: description: The tenant the message belongs to. format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ type: string - in: path name: messageID required: true schema: description: The audio message to transcribe. format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ type: string requestBody: content: application/json: schema: properties: language: description: ISO-639-1 language hint for the engine (defaults to `pt`). maxLength: 5 minLength: 2 type: string type: object required: true responses: '200': content: application/json: schema: additionalProperties: false properties: message: additionalProperties: false description: The message with messageValue.transcription filled in. properties: campaignModelID: description: >- The campaign model this message originated from, if any. nullable: true type: string contactID: description: The contact this message belongs to. type: string createdAt: description: When this message was created. format: date-time type: string messageAutonomous: description: >- Whether this message was sent autonomously (by a bot/automation). type: boolean messageChannel: description: The channel this message was sent through. type: string messageDirection: description: Whether this message is inbound or outbound. type: string messageExternalID: description: Provider-side identifier for this message, if any. type: string messageFingerprint: description: Deduplication fingerprint for this message. type: string messageID: description: Unique identifier for this message. type: string messageKey: description: >- The message content type; `audio` or `voice` for the transcribe endpoints. type: string messageMeta: additionalProperties: {} description: Arbitrary metadata attached to the message. type: object messageStatus: description: Numeric status code for this message. type: number messageValue: additionalProperties: {} description: >- Message content, including `transcription` ({ locale, parts, text }) once transcribed. type: object operatorID: description: The operator who sent this message, if any. nullable: true type: string sessionID: description: The session this message belongs to. type: string tenantID: description: The tenant this message belongs to. type: string updatedAt: description: When this message was last updated. format: date-time type: string required: - messageID - tenantID - contactID - sessionID - operatorID - campaignModelID - messageAutonomous - messageChannel - messageDirection - messageKey - messageValue - messageMeta - messageStatus - messageFingerprint - createdAt - updatedAt type: object required: - message type: object description: Response for status 200. '400': content: application/json: schema: properties: errors: items: oneOf: - $ref: '#/components/schemas/MissingTenantIDError' - $ref: '#/components/schemas/MissingMessageIDError' - $ref: '#/components/schemas/RequestValidationError' - $ref: '#/components/schemas/InvalidProviderError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- MissingTenantIDError (error_code 1001): tenantID absent from the URL. | MissingMessageIDError (error_code 1069): messageID absent from the URL. | RequestValidationError (error_code 1002): params or body fail schema validation. | InvalidProviderError (error_code 1103): MESSAGE_TRANSCRIBE_ENGINE names an unknown engine. '401': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/UnauthorizedError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: 'UnauthorizedError (error_code 1003): missing/invalid operator token.' '403': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/ForbiddenError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: 'ForbiddenError (error_code 1004): operator token rejected upstream.' '404': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/MessageNotFoundError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- MessageNotFoundError (error_code 1068): messageID does not exist for this tenant (or is not an 'audio'/'voice' message). '422': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/MessageNotTranscribableError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- MessageNotTranscribableError (error_code 1820): the message carries no media address to transcribe. '500': content: application/json: schema: properties: errors: items: oneOf: - $ref: '#/components/schemas/MissingConfigurationError' - $ref: '#/components/schemas/UnknownError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- MissingConfigurationError (error_code 5001): the selected engine is not configured in this environment. | UnknownError (error_code 5999): Unexpected internal error not otherwise documented for this endpoint. '502': content: application/json: schema: properties: errors: items: $ref: '#/components/schemas/MessageTranscribeFailedError' maxItems: 1 minItems: 1 type: array required: - errors type: object description: >- MessageTranscribeFailedError (error_code 5015): the engine produced no usable transcription. security: - operatorAuth: [] components: schemas: MissingTenantIDError: additionalProperties: false properties: error: enum: - MissingTenantIDError type: string error_code: enum: - 1001 type: number message: example: tenantID is required. type: string statusCode: enum: - 400 type: number required: - statusCode - error - error_code - message type: object MissingMessageIDError: additionalProperties: false properties: error: enum: - MissingMessageIDError type: string error_code: enum: - 1069 type: number message: example: messageID is required. type: string statusCode: enum: - 400 type: number required: - statusCode - error - error_code - message type: object RequestValidationError: additionalProperties: false properties: error: enum: - RequestValidationError type: string error_code: enum: - 1002 type: number fields: items: additionalProperties: false properties: allowed: type: string field: type: string received: type: string required: - field - received - allowed type: object type: array message: example: Invalid request data. type: string statusCode: enum: - 400 type: number required: - statusCode - error - error_code - message - fields type: object InvalidProviderError: additionalProperties: false properties: error: enum: - InvalidProviderError type: string error_code: enum: - 1103 type: number message: example: Invalid or unsupported provider (check PLUGIN_URN). type: string statusCode: enum: - 400 type: number required: - statusCode - error - error_code - message type: object UnauthorizedError: additionalProperties: false properties: error: enum: - UnauthorizedError type: string error_code: enum: - 1003 type: number message: example: You are not authorized to perform this request. type: string statusCode: enum: - 401 type: number required: - statusCode - error - error_code - message type: object ForbiddenError: additionalProperties: false properties: error: enum: - ForbiddenError type: string error_code: enum: - 1004 type: number message: example: You do not have access to this resource. type: string statusCode: enum: - 403 type: number required: - statusCode - error - error_code - message type: object MessageNotFoundError: additionalProperties: false properties: error: enum: - MessageNotFoundError type: string error_code: enum: - 1068 type: number message: example: Message not found. type: string statusCode: enum: - 404 type: number required: - statusCode - error - error_code - message type: object MessageNotTranscribableError: additionalProperties: false properties: error: enum: - MessageNotTranscribableError type: string error_code: enum: - 1820 type: number message: example: Only audio messages with a media address can be transcribed. type: string statusCode: enum: - 422 type: number required: - statusCode - error - error_code - message type: object MissingConfigurationError: additionalProperties: false properties: error: enum: - MissingConfigurationError type: string error_code: enum: - 5001 type: number message: example: Required configuration is missing. type: string statusCode: enum: - 500 type: number required: - statusCode - error - error_code - message type: object UnknownError: additionalProperties: false properties: error: enum: - UnknownError type: string error_code: enum: - 5999 type: number message: example: For some unknown reason your request has not succeeded. type: string statusCode: enum: - 500 type: number required: - statusCode - error - error_code - message type: object MessageTranscribeFailedError: additionalProperties: false properties: error: enum: - MessageTranscribeFailedError type: string error_code: enum: - 5015 type: number message: example: Failed to transcribe the message audio. type: string statusCode: enum: - 502 type: number required: - statusCode - error - error_code - message type: object securitySchemes: operatorAuth: bearerFormat: JWT description: >- Behalf of an Operator (default). A JWT issued by Talqui Core when an operator signs in, scoped to every tenant that operator belongs to. Send as `Authorization: Bearer `. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.