Como integrar a API oficial do WhatsApp com chatbots Appuni (e evitar loops infinitos de mensagens)

Em poucas palavras: ao integrar a API oficial do WhatsApp Cloud com chatbots da Appuni, é comum ver mensagens de boas-vindas repetindo sem parar. Aqui você aprende a: (1) usar GET para descobrir/validar IDs e templates, (2) montar o POST correto para envio do template e (3) configurar o fluxo para não criar loop infinito.

Quer uma solução completa de chatbot no WhatsApp? Conheça: https://winove.com.br/chat-whatsapp.

0) Pré-requisitos

Conta no Meta Business com WhatsApp Business Account (WABA) e número verificado.
Access Token válido (padrão Cloud API).
Template aprovado (APPROVED), ex.: modelo_boas_vindas.
Um fluxo no Appuni com etapa “Boas-vindas” chamando Webhook.

1) Antes do POST: usando GET para descobrir e validar informações

Vamos descobrir IDs corretos e conferir se o template existe e está aprovado. Use um REST client ou curl.

1.1 Descobrir o phone_number_id a partir do WABA

Endpoint: GET /{WABA_ID}/phone_numbers

curl -X GET \
  "https://graph.facebook.com/v23.0/<WABA_ID>/phone_numbers" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Você precisa do id que vem nessa resposta — ele é o phone_number_id usado no POST de envio.

1.2 Conferir os templates aprovados

Endpoint: GET /{WABA_ID}/message_templates

curl -X GET \
  "https://graph.facebook.com/v23.0/<WABA_ID>/message_templates?limit=50" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Procure pelo name e language do seu template (ex.: modelo_boas_vindas / pt_BR) e verifique status: "APPROVED".

1.3 (Opcional) Checar dados do número

Endpoint: GET /{phone_number_id}?fields=display_phone_number,verified_name,quality_rating

curl -X GET \
  "https://graph.facebook.com/v23.0/<PHONE_NUMBER_ID>?fields=display_phone_number,verified_name,quality_rating" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

2) Montando o POST de envio (template)

Endpoint: POST /{phone_number_id}/messages

Headers

Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

Body (usando a variável do Appuni para o número do remetente):

{
  "messaging_product": "whatsapp",
  "to": "{{contact_number}}",
  "type": "template",
  "template": {
    "name": "modelo_boas_vindas",
    "language": { "code": "pt_BR" }
  }
}

? Dica: Use {{contact_number}} para enviar a mensagem para o usuário que iniciou a conversa.

⚠️ Atenção: não envie para o próprio número comercial (o da WABA). A Cloud API rejeita (erro genérico (#100) Invalid parameter).

3) Evitando o loop infinito no Appuni

A) Gatilhar “Boas-vindas” apenas na primeira interação

Abra o nó Configurações.
Em Primeira interação, selecione a etapa Boas-vindas.
Remova a seta direta Início → Boas-vindas.

B) Ajustar “Mensagem não reconhecida”

Evite apontar para Boas-vindas; direcione para “Menu Principal” ou outra etapa.

C) Variável de controle (flag)

Se welcome_sent != '1' {
  Envia template (Webhook POST)
  welcome_sent = '1'     // escopo: contato; expiração: 24h (se disponível)
} Senão {
  Continua o fluxo normalmente (sem template)
}

4) Erros comuns e como corrigir

POST no endpoint errado (usando /{WABA_ID}/messages): use sempre /{PHONE_NUMBER_ID}/messages.
“Invalid parameter” (#100): geralmente é to igual ao seu próprio número ou template/idioma inexistente.
“Tried accessing nonexisting field (messages) on node type (WhatsAppBusinessPhoneNumber)”: confunda de ID (use o phone_number_id correto obtido no GET).

5) Resultado esperado

Primeira mensagem do cliente → recebe o template uma única vez.
Mensagens seguintes → fluxo normal, sem repetição.
Sem loops, sem spam, melhor experiência.

6) Conclusão

Usando GET para descobrir e validar phone_number_id e templates — e então construindo o POST correto no Appuni — você garante um disparo de boas-vindas impecável e sem loop. Controle de gatilhos e flags fecha o ciclo de forma profissional.

Quer acelerar esse setup com boas práticas? Veja nossa solução de chatbot: https://winove.com.br/chat-whatsapp.