Apariencia
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));toes el número con código de país (en México,52y el número; los espacios y el+se ignoran).- La API responde
202 Acceptedconstatus: "queued": el envío ocurre en segundo plano. Sigue el estado con los webhooks o conGET /api/v1/messages/{id}. Idempotency-Keyhace seguros los reintentos: si repites la petición con la misma clave, no se envía dos veces (Idempotencia).- Si algo falla,
error.codete 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
2xxen 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
- Multimedia: imágenes, documentos, audio y video con
multipart/form-data. - Encuestas y ubicaciones y contactos.
- Casos completos: notificaciones de pedidos y bot de respuestas.
Pruébalo gratis
Crea tu cuenta: 50 mensajes de prueba, sin tarjeta y sin límite de días.