Canal Telegram

Como funciona

O Planoit usa um bot próprio da aviait, compartilhado por padrão entre todas as aplicações. Uma aplicação que preferir um bot dedicado pode cadastrar o token do seu próprio bot — veja Credencial do canal abaixo.

Restrição real da Bot API do Telegram, não do Planoit: um bot não pode iniciar conversa com um usuário que nunca falou com ele. O destinatário precisa ter dado /start (ou qualquer mensagem) para o bot em algum momento antes da sua aplicação tentar enviar algo — não há como contornar isso. Descobrir o chat_id do destinatário também é responsabilidade de quem integra (normalmente capturado no primeiro contato, via um webhook próprio do seu fluxo de onboarding).

Este canal é disparo avulso (fire-and-forget), igual ao e-mail: sem leitura de resposta, sem bot interativo, sem suporte a grupos/canais — só chat 1:1 com um chat_id numérico conhecido.

Enviando uma mensagem

curl -X POST https://planoit.aviait.com.br/api/v1/messages \
  -H "Authorization: Bearer pln_prd_<key_id>_<secret>" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "telegram",
    "templateSlug": "boas-vindas-telegram",
    "recipient": "123456789",
    "payload": { "nome": "Maria" }
  }'

Resposta (202 Accepted):

{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "queued" }

Campos do corpo

Campo	Obrigatório	Descrição
`channel`	sim	Sempre `"telegram"`.
`templateSlug`	sim	Slug do template cadastrado para `channel='telegram'`. Mesma resolução aplicação→global do e-mail.
`recipient`	sim	O `chat_id` do destinatário, como string numérica (ex.: `"123456789"`). Aceita negativo (reservado para grupos — não suportado operacionalmente hoje).
`payload`	não	Variáveis do template. O texto é renderizado como texto puro — sem HTML, sem Markdown do Telegram (`parse_mode`). Caracteres como `&`, `<`, `>` saem literalmente, sem escapar.

Não há senderId neste canal — Telegram não tem conceito de remetente verificado como o e-mail. O que existe é a credencial do bot, resolvida automaticamente (veja abaixo).

Credencial do canal

Por padrão, toda aplicação usa o bot default da aviait. Um administrador pode cadastrar um bot próprio para uma aplicação específica — quando existe um override, ele tem prioridade sobre o default, só para aquela aplicação.

Endpoint	O que faz
`PUT /admin/platform-channel-defaults/telegram`	Define o bot token default da plataforma (afeta toda aplicação sem override).
`PUT /admin/applications/:id/channel-credentials/telegram`	Define um bot token específico para uma aplicação.
`DELETE /admin/applications/:id/channel-credentials/telegram`	Remove o override — a aplicação volta a usar o default.
`GET /admin/channel-credentials/`	Lista o que está configurado (nunca devolve o token em claro).

Esses endpoints são administrativos (requerem sessão de admin, não API key de aplicação) — peça a um administrador da plataforma se sua aplicação precisar de um bot dedicado.

Se nenhuma credencial estiver configurada (nem override, nem default), o envio falha com 422 CHANNEL_NOT_CONFIGURED.

Limites e erros específicos deste canal

Limite de tamanho: 4096 caracteres por mensagem. Payload que gera texto maior falha permanentemente com message_too_long — o Planoit não trunca.
Rate limit: a Bot API aceita ~30 mensagens/segundo globais e recomenda no máximo 1 mensagem/segundo por chat_id — o worker do Planoit já respeita isso, não é necessário throttle do seu lado.
Destinatário nunca deu /start, ou bloqueou o bot depois: tratado como falha permanente (sem retry) nos dois casos, registrado internamente com o motivo blocked_or_never_started.

`code`	HTTP	Quando acontece
`CHANNEL_NOT_ENABLED`	422	O canal `telegram` não está habilitado neste ambiente (feature flag por ambiente).
`CHANNEL_NOT_CONFIGURED`	422	Nenhuma credencial de bot configurada (nem override, nem default).

Veja a referência completa de erros para os códigos comuns a todos os canais.