Enviar mensagem de WhatsApp com Node.js em 5 minutos
Da chave de API ao primeiro envio pelo WhatsApp com Node.js: fetch nativo ou cliente TypeScript, resposta 202, clientRef contra duplicidade e erros 400 e 429.
Você tem um sistema em Node.js e quer que ele mande uma mensagem de WhatsApp: a confirmação de um pedido, o lembrete de uma consulta, o aviso de que um boleto venceu. A parte difícil não é o código. É saber o que precisa estar pronto antes da primeira chamada, o que a resposta quer dizer e como não mandar a mesma mensagem duas vezes quando a rede falha.
Este tutorial vai do zero ao primeiro envio com a apiwpp usando o fetch que já vem no Node.js, sem instalar nada. Depois mostra o mesmo envio com um cliente TypeScript gerado da especificação OpenAPI, o clientRef que torna a chamada segura para repetir e os erros que o seu código precisa tratar.
Se o número ainda não está conectado, comece pelo guia de conexão por QR code ou código de pareamento e volte aqui: o envio só funciona com a conexão aberta.
O que você precisa antes de começar
São quatro coisas, e três delas se resolvem no painel:
- Uma conta na apiwpp. O teste grátis dura 7 dias, libera 1 número com os recursos do plano PRO e não pede cartão.
- Um projeto. Ele representa um sistema seu, com o próprio endereço de webhook e as próprias chaves de API. Cada número de WhatsApp é uma conexão dentro do projeto.
- Uma chave de API com o escopo
messages:send. Crie a chave no projeto e marque só os escopos de que o sistema precisa. Ela começa comwag_live_e aparece uma única vez: guarde num cofre de segredos ou numa variável de ambiente, nunca no repositório. - Um número conectado, com a conexão no status
open. Anote o id da conexão: é ele que vai na URL do envio.
Do lado do Node.js, qualquer versão 18 ou mais recente serve, porque todas já trazem o fetch global. Os exemplos usam módulos ES (arquivos .mjs) para poder usar await no nível do arquivo.
Deixe a chave e o id da conexão no ambiente do terminal:
export APIWPP_KEY="wag_live_…"
export APIWPP_CONNECTION_ID="8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f"
Para conferir se a chave funciona antes de enviar qualquer coisa, a rota GET /me responde a organização, os escopos e os projetos que a chave alcança:
curl -s https://api.apiwpp.com/me -H "Authorization: Bearer $APIWPP_KEY"
A chave vai no cabeçalho Authorization: Bearer em toda requisição. O cabeçalho X-Api-Key também é aceito, se a sua ferramenta preferir.
Enviar a primeira mensagem com fetch
Crie um arquivo send.mjs. O envio é um único POST /connections/{id}/send com o destinatário, o texto e um clientRef:
// send.mjs
const API = 'https://api.apiwpp.com'
const connectionId = process.env.APIWPP_CONNECTION_ID
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: '5511988887777',
message: 'Olá, Ana! Seu pedido 1234 foi confirmado.',
clientRef: 'pedido-1234-confirmacao',
}),
})
const body = await response.json()
console.log(response.status, body)
node send.mjs
Se tudo estiver certo, a saída mostra o status 202 e um corpo como este:
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1 }
É isso: a mensagem está a caminho. O resto do tutorial explica o que cada parte quer dizer e como deixar esse código pronto para produção.
O campo to
O destinatário vai em to só com dígitos, com o código do país e o DDD: 5511988887777, sem +, espaços ou traços. Antes de enviar, a apiwpp pergunta ao WhatsApp em qual endereço aquele número está registrado. Por isso contas antigas, criadas antes do nono dígito, recebem a mensagem mesmo que você mande o número com o 9. A apiwpp nunca inclui nem remove o dígito por conta própria; o motivo está no guia sobre o nono dígito.
Um número que não tem WhatsApp falha na hora, sem novas tentativas. Para limpar uma base antes de enviar, a rota POST /connections/{id}/contacts/check verifica até 100 números de uma vez.
Outros tipos de conteúdo
O texto vai em message. No lugar dele, o mesmo endpoint aceita media (imagem, vídeo, áudio, documento ou figurinha a partir de uma URL https pública), location ou template com variáveis. Antes de cada texto, a apiwpp mostra "digitando…" por 1,5 segundo; o campo typingDelay, em milissegundos, muda esse tempo. O envio de arquivos tem um guia próprio: como enviar PDF, imagem, áudio e vídeo.
Por que a resposta é 202, e não 200
A chamada de envio não espera a mensagem sair. Ela coloca o envio na fila do número e responde 202 Accepted na hora, com três campos:
| Campo | O que é |
|---|---|
jobId | O identificador do envio na fila |
scheduledAt | Quando o envio está previsto, em milissegundos unix |
position | O lugar do envio na fila do número |
A fila existe para proteger o número. Por padrão, cada número envia no máximo 3 mensagens por minuto, 60 por hora e 200 por dia, com um intervalo aleatório de 3 a 8 segundos entre dois envios e pelo menos 30 segundos entre duas mensagens para a mesma pessoa. Nos primeiros 14 dias depois de conectar, os limites são menores e sobem por etapas. Os detalhes estão na página da fila com ritmo anti-bloqueio e no guia sobre como evitar o bloqueio do número.
Na prática, isso muda a forma de pensar o código: um 202 quer dizer "aceito", não "entregue". Se o seu sistema precisa mostrar que a mensagem chegou ou foi lida, ele escuta o evento message.delivery no webhook, como mostra a última seção. Para ver o estado da fila de um número (limites em vigor, uso atual e etapa do aquecimento), use GET /connections/{id}/queue. Para cancelar um envio que ainda não saiu, DELETE /connections/{id}/queue/{jobId}.
O mesmo envio com o cliente TypeScript
A apiwpp publica a especificação OpenAPI 3.1 da API. A partir dela, dá para ter um cliente em que cada rota, corpo e resposta é tipado: se você errar o nome de um campo, o editor avisa antes de rodar. Os clientes TypeScript e PHP são gerados da especificação e, enquanto não estão num registro de pacotes, você pede o pacote pronto pelo suporte ou gera os tipos no seu projeto.
Gerar só os tipos leva um comando, e a camada de chamadas é o openapi-fetch, que não passa de um invólucro fino sobre o fetch:
npx openapi-typescript https://docs.apiwpp.com/openapi.json -o src/apiwpp.d.ts
npm install openapi-fetch
// src/whatsapp.ts
import createClient from 'openapi-fetch'
import type { paths } from './apiwpp'
const apiwpp = createClient<paths>({
baseUrl: 'https://api.apiwpp.com',
headers: { Authorization: `Bearer ${process.env.APIWPP_KEY}` },
})
const { data, error, response } = await apiwpp.POST('/connections/{id}/send', {
params: { path: { id: process.env.APIWPP_CONNECTION_ID! } },
body: { to: '5511988887777', message: 'Olá, Ana! Seu pedido 1234 foi confirmado.', clientRef: 'pedido-1234-confirmacao' },
})
if (error) throw new Error(`${response.status}: ${error.error}`)
console.log(data.jobId, data.scheduledAt, data.position)
O resultado é o mesmo do exemplo com fetch; a diferença é que data e error já chegam com os tipos da especificação. A página do cliente TypeScript e a de OpenAPI e clientes gerados trazem mais detalhes, e a referência interativa, em português, fica na documentação.
clientRef: repetir sem mandar duas vezes
Em produção, a pergunta não é se uma requisição vai dar timeout, e sim quando. E um timeout não diz se o envio entrou na fila. Sem proteção, a retentativa do seu cliente HTTP, do job ou do usuário apertando o botão de novo manda a mesma mensagem duas vezes.
O clientRef resolve isso. Ele é o seu identificador do envio, com até 200 caracteres:
- A primeira requisição com um
clientRefnuma conexão coloca a mensagem na fila e responde202. - Uma repetição com o mesmo
clientRef, na mesma conexão, responde200com o job original e"duplicate": true, sem colocar nada na fila. - O
clientReffica reservado por 7 dias e volta nos eventosmessage.outgoing,message.deliveryemessage.send_failed, ligando cada evento ao registro do seu sistema.
{ "jobId": "c2a4e6f8-1b3d-4f5a-8c7e-9d0b1a2c3e4f", "scheduledAt": 1790251205000, "position": 1, "duplicate": true }
Use um valor que já existe no seu domínio e descreve aquele aviso, como pedido-1234-confirmacao ou consulta-987-lembrete-vespera. Nunca gere um valor aleatório a cada tentativa: assim cada retentativa vira um envio novo, e a proteção some. Se um envio aceito falhar depois e você quiser mandar de novo de propósito, use um clientRef novo, como pedido-1234-confirmacao-2. O assunto tem um guia inteiro sobre mensagens duplicadas e idempotência.
Tratar os erros: 400, 401, 403 e 429
Todo erro responde um status HTTP e um JSON com pelo menos o campo error. Esse campo é um texto para pessoas e pode mudar, então decida pelo status:
| Status | Quando acontece | O que o seu código faz |
|---|---|---|
400 | Corpo inválido, conteúdo faltando ou conexão fora do status open | Corrigir a requisição ou esperar a reconexão; repetir igual não adianta |
401 | Chave ausente, desconhecida, revogada ou expirada | Conferir a chave; não repetir |
403 | A chave não tem o escopo da operação | Usar uma chave com messages:send |
429 | Limite de requisições ou teto de destinatários novos do número | Esperar o tempo do cabeçalho Retry-After |
5xx | Falha do lado da API | Repetir com espera crescente, com o mesmo clientRef |
A conexão fora do ar é o 400 mais comum no começo:
{ "error": "Connection not ready (status: close)" }
O 429 do envio merece atenção. Cada número alcança, por padrão, até 100 destinatários novos a cada 24 horas: pessoas que não trocaram mensagem com o número nos últimos 28 dias. Passado esse teto, a resposta traz "error": "new_recipient_cap_reached" e o cabeçalho Retry-After, e nada entra na fila. Mensagens para contatos conhecidos continuam sendo aceitas.
Juntando tudo numa função reaproveitável:
// whatsapp.mjs
const API = 'https://api.apiwpp.com'
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
export async function sendWhatsApp({ connectionId, to, message, clientRef }) {
for (let attempt = 0; attempt < 4; attempt++) {
let response
try {
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 }),
signal: AbortSignal.timeout(10_000),
})
} catch {
await sleep(1000 * 2 ** attempt) // network error or timeout: same clientRef, no duplicate
continue
}
const body = await response.json()
if (response.ok) return body // 202 queued, or 200 with duplicate: true
if (response.status === 429) {
const retryAfter = Number(response.headers.get('retry-after') ?? 60)
const error = new Error(body.error)
Object.assign(error, { status: 429, retryAfter })
throw error // let your job queue reschedule it
}
if (response.status >= 500) {
await sleep(1000 * 2 ** attempt)
continue
}
throw Object.assign(new Error(body.error), { status: response.status }) // 4xx: fix the cause
}
throw new Error(`send ${clientRef} failed after retries`)
}
Repare em três escolhas. Timeouts, erros de rede e 5xx são repetidos com espera crescente e o mesmo clientRef, então nenhuma retentativa duplica a mensagem. O 429 não é repetido dentro da função: ele sobe com o retryAfter para que a sua fila de jobs (BullMQ, uma tabela, um cron) agende para depois, em vez de segurar um processo esperando. E os outros 4xx falham de vez, porque repetir não muda o resultado.
Próximo passo: saber se a mensagem chegou
O 202 diz que a mensagem entrou na fila. O que acontece depois chega por webhook: a apiwpp faz um POST no endereço do projeto para cada evento, no mesmo envelope type, connectionId, tenantId, externalId, timestamp e data. Para quem acabou de enviar, três eventos importam:
| Evento | Quando chega |
|---|---|
message.delivery | O status da mensagem mudou: sent, delivered, read ou failed, com o messageId e o seu clientRef |
message.send_failed | Um envio com clientRef não vai acontecer, com o motivo em reason (por exemplo, not_on_whatsapp) |
message.incoming | O destinatário respondeu |
Com um segredo definido no projeto, cada entrega vem assinada com HMAC-SHA256 nos cabeçalhos X-Sales-Timestamp e X-Sales-Signature. Um receptor mínimo em Express verifica a assinatura sobre o corpo bruto, responde rápido e processa depois:
// webhook.mjs
import express from 'express'
import { createHmac, timingSafeEqual } from 'node:crypto'
const secret = process.env.APIWPP_WEBHOOK_SECRET
if (!secret) throw new Error('APIWPP_WEBHOOK_SECRET is not set')
function isSigned(rawBody, timestamp, signature) {
if (!/^\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)
}
const app = express()
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 within 10 s, work afterwards
if (event.type === 'message.delivery') {
console.log(event.data.clientRef, event.data.status) // update your record
}
})
app.listen(3000)
A entrega é feita pelo menos uma vez, com até 6 tentativas quando o seu endpoint falha, então o mesmo evento pode chegar duas vezes: processe de forma idempotente. O passo a passo completo, com o envelope de cada evento e o reenvio pelo painel, está no guia de webhooks do WhatsApp e na página de webhooks assinados. Para um resumo de envio e recebimento lado a lado, veja a integração com Node.js.
Como começar hoje
- Crie sua conta na apiwpp e conecte o número pelo QR code: o teste de 7 dias não pede cartão.
- Crie uma chave de API com o escopo
messages:sende guarde emAPIWPP_KEY, junto com o id da conexão. - Rode o
send.mjsdeste tutorial para o seu próprio número e confira a resposta202. - Troque o exemplo pela função
sendWhatsAppe escolha umclientRefestável para cada tipo de aviso do seu sistema. - Suba o receptor de webhook, defina o segredo do projeto e atualize seus registros com o
message.delivery. Quando for hora de mais números, os valores por número estão em preços.
Perguntas frequentes
Preciso instalar algum pacote para enviar mensagem de WhatsApp com Node.js?
Não. O fetch global do Node.js 18 ou mais recente basta para chamar a API. Pacotes só entram se você quiser: o Express (ou outro servidor HTTP) para receber webhooks e o openapi-fetch com os tipos gerados da especificação para ter chamadas tipadas.
Por que a mensagem não sai no mesmo segundo?
Porque cada número tem uma fila com ritmo que reduz o risco de bloqueio: por padrão, até 3 mensagens por minuto, com 3 a 8 segundos entre dois envios. A resposta 202 já traz o horário previsto em scheduledAt e a posição na fila. Por isso a API não serve para códigos de verificação que precisam chegar na hora.
Qual formato de número uso no campo to?
Só dígitos, com o código do país e o DDD, como 5511988887777. A apiwpp consulta o WhatsApp para saber em qual endereço o número está registrado, então o nono dígito é resolvido sem você montar nada à mão. Números que não estão no WhatsApp falham na hora.
O que acontece se eu repetir a requisição depois de um timeout?
Se ela tiver o mesmo clientRef, nada é enviado de novo: a API responde 200 com o job original e "duplicate": true. O clientRef fica reservado por 7 dias na mesma conexão. Sem clientRef, a repetição coloca uma segunda mensagem na fila.
Posso usar o mesmo código em TypeScript?
Sim. O exemplo com fetch funciona igual em TypeScript. Se preferir tipos para cada rota e resposta, gere-os da especificação OpenAPI 3.1 com o openapi-typescript e faça as chamadas com o openapi-fetch, como na seção sobre o cliente TypeScript.
Como sei se a mensagem foi entregue e lida?
Pelo evento message.delivery no webhook do projeto, que informa sent, delivered, read ou failed junto com o messageId e o seu clientRef. Se o envio não puder acontecer, chega message.send_failed com o motivo. A resposta do envio só confirma que a mensagem entrou na fila.
Leia também: