Depois que você chama POST /v1/telegram/messages, o registro vive na tabela dedicada de outbound Telegram. O campo status (e às vezes sentAt, deliveredAt, readAt) conta a história do envio.
Status de processamento
Estes são os estados mais importantes do pipeline de envio:
| Status | O que significa |
|---|
QUEUED | Aceitamos o pedido; a mensagem está na fila Redis (ou aguardando janela de envio / rate limit) para o worker processar. |
SCHEDULED | Agendada para o futuro (schedule.sendAt); ainda não entrou na mesma fila “imediata” que QUEUED após o horário. |
PROCESSING | O worker pegou o job e está enviando ao Telegram (Bot API ou MTProto USER). |
SENT | O Telegram aceitou a mensagem do nosso lado (equivalente a “saiu para a rede” do provedor). |
FAILED | Esgotaram-se as retentativas ou o erro foi considerado permanente (ex.: bot bloqueado, chat inválido, 403). |
CANCELLED | Você cancelou a tempo (POST .../cancel) enquanto ainda era fila/agendamento — não foi entregue ao destino. |
Status de engajamento e edição
Depois do envio, outros valores podem aparecer conforme eventos reais:
| Status | O que significa |
|---|
DELIVERED | Indica entrega ao destinatário quando o produto/conector expõe esse passo (nem todo canal Telegram replica “entregue” como o WhatsApp). |
READ | Leitura registrada — em modo USER, pode haver sincronização MTProto; em bot, depende do que o Telegram expõe. |
RESPONDED | O destinatário respondeu (reply) a essa mensagem, quando o Notifique correlaciona entrada e saída. |
EDITED | O texto foi alterado via API de edição suportada. |
DELETED | A mensagem foi apagada no chat via API (quando permitido). |
Usuários podem desativar confirmações ou o Telegram pode não enviar todos os “acks” que você espera. SENT não garante que a pessoa leu.
Filas e prioridade
O Telegram usa filas Redis próprias (separadas do WhatsApp):
HIGH — fila de prioridade (processada antes da fila normal).- Realtime — classe de despacho “tempo real” quando aplicável ao payload.
- Padrão — fila principal de pendentes.
No corpo do envio, use algo como "options": { "priority": "high" } quando fizer sentido (OTP, alertas). Não abuse de prioridade alta para campanha em massa — prejudica confiabilidade e pode violar políticas da conta.
Retentativas e erros temporários
Se a rede oscila ou o Telegram responde com erro recuperável, o worker reenfileira com espera crescente (backoff em degraus de segundos até horas, conforme implementação). Se o erro for permanente (bloqueio, 400/403 claros, etc.), o status vai a FAILED e pode ser disparado telegram.failed.
Mensagens que morrem após todas as tentativas podem gerar rastro em dead letter interna para auditoria.
Webhooks
Para acompanhar sem polling:
telegram.sent, telegram.failed, telegram.cancelled, telegram.received, etc. — veja a tabela de eventos.
Próximos passos
