Números de la bandeja y webhooks de mensajes entrantes

En la página Números de la bandeja eliges cuáles de tus números de WhatsApp se sincronizan con la bandeja Unibox, donde tu equipo lee y responde sus chats. Si le das a un número una URL de webhook, WbizTool también envía a tu servidor cada mensaje nuevo que recibe o envía, como JSON firmado: registra conversaciones en un CRM, avisa a tu equipo o lanza una respuesta automática.

¿Estás creando el receptor? Ve a Cómo se entregan los webhooks, Verificar la firma y Contenido.

Quién puede hacerlo: los Propietarios y los Editores añaden números, cambian webhooks y ven el secreto del webhook. Los Analistas no ven Números de la bandeja en la barra lateral. Requiere el complemento Unibox: $20 al mes o $200 al año según los precios de lista en EE. UU. por cada número de la bandeja (tu precio aparece en Facturación y planes), que un Propietario añade a un plan de pago o de por vida en Facturación y planes (consulta Complementos). Su cantidad es cuántos números pueden estar en la bandeja a la vez.

Abre Números de la bandeja en Bandeja de entrada en la barra lateral, o ve a /unibox/listeners/.

Antes de empezar#

• El complemento Unibox con un número de bandeja libre: la línea bajo el título de la página dice, por ejemplo, "2 de 3 números de bandeja en uso (complemento Unibox)", o "Sin complemento Unibox" (consulta Sin el complemento Unibox).
• Un número de WhatsApp conectado con un código QR o un código de vinculación, que muestre Conectado en Números de WhatsApp. Los números conectados mediante la extensión del navegador no se pueden añadir. Una cuenta de Telegram conectada se puede añadir como un número.
• Para un webhook: una dirección https:// de 500 caracteres como máximo, accesible desde internet (no localhost ni una red privada), que acepte solicitudes POST con un cuerpo JSON y responda 2xx en 8 segundos.

Añadir un número a la bandeja#

1. Abre el diálogo

   Haz clic en Añadir número a la bandeja en la parte superior derecha de la página.

2. Elige el número

   Elígelo en Número de WhatsApp. La lista muestra tus números conectados que aún no están en la bandeja.

3. Añade un webhook (opcional)

   Escribe tu dirección en URL del webhook (opcional). Entonces aparece Mensajes que se envían: deja marcado Mensajes recibidos, Mensajes enviados o ambos. Puedes añadir o cambiar el webhook más tarde.

   

4. Añádelo

   Haz clic en Añadir número. Verás "Número añadido: sus chats empiezan a sincronizarse en unos minutos." Si escribiste una URL de webhook, se abre Tu secreto del webhook: haz clic en Copiar y guarda el secreto donde tu servidor pueda leerlo. Puedes volver a verlo más tarde en Configuración del webhook.

• Solo mensajes nuevos. Un número se sincroniza desde el momento en que lo añades: los mensajes anteriores no se importan ni se envían.
• ¿Todos los números en uso? El diálogo dice "Todos tus números de bandeja están en uso. Detén o quita uno, o añade más al complemento Unibox." Detén o quita un número, o pide a un Propietario que aumente la cantidad del complemento (Ver complementos).
• Volver a añadir un número quitado recupera su bandeja ("Número añadido de nuevo: sus chats vuelven a sincronizarse a partir de ahora."); los mensajes del tiempo en que estuvo quitado no se recogen. Con una URL de webhook conserva su secreto anterior si lo tenía (usa Mostrar en Configuración del webhook); si no, se abre Tu secreto del webhook con uno nuevo.

Qué muestra la tarjeta de un número#

Cada tarjeta muestra el número, cuándo WbizTool lo revisó por última vez en busca de mensajes ("Última revisión: hace 1 min", o Nunca revisado), sus Mensajes y Contactos sincronizados (todos los chats sincronizados desde él, incluidos los que no tienen mensajes en la bandeja), su Último mensaje y su Webhook: la URL y lo que envía, como "Envía cada mensaje recibido y enviado · firmado con un secreto", o "Ninguno: los mensajes solo aparecen en la bandeja." Una insignia Zapier significa que un Zap recibe los mensajes (consulta Zapier y los números de la bandeja).

La insignia de la parte superior derecha indica lo que está haciendo el número:

Cambiar la URL del webhook o los mensajes que se envían#

1. Abre la configuración del webhook

   Haz clic en Configuración del webhook en la tarjeta del número.

2. Cambia la configuración

   Edita la URL del webhook (opcional) y las marcas de Mensajes que se envían. Para desactivar el webhook, borra la URL.

3. Guarda

   Haz clic en Guardar. Verás "Configuración del webhook guardada."

   

• Cambiar la URL conserva el secreto. Borrar la URL lo elimina; una URL que se añada después recibe un secreto nuevo, que se muestra una vez en Tu secreto del webhook.
• Si no hay ninguna casilla marcada, la tarjeta dice "No hay eventos seleccionados: no se envía nada".

Mostrar o regenerar el secreto#

El secreto tiene 32 letras y dígitos. En Configuración del webhook, bajo Secreto del webhook, Mostrar lo revela con Copiar al lado. Regenerar pregunta "¿Generar un nuevo secreto? El actual deja de funcionar de inmediato: actualízalo allí donde compruebes las firmas." Haz clic en Generar nuevo secreto: se guarda al instante ("Nuevo secreto generado."), sin Guardar, y todas las solicitudes a partir de entonces se firman con él, incluidos los reintentos de mensajes anteriores.

Detener, iniciar o quitar un número#

Los webhooks pendientes de reintento se descartan cuando detienes o quitas el número o cambias su URL.

Cómo se entregan los webhooks#

• Cuándo: cada número de la bandeja se revisa aproximadamente una vez por minuto mientras está conectado; las revisiones se pausan mientras envía mensajes, como una campaña. Un mensaje se envía tras la revisión que lo encuentra, normalmente en uno o dos minutos. No hay botón de prueba: envía un mensaje al número desde otro teléfono.
• Una solicitud por mensaje: message_received para Mensajes recibidos; message_sent para Mensajes enviados, enviados desde el teléfono, WhatsApp Web o por WbizTool (campañas, la API, recordatorios). Las respuestas enviadas desde la bandeja Unibox normalmente no se envían: la bandeja ya las tiene.
• Éxito: cualquier estado 2xx en 8 segundos. Las redirecciones no se siguen: un 3xx cuenta como fallo.
• Reintentos: un tiempo de espera agotado, un error de conexión, 429 o un 5xx se reintentan 3 veces, a los 30 segundos, 1 minuto y 2 minutos. Otras respuestas, como 400 o 404, y un certificado TLS no válido no se reintentan.
• 410 Gone: WbizTool desactiva el webhook del número (se eliminan la URL y el secreto; en un hook de Zapier, vuelve tu propio webhook anterior). El número sigue sincronizándose con la bandeja.
• Orden y repeticiones: las solicitudes pueden llegar desordenadas y, rara vez, dos veces. Ordena por message.whatsapp_timestamp y omite un message.id que ya hayas procesado para el mismo whatsapp_client_id. Si dos de tus números están en un mismo grupo, cada uno envía su propia copia.
• Mensajes tardíos: un mensaje que se recoge tarde, por ejemplo después de que el número se reconecte o de una pausa en las revisiones, se envía igualmente, con replayed en true si tiene más de 10 minutos. Los mensajes que llegaron mientras el número estaba detenido no se envían después de Iniciar (consulta Detener, iniciar o quitar un número).
• Comprobación de la dirección: la URL se vuelve a comprobar antes de cada solicitud; a un host que ahora apunta a una red privada, o que no se resuelve, no se le envía nada, y ese mensaje no se reintenta.

Cabeceras#

Verificar la firma#

Cada solicitud se firma con el secreto del webhook del número usando HMAC-SHA256 sobre el cuerpo sin procesar de la solicitud, exactamente como se recibe. El resumen hexadecimal en minúsculas se envía en X-Wbiztool-Signature como sha256=<digest>. Un webhook configurado en la página Números de la bandeja siempre tiene secreto, así que la cabecera siempre está presente.

Calcula la firma a partir de los bytes sin procesar antes de analizar el JSON. Analizar y volver a codificar el cuerpo lo cambia (espacios, caracteres escapados), y la firma no coincidirá.

// Express: register this route before app.use(express.json()), or the raw body is lost
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WBIZTOOL_WEBHOOK_SECRET;

app.post("/wbiztool/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Wbiztool-Signature") || "";

  const a = Buffer.from(received), b = Buffer.from(expected);
  const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
  if (!valid) return res.status(401).send("Invalid signature");

  const data = JSON.parse(req.body.toString("utf8"));
  if (data.event === "message_received") {
    console.log(`New message from ${data.contact.phone}: ${data.message.content}`);
  }
  res.sendStatus(200); // answer quickly; do slow work in the background
});

app.listen(3000);

# Flask
import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["WBIZTOOL_WEBHOOK_SECRET"].encode()


@app.post("/wbiztool/webhook")
def wbiztool_webhook():
    raw_body = request.get_data()  # raw bytes, before parsing
    expected = "sha256=" + hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Wbiztool-Signature", "")
    if not hmac.compare_digest(expected, received):
        abort(401)

    data = json.loads(raw_body)
    if data["event"] == "message_received":
        print(f"New message from {data['contact']['phone']}: {data['message']['content']}")
    return "", 200

<?php
$secret   = getenv('WBIZTOOL_WEBHOOK_SECRET');
$rawBody  = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$received = $_SERVER['HTTP_X_WBIZTOOL_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($rawBody, true);
if ($data['event'] === 'message_received') {
    error_log('New message from ' . $data['contact']['phone'] . ': ' . $data['message']['content']);
}
http_response_code(200);

Para probar tu receptor antes de que llegue un mensaje real, firma tú mismo un cuerpo y envíalo:

BODY='{"event":"message_received","message":{"content":"Test"},"contact":{"phone":"12125550120"}}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WBIZTOOL_WEBHOOK_SECRET" | sed 's/^.* //')
curl -X POST https://your-server.example/wbiztool/webhook -H 'Content-Type: application/json' -H "X-Wbiztool-Signature: sha256=$SIG" -d "$BODY"

La firma cubre el cuerpo, incluido su timestamp, que es nuevo en cada intento. Para rechazar solicitudes repetidas, rechaza un timestamp de hace más de 5 minutos y omite un message.id que ya hayas procesado.

Contenido#

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:30:31.482913+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0C1A2B3D4E5F60718",
    "type": "chat",
    "content": "Can I add a gift note to it?",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:30:04+00:00",
    "whatsapp_timestamp": 1792060204,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_sent",
  "timestamp": "2026-10-15T10:34:22.117205+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0F9E8D7C6B5A40312",
    "type": "chat",
    "content": "Of course! Send us the text and we'll print it on a card.",
    "from": "12125550120",
    "from_name": "Emma Thompson",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:33:40+00:00",
    "whatsapp_timestamp": 1792060420,
    "direction": "outgoing",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550120",
    "lid": null,
    "phone_hidden": false,
    "name": "Emma Thompson",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:35:48.904311+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected]_3EB0A7B6C5D4E3F20109",
    "type": "image",
    "content": "📸 Image",
    "from": "12125550122",
    "from_name": "Sofia Martinez",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:34:51+00:00",
    "whatsapp_timestamp": 1792060491,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "media": {
      "filename": "",
      "mimetype": "image/jpeg",
      "size": 245760,
      "url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/unibox/10314/media/false_12125550122%40c.us_3EB0A7B6C5D4E3F20109.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=…&X-Amz-Date=20261015T103548Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=…"
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "12125550122",
    "lid": null,
    "phone_hidden": false,
    "name": "Sofia Martinez",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  }
}

{
  "event": "message_received",
  "timestamp": "2026-10-15T10:39:40.330187+00:00",
  "replayed": false,
  "webhook_id": 51,
  "whatsapp_client_id": "101",
  "whatsapp_phone": "12125550101",
  "platform": "whatsapp",
  "message": {
    "id": "[email protected][email protected]",
    "type": "chat",
    "content": "Will there be a larger size?",
    "from": "120363041234567890",
    "from_name": "Lumen VIP Club",
    "to": "12125550101",
    "timestamp": "2026-10-15T10:39:02+00:00",
    "whatsapp_timestamp": 1792060742,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0,
    "sender": {
      "phone": "12125550126",
      "name": "Olivia Brooks",
      "phone_hidden": false
    }
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "120363041234567890",
    "lid": null,
    "phone_hidden": false,
    "name": "Lumen VIP Club",
    "is_group": true,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Lumen & Wick"
  },
  "group": {
    "name": "Lumen VIP Club"
  }
}

Los números, ID y nombres de arriba son ejemplos. El cuerpo real es una sola línea de JSON compacto, y cada carácter no ASCII (letras con acento, otros alfabetos, emojis) llega como un escape \uXXXX, como \ud83d\udcf8 para 📸. Pueden añadirse más campos; ignora los que no uses.

Campos de nivel superior#

Campos de message#

Campos de contact#

Zapier y los números de la bandeja#

El disparador Incoming WhatsApp Message de WbizTool en Zapier usa estos webhooks. Activar un Zap añade el número a la bandeja si hace falta (ocupando uno de tus números de bandeja) y apunta su webhook a Zapier, solo para los mensajes recibidos, con su propio secreto; la tarjeta muestra una insignia Zapier. Tu propia URL de webhook, tu secreto y tus marcas vuelven cuando se desactiva el Zap.

Configuración del webhook avisa entonces: "Este webhook pertenece a un Zap de Zapier. Si cambias o quitas la URL, el Zap deja de recibir mensajes." Detener y Quitar también avisan: el Zap sigue activado en Zapier pero no recibe nada, así que desactívalo en Zapier. Consulta Cómo funciona el disparador con tus números de bandeja.

Sin el complemento Unibox#

La página dice "Sin complemento Unibox" y "El complemento Unibox no está activo en este espacio de trabajo.", y Añadir número a la bandeja abre Complemento Unibox requerido: "Para añadir números de WhatsApp a la bandeja compartida y recibir sus mensajes por webhook, suscríbete al complemento Unibox." Un Propietario hace clic en Ver complementos y añade el complemento Número para Unibox en Facturación y planes, en un plan de pago o de por vida (no en la prueba gratuita).

Cuando el complemento termina o un número se desconecta#

• El complemento termina: todos los números de la bandeja se detienen, al instante o en aproximadamente una hora. Las tarjetas muestran Detenido con "Detenido porque el complemento Unibox no está activo en este espacio de trabajo." Se avisa a los Propietarios y Editores de qué bandejas se detuvieron, en el correo de facturación o en la alerta "Se han detenido algunos números o funciones de …" (Problemas con números y envíos en Notificaciones). Las conversaciones, las URL de webhook y los secretos se conservan: cuando vuelva el complemento, haz clic en Iniciar en cada número. Los mensajes del tiempo en que estuvo detenido se añaden entonces a la bandeja, hasta 30 días atrás, pero no se envían a tu webhook.
• El complemento cubre menos números de los que están activos: "Hay más números activos de los que permite tu complemento. Los extra más recientes se detienen automáticamente en aproximadamente una hora."
• El número se desconecta: la tarjeta muestra Número desconectado y no se sincroniza ni se envía nada. Después de reconectarlo, los mensajes que llegaron mientras tanto también se recogen y se envían; los que tienen más de 10 minutos llevan replayed en true.
• Se reconecta con otro teléfono: el número de la bandeja y su webhook continúan con el número nuevo (mismo whatsapp_client_id, nuevo whatsapp_phone) desde ese momento; los chats antiguos se quedan en la bandeja como historial.

Solución de problemas#

Relacionado#

• Bandeja Unibox: lee y responde los chats de tus números de bandeja
• Integración con Zapier
• Conecta tu número de WhatsApp
• Planes y facturación
• API de envío de mensajes: su campo webhook informa de si un mensaje que envías salió (es un webhook distinto)