Ir al contenido

Enviar WhatsApp desde Node.js ​

ZAPPIO es una API HTTP + JSON: en Node.js no necesitas SDK. Con fetch (Node 18 o superior) envías el mensaje y con Express recibes las respuestas de tus clientes por webhook.

Antes de empezar necesitas una cuenta, una instancia conectada y una API key: sigue el Quickstart (pasos 1 a 7). Al terminar tendrás estas variables:

bash
export ZAPPIO_API_URL="https://zappio.cloud"
export ZAPPIO_API_KEY="zp_..."
export ZAPPIO_INSTANCE="ins_..."

Enviar un mensaje ​

js
// zappio.js
const API = `${process.env.ZAPPIO_API_URL}/api/v1`;

async function sendWhatsApp(to, text, idempotencyKey) {
  const res = await fetch(`${API}/messages`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ZAPPIO_API_KEY}`,
      'Content-Type': 'application/json',
      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
    },
    body: JSON.stringify({ instance: process.env.ZAPPIO_INSTANCE, to, type: 'text', text }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body.data; // { id: "msg_...", status: "queued", ... }
}

module.exports = { sendWhatsApp };
js
const { sendWhatsApp } = require('./zappio');

sendWhatsApp('5215500000000', 'Hola desde Node.js 👋', 'saludo-1').then((msg) => console.log(msg.id, msg.status));
  • to es el número con código de país (en México, 52 y el número; los espacios y el + se ignoran).
  • La API responde 202 Accepted con status: "queued": el envío ocurre en segundo plano. Sigue el estado con los webhooks o con GET /api/v1/messages/{id}.
  • Idempotency-Key hace seguros los reintentos: si repites la petición con la misma clave, no se envía dos veces (Idempotencia).
  • Si algo falla, error.code te dice qué pasó (Errores).

Recibir respuestas con Express ​

Registra en el panel un webhook con la URL de tu servidor y el evento message.received. ZAPPIO te enviará cada mensaje entrante firmado; verifica la firma con el cuerpo crudo antes de leer el JSON.

La función de verificación (sin dependencias, probada contra el vector de prueba):

js
'use strict';
const crypto = require('node:crypto');

/**
 * Verifies a ZAPPIO webhook. `rawBody` must be the exact bytes received (a Buffer or the unparsed string), not
 * JSON.stringify(req.body). No dependencies.
 */
function verifyZappioWebhook(secret, timestamp, signatureHeader, rawBody, now = Math.floor(Date.now() / 1000), tolerance = 300) {
  // Reject stale or future timestamps: a captured request cannot be replayed later.
  if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > tolerance) return false;

  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(String(signatureHeader));
  return a.length === b.length && crypto.timingSafeEqual(a, b); // constant-time comparison
}

module.exports = { verifyZappioWebhook };

// --- Self-check against the shared test vector: node verify-webhook.js webhook-signature-vector.json
if (require.main === module && process.argv[2]) {
  const vector = JSON.parse(require('node:fs').readFileSync(process.argv[2], 'utf8'));
  let failed = 0;
  for (const c of vector.cases) {
    const ok = verifyZappioWebhook(c.secret, c.timestamp, c.signature, c.body, c.now, vector.tolerance_seconds);
    if (ok !== c.valid) {
      console.error(`FAIL node: ${c.name}`);
      failed++;
    }
  }
  if (failed === 0) console.log(`node: ${vector.cases.length} cases OK`);
  process.exit(failed === 0 ? 0 : 1);
}

Y el endpoint:

js
// server.js
const express = require('express');
const { verifyZappioWebhook } = require('./verify-webhook');
const { sendWhatsApp } = require('./zappio');

const app = express();

// express.raw: el cuerpo llega como Buffer, sin convertir a JSON (la firma se calcula sobre esos bytes).
app.post('/webhooks/zappio', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyZappioWebhook(
    process.env.ZAPPIO_WEBHOOK_SECRET, // el secreto zpwh_... de tu endpoint
    req.get('X-Zappio-Timestamp') ?? '',
    req.get('X-Zappio-Signature') ?? '',
    req.body,
  );
  if (!ok) return res.sendStatus(401);

  res.sendStatus(200); // responde rápido; el trabajo va después
  const event = JSON.parse(req.body);
  if (event.type !== 'message.received') return;

  const msg = event.data.message;
  if (msg.group_id === null && msg.type === 'text') {
    sendWhatsApp(msg.from, `Recibimos tu mensaje: "${msg.text}"`).catch(console.error);
  }
});

app.listen(3000);
  • Responde un 2xx en menos de 10 segundos y haz el trabajo después (reintentos y duplicados).
  • Un mismo evento puede llegar más de una vez: deduplica por event.id.

Siguientes pasos ​

Pruébalo gratis

Crea tu cuenta: 50 mensajes de prueba, sin tarjeta y sin límite de días.