API de WhatsApp para Dify

O que dá para fazer com Dify e WhatsApp

• Atendimento de primeiro nível

  O agente responde dúvidas a partir da base de conhecimento e passa para uma pessoa quando não sabe.

• Triagem

  O agente entende o assunto da mensagem e encaminha para o setor certo.

• Assistente da equipe

  Quem trabalha na rua consulta procedimento, preço ou estoque pelo WhatsApp.

• Aviso escrito pelo agente

  Um workflow resume um documento ou um pedido e manda o resumo para quem precisa.

Enviar mensagens pelo Dify

1. 1

   Adicione o nó HTTP Request

   No workflow ou chatflow do Dify, coloque um nó HTTP Request depois do nó que gera o texto. Method POST, URL https://zapixo.com.br/api/v1/messages/text.

2. 2

   Headers e corpo

   Header Authorization com Bearer zpx_... e corpo em JSON. As variáveis do fluxo entram pelo seletor do próprio nó:

   {
     "instance": "ia-bot",
     "number": "<variável com o telefone>",
     "text": "<variável com a resposta do modelo>"
   }

3. 3

   Guarde a chave fora do fluxo

   App exportado ou compartilhado leva junto o que estiver escrito nos nós. Guarde a chave numa variável de ambiente do app, do tipo secreto, e use a variável no header.

Receber mensagens no Dify

1. 1

   Gere a chave de API do app

   Na tela do app no Dify, em Acesso à API, gere a chave. Ela é do app, não da conta: cada app tem a sua.

2. 2

   A ponte chama a API de chat

   A ponte recebe o messages.upsert do Zapixo, descarta fromMe e manda o texto ao Dify. user identifica quem fala e conversation_id mantém a memória da conversa. No Dify self-hosted, troque api.dify.ai pelo endereço da sua instância:

   const r = await fetch("https://api.dify.ai/v1/chat-messages", {
     method: "POST",
     headers: {
       Authorization: `Bearer ${process.env.DIFY_APP_KEY}`,
       "Content-Type": "application/json",
     },
     body: JSON.stringify({
       inputs: {},
       query: texto,
       response_mode: "blocking",
       conversation_id: conversas.get(numero) ?? "",
       user: numero,
     }),
   });
   
   const { answer, conversation_id } = await r.json();
   conversas.set(numero, conversation_id); // em produção, guarde no banco

3. 3

   Devolva pelo Zapixo

   Mande answer para o número com /api/v1/messages/text. Texto acima de 4.096 caracteres não passa na API: divida em partes antes de enviar.

Erros comuns e como resolver

Agente sem memória

Sem devolver o conversation_id, cada mensagem abre uma conversa nova no Dify e o agente esquece o que acabou de ouvir. Guarde um por número.

Resposta em dobro

Modelo leva segundos para responder. Se a ponte só devolver 2xx ao Zapixo depois do Dify, passa dos 10 segundos e o Zapixo tenta de novo — o agente responde duas vezes. Responda o webhook na hora, processe depois e ignore data.key.id repetido.

Mensagem longa recusada

Acima de 4.096 caracteres a API responde 400 com Validation failed. Divida o texto, ou peça ao modelo respostas curtas na instrução.

Formatação estranha no WhatsApp

O WhatsApp não mostra título nem tabela em Markdown como o chat do Dify: vira símbolo solto. Peça texto corrido e curto na instrução do agente.

Custo que dispara

Cada mensagem recebida é uma chamada ao modelo. Descarte grupo (@g.us) e fromMe antes de chamar o Dify, e limite quantas mensagens um número pode mandar por hora.

Perguntas frequentes