Pular para o conteúdo
apiwpp

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.

Equipe apiwpp · 11 min de leitura

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:

  1. 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.
  2. 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.
  3. 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 com wag_live_ e aparece uma única vez: guarde num cofre de segredos ou numa variável de ambiente, nunca no repositório.
  4. Um número conectado, com a conexão no status open. Anote o id da conexão: é ele que vai na URL do envio.
Criando a chave de API no painel com apenas os escopos necessários.

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:

CampoO que é
jobIdO identificador do envio na fila
scheduledAtQuando o envio está previsto, em milissegundos unix
positionO 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}.

Do POST /send ao evento message.delivery: a resposta 202 chega na hora, a entrega é contada pelo webhook.

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 clientRef numa conexão coloca a mensagem na fila e responde 202.
  • Uma repetição com o mesmo clientRef, na mesma conexão, responde 200 com o job original e "duplicate": true, sem colocar nada na fila.
  • O clientRef fica reservado por 7 dias e volta nos eventos message.outgoing, message.delivery e message.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:

StatusQuando aconteceO que o seu código faz
400Corpo inválido, conteúdo faltando ou conexão fora do status openCorrigir a requisição ou esperar a reconexão; repetir igual não adianta
401Chave ausente, desconhecida, revogada ou expiradaConferir a chave; não repetir
403A chave não tem o escopo da operaçãoUsar uma chave com messages:send
429Limite de requisições ou teto de destinatários novos do númeroEsperar o tempo do cabeçalho Retry-After
5xxFalha do lado da APIRepetir 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:

EventoQuando chega
message.deliveryO status da mensagem mudou: sent, delivered, read ou failed, com o messageId e o seu clientRef
message.send_failedUm envio com clientRef não vai acontecer, com o motivo em reason (por exemplo, not_on_whatsapp)
message.incomingO 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

  1. Crie sua conta na apiwpp e conecte o número pelo QR code: o teste de 7 dias não pede cartão.
  2. Crie uma chave de API com o escopo messages:send e guarde em APIWPP_KEY, junto com o id da conexão.
  3. Rode o send.mjs deste tutorial para o seu próprio número e confira a resposta 202.
  4. Troque o exemplo pela função sendWhatsApp e escolha um clientRef estável para cada tipo de aviso do seu sistema.
  5. 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:

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.