🚀 Wati AI ya está aquí – La Capa de Inteligencia Conversacional para Empresas Modernas Explorar🚀 Wati AI ya está aquí →

API de Webhooks de WhatsApp

API de webhook de WhatsApp: entérate en el momento en que algo cambie.

Nuevos mensajes, confirmaciones de entrega y lectura, clics en botones, envíos fallidos y revisiones de plantillas llegan a tu URL en formato JSON. 19 tipos de eventos, con reintentos si tu servidor no está disponible.

Última actualización

  • Más de 16,000empresas en más de 190 países
  • 4.6/5calificación promedio en G2
  • OficialMeta Business Partner y BSP de WhatsApp
G2 Leader, ChatbotsG2 Leader Mid-Market, ChatbotsG2 Momentum Leader, ChatbotsG2 Most Implementable, WhatsApp MarketingISO 27001GDPR

Una URL. Cada estado, al instante.

Deja de hacer sondeos. Wati envía el evento y espera tu 200.

  • Comienza con una plantillaUna plantilla aprobada abre la conversación, ya sea para un cliente o para 10,000.
  • Continúa en el chatTexto, contenido multimedia y botones una vez que el cliente responde.
  • Termina con tu equipoLos webhooks informan a tu código. La bandeja de entrada del equipo informa a tu personal.
El producto

Envía. Responde. Recibe. Deriva.

Webhooks

Cada respuesta, en el momento en que llega.

Los webhooks envían nuevos mensajes, confirmaciones de lectura, clics y errores a tu URL. Sin sondeos (polling).

Difusiones

Mensajes personales, enviados a escala.

Elige una plantilla aprobada y envíala hasta a 10 000 destinatarios. Cada persona recibe sus propias variables y cada resultado se devuelve por número.

Mensajería

Responde con algo más que texto.

Dentro de la ventana de 24 horas, envía texto, imágenes, archivos, botones de respuesta y selectores de lista, con un indicador de escritura mientras trabajas.

Actualizaciones de pedidos y alertas

La actualización correcta, cuando ocurre.

Tu tienda, sistema de reservas o facturación envía una plantilla aprobada cuando algo cambia. Los clientes tocan un botón o responden.

Respuesta automática y chatbots

Tu código responde.

El webhook de mensajes lleva cada nuevo mensaje a tu servidor. Responde con los endpoints de envío o inicia un chatbot de Wati en los planes Pro y Business.

Bandeja de entrada del equipo

El código lo empieza. Las personas lo terminan.

Las respuestas llegan a la bandeja de entrada del equipo de Wati. Asigna un operador, establece el estado y añade etiquetas mediante la API para que la persona correcta lo gestione.

Contactos y segmentos

Tu CRM, reflejado en Wati.

Crea y actualiza contactos con atributos personalizados, y luego visualiza una vista previa de un segmento antes de enviarle un mensaje.

InstagramComentarios y mensajes directos de Instagram

Crea también automatización para Instagram.

Enumera comentarios en tus publicaciones, responde en público o envía una respuesta privada.

Empieza ahora

En funcionamiento en tres pasos.

  1. Conectar

    Conecta tu número

    Vincula tu número de WhatsApp mediante el Registro integrado de Meta dentro de Wati.

  2. Autenticar

    Obtén un token

    Crea un token de API en Wati y asígnale únicamente los permisos que necesites. Guárdalo en tu servidor.

  3. Enviar

    Haz tu primera llamada

    Envía una plantilla aprobada con una sola solicitud. Después, añade un webhook para hacer un seguimiento de la entrega.

Tu primera solicitud, explicada

Esto es lo que incluye una solicitud y dónde aparece cada parte en el mensaje.

  1. Quién

    El número de WhatsApp del cliente, con el código de país.

    phone_number14155552671
  2. Qué mensaje

    El nombre de una plantilla que Meta haya aprobado en tu cuenta.

    template_nameorder_update
  3. Qué rellenar

    Los valores para los espacios en blanco de la plantilla, uno por persona.

    custom_paramsname = Mayaorder_id = 10482
  4. Tu clave

    Tu token de API, que se envía con cada solicitud. Guárdalo en tu servidor.

    Authorization: Bearer <token>
  5. Lo que recibes

    Un código 200 significa que Wati aceptó el mensaje, junto con un broadcast_id. El estado de entregado y leído llega más tarde mediante un webhook.

    200broadcast_id

El texto del mensaje y order_update son ejemplos. La redacción la define tu plantilla aprobada.

Código listo para copiarOcultar el código
WEBHOOKevento de mensaje entrante, POST /api/ext/v3/conversations/messages/text saliente
# 1. Wati envía mediante POST cada nuevo mensaje a tu URL de webhook (evento: message).
# 2. Tu código toma la respuesta y la devuelve:
curl -X POST "https://live-mt-server.wati.io/api/ext/v3/conversations/messages/text" \
  -H "Authorization: Bearer $WATI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "14155552671",
    "text": "Sí, estamos abiertos de 9 a. m. a 9 p. m."
  }'
200 Ejemplo de respuestaEjemplo de documentación, recortado
{
  "id": "507f1f77bcf86cd799439011",
  "wa_id": "14155552671",
  "name": "Maya",
  "phone": "+14155552671",
  "opted_in": true,
  "custom_params": [
    { "name": "city", "value": "Singapore" },
    { "name": "customer_tier", "value": "vip" }
  ],
  "channel_type": "whatsapp"
}
Integrado

Lo que Wati gestiona para que tú no tengas que hacerlo.

Incorporación de números

Conéctate a través del Registro Integrado de Meta. La cuenta de WhatsApp Business se registra para tu empresa.

Estado de las plantillas

Los cambios de aprobación, calidad y categoría llegan como webhooks, para que lo sepas antes de que un envío falle.

Reintentos de webhooks

Hasta 144 reintentos, cada 10 minutos. Si tu endpoint sigue fallando, Wati te envía un correo electrónico.

Límites de frecuencia y colas

Si vas demasiado rápido, obtienes un 429 con una cabecera Retry-After. Los mensajes aceptados esperan en una cola.

Transferencia a humanos

Una bandeja de entrada de equipo compartida para las conversaciones que tu código no debería responder a solas.

Tokens de API con ámbito

v3 es compatible con tokens con ámbito, por lo que cada integración obtiene únicamente el acceso que necesita.

Envíos programados

Programa el envío de una plantilla para más tarde con una sola llamada. Wati la envía a tiempo.

Estimación de costos previa

Calcula el costo de una difusión antes de enviar nada.

Bajo el capó

Los endpoints, por capacidad.

Plantillas

Inicia conversaciones con plantillas aprobadas, ahora o de forma programada.

Documentación →
GET/messageTemplatesPOST/messageTemplates/sendPOST/messageTemplates/schedule

Difusiones

Lee los resultados de las campañas y el estado por destinatario, y calcula el costo primero.

Documentación →
GET/broadcastsGET/broadcasts/{broadcast_id}/recipientsPOST/broadcasts/estimate-cost

Mensajería

Responde con texto, contenido multimedia o botones dentro de la ventana de 24 horas.

Documentación →
POST/conversations/messages/textPOST/conversations/messages/fileViaUrlPOST/conversations/messages/interactivePOST/conversations/typingIndicator

Chatbots Pro+

Enumera tus chatbots de Wati e inicia uno para un contacto.

Documentación →
GET/chatbotsPOST/chatbots/start

Webhooks

Gestiona las suscripciones y enumera los tipos de eventos que puedes recibir.

Documentación →
GET/webhooksGET/webhooks/event-typesPUT/webhooks/{id}

Contactos y segmentos

Sincroniza contactos y atributos desde tu CRM y, a continuación, segmenta tu audiencia.

Documentación →
POST/contactsPUT/contactsPOST/segments/evaluate

Bandeja de entrada del equipo

Asigna un operador, cambia el estado, y añade o elimina etiquetas.

Documentación →
PUT/conversations/{target}/operatorPUT/conversations/{target}/statusPOST/conversations/{target_conv}/tags

Instagram

Enumera publicaciones y comentarios, responde en público o en privado, y comprueba los permisos.

Documentación →
GET/posts/{post_id}/commentsPOST/comments/{comment_id}/repliesPOST/comments/{comment_id}/privateReplyGET/channels/{channel}/permissions

Las rutas son relativas a https://live-mt-server.wati.io/api/ext/v3. La creación de un webhook utiliza la ruta heredada POST /{tenantId}/api/v2/webhookEndpoints.

Para los agentes de IA, el servidor Wati MCP cubre las mismas acciones de WhatsApp y puede responder a mensajes directos de Instagram y chats de Messenger con texto.

Ver los 19 tipos de eventos de webhooks de WhatsApp

Mensajes

  • message
  • newContactMessageReceived
  • sessionMessageSent_v2
  • templateMessageSent_v2

Estado de entrega

  • sentMessageDELIVERED_v2
  • sentMessageREAD_v2
  • sentMessageREPLIED_v2
  • templateMessageFailed

Plantillas y cuenta

  • templateReviewed
  • templateQualityUpdated
  • templateCategoryUpdated
  • wabaStatusReviewUpdate
  • PhoneNumberQualityUpdatedEvent
  • accountUpdated
  • accountDeleted
  • phoneNumberDeleted

Interacción y llamadas

  • chatbotTriggered
  • ctaUrlClicked
  • call.status

Las versiones BSUID de varios eventos también están disponibles. Documentación de webhooks

Límites y planes

Límites claros. Publicados.

30 a 100 por cada 10 s

Envíos de plantillas

Llamadas para enviar plantillas, según tu plan (Growth, Pro o Business).

10 000 destinatarios

Por llamada de envío de v3

Una plantilla, hasta 10 000 personas, cada una con sus propias variables.

24 h de ventana

Respuestas de formato libre

El texto, el contenido multimedia y los botones requieren una ventana de servicio de atención al cliente abierta. Fuera de ella, envía una plantilla.

429 Retry-After

Cuando vas demasiado rápido

Wati te indica cuánto tiempo debes esperar. Los mensajes aceptados se procesan en una cola.

Límites de frecuencia y disponibilidad de planes en detalle
Límites de frecuencia documentados por plan
EndpointGrowthProBusiness
/addContact, /getContacts10 / 10 s10 / 10 s10 / 10 s
/getMessages10 / 10 s10 / 10 s10 / 10 s
/sendTemplateMessage30 / 10 s60 / 10 s100 / 10 s
/sendTemplateMessages30 / 10 s60 / 10 s100 / 10 s

Límites publicados en Errors & Rate Limits, organizados por nombre de endpoint. La llamada masiva de v1 admite hasta 1000 contactos. Los endpoints principales de mensajería, plantillas y contactos están incluidos en todos los planes. La asignación de equipos, el estado del chat, los chatbots y los segmentos personalizados requieren Pro o Business. La actualización de atributos para muchos contactos a la vez requiere Business. Disponibilidad de endpoints por plan. Para límites más altos, habla con Wati sobre tu caso de uso.

Preguntas frecuentes

Preguntas frecuentes

La referencia completa de la API es pública. Leer la documentación

¿Qué eventos pueden enviar los webhooks de Wati?

19 tipos de eventos de WhatsApp, incluidos message, sentMessageDELIVERED_v2, sentMessageREAD_v2, sentMessageREPLIED_v2, templateMessageFailed, templateReviewed, ctaUrlClicked, chatbotTriggered y call.status. GET /webhooks/event-types enumera los disponibles para tu espacio de trabajo.

¿Qué pasa si mi servidor está caído?

Wati espera un HTTP 200 para cada evento. Si no lo recibe, vuelve a intentarlo hasta 144 veces, cada 10 minutos. Si un webhook sigue fallando, Wati lo marca como defectuoso y te envía un correo electrónico.

¿Cómo configuro un webhook de WhatsApp?

Registra tu URL y elige los tipos de evento en el panel de Wati o mediante la API. Puedes listar, actualizar y eliminar suscripciones con los endpoints v3 de /webhooks. Mantén el controlador rápido: responde con un 200 primero y luego realiza el procesamiento.

¿Necesito saber programar?

Menos que antes. Los creadores de aplicaciones con IA pueden escribir las llamadas a la API a partir de instrucciones en lenguaje sencillo, y los ejemplos de esta página muestran cada llamada.

Aún necesitas un número de WhatsApp conectado a Wati, un token de API y una plantilla aprobada por Meta antes de poder iniciar una conversación. Si una herramienta de IA escribe el código, asegúrate de que tu token permanezca en el servidor.

¿Cuáles son los límites de velocidad de la API?

Las llamadas de contactos y del historial de mensajes están limitadas a 10 solicitudes cada 10 segundos en todos los planes. Los envíos de plantillas están limitados a 30, 60 o 100 solicitudes cada 10 segundos en Growth, Pro y Business. Cuando alcanzas un límite, obtienes un HTTP 429 con una cabecera Retry-After. Para límites más altos, ponte en contacto con Wati.

¿Puedo enviar un mensaje a un cliente en cualquier momento?

En WhatsApp, los textos de formato libre, los archivos multimedia y los mensajes interactivos requieren una ventana de servicio al cliente abierta de 24 horas. Fuera de esa ventana, inicia la conversación con una plantilla aprobada por Meta.

¿Cuál es la diferencia entre la aplicación WhatsApp Business y la API?

La aplicación Business es para chats manuales en un teléfono, con hasta 5 dispositivos vinculados y listas de difusión limitadas a 256 contactos. La API conecta WhatsApp a tus propios sistemas. Puedes enviar plantillas aprobadas a gran escala, automatizar respuestas, recibir webhooks y compartir un solo número en una bandeja de entrada para equipos.

¿Qué endpoints se incluyen en mi plan?

La mensajería principal, las plantillas y los endpoints de contacto se incluyen en todos los planes. La asignación de equipos, el estado del chat, los chatbots y los segmentos personalizados requieren Pro o Business. La documentación enumera la disponibilidad de endpoints por plan.

Tu primer mensaje está a solo una solicitud de distancia.

Comienza gratis, conecta tu número de WhatsApp en Wati y realiza tu primera llamada.