API de WhatsApp para Node.js: envio com fetch e webhook com Express
Envie mensagens de WhatsApp com fetch no Node.js, trate 202, 400 e 429 e receba webhooks no Express com verificação da assinatura HMAC.
Atualizado em
A apiwpp é uma API REST com JSON: no Node.js, o fetch nativo basta para enviar mensagens, sem nenhum pacote extra. Para receber mensagens e confirmações de entrega, você expõe um endpoint HTTP, e o Express resolve isso em poucas linhas. Esta página mostra os dois lados, com o tratamento de erros que uma integração em produção precisa.
O que você precisa
- Uma conta na apiwpp: o teste grátis de 7 dias libera 1 número com os recursos do plano PRO, sem cartão.
- Um número conectado ao projeto, por QR code ou código de pareamento.
- Uma chave de API do projeto com o escopo
messages:send, guardada numa variável de ambiente (APIWPP_KEY). - Node.js 18 ou mais recente, que já traz o
fetch.
A chave vai no cabeçalho Authorization: Bearer. O identificador da conexão aparece no painel e nas respostas da API.
Enviar uma mensagem com fetch
POST /connections/{id}/send coloca a mensagem na fila do número e responde 202 na hora, com o jobId, o horário previsto do envio (scheduledAt, em milissegundos unix) e a posição na fila:
const API = 'https://api.apiwpp.com'
export async function sendWhatsApp(connectionId, to, message, clientRef) {
const response = await fetch(`${API}/connections/${connectionId}/send`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.APIWPP_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ to, message, clientRef }),
})
const body = await response.json().catch(() => ({})) // a proxy error may not be JSON
if (!response.ok) throw Object.assign(new Error(body.error ?? `HTTP ${response.status}`), { status: response.status, response })
return body // { jobId, scheduledAt, position }, and "duplicate": true on a repeat
}
await sendWhatsApp(connectionId, '5511988887777', 'Olá! Seu pedido saiu para entrega.', 'pedido-1234')
O campo to leva só dígitos, com o código do país e o DDD. Antes de enviar, a API consulta em qual endereço o número está registrado no WhatsApp, então contas antigas sem o nono dígito recebem normalmente.
Antes do texto, o destinatário vê "digitando…" por 1,5 segundo, o padrão do campo typingDelay (em milissegundos). Além de message, o corpo aceita media (imagem, vídeo, áudio, documento ou figurinha por URL https pública), location ou template com variables. Um PDF, por exemplo:
await fetch(`${API}/connections/${connectionId}/send`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.APIWPP_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
to: '5511988887777',
media: {
type: 'document',
url: 'https://cdn.sualoja.com.br/notas/1234.pdf',
mimetype: 'application/pdf',
fileName: 'nota-1234.pdf',
caption: 'Sua nota fiscal do pedido 1234',
},
clientRef: 'pedido-1234-nota',
}),
})
A URL precisa ser https e pública: endereços internos ou privados são recusados. Os demais formatos estão no envio de mídia e na documentação.
Repetir sem duplicar com clientRef
Uma requisição pode dar timeout depois de a API já ter aceitado o envio. Se você repetir com o mesmo clientRef, a resposta é 200 com o job original e "duplicate": true, e nada entra na fila de novo. O clientRef fica reservado por 7 dias e volta nos eventos message.delivery e message.send_failed, ligando cada evento ao registro do seu sistema.
Use um identificador que já existe no seu domínio, como o id do pedido ou do agendamento, e nunca um valor aleatório gerado a cada tentativa. Para reenviar de propósito uma mensagem que falhou, use um clientRef novo (pedido-1234-2): o antigo só devolveria o job original. Os detalhes estão em idempotência com clientRef.
Tratar 400 e 429
Os erros vêm em JSON com o campo error. Os dois que uma integração precisa prever:
| Status | O que significa | O que fazer |
|---|---|---|
400 | Corpo inválido ou conexão fora do status open | Corrigir o corpo ou esperar a reconexão (evento connection.status) |
401 e 403 | Chave inválida, revogada ou sem o escopo messages:send | Conferir a chave; repetir não resolve |
429 | Limite atingido, como o teto de destinatários novos por dia (new_recipient_cap_reached) | Tentar de novo depois do tempo do cabeçalho Retry-After |
Com o teto de destinatários novos, nada é colocado na fila: o seu sistema decide se agenda para mais tarde ou avisa a equipe.
try {
await sendWhatsApp(connectionId, to, text, `pedido-${order.id}`)
} catch (error) {
if (error.status === 429) {
const seconds = Number(error.response.headers.get('retry-after') ?? 60)
await scheduleRetry(order.id, seconds) // your queue: BullMQ, a cron, a table
} else {
throw error
}
}
Receber eventos com Express
Cada evento chega como um POST no endereço de webhook do projeto, assinado com HMAC-SHA256 quando o projeto tem um segredo. A verificação precisa do corpo bruto, por isso a rota usa express.raw em vez de express.json:
import express from 'express'
import { createHmac, timingSafeEqual } from 'node:crypto'
const app = express()
const secret = process.env.APIWPP_WEBHOOK_SECRET
function isSigned(rawBody, timestamp, signature) {
if (!secret || !/^\d+$/.test(timestamp ?? '') || !signature) return false
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
const mac = createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex')
const expected = Buffer.from(`sha256=${mac}`)
const received = Buffer.from(signature)
return expected.length === received.length && timingSafeEqual(expected, received)
}
app.post('/webhooks/whatsapp', express.raw({ type: 'application/json' }), (req, res) => {
if (!isSigned(req.body, req.get('x-sales-timestamp'), req.get('x-sales-signature'))) {
return res.sendStatus(401)
}
const event = JSON.parse(req.body.toString('utf8'))
res.sendStatus(204) // answer fast, process afterwards
queue.add(event) // your background worker
})
app.listen(3000)
Responda com um status 2xx em até 10 segundos e processe o evento depois. Uma entrega que falha é tentada de novo até 6 vezes, e a entrega é pelo menos uma vez: guarde o messageId dos eventos já processados e ignore os repetidos. Tipos de evento que o seu código não conhece devem ser ignorados, não recusados.
Os tipos de evento e o envelope completo estão em webhooks assinados. Para um passo a passo mais longo, veja o tutorial enviar mensagem de WhatsApp com Node.js, e para chamadas tipadas, o cliente TypeScript.
Perguntas frequentes
Preciso instalar algum pacote para usar a API no Node.js?
Não. O fetch nativo do Node.js 18 ou mais recente basta para enviar. Para receber webhooks, qualquer servidor HTTP serve; o exemplo usa o Express. Se preferir chamadas tipadas, há um cliente TypeScript gerado da especificação OpenAPI.
Por que a resposta do envio é 202 e não 200?
Porque a mensagem entra na fila do número, que respeita limites de ritmo para proteger o número de bloqueios. A resposta traz o horário previsto e a posição na fila; o resultado chega depois pelo evento message.delivery.
Como sei se a mensagem foi entregue ou lida?
Pelo webhook. O evento message.delivery chega a cada mudança de status (sent, delivered, read ou failed) com o messageId e o clientRef que você enviou. Um envio aceito que não vai acontecer, como um número fora do WhatsApp, chega como message.send_failed, com o motivo.
Posso usar o body parser JSON do Express no webhook?
Não na rota do webhook. A assinatura é calculada sobre o corpo exatamente como chegou, e o express.json o transforma antes da verificação. Use express.raw nessa rota e faça o JSON.parse depois de conferir a assinatura.
Outras integrações
Todos: Integrações →Tipos gerados da especificação OpenAPI 3.1 com o openapi-typescript e chamadas pelo openapi-fetch: cada rota, corpo, resposta e evento de webhook tipado, sem código escrito à mão.
Envie mensagens com curl ou Guzzle, use o cliente PHP gerado da especificação OpenAPI 3.1 e receba os eventos num script que confere a assinatura HMAC-SHA256 com hash_hmac e hash_equals.
Envie mensagens de WhatsApp a partir de Jobs do Laravel com o Http facade e clientRef, receba os eventos numa rota protegida por um middleware de assinatura HMAC e processe tudo na fila, sem duplicar.