Quase tudo o que se pede a uma API do WhatsApp se resume a quatro coisas: enviar uma mensagem, consultar algo, alterar um registro e ser avisado quando algo aconteceu. O Spun oferece as quatro por HTTP simples, sobre o mesmo número que a sua equipe atende na caixa de entrada, com autenticação por uma chave que você mesmo cria e limita exatamente ao que a integração precisa.
Esta página é a versão prática: quais são os endpoints, como funcionam a autenticação e os escopos, o que acontece quando a sua linha de WhatsApp está offline no momento da chamada e onde fica o contrato legível por máquina.
Chaves, escopos e o tamanho do estrago de um vazamento
A autenticação é um token bearer. Você cria uma chave no app, ela é mostrada uma única vez, e toda requisição a envia em um cabeçalho Authorization. O Spun guarda apenas um hash da chave, então uma chave perdida não pode ser recuperada, só substituída.
A parte que merece um minuto de atenção são os escopos. Uma chave não é simplesmente “acesso à conta”: ela carrega uma lista de escopos, e cada endpoint verifica o escopo específico de que precisa. Uma chave só com read_contacts não consegue enviar uma mensagem. Uma chave só com send_message não consegue listar os seus contatos. Além dos escopos, uma chave pode ter uma data de expiração e uma lista de IPs permitidos, para que uma chave emitida para um servidor com endereço fixo pare de funcionar no momento em que for usada de qualquer outro lugar.
- send_message cobre envios de texto e de mídia, e a consulta de um envio que entrou na fila.
- read_contacts, read_messages e read_labels são o lado de leitura, concedidos separadamente.
- manage_contacts e manage_labels cobrem criar, atualizar e etiquetar.
- check_phone responde se um número está acessível no WhatsApp.
- manage_webhooks cria, lista e exclui assinaturas de webhook.
Requisição
curl -X POST https://api.spun.com/api/integrations/send-message \
-H "Authorization: Bearer wap_0f3c9a1d7b524e86a1c05d9e2f7b48ac" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550142",
"text": "Your appointment is confirmed for Thursday at 10:00.",
"idempotency_key": "booking-8871"
}'Resposta
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"message_id": "yq0Zt9C1sK2mfE7x"
}Chaves criadas para o servidor MCP do Spun são recusadas de propósito nesta API, mesmo quando são chaves válidas. As duas superfícies têm regras de aprovação diferentes, e uma chave emitida para uma não pode ser usada silenciosamente na outra.
Veja também: Conectar um assistente de IA em vez de escrever código
O que os endpoints da API do WhatsApp realmente cobrem
A superfície é pequena e estável de propósito, e não um espelho completo do produto. Ela existe para que um sistema externo possa fazer o que sistemas externos realmente precisam fazer.
- Envio: uma mensagem de texto, ou mídia por URL ou em base64, com legenda opcional.
- Contatos: criar um contato, atualizá-lo e listar contatos com paginação por cursor.
- Etiquetas: listar as etiquetas do espaço de trabalho, aplicar uma a uma conversa, remover uma.
- Mensagens: listar mensagens com paginação por cursor, para sincronizar com um data warehouse ou um CRM.
- Verificar número: confirmar que um número está no WhatsApp antes de montar uma lista com ele.
- Fila: consultar um envio que entrou na fila porque a linha estava offline.
- Webhooks: criar, listar e excluir assinaturas.
O contrato legível por máquina é publicado em /api/integrations/openapi.json e pode ser lido sem chave, para que quem cria um node do n8n, quem monta um app no Zapier ou o seu próprio gerador possa baixar a especificação antes que alguém tenha emitido credenciais.
O que acontece quando a linha de WhatsApp está offline
Esta é a parte que surpreende as pessoas, então vale ser explícito. O Spun envia por uma sessão ativa do WhatsApp, e uma sessão ativa pode cair exatamente no segundo em que o seu código faz a chamada. A API não finge o contrário, e se comporta de forma diferente para texto e para mídia, de propósito.
Um envio de texto para uma linha offline retorna 202 em vez de um erro, com um id de fila. A mensagem fica retida e é entregue quando a linha se reconecta, e você pode consultar o endpoint da fila para saber o que aconteceu com ela. Um envio de mídia para uma linha offline retorna um conflito e não envia nada. Essa assimetria é deliberada: a fila despacha as mensagens como texto, então uma imagem na fila chegaria como uma legenda sem a foto. Falhar de forma clara é o melhor resultado, e a sua lógica de nova tentativa decide o que fazer.
O limite de taxa é de 60 requisições por minuto por chave, com os cabeçalhos padrão de limite de taxa em toda resposta, para que um cliente possa desacelerar pelos cabeçalhos em vez de por um 429 que não esperava.
Webhooks: ser avisado em vez de consultar
Consultar um endpoint de mensagens em intervalos fixos não combina com uma conversa, então a API pode enviar os eventos até você. Você registra uma URL e os eventos que interessam, e o Spun envia um corpo JSON para ela conforme eles acontecem.
Toda entrega leva nos cabeçalhos o nome do evento e um id de entrega único e, quando a assinatura tem um segredo de assinatura, uma assinatura HMAC-SHA256 do corpo exato. Verifique a assinatura antes de confiar no conteúdo: ela é a única coisa que separa o seu endpoint de qualquer pessoa que descubra a URL. O segredo é devolvido uma vez, quando você cria a assinatura, e nunca mais.
- Eventos de mensagem, recebida e enviada.
- Contato criado, atualizado e excluído.
- Etiqueta atribuída.
- Fluxo de chat concluído, envio da fila processado, lead qualificado.
- Conversa encerrada, chamada concluída e estágio do pipeline alterado.
Veja também: Conectar o Spun ao Zapier e ao Make · Conectar o Spun ao n8n · Conectar um helpdesk: Zendesk, Zoho Desk, Freshdesk, HubSpot Service Hub, Jira
Limites e ressalvas honestas
- Esta não é a API do WhatsApp Business. É a API do próprio Spun na frente do seu número vinculado, então não há modelos de mensagem para aprovar nem tarifas por mensagem, e também não há garantias oficiais da Meta.
- Sessenta requisições por minuto por chave. Trabalho em grande volume pertence às campanhas, que controlam o próprio ritmo como devem, e não a um loop apertado de API.
- A lista de endpoints acima é toda a superfície hoje. O que não está nela não está disponível, e não se deve contar com nenhum endpoint não documentado.
- Uma chave tem escopos, mas não é por usuário. Trate-a como uma credencial do espaço de trabalho e troque-a quando alguém com acesso sair.
- Enviar para pessoas que nunca deram consentimento fará o WhatsApp limitar o número, seja qual for o caminho que a mensagem tomou.
Veja também: Como o Spun se conecta ao WhatsApp