> ## 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 mensagem no Telegram > Envia mensagem para um ou vários destinatários no Telegram. Escreva o texto na hora ou use um template. ## OpenAPI ````yaml /telegram-api/api-reference/openapi-telegram.json post /v1/telegram/messages openapi: 3.0.3 info: title: Notifique API — Telegram description: >- Envie mensagens Telegram e gerencie conexões. Autentique com `Authorization: Bearer sk_live_...` ou `x-api-key`. version: 1.0.0 servers: - url: https://api.notifique.dev description: Produção security: - ntfTgBearerAuth: [] - ntfTgApiKeyHeader: [] tags: - name: Mensagens description: Enviar e gerenciar mensagens - name: Instâncias description: Criar e conectar bots ou contas USER - name: Chats description: Listar chats paths: /v1/telegram/messages: post: tags: - Mensagens summary: Enviar mensagem no Telegram description: >- Envia mensagem para um ou vários destinatários no Telegram. Escreva o texto na hora ou use um template. 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: instanceId: inst_abc to: - '@usuario' type: TEXT payload: message: Olá! image: summary: Imagem value: instanceId: inst_abc to: - '@usuario' type: IMAGE payload: mediaUrl: https://example.com/image.jpg caption: Legenda video: summary: Vídeo value: instanceId: inst_abc to: - '@usuario' type: VIDEO payload: mediaUrl: https://example.com/video.mp4 document: summary: Documento value: instanceId: inst_abc to: - '@usuario' type: DOCUMENT payload: mediaUrl: https://example.com/file.pdf fileName: file.pdf location: summary: Localização value: instanceId: inst_abc to: - '@usuario' type: LOCATION payload: latitude: -23.55 longitude: -46.63 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 status: QUEUED scheduledAt: null '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 status: QUEUED scheduled: summary: Agendada value: success: true data: messageIds: - clxx_c status: SCHEDULED scheduledAt: '2026-04-15T10:00:00.000Z' '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 instâncias do plano ou instância 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: Instância 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: Não 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: - instanceId - to - type - payload properties: instanceId: type: string to: type: array items: type: string minItems: 1 maxItems: 100 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.) 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: url: type: string format: uri maxLength: 2048 secret: type: string description: Opcional. Segredo HMAC. 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`. NtfTg_SendTelegramMessageAccepted: type: object properties: success: type: boolean data: type: object properties: messageIds: type: array items: type: string status: type: string enum: - QUEUED - SCHEDULED scheduledAt: type: string nullable: true 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: >- Mensagem 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 [Respostas 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 securitySchemes: ntfTgBearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'Authorization: Bearer sk_live_xxxxx' ntfTgApiKeyHeader: type: apiKey in: header name: x-api-key ````