Como enviar mensagem de WhatsApp por API (Node.js, Python e PHP)

São quatro itens. Uma conta no ZapZap, uma instância (o número de WhatsApp) conectada por QR code no painel, a chave e o segredo da API, e o ID da instância. A chave (x-api-key) e o segredo (x-api-secret) ficam no painel, em Configurações e API, e o ID da instância aparece na lista de instâncias.

Toda requisição leva os dois cabeçalhos de autenticação. Não há OAuth nem sessão: a documentação de autenticação mostra o formato completo. O segredo é de uso exclusivo do seu servidor, nunca o coloque em código que roda no navegador ou no aplicativo do cliente.

Antes de escrever código, confirme que tudo funciona com uma chamada direta. Troque os valores em maiúsculas pelos seus. O número vai com DDI e só dígitos (55 para o Brasil, depois DDD e número).

curl -X POST https://api.zapzapapi.com/api/v1/SEU_INSTANCE_ID/send/text \
  -H "Content-Type: application/json" \
  -H "x-api-key: SUA_API_KEY" \
  -H "x-api-secret: SEU_API_SECRET" \
  -d '{"number":"5511999999999","text":"Olá! Teste de envio pela API."}'

No Node.js 18 ou superior o fetch já vem embutido, então não precisa instalar nada. Guarde as credenciais em variáveis de ambiente.

const resposta = await fetch(
  `https://api.zapzapapi.com/api/v1/${process.env.ZAPZAP_INSTANCE_ID}/send/text`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.ZAPZAP_API_KEY,
      "x-api-secret": process.env.ZAPZAP_API_SECRET,
    },
    body: JSON.stringify({
      number: "5511999999999",
      text: "Olá! Seu pedido saiu para entrega.",
    }),
  },
);

if (!resposta.ok) {
  throw new Error(`Falha ${resposta.status}: ${await resposta.text()}`);
}
console.log(await resposta.json());

Em Python, a biblioteca requests deixa o envio curto. Defina sempre um timeout para a chamada não ficar pendurada.

import os
import requests

url = f"https://api.zapzapapi.com/api/v1/{os.environ['ZAPZAP_INSTANCE_ID']}/send/text"
cabecalhos = {
    "Content-Type": "application/json",
    "x-api-key": os.environ["ZAPZAP_API_KEY"],
    "x-api-secret": os.environ["ZAPZAP_API_SECRET"],
}
corpo = {"number": "5511999999999", "text": "Olá! Sua consulta está confirmada."}

resposta = requests.post(url, json=corpo, headers=cabecalhos, timeout=30)
resposta.raise_for_status()
print(resposta.json())

Em PHP o cURL nativo resolve, sem biblioteca extra.

<?php
$url = "https://api.zapzapapi.com/api/v1/" . getenv("ZAPZAP_INSTANCE_ID") . "/send/text";

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "x-api-key: " . getenv("ZAPZAP_API_KEY"),
        "x-api-secret: " . getenv("ZAPZAP_API_SECRET"),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "number" => "5511999999999",
        "text" => "Olá! Seu boleto vence amanhã.",
    ]),
]);

$resposta = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException("Falha $status: $resposta");
}
echo $resposta;

Valide o número antes de enviar: DDI mais DDD mais número, só dígitos. Um número malformado é o erro mais comum e o mais fácil de evitar. Trate a resposta: status 4xx quase sempre é problema da requisição e não adianta repetir igual, enquanto falha de rede ou 5xx pode ser repetida algumas vezes com espera crescente entre as tentativas.

Mantenha o segredo no servidor e rode a chamada em fila ou tarefa em segundo plano, não dentro do clique do usuário. Assim uma lentidão no envio não trava a sua tela. A API responde de forma síncrona, e todo envio exibe o indicador de digitando antes de entregar, com duração proporcional ao tamanho do texto, o que deixa o envio mais natural.

Respeite o ritmo. Enviar muitas mensagens iguais em sequência, para pessoas que não esperam receber, é o padrão que mais leva a denúncias. Nenhuma técnica elimina o risco de bloqueio, mas aquecer o número, variar o texto e enviar só para quem consentiu reduz a chance. O guia de anti-bloqueio detalha cada ponto.

Enviar é metade do fluxo. Para receber as respostas dos clientes, configure um webhook e trate os eventos no seu sistema, como mostra a documentação de webhooks. Se você usa ferramentas no-code, veja as integrações com n8n, Make e outras, que fazem esse mesmo envio sem escrever código.