Pular para o conteúdo
apiwpp
Integração

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

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:

StatusO que significaO que fazer
400Corpo inválido ou conexão fora do status openCorrigir o corpo ou esperar a reconexão (evento connection.status)
401 e 403Chave inválida, revogada ou sem o escopo messages:sendConferir a chave; repetir não resolve
429Limite 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.

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.

Conecte seu primeiro número hoje.

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