WhatsApp no Dify pela API oficial, com o ZapClaw

Em resumo: o ZapClaw envia cada mensagem do WhatsApp a um Webhook Trigger num workflow do Dify. O workflow lê a mensagem, consulta o seu modelo num nó LLM e responde com um HTTP Request. As mensagens passam pela API Cloud oficial da Meta, e o número continua funcionando no app WhatsApp Business do celular. Sem servidor intermediário e sem app próprio na Meta.

Conecte o seu número em minutos e dê um número de WhatsApp ao seu app do Dify, no Dify Cloud ou na sua própria instalação.

Plano Business: R$ 99 por mês, com números ilimitados

Comece grátis Ver os passos

O que você precisa para conectar

Não precisa de CNPJ nem de empresa verificada para conectar. A lista completa.

Por que a API oficial para um app do Dify

Por que um Webhook Trigger, e não a API do Dify

O Dify também roda um workflow pela API do app (POST /v1/workflows/run), mas essa chamada exige um cabeçalho Authorization: Bearer com a chave de API do app. Um webhook do ZapClaw só envia os próprios cabeçalhos, então não consegue chamar essa API diretamente. O Webhook Trigger aceita uma requisição HTTP simples, que é exatamente o que o ZapClaw envia. Se você já tem um servidor entre o ZapClaw e o Dify, esse servidor pode chamar a API do app.

Os triggers só rodam em apps do tipo Workflow, não em apps Chatflow ou Agent. Um Dify self-hosted tem triggers desde a versão 1.10.0, lançada em novembro de 2025; numa instalação mais antiga, atualize antes.

Configure em seis passos

  1. No Dify, crie um app do tipo Workflow. No canvas, clique com o botão direito e escolha Add Node > Start > Webhook Trigger. Defina o método como POST e o content type como application/json.
  2. Adicione três parâmetros do corpo da requisição, todos opcionais: event como String, data como Object e account como Object. Os nomes precisam ser iguais às chaves do ZapClaw. Um parâmetro obrigatório que falte impede o workflow de começar, e o evento de teste do painel não traz account.
  3. Depois do trigger, adicione nesta ordem: um nó Code que lê a mensagem, um If-Else que só segue quando text não está vazio, um nó LLM que escreve a resposta, um segundo nó Code que monta o corpo do envio e um HTTP Request que o envia. A configuração de cada um está abaixo.
  4. No ZapClaw, conecte o seu número, crie uma chave de API e cole a URL de teste do trigger em Webhook. Em Eventos a receber, deixe marcado só Mensagens recebidas: senão cada status de entrega iniciaria uma execução, e no Dify Cloud cada execução conta na cota de triggers. No Dify, clique em Run this step no trigger e mande uma mensagem de WhatsApp para o seu número de outro celular. A aba Last Run do trigger mostra o que chegou.
  5. Publique o workflow e, no ZapClaw, troque a URL de teste pela URL de webhook do trigger.
  6. Mande outra mensagem de WhatsApp do outro celular: o workflow responde.

Os dois nós Code

Os dois rodam Python. No primeiro, ligue as variáveis de entrada event, data e account às saídas do trigger e declare três saídas String: sender, customer e text. Tudo o que não for um texto recebido deixa text vazio, então atualizações de status e o evento de teste param no If-Else e as suas próprias respostas nunca entram em loop.

def main(event: str, data: dict, account: dict) -> dict:
    data = data or {}
    account = account or {}
    text = ""
    if event == "message.received" and data.get("type") == "text":
        text = (data.get("text") or {}).get("body") or ""
    return {
        "sender": str(account.get("display_phone_number") or account.get("phone_number_id") or ""),
        "customer": str(data.get("from") or data.get("user_id") or ""),
        "text": text,
    }

No nó LLM, escolha o seu modelo, escreva as instruções no prompt de sistema e coloque o text do primeiro nó Code no prompt do usuário. No segundo nó Code, ligue sender e customer ao primeiro e reply à saída text do nó LLM, e declare uma saída Object, body. Montado em código, o corpo continua sendo JSON válido, sejam quais forem as aspas ou quebras de linha que o modelo escrever.

def main(sender: str, customer: str, reply: str) -> dict:
    return {
        "body": {"from": sender, "to": customer, "text": reply},
    }

Para provar a ida e a volta antes de configurar um modelo, ligue reply ao text do primeiro nó Code: o workflow responde com o mesmo texto que recebeu.

O nó HTTP Request

Texto livre funciona dentro de 24 horas desde a última mensagem do cliente. Fora dessa janela, a Meta só aceita um template aprovado: chame POST /api/v1/send/template.

Para testar a sua chave antes de montar o workflow, faça a mesma chamada num terminal. Uma mensagem enviada responde 201.

curl -X POST https://api.zapclaw.app/api/v1/send/text \
  -H "X-API-Key: zc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "from": "15551617409", "to": "15555550100", "text": "Hello from Dify" }'

O que chega no Webhook Trigger

Cada mensagem chega como um evento message.received, e o trigger entrega ao workflow as suas três chaves de primeiro nível: event, data com a mensagem (o texto em data.text.body, o remetente em data.from, o nome do contato em data.contact_name) e account com o seu número. Uma mensagem de mídia traz uma media_url que você baixa com a sua chave de API.

{
  "event": "message.received",
  "sequence": 1042,
  "timestamp": "2026-05-21T14:00:00.000Z",
  "data": {
    "from": "15555550100",
    "user_id": "US.1A2B3C4D5E6F7G8H9I0J",
    "contact_name": "Maria Silva",
    "contact_username": "maria_lima",
    "message_id": "wamid.HBg...",
    "type": "text",
    "timestamp": "1747836000",
    "text": { "body": "Hello" }
  },
  "account": {
    "phone_number_id": "964283400112599",
    "display_name": "My Business",
    "display_phone_number": "+1 555 161-7409"
  }
}

Toda requisição traz um cabeçalho X-ZapClaw-Signature, um HMAC-SHA256 do corpo bruto feito com a sua chave de assinatura: como verificar (em inglês). O Webhook Trigger do Dify extrai campos e cabeçalhos, mas não documenta um jeito de ler o corpo bruto que a assinatura cobre, então guarde a URL do trigger só para você, como uma senha.

Bom saber

Quanto custa

A Meta cobra as tarifas de mensagem do WhatsApp direto de você, sem margem do ZapClaw. Todos os planos e preços.

Para quem é

Equipes que montam a sua IA no Dify e querem levá-la ao WhatsApp: respostas a partir de uma base de conhecimento, qualificação de leads, primeiro atendimento. Agências conectam os números dos clientes no plano Agency, cada cliente isolado dos outros. Não serve para disparo em massa.

Para ir além

Fontes

Verificado em 15 de outubro de 2026. O Dify muda rápido, então, se uma configuração parecer diferente, confira a fonte. As fontes estão em inglês.

Coloque o seu app do Dify no WhatsApp hoje

Comece no plano grátis: um número, sem cartão. Passe para o plano Business quando precisar de mais números ou de mais mensagens.

Comece grátis Ver a documentação do webhook (em inglês)