Nuevo Safe Mode calienta los números nuevos para reducir el riesgo de bloqueo en WhatsApp. Más información →

Maytapi/Documentación//webhook

/webhookEventos en tiempo real en JSON

API de webhooks de WhatsApp

Recibe en tu propio servidor los mensajes entrantes de WhatsApp, las confirmaciones de entrega y lectura y los cambios de estado de la sesión en el momento en que ocurren. Configura una URL y todos los números conectados envían allí sus eventos en JSON.

  • mensajes entrantes
  • confirmaciones de entrega y lectura
  • estado de la sesión
  • una URL para todos los números
Webhooks de WhatsApp para confirmaciones de entrega y lectura
Configuración del webhook en la consola de Maytapi y el mensaje entrante de WhatsApp entregado al webhook
Eventos

Cuatro tipos de evento, un solo endpoint

Cada evento tiene un campo type, así un único endpoint puede enrutar mensajes, confirmaciones y cambios de estado de todos tus números.

  • type: message

    Mensajes entrantes

    Texto, imágenes, vídeo, audio, documentos, ubicaciones y tarjetas de contacto enviados a tu número, con el remitente y el id de la conversación.

  • type: ack

    Confirmaciones de entrega y lectura

    Sabe cuándo un mensaje enviado se entregó, llegó al teléfono, se vio, se reprodujo o se eliminó.

  • type: status

    Estado de la sesión

    Recibe un aviso cuando un teléfono pasa a activo, espera un escaneo QR, queda inactivo o informa de un error.

  • live chat

    Eventos de chat en vivo

    Si usas la API junto con LiveChat, los eventos de los agentes llegan al mismo webhook.

  • phone_id

    Enrutamiento multinúmero

    Cada evento incluye product_id y phone_id, así un endpoint sirve a todos los números de tu cuenta.

  • reply

    URL de respuesta lista

    Los mensajes entrantes incluyen una URL reply: responder al cliente es una sola petición POST.

Configuración

Configura tu webhook con una petición

Envía tu endpoint HTTPS a /setWebhook una vez. A partir de ahí, cada teléfono conectado a tu producto envía sus eventos a esa URL en JSON.

  • ✓Una URL para todos los números conectados
  • ✓JSON simple mediante HTTPS POST
  • ✓Cámbiala cuando quieras desde el panel o la API
curl -X POST "https://api.maytapi.com/api/$PID/setWebhook" \
  -H "x-maytapi-key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhook": "https://example.com/maytapi/webhook"}'
En directo

Mensajes y confirmaciones al instante

Un cliente escribe y tu servidor lo sabe. Envías un mensaje y las confirmaciones de entrega y lectura llegan en segundos, sin consultas periódicas.

  • ✓Devuelve HTTP 200 para confirmar el evento
  • ✓Procesa los eventos de forma asíncrona con mucho volumen
  • ✓Usa msgId para relacionar confirmaciones y mensajes
message"type": "text", "text": "¿Ya se envió mi pedido?"
ack · delivered"ackCode": 1, "ackType": "delivered"
ack · reached"ackCode": 2, "ackType": "reached"
ack · seen"ackCode": 3, "ackType": "seen"
status"status": "active"
Payloads

Cómo es un evento

Los eventos son objetos JSON compactos. El campo type indica cómo tratarlo; product_id y phone_id indican a qué cuenta y número pertenece.

  • ✓message: texto, multimedia, ubicación, vCard y más
  • ✓ack: progreso de entrega con ackCode y ackType
  • ✓status: active, qr-code, idle, phone-error, loading, disabled
{
  "type": "message",
  "product_id": "1a2b3c4d-…",
  "phone_id": 12345,
  "user": {
    "id": "3461xxxxx67@c.us",
    "name": "Customer",
    "phone": "3461xxxxx67"
  },
  "message": {
    "id": "3EB081AF26FADE6416D8",
    "type": "text",
    "text": "Is my order shipped?",
    "fromMe": false
  },
  "conversation": "3461xxxxx67@c.us",
  "receiver": "3461xxxxx21",
  "timestamp": 1574081887,
  "reply": "https://api.maytapi.com/api/1a2b3c4d-…/12345/sendMessage"
}
Confirmaciones

Entrega y lectura, código a código

Los eventos ack indican hasta dónde llegó cada mensaje enviado. Si no los necesitas, desactívalos con /setAckPreference y recibe solo los mensajes entrantes.

  • ✓Las notas de voz también avisan cuando se reproducen
  • ✓También se notifican los mensajes eliminados
ackTypeackCodeSignificado
delivered1Entregado a los servidores de WhatsApp
reached2Llegó al teléfono del destinatario
seen3Visto por el destinatario
played4Mensaje de voz reproducido
deleted5Eliminado por el usuario
Respuesta

Responde desde el mismo evento

Los mensajes entrantes incluyen una URL reply lista. Confirma el webhook rápido y después envía tu respuesta: un patrón sencillo para respuestas automáticas y chatbots.

  • ✓Funciona con cualquier lenguaje o framework
  • ✓Ignora tus propios mensajes con message.fromMe
app.post("/maytapi/webhook", express.json(), async (req, res) => {
  res.sendStatus(200); // acknowledge first

  const event = req.body;
  if (event.type !== "message" || event.message.fromMe) return;

  await fetch(event.reply, {
    method: "POST",
    headers: { "x-maytapi-key": TOKEN, "Content-Type": "application/json" },
    body: JSON.stringify({
      to_number: event.conversation,
      type: "text",
      message: "Thanks! We received your message."
    })
  });
});
Casos de uso

Qué construyen los equipos con el webhook

  • Sincronización con CRM y helpdesk

    Cada mensaje entrante de WhatsApp se convierte automáticamente en un ticket o una entrada en tu CRM.

  • Chatbots y agentes de IA

    Pasa los mensajes entrantes a tu bot o agente de IA y responde en tiempo real con la URL reply.

  • Seguimiento de entregas

    Guarda las confirmaciones de entrega y lectura para saber qué avisos de pedido vieron realmente los clientes.

  • Monitorización de sesiones

    Avisa a tu equipo cuando un número necesita un nuevo escaneo QR o informa de un error.

  • Automatizaciones sin código

    Apunta el webhook a n8n o Make y crea flujos sin escribir un backend.

  • Bandeja compartida

    Dirige las conversaciones de varios números a la persona adecuada del equipo.

FAQ

Preguntas frecuentes sobre webhooks de WhatsApp

Pregunta lo que quieras a nuestro equipo de soporte por WhatsApp. El tiempo medio de respuesta es inferior a 24 horas.

Centro de ayuda →
¿Qué es un webhook de WhatsApp?

Un webhook es una URL de tu servidor a la que Maytapi llama con una petición HTTPS POST cada vez que ocurre algo en tu número de WhatsApp: un mensaje entrante, una confirmación de entrega o lectura o un cambio de estado de la sesión.

¿Qué eventos llegan a mi webhook?

Mensajes entrantes (type: message), confirmaciones de entrega y lectura (type: ack), cambios de estado de la sesión (type: status) y, si usas la API con LiveChat, eventos del chat en vivo.

¿Necesito una URL HTTPS pública?

Sí. El webhook debe ser accesible desde internet. Durante el desarrollo puedes exponer tu servidor local con un túnel como ngrok.

¿Un webhook puede atender varios números?

Sí. El webhook se configura por producto y cada evento incluye el phone_id, así que un único endpoint sirve a todos los números de tu cuenta.

¿Puedo desactivar las confirmaciones de entrega y lectura?

Sí. Llama a /setAckPreference con ack_delivery en false y tu webhook recibirá solo mensajes entrantes y cambios de estado.

Empieza a usar la API de WhatsApp

Consigue tu clave y envía tu primer mensaje en diez minutos

Sin aprobación, sin plantillas, sin tarjeta. Todos los endpoints abiertos durante tres días.