Como disparar um flow de whatsapp a partir de um webhook

Este documento descreve como o sistema recebe o webhook de WhatsApp Flows e como enviar dados para matricular um novo contato em um fluxo automatizado.

Importante: O webhook de flows serve para disparar a automação a partir de sistemas externos (CRM, RD Station, integrações próprias, etc.).

Pré-requisitos

1. Conta com a funcionalidade WhatsApp Flows habilitada.
2. Configurar um fluxo de disparo de templates de Whatsapp, tutorial aqui.
3. Fluxo ativo e com pelo menos uma etapa configurada.
4. Telefone presente e válido após normalização (obrigatório para WhatsApp).

Se o fluxo estiver em rascunho mas já tiver etapas, o backend pode ativar o fluxo automaticamente na primeira chamada bem-sucedida.

Onde isso aparece na interface

Na tela do fluxo, o cartão exibe o nome, a descrição, métricas (inscrições, conclusões), canal Whatsapp, gatilho Webhook e o URL do webhook que você deve configurar no sistema de origem.

Exemplo ilustrativo (tela acima):

O {flow_id} é o identificador numérico do fluxo (no exemplo da URL visível, 4). O {token} é um segredo gerado automaticamente — não compartilhe publicamente; use apenas em integrações confiáveis.

Endpoint HTTP

Autenticação

O token do path deve coincidir com o token armazenado no fluxo. Também é aceito:

• query string: ?token=...
• header: X-Webhook-Token: ...

Requisições sem token válido recebem 401 Unauthorized.

Formato do corpo (Content-Type)

Formatos suportados:

• application/json (recomendado)
• application/x-www-form-urlencoded
• multipart/form-data

Outros tipos podem ser interpretados como JSON no corpo bruto.

Parâmetros internos flow_id e token não entram na “carga útil” de negócio — o restante do JSON vira o payload processado.

Formato Standard (recomendado para APIs próprias)

Telefone (obrigatório)

Um dos campos (raiz do JSON):

phone, phone_number, phoneNumber, mobile, whatsapp, customer_phone, entre outros definidos no StandardProcessor.

Nome (opcional)

Ex.: name, full_name, first_name + last_name, customer_name, etc.

E-mail (opcional)

Ex.: email, email_address, contact_email, etc.

Status inicial do enrollment (opcional)

initial_status, status, enrollment_status — padrão active.

Demais campos

Qualquer outra chave no nível raiz vira atributo adicional do contato (exceto as chaves reservadas listadas no processador).

Exemplo mínimo

{

"phone": "5511999998888",

"name": "Maria Silva",

"email": "maria@example.com"

}

Exemplo com curl

Use o URL completo copiado do painel do fluxo (flow_id + token no path). Exemplo real de chamada ao fluxo 13 em atendimento.leadster.com.br:

curl -sS -X POST \

'https://atendimento.leadster.com.br/webhooks/whatsapp_flows/0/BgqJiSpnpudRytWgTgP1ArGiyKyTVXl-JGOpwCO68Px' \

-H 'Content-Type: application/json' \

-d '{

"phone": "5511999998888",

"name": "João Teste",

"email": "joao@example.com"

}'

Respostas observadas na prática

Os valores de enrollment_id e contact_id mudam a cada matrícula. Garanta que o fluxo esteja ativo no painel antes de integrar; caso contrário corrija o status e tente de novo.

Segurança: o token no URL é secreto. Não versione tokens reais em repositórios públicos; prefira variáveis de ambiente ou segredos no CI. Se o token vazar, use regenerar token no fluxo e atualize a URL nas integrações.

Normalização de telefone

• Aceita números com ou sem +.
• Números locais curtos podem receber DDI conforme configuração do fluxo (default_country_dial_code / default_country_code) ou heurísticas da inbox/conta.

Variáveis de webhook → atributos customizados

No webhook_config do fluxo é possível listar webhook_variables. Os valores são preenchidos a partir do payload ou dos atributos adicionais normalizados e ficam disponíveis para templates (Liquid) nas etapas, truncados a 255 caracteres.

Respostas da API

Sucesso — 200 OK

{

"success": true,

"message": "Contact enrolled successfully",

"enrollment_id": 123,

"contact_id": 456

}

(enrollment_id e contact_id são os IDs reais na sua conta.)

Erros comuns

Checklist rápido para integrar

1. Copiar o URL do Webhook da tela do fluxo (ou montar com flow_id + token válido).
2. Configurar o sistema de origem para enviar POST com Content-Type: application/json.
3. Incluir pelo menos o telefone no corpo, no formato aceito pelo processador (Standard ou o detectado).
4. Tratar 200 com success: true e guardar enrollment_id / contact_id se necessário para auditoria.