Receita de integração

WhatsApp + n8n: envie e receba WhatsApp nos seus fluxos de trabalho

Funciona hoje com o nó HTTP RequestÚltima verificação: outubro de 2026

O Spun tem uma REST API criada exatamente para esse tipo de automação, e o n8n não precisa de nada especial para usá-la: um nó “HTTP Request” com um token Bearer envia mensagens de WhatsApp, faz upload de mídia, cria e atualiza contatos, aplica etiquetas e verifica se um número está no WhatsApp. Um nó de gatilho “Webhook” recebe de volta os eventos reais do WhatsApp, assinados para que você possa comprovar que vieram do Spun.

Esta página é o caminho que funciona hoje, escrita a partir da API em produção e não de um roadmap. Quando algo ainda não é self-service, ela diz isso em vez de fingir o contrário.

1. Crie uma chave de API

  1. 1

    Abra “Chaves de API”

    Na sua caixa de entrada do Spun: “Configurações”, depois “Webhooks”, depois “Gerenciar Chaves da API” e depois “Nova Chave”.

  2. 2

    Dê um nome e escolha os escopos

    Dê um nome como “n8n Production”. Ative só o que o fluxo de trabalho precisa: “Send Messages” para texto e mídia, “Check Phone Numbers”, “Manage Contacts”, “Read Contacts”, “Manage Labels” e “Read Labels”. Cada endpoint abaixo informa o escopo que exige.

  3. 3

    Copie uma única vez

    A chave começa com wap_ e é exibida uma única vez. Guarde-a no n8n como credencial, nunca colada em um parâmetro de nó, onde ela acaba no log de execução.

  4. 4

    Opcional: restrinja a chave ao seu servidor n8n

    Um n8n auto-hospedado tem um IP de saída estável, o que torna uma chave de API muito mais segura do que o normal. Configure “IPs permitidos” na chave com o endereço de saída do seu n8n ou com uma faixa CIDR, e uma chave roubada fica inútil em qualquer outro lugar. Se deixar vazio, a chave funciona de qualquer lugar. Errar essa configuração nunca bloqueia o seu acesso às “Configurações”, que usam o seu login do Spun e não a chave.

No n8n, adicione a chave como credencial “Header Auth”: nome do cabeçalho Authorization, valor do cabeçalho Bearer wap_YOUR_KEY. Reutilize essa mesma credencial em todos os nós do Spun de todos os seus fluxos de trabalho.

2. Envie mensagens de WhatsApp a partir de um fluxo de trabalho

Adicione um nó “HTTP Request”, defina o método e a URL, anexe a credencial “Header Auth” e envie JSON. Todos os endpoints ficam sob a mesma URL base, https://api.spun.com/api/integrations.

  • send-message (escopo: “Send Messages”): uma mensagem de texto. Se o canal do WhatsApp estiver offline naquele momento, a API responde 202 com um queue_id em vez de falhar, e a mensagem sai quando o canal se reconecta.
  • send-media (“Send Messages”): uma imagem, um vídeo, um arquivo de áudio, uma mensagem de voz ou um documento, a partir de uma URL pública ou de um upload em base64, com legenda opcional em imagens, vídeos e documentos.
  • check-phone (“Check Phone Numbers”): informa se este número tem WhatsApp. Aceita até 20 números em uma única chamada, então agrupe em vez de percorrer um por um em loop.
  • create-contact e update-contact (“Manage Contacts”): mantenha o registro de um lead sincronizado a partir de um formulário, um CRM ou uma planilha. Informar um número de telefone atualiza o contato existente em vez de criar um duplicado.
  • contacts (“Read Contacts”): busque um contato por número de telefone ou por id.
  • apply-label e remove-label (“Manage Labels”): etiquete um chat a partir de um gatilho externo, por exemplo, aplique a etiqueta “Novo lead” a um chat no momento em que um formulário é enviado.
  • labels (“Read Labels”): lista as etiquetas da conta, que também é a forma mais barata de confirmar que uma chave funciona.
Enviar uma mensagem de WhatsApp (POST /api/integrations/send-message)
POST https://api.spun.com/api/integrations/send-message
Authorization: Bearer wap_YOUR_KEY
Content-Type: application/json

{
  "to": "15551234567",
  "text": "Hi {{ $json.first_name }}, thanks for getting in touch.",
  "idempotency_key": "{{ $execution.id }}"
}

Informe um idempotency_key nos envios e defina para ele um valor estável durante a execução, como {{ $execution.id }}. Se o n8n repetir o nó, o Spun reconhece a chave em vez de enviar a mensagem duas vezes.

3. Envie um arquivo, uma imagem ou uma mensagem de voz

A mídia vai para um endpoint separado. Informe exatamente um dos dois: media_url, que o Spun baixa, ou media_base64, que o Spun envia primeiro por você.

  • type é um destes valores: image, video, audio, voice ou document.
  • A legenda vai junto em image, video e document. Áudios e mensagens de voz não têm legenda no WhatsApp.
  • Uma mensagem de voz enviada em base64 é convertida automaticamente para o formato que o WhatsApp espera. Uma mensagem de voz passada como URL é enviada exatamente como está, então ela já precisa estar em ogg ou opus; caso contrário, envie em base64 e deixe o Spun converter.
  • A mídia, de propósito, não entra na fila quando o canal está offline. O texto entra na fila, mas a mídia responde 409 channel_offline, porque reenviar uma mensagem de mídia da fila a entregaria como texto. Trate o 409 com as novas tentativas do n8n em vez de tratá-lo como falha permanente.
Enviar um documento (POST /api/integrations/send-media)
POST https://api.spun.com/api/integrations/send-media
Authorization: Bearer wap_YOUR_KEY
Content-Type: application/json

{
  "type": "document",
  "to": "15551234567",
  "media_url": "https://example.com/invoice-1043.pdf",
  "filename": "invoice-1043.pdf",
  "caption": "Your invoice"
}

4. Dispare um fluxo de trabalho com um evento do WhatsApp

  1. 1

    Crie primeiro o nó Webhook

    Adicione um nó de gatilho “Webhook” a um novo fluxo de trabalho e copie a “Production URL” dele. O n8n só atende essa URL enquanto o fluxo de trabalho está ativo, então ative-o antes de testar.

  2. 2

    Cole a URL no Spun

    “Configurações”, depois “Webhooks”, depois “Adicionar Webhook”. Cole a URL do n8n, escolha quais eventos devem dispará-lo e salve. O Spun assina cada entrega com o segredo exibido para essa assinatura de eventos.

  3. 3

    Envie uma mensagem de teste

    Mande uma mensagem do seu celular para o número de WhatsApp conectado. O nó Webhook recebe o payload real, que é o exemplo a partir do qual você monta o resto do fluxo de trabalho.

  • Eventos que você pode assinar: mensagem recebida, mensagem enviada, contato criado, contato atualizado, contato excluído, etiqueta atribuída, fluxo de chat concluído, mensagem da fila processada, lead qualificado, chat arquivado e ligação concluída.
  • X-Webhook-Signature é um HMAC-SHA256 do corpo bruto exato da solicitação, escrito como sha256 seguido do digest em hexadecimal. Verifique-o contra os bytes do corpo bruto, não contra uma cópia reserializada do JSON já interpretado, porque não há garantia de que a ordem das chaves sobreviva a uma interpretação e a uma nova codificação.
  • Uma entrega é repetida até três vezes, imediatamente, depois de 5 segundos e depois de 30 segundos, e cada tentativa espera 10 segundos por uma resposta. Qualquer 2xx conta como entregue.
  • Por causa dessas novas tentativas, o mesmo evento pode chegar duas vezes. O event_id continua igual entre as novas tentativas de um mesmo evento, então use-o para ignorar duplicados.
O que o Spun publica em message.inbound
POST https://your-n8n.example.com/webhook/abc123
X-Webhook-Event: message.inbound
X-Webhook-Delivery: 550e8400-e29b-41d4-a716-446655440000
X-Webhook-Signature: sha256=<hmac of the raw body>

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "message.inbound",
  "timestamp": "2026-08-18T10:30:00.000Z",
  "org_id": "123",
  "data": {
    "message_id": "[email protected]_ABC123",
    "chat_id": "[email protected]",
    "from": "15551234567",
    "type": "text",
    "text": "Hello!"
  }
}

Verificar a assinatura importa mais do que parece: a URL do webhook é a única coisa que protege o fluxo de trabalho, e as URLs de webhook do n8n são fáceis o bastante de adivinhar para valer a pena verificar a assinatura.

O payload do webhook do WhatsApp, campo por campo

Os eventos de mensagem trazem o que um fluxo de trabalho normalmente teria que descobrir sozinho. O número do cliente chega pronto para usar no formato internacional, os grupos vêm sinalizados, o nome e o e-mail do contato do Spun vêm junto quando o Spun os tem, e a mídia chega como um link assinado que o seu fluxo de trabalho pode baixar por 24 horas.

  • peer_phone_e164 é null para grupos e para chats sem um número de telefone por trás.
  • Quando um arquivo ainda não terminou de ser processado no momento em que o evento é enviado, media_pending é true e media_url é null. O evento não é enviado de novo quando o arquivo fica pronto, então adicione uma nota apontando para a conversa no Spun.
  • conversation.closed é disparado quando um chat é arquivado no Spun e conversation.reopened quando ele é recuperado, e é assim que um fluxo de trabalho mantém um ticket ou um registro em sincronia com a caixa de entrada.
  • Fechar ou reabrir uma conversa a partir do seu fluxo de trabalho passa por POST /api/integrations/conversations/close e /reopen, que exigem o escopo “Fechar e Reabrir Conversas” na chave.
Campos extras em message.inbound e message.outbound (ilustrativo)
{
  "is_group": false,
  "peer_phone_e164": "+15551234567",
  "contact_id": "8812",
  "contact_name": "Sarah Miller",
  "contact_email": "[email protected]",
  "type": "image",
  "text": null,
  "caption": "The damaged box",
  "media_url": "https://<signed link, valid for 24 hours>",
  "media_mime": "image/jpeg",
  "media_filename": null,
  "media_size": 182344,
  "media_pending": false
}

Relacionado: Documentação: cada evento e campo, com detalhes de assinatura e novas tentativas

Fluxos de trabalho prontos para help desks

Os mesmos webhooks e a mesma API alimentam fluxos de trabalho do n8n prontos que transformam conversas do WhatsApp em tickets do help desk e enviam as respostas dos agentes de volta ao WhatsApp. Cada um vem com um guia de configuração.

Relacionado: Todas as integrações do WhatsApp com help desks · Zendesk · Zoho Desk · Freshdesk · HubSpot Service Hub · Jira Service Management

5. A descrição completa da API

A descrição completa da API, legível por máquina, é publicada como um documento OpenAPI 3.1, de acesso livre e sem precisar de chave de API. Ela inclui cada endpoint, cada campo de solicitação, o formato de cada resposta, cada código de erro e o envelope do webhook, o que costuma ser mais rápido do que ler um guia.

Especificação pública OpenAPI 3.1
curl https://api.spun.com/api/integrations/openapi.json

O n8n pode importar uma descrição OpenAPI diretamente ao gerar um nó personalizado ou um nó HTTP declarativo, então este é o caminho mais curto do zero até um conjunto de operações que funciona.

Um nó nativo do Spun para o n8n

Tudo acima usa o nó genérico “HTTP Request”, e é por isso que funciona hoje, sem espera. Um nó comunitário dedicado do Spun já foi construído e está em processo de publicação: ele transforma os mesmos endpoints em operações nomeadas com campos adequados, adiciona uma credencial do Spun com teste de conexão embutido e dá ao lado do gatilho um nó que se inscreve e cancela a inscrição sozinho quando você ativa ou desativa o fluxo de trabalho, verificando a assinatura de cada entrega por você.

Ele ainda não está no registro de nós comunitários do n8n, então no momento não há nada para instalar, e esta página não finge o contrário. Duas capacidades chegam com ele: o gatilho que se inscreve sozinho e a consulta periódica do histórico de mensagens em um agendamento, para o caso em que uma instância do n8n não consegue receber webhooks de entrada de jeito nenhum. As duas dependem de permissões de chave de API que ainda não são oferecidas no editor de chaves, por isso são descritas aqui em vez de passadas como instruções.

Até ele ser listado, o caminho com “HTTP Request” desta página é a forma suportada de usar o Spun com o n8n, e continua suportada depois.

O que saber antes de construir em cima disso

  • O limite é de 60 solicitações por minuto por chave de API, somando todos os endpoints. Agrupe as verificações de números em até 20 por chamada e coloque um nó “Wait” dentro de qualquer loop que se espalhe por uma lista grande.
  • remove-label exige o id da etiqueta, ao contrário de apply-label, que também aceita o nome da etiqueta. Chame o endpoint labels uma vez no início do fluxo de trabalho e guarde os ids.
  • Hoje as assinaturas de webhook são criadas dentro das “Configurações” do Spun. Uma ferramenta de fluxos de trabalho ainda não consegue criar a própria assinatura com uma chave que você possa gerar no editor de chaves.
  • É uma API baseada em chaves. Ela não tem uma tela de OAuth “connect your Spun account”, e isso é proposital: as conexões de assistentes de IA usam um mecanismo separado, baseado em consentimento, e chaves separadas, e os dois não podem ser misturados em uma mesma chave.
  • Tudo fica restrito ao número de WhatsApp ao qual a chave pertence. Uma conta com vários números tem uma chave por número, e não uma única chave que abranja todos eles.

Relacionado: WhatsApp + Zapier e Make · WhatsApp + Google Sheets (totalmente nativa, sem chave de API) · WhatsApp + HubSpot CRM

Perguntas frequentes

Preciso esperar um nó oficial do Spun para usar o n8n?

Não. O nó “HTTP Request” cobre todas as ações hoje: envio de texto e mídia, contatos, etiquetas e verificação de números, com um nó de gatilho “Webhook” para os eventos recebidos. Um nó nativo está sendo publicado para facilitar a configuração dessas mesmas coisas, não para torná-las possíveis.

Existe um nó do Spun no registro comunitário do n8n?

Ainda não. O pacote está construído, mas não listado, então no momento não há nada para instalar. A configuração com “HTTP Request” desta página funciona agora e continua funcionando depois que o nó for listado.

Como faço a autenticação?

Crie uma chave de API em “Configurações”, depois “Webhooks”, depois “Gerenciar Chaves da API”, ative só os escopos de que você precisa e guarde-a no n8n como credencial “Header Auth” que envia Authorization: Bearer wap_YOUR_KEY. Você também pode restringir a chave ao endereço IP ou à faixa do seu servidor n8n.

Como evito que as novas tentativas do n8n enviem a mesma mensagem de WhatsApp duas vezes?

Envie um idempotency_key com a solicitação e mantenha-o estável durante a execução, por exemplo o id de execução do n8n. O Spun reconhece uma chave repetida e devolve o resultado original em vez de enviar de novo.

Como verifico se um webhook realmente veio do Spun?

Cada entrega traz X-Webhook-Signature, um HMAC-SHA256 do corpo bruto exato calculado com o segredo da assinatura de eventos, no formato sha256 seguido do digest em hexadecimal. Calcule o mesmo HMAC sobre o corpo bruto da solicitação e compare. Use os bytes brutos em vez de recodificar o JSON já interpretado, porque a ordem das chaves pode mudar e a comparação falharia em entregas perfeitamente válidas.

O que acontece se o canal do WhatsApp estiver offline quando o meu fluxo de trabalho rodar?

As mensagens de texto são aceitas e entram na fila, e a resposta informa isso com um id de fila que você pode consultar. A mídia não entra na fila e devolve um erro de canal offline, porque uma mensagem de mídia da fila chegaria como texto simples. Deixe o n8n repetir esse nó.

Quais são os limites de solicitações?

60 solicitações por minuto por chave de API, somando todos os endpoints. A verificação de números aceita 20 números em uma única chamada, que é a forma mais fácil de ficar bem abaixo do limite ao validar uma lista.

Onde está a referência completa da API?

Uma descrição OpenAPI 3.1 de cada endpoint está publicada em https://api.spun.com/api/integrations/openapi.json e não exige chave de API para ser lida.

Pegue uma chave de API e comece a construir

O acesso à API vem com os planos de WhatsApp do Spun, junto com a caixa de entrada compartilhada da equipe, as respostas com IA e as integrações nativas com o Google Sheets e o HubSpot. Preço fixo a partir de R$249 por mês, teste grátis.

Comece grátis: 7 dias com tudo incluído

Ver todas as integrações