Como enviar mensagem WhatsApp com Node.js

Integrar WhatsApp em aplicações Node.js é uma das tarefas mais comuns para desenvolvedores brasileiros que precisam automatizar notificações, confirmar pedidos ou construir chatbots. Neste guia, você vai aprender a enviar mensagens via API REST usando Node.js — com exemplos práticos que funcionam em produção.

Por que usar uma API REST?

Antes de mergulhar no código, vale entender o cenário. O WhatsApp não oferece uma API pública direta para desenvolvedores individuais. As opções são: API oficial via Business Solution Provider (BSP), bibliotecas open source como Baileys, ou serviços gerenciados que abstraem a infraestrutura.

Para a maioria dos MVPs e automações internas, uma API REST gerenciada como o Zapixo resolve o problema sem exigir que você mantenha servidores, Docker ou atualizações da Evolution API.

Pré-requisitos

Para seguir este tutorial, você precisa de:

• Node.js 18 ou superior (com fetch nativo)
• Uma conta no Zapixo com instância conectada
• Uma chave de API gerada no painel

Se ainda não tem conta, o cadastro leva menos de dois minutos e você pode pagar via Pix.

Configuração do projeto

Crie um diretório e inicialize:

mkdir whatsapp-node && cd whatsapp-node
npm init -y

Para projetos que preferem axios:

npm install axios dotenv

Crie um arquivo .env:

ZAPIXO_API_KEY=zpx_sua_chave_aqui
ZAPIXO_INSTANCE=minha-loja

Enviando mensagem com fetch nativo

Node.js 18+ inclui fetch globalmente. Este é o método mais simples:

const API_KEY = process.env.ZAPIXO_API_KEY;
const INSTANCE = process.env.ZAPIXO_INSTANCE;

async function enviarMensagem(numero, texto) {
  const response = await fetch(
    "https://zapixo.com.br/api/v1/messages/text",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        instance: INSTANCE,
        number: numero,
        text: texto,
      }),
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Erro ${response.status}: ${JSON.stringify(error)}`);
  }

  return response.json();
}

// Uso
enviarMensagem("5511999999999", "Olá! Seu pedido #1234 foi confirmado.")
  .then((data) => console.log("Enviado:", data))
  .catch((err) => console.error(err));

Formato do número

O número deve incluir código do país (55 para Brasil) e DDD, sem símbolos:

• Correto: 5511999999999
• Incorreto: +55 (11) 99999-9999

Enviando com axios

Se preferir axios por causa de interceptors ou timeout configurável:

import axios from "axios";

const client = axios.create({
  baseURL: "https://zapixo.com.br/api/v1",
  headers: {
    Authorization: `Bearer ${process.env.ZAPIXO_API_KEY}`,
    "Content-Type": "application/json",
  },
  timeout: 10000,
});

async function enviarMensagem(numero, texto) {
  const { data } = await client.post("/messages/text", {
    instance: process.env.ZAPIXO_INSTANCE,
    number: numero,
    text: texto,
  });
  return data;
}

Enviando mídia

Para enviar imagens com legenda:

async function enviarImagem(numero, urlImagem, legenda) {
  const response = await fetch(
    "https://zapixo.com.br/api/v1/messages/media",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        instance: INSTANCE,
        number: numero,
        mediaUrl: urlImagem,
        caption: legenda,
      }),
    }
  );
  return response.json();
}

A URL da mídia deve ser pública e acessível via HTTPS.

Verificando status da instância

Antes de enviar mensagens em lote, verifique se a instância está conectada:

async function verificarStatus() {
  const response = await fetch(
    `https://zapixo.com.br/api/v1/instances/${INSTANCE}/status`,
    {
      headers: { Authorization: `Bearer ${API_KEY}` },
    }
  );
  const data = await response.json();
  return data.status; // "connected", "connecting", "disconnected"
}

Tratamento de erros

Implemente retry com backoff exponencial para erros temporários:

async function enviarComRetry(numero, texto, maxTentativas = 3) {
  for (let i = 0; i < maxTentativas; i++) {
    try {
      return await enviarMensagem(numero, texto);
    } catch (err) {
      if (i === maxTentativas - 1) throw err;
      await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, i)));
    }
  }
}

Integração com Express

Exemplo de endpoint que dispara WhatsApp ao confirmar pedido:

import express from "express";

const app = express();
app.use(express.json());

app.post("/pedidos/:id/confirmar", async (req, res) => {
  const { telefone, nome } = req.body;

  try {
    await enviarMensagem(
      telefone,
      `Olá ${nome}! Seu pedido #${req.params.id} foi confirmado.`
    );
    res.json({ ok: true });
  } catch (err) {
    res.status(502).json({ error: "Falha ao enviar WhatsApp" });
  }
});

app.listen(3000);

Rate limit

A API do Zapixo permite 60 requisições por minuto por chave. Monitore os headers X-RateLimit-Remaining e X-RateLimit-Reset para evitar bloqueios em disparos maiores.

Boas práticas

1. Nunca commite a API key — use variáveis de ambiente
2. Valide números antes de enviar
3. Obtenha consentimento — LGPD exige base legal para contato
4. Evite spam — mensagens não solicitadas violam termos do WhatsApp
5. Use filas (Bull, BullMQ) para volumes maiores que 60/min

Conclusão

Enviar mensagens WhatsApp com Node.js via API REST é direto: uma requisição POST com Bearer token. O Zapixo abstrai toda a complexidade da Evolution API, permitindo que você foque na lógica de negócio. Cadastre-se em zapixo.com.br, conecte sua instância e comece a integrar em minutos.