Como usar o Webhook de Contatos
Nível: Intermediário
Tempo de leitura: 6 min
Plano necessário: Todos os planos
O que é o Webhook de Contatos
O Webhook de Contatos é um endpoint HTTP que recebe dados de sistemas externos e os salva automaticamente nos campos personalizados dos seus contatos na Wevi.
Com isso, você consegue fazer o agente responder de forma personalizada usando dados que vivem no seu CRM, ERP ou qualquer outro sistema, sem precisar perguntar nada ao cliente durante a conversa.
Diferença em relação às ações do agente: As ações de agente são webhooks de saída: o agente coleta dados na conversa e envia para fora. O Webhook de Contatos é de entrada: um sistema externo envia dados para a Wevi antes ou durante a conversa.
Para que serve na prática
- Seu CRM envia o plano e o valor do contrato de cada cliente para a Wevi. O agente já sabe, sem perguntar, se o cliente é Pro ou Basic.
- Seu sistema de pedidos atualiza o status do último pedido do contato. O agente cita o número do pedido na saudação.
- Uma ferramenta de automação (n8n, Make, Zapier) enriquece o contato assim que ele preenche um formulário.
Como acessar o endpoint e o token
- No painel, vá em Conta e clique na aba Desenvolvedores
- Localize o bloco Webhook de Contatos
- Copie a URL do Endpoint e o Token
O token é permanente até você clicar em "Revogar e gerar novo token".
Formato da requisição
POST <endpoint>
Authorization: Bearer <token>
Content-Type: application/json
{
"email": "cliente@exemplo.com",
"fields": {
"plano": "pro",
"empresa": "Acme Ltda",
"ultimo_pedido": "PED-8821"
}
}
O contato é identificado pelo email ou pelo phone (formato internacional, ex: 5511999001122). Pelo menos um dos dois é obrigatório.
O objeto fields aceita pares chave/valor em texto. As chaves precisam estar cadastradas como Campos personalizados na sua organização: enviar uma chave não cadastrada retorna erro 400 e nenhum dado é gravado.
Como usar os dados no agente
Depois que os campos estão preenchidos, use {{contact.chave}} no system prompt do agente. A Wevi substitui o marcador pelo valor salvo no contato quando a conversa começa.
Exemplo de prompt:
Você é o assistente da Acme. O cliente que está falando com você é {{contact.nome}}
da empresa {{contact.empresa}}, no plano {{contact.plano}}.
Se o plano for "enterprise", ofereça suporte prioritário e mencione o gerente de conta.
Se for "basic", direcione para a central de autoatendimento antes de escalar.
Se o campo não estiver preenchido, o marcador é substituído por uma string vazia. Prefira prompts que funcionem mesmo com campos ausentes.
Como usar os campos em campanhas
Os mesmos campos personalizados ficam disponíveis como variáveis nas campanhas de WhatsApp. No formulário de campanha, ao configurar as variáveis do template, selecione "Campo do contato" e escolha o campo desejado na lista.
Isso permite campanhas como: "Olá {{contact_name}}, seu plano {{plano}} renova em {{data_renovacao}}."
Veja mais em: Como criar e gerenciar campanhas no WhatsApp →
Exemplo completo com n8n
- No n8n, adicione um nó HTTP Request após o evento que dispara a atualização (ex: "cliente fez login")
- Configure:
- Method: POST
- URL: cole o endpoint da Wevi
- Authentication: Generic Credential Type → Header Auth
- Name:
Authorization - Value:
Bearer <seu token>
- Name:
- Em Body, selecione JSON e monte o payload com os dados do contato
- Teste com um contato real e verifique em Contatos na Wevi se os campos foram atualizados
O mesmo padrão funciona em Make, Zapier, scripts Python ou qualquer ferramenta que suporte HTTP.
Importar contatos do CRM em lote
O endpoint aceita um contato por chamada. Para trazer toda a base do CRM:
- Exporte seus contatos como CSV ou use a API do CRM para listar todos
- Para cada contato, faça um POST com email/telefone + campos que quer trazer
- Se o contato já existe na Wevi, os campos são atualizados. Se não existe, é criado automaticamente
Exemplo em n8n: use um nó "Split In Batches" para iterar a lista e um nó "HTTP Request" para cada contato. Coloque um delay de 200ms entre as chamadas para respeitar o limite de velocidade.
Limites de velocidade
O endpoint aceita 300 chamadas por minuto por token. Ao ultrapassar, retorna 429 Too Many Requests com o header Retry-After indicando quantos segundos aguardar antes de tentar de novo.
{ "error": "Too many requests", "retry_after": 8 }
Para importações grandes, calcule o tempo esperado com base nesse limite:
| Base de contatos | Tempo estimado |
|---|---|
| 1.000 | ~4 min |
| 5.000 | ~17 min |
| 10.000 | ~34 min |
| 50.000 | ~2h 47min |
Campos que ainda não existem
Se você enviar uma chave em fields que ainda não foi cadastrada como campo personalizado da organização, o request inteiro retorna 400 e nenhum dado é gravado. A resposta lista as chaves desconhecidas:
{
"error": "unknown_fields",
"message": "Algumas chaves em 'fields' não estão cadastradas em Campos personalizados. Cadastre as chaves antes de enviar.",
"unknown_fields": ["plano", "categoria"]
}
Cadastre as chaves em Conta → Campos personalizados antes de chamar o endpoint. As chaves devem bater exatamente (case-sensitive, incluindo underscores).
Erros comuns
400 unknown_fields
Você enviou chaves em fields que não estão cadastradas em Conta → Campos personalizados. A resposta lista quais. Cadastre as chaves e tente de novo.
401 Unauthorized
Token ausente, inválido ou revogado. Copie um token novo em Conta → Desenvolvedores.
Campos chegam mas o marcador no prompt continua vazio
Verifique se a chave enviada em fields é idêntica à chave do campo personalizado cadastrado (incluindo letras minúsculas e underscores).
429 Too Many Requests
Limite de 300 chamadas por minuto atingido. Leia o campo retry_after na resposta e aguarde esse número de segundos antes de continuar.