> ## Documentation Index > Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt > Use this file to discover all available pages before exploring further. # Enviar mensaje en Telegram > Envía un mensaje a uno o más destinatarios en Telegram. Escribe el texto al momento o usa una plantilla. ## OpenAPI ````yaml /es/telegram-api/api-reference/openapi-telegram.json post /v1/telegram/messages openapi: 3.0.3 info: title: Notifique API — Telegram description: >- Envíe mensajes de Telegram y gestione conexiones. Autentíquese con `Authorization: Bearer sk_live_...` o `x-api-key`. version: 1.0.0 servers: - url: https://api.notifique.dev description: Producción security: - ntfTgBearerAuth: [] - ntfTgApiKeyHeader: [] tags: - name: Mensajes description: Enviar y gestionar mensajes - name: Instancias description: Crear y conectar bots o cuentas USER - name: Chats description: Listar chats paths: /v1/telegram/messages: post: tags: - Mensagens summary: Enviar mensaje en Telegram description: >- Envía un mensaje a uno o más destinatarios en Telegram. Escribe el texto al momento o usa una plantilla. operationId: ntfTg_postV1TelegramSend parameters: - name: Idempotency-Key in: header required: false schema: type: string - name: x-idempotency-key in: header required: false schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NtfTg_SendTelegramMessageRequest' examples: text: summary: Texto value: to: - '@usuario' type: text payload: message: Olá! from: inst_abc image: summary: Imagen value: to: - '@usuario' type: image payload: mediaUrl: https://example.com/image.jpg caption: Legenda mimetype: image/jpeg fileName: image.jpg from: inst_abc video: summary: Vídeo value: to: - '@usuario' type: video payload: mediaUrl: https://example.com/video.mp4 mimetype: video/mp4 fileName: video.mp4 from: inst_abc audio: summary: Audio value: to: - '@usuario' type: audio payload: mediaUrl: https://example.com/audio.mp3 mimetype: audio/mpeg fileName: audio.mp3 from: inst_abc document: summary: Documento value: to: - '@usuario' type: document payload: mediaUrl: https://example.com/file.pdf fileName: file.pdf mimetype: application/pdf from: inst_abc location: summary: Ubicación value: to: - '@usuario' type: location payload: latitude: -23.55 longitude: -46.63 from: inst_abc responses: '200': description: >- Mesmo corpo de sucesso de um envio anterior: você reutilizou `Idempotency-Key` ou `x-idempotency-key` e o servidor devolve o resultado já registrado (não duplica envio). content: application/json: schema: $ref: '#/components/schemas/NtfTg_SendTelegramMessageAccepted' example: success: true data: messageIds: - clxx_msg_1 count: 1 status: QUEUED scheduledAt: null sandbox: false '202': description: >- Aceito. `data.messageIds` lista os IDs internos; `status` é `QUEUED` (envio imediato na fila) ou `SCHEDULED` (com `scheduledAt` em ISO 8601 quando houver agendamento). content: application/json: schema: $ref: '#/components/schemas/NtfTg_SendTelegramMessageAccepted' examples: queued: summary: Na fila value: success: true data: messageIds: - clxx_a - clxx_b count: 2 status: QUEUED sandbox: false scheduled: summary: Programada value: success: true data: messageIds: - clxx_c count: 1 status: SCHEDULED scheduledAt: '2026-04-15T10:00:00.000Z' sandbox: false '400': description: >- Corpo inválido, tipo não suportado, validação de conteúdo ou regra de negócio. content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' example: success: false error: Bad Request message: Unsupported message type for this Telegram instance mode. code: TELEGRAM_TYPE_UNSUPPORTED '401': description: Chave ausente ou inválida. content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' example: success: false error: Unauthorized message: Invalid or missing API Key code: UNAUTHORIZED '402': description: >- Plano/créditos: workspace bloqueado, saldo insuficiente ou limite de gasto da chave. content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' examples: blocked: summary: Workspace value: success: false error: Payment Required message: Plan expired or suspended code: WORKSPACE_BLOCKED credits: summary: Créditos value: success: false error: Payment Required message: Insufficient credits. code: INSUFFICIENT_CREDITS keyLimit: summary: Limite da chave value: success: false error: Payment Required message: API key spend limit exceeded. code: API_KEY_SPEND_LIMIT_EXCEEDED '403': description: >- Sem escopo **telegram:send**, limite de instancias do plano ou instancia não permitida para esta chave. content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' examples: scope: value: success: false error: Forbidden message: 'Missing scope: telegram:send' code: FORBIDDEN instance: value: success: false error: Forbidden message: Access to this instance is not allowed by this API Key code: FORBIDDEN '404': description: Instancia inexistente ou não é Telegram. content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' example: success: false error: Not Found message: Instance not found code: NOT_FOUND '429': description: >- Limite de mensagens pendentes no canal Telegram para este workspace. Pode vir cabeçalho `Retry-After` (segundos) no aviso leve. content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' examples: soft: summary: Aviso (tente de novo em breve) value: success: false error: Too Many Requests message: Workspace backlog soft limit reached for Telegram. code: WORKSPACE_BACKLOG_SOFT_LIMIT hard: summary: Limite rígido value: success: false error: Too Many Requests message: Workspace backlog limit reached for Telegram. code: WORKSPACE_BACKLOG_LIMIT '503': description: No foi possível colocar o job na fila (tente de novo). content: application/json: schema: $ref: '#/components/schemas/NtfTg_ErrorResponse' example: success: false error: Service Unavailable message: Failed to enqueue message code: SERVICE_UNAVAILABLE components: schemas: NtfTg_SendTelegramMessageRequest: type: object required: - from - to - type - payload properties: to: type: array items: type: string minItems: 1 maxItems: 500 description: chat_id ou @username type: type: string enum: - text - image - video - audio - document - location - template payload: type: object description: >- Conforme `type` (message, mediaUrl, latitude/longitude, templateId/variables, etc.) properties: mediaUrl: type: string format: uri description: URL pública. Obrigatório para image, video, audio, document. fileName: type: string description: Nome do arquivo. Obrigatório para mídia. mimetype: type: string description: >- Mimetype (ex.: image/jpeg, audio/mpeg, application/pdf). Obrigatório para mídia. caption: type: string maxLength: 1024 description: Legenda opcional para mídia. latitude: type: number longitude: type: number name: type: string address: type: string templateId: type: string description: Obrigatório para type=template. variables: type: object additionalProperties: type: string description: Variáveis do template. buttons: type: array maxItems: 3 description: >- Botones inline URL (texto o media). Cada ítem: label (o displayText) y url HTTPS. items: type: object required: - label - url properties: label: type: string maxLength: 64 displayText: type: string description: Alias de label. message: type: string example: Olá! schedule: type: object properties: sendAt: type: string format: date-time options: type: object properties: priority: type: string enum: - high - normal - low description: >- `high` = fila Redis `queue:telegram:priority` e fila prioritária de webhooks. maxRetries: type: integer webhook: type: object description: >- Webhook só para este envio (eventos `telegram.*`). URL HTTPS pública. required: - url properties: secret: type: string description: Opcional. Segredo HMAC. autoReplyText: type: string maxLength: 4096 description: >- Texto enviado automáticamente (1×) cuando el destinatario responda. metadata: type: object additionalProperties: type: string description: >- Metadados em `TelegramOutboundMessage.metadata` (string→string). `priority` em `options` usa fila dedicada Telegram + fila prioritária de webhooks quando `high`. localization: type: object description: >- Tradução por destinatário (manual ou IA). Campos traduzíveis: payload.message, payload.caption. properties: mode: type: string enum: - 'off' - manual - ai default: 'off' description: >- off = sem tradução; manual = usa i18n; ai = traduz com IA conforme idioma do contato. sourceLocale: type: string description: 'Locale BCP-47 do texto base (ex.: pt-BR).' i18n: type: object additionalProperties: true description: >- Mapa locale → string ou objeto com chaves por campo (message, caption, …). Usado com localization.mode=manual. variables: type: object additionalProperties: type: string description: >- Variáveis para substituir placeholders {{chave}} em payload.message, payload.caption e options.autoReplyText. from: type: string description: 'Instância Telegram: id ou nome.' example: to: - '5511999999999' type: text payload: mediaUrl: https://example.com/resource fileName: string mimetype: string caption: string latitude: 1 longitude: 1 name: Exemplo address: string templateId: clxx... variables: {} buttons: - label: string displayText: string schedule: sendAt: '2025-02-10T14:00:00.000Z' options: priority: high maxRetries: 1 webhook: secret: string autoReplyText: string metadata: {} localization: mode: 'off' sourceLocale: string i18n: {} variables: {} from: clxx... NtfTg_SendTelegramMessageAccepted: type: object properties: success: type: boolean data: type: object additionalProperties: true example: messageIds: - clxx_msg_1 count: 1 status: QUEUED scheduledAt: null sandbox: false properties: messageIds: type: array items: type: string example: - clxx_a - clxx_b count: type: integer example: 2 status: type: string example: QUEUED sandbox: type: boolean example: false scheduledAt: type: string example: '2026-04-15T10:00:00.000Z' from: type: string description: 'Instância Telegram: id ou nome.' example: success: true required: - from NtfTg_ErrorResponse: type: object properties: success: type: boolean example: false error: type: string description: 'Rótulo HTTP do erro (ex.: Unauthorized, Bad Request, Not Found).' message: type: string description: >- Mensaje legível para exibir ao usuário (localizada via Accept-Language / x-locale quando aplicável). code: type: string description: >- Código estável da API v1 (enum). Sempre presente em erros. Use com o status HTTP para decidir retry ou correção. Ver [Respuestas de erro](/guides/conceitos/resposta-de-erros). details: type: array items: type: object properties: field: type: string message: type: string required: - success - error - message - code example: success: false error: string message: string code: string details: - field: string message: string securitySchemes: ntfTgBearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'Authorization: Bearer sk_live_xxxxx' ntfTgApiKeyHeader: type: apiKey in: header name: x-api-key ````