Canal WhatsApp

Como funciona

O Planoit não fala o protocolo WhatsApp diretamente — ele chama a API do Intera, a plataforma de atendimento WhatsApp da aviait, autenticado por token de integração. O Intera é quem mantém a sessão real com o WhatsApp (via Baileys, biblioteca não-oficial) e quem efetivamente envia a mensagem.

Mesmo modelo de credencial do Telegram: um número “notificações de sistema” default, compartilhado entre aplicações, mais a opção de uma aplicação usar um número próprio que já esteja conectado no Intera. O número default é dedicado só a notificações do Planoit — nunca um número operacional que já atende outro bot/CRM no Intera.

Este canal é disparo avulso (fire-and-forget), igual ao e-mail e ao Telegram: sem leitura de resposta, sem bot interativo, sem suporte a grupos — só mensagem de texto para um número de telefone.

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": "whatsapp",
    "templateSlug": "boas-vindas-whatsapp",
    "recipient": "+5511999999999",
    "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 `"whatsapp"`.
`templateSlug`	sim	Slug do template cadastrado para `channel='whatsapp'`. Mesma resolução aplicação→global do e-mail.
`recipient`	sim	Telefone em E.164, com o `+` obrigatório (ex.: `"+5511999999999"`). Sem o `+`, a validação falha.
`payload`	não	Variáveis do template. O texto é renderizado como texto puro — sem formatação WhatsApp (negrito/itálico via `*`/`_`), sem Markdown.

Não há senderId neste canal — quem envia é sempre o número conectado no Intera (default da plataforma ou override da aplicação), não um remetente verificado como o e-mail.

Credencial do canal

Por padrão, toda aplicação usa o número default da aviait. Um administrador pode cadastrar um número próprio (já conectado e delegado no Intera) 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/whatsapp`	Define o token de integração + `instance_id` do Intera default da plataforma.
`PUT /admin/applications/:id/channel-credentials/whatsapp`	Define um token + `instance_id` específico para uma aplicação.
`DELETE /admin/applications/:id/channel-credentials/whatsapp`	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).

O corpo de PUT recebe credential (o token de integração emitido pelo Intera) e externalRef (o instance_id da instância WhatsApp delegada — diferente do Telegram, este campo é obrigatório para o canal funcionar, já que um token de integração do Intera pode ter acesso a mais de uma instância).

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 número 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

Formato do destinatário: só E.164 com + é aceito — "5511999999999" (sem +) ou formatos locais ("(11) 99999-9999") falham com 422 VALIDATION_ERROR antes mesmo de chegar ao Intera.
Sem confirmação síncrona de entrega: a resposta 202 confirma só que a mensagem foi aceita pelo Intera, não que o destinatário a recebeu de fato — mesmo modelo assíncrono dos outros canais.

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

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