Integración domótica WhatsApp, gratuita y de código abierto
Hable con Gladys en WhatsApp con la API oficial WhatsApp Business Cloud de Meta.
Publicado por William-De71
- Mensajería
- Versión 0.1.0
- Requiere Gladys >=5.1.0
- ★ 0
Presentación
Hable con Gladys por WhatsApp, con la API oficial WhatsApp Business Cloud de Meta. Cada usuario de Gladys vincula su número de WhatsApp; sus mensajes llegan a Gladys, que le responde por WhatsApp y le envía allí sus notificaciones. Las escenas pueden reaccionar a los mensajes recibidos (botones de plantillas, ubicaciones…) y enviar plantillas de mensaje aprobadas.
La integración usa la nube de Meta (graph.facebook.com): los textos intercambiados con Gladys salen de su red local. Para recibir mensajes hace falta Gladys Plus, que proporciona a Meta una dirección HTTPS pública; sin él, Gladys solo puede enviar.
Requisitos
- Gladys Assistant 5.1.0 o posterior.
- Una aplicación de Meta de tipo Empresa, con el producto WhatsApp, y un número de empresa. El número de prueba que ofrece Meta también funciona, pero solo llega a los 5 números registrados en WhatsApp → Configuración de la API.
- Un usuario del sistema (Configuración del negocio → Usuarios → Usuarios del sistema) que tenga la aplicación y la cuenta de WhatsApp, con un token sin caducidad y los permisos
whatsapp_business_messagingywhatsapp_business_management. El token temporal de la página de configuración de la API caduca a las 24 horas. - Gladys Plus, para recibir mensajes.
- Meta factura los mensajes de una empresa según su tarifa (sobre todo las plantillas enviadas fuera de la ventana de 24 horas).
Configuración
| Campo | Qué introducir |
|---|---|
| Identificador del número de teléfono | El identificador que aparece en WhatsApp → Configuración de la API (no el número) |
| Token de acceso | El token permanente del usuario del sistema |
| Identificador de la cuenta de WhatsApp Business | Opcional: permite a la integración registrar su webhook en Meta y listar sus plantillas |
| Token de verificación | Déjelo vacío: la integración lo genera; péguelo en Meta |
| Registrar el webhook | Activado por defecto: el webhook de la cuenta sigue la URL de Gladys Plus |
| Plantilla de respaldo | Nombre de una plantilla aprobada con una variable en el cuerpo, p. ej. gladys_notification |
| Idioma de la plantilla | Su código de idioma, como en WhatsApp Manager: en_US, fr, de, es… |
| Marcar los mensajes recibidos como leídos | Checks azules para el remitente |
| Idioma de las respuestas | Idioma de las respuestas enviadas antes de vincular un número |
Recibir mensajes: en el bloque Webhooks de Gladys Plus, guarde su clave Open API (Gladys Plus → Ajustes → Open API). Aparece entonces la URL del webhook. En la aplicación de Meta, abra WhatsApp → Configuración, pegue esta URL como URL de devolución de llamada y el token de verificación de la integración como Token de verificación, y suscríbase al campo messages. Si el identificador de la cuenta de WhatsApp Business está indicado, la integración también dirige por sí misma el webhook de la cuenta a esta URL, y de nuevo cada vez que cambia (el botón Registrar el webhook lo hace a petición).
La ventana de 24 horas: WhatsApp solo permite a una empresa enviar texto libre en las 24 horas siguientes al último mensaje del usuario. Cree una plantilla en WhatsApp Manager (categoría Utilidad, una variable en el cuerpo, por ejemplo Gladys: {{1}}), espere a que se apruebe e indique su nombre: fuera de la ventana, Gladys envía sus mensajes con ella. Sin ella, Meta rechaza esos mensajes.
Uso
Vincular su número: en la pantalla de configuración, Vincular mi cuenta → genere un código y envíelo por WhatsApp al número de empresa, en menos de 15 minutos. Gladys responde que su cuenta está vinculada. Después escriba a Gladys como en el chat de Gladys.
Sin Gladys Plus, use el botón Vincular un número sin Gladys Plus: introduzca su número (formato internacional) y el código. Gladys le enviará entonces sus notificaciones con la plantilla de respaldo; sus mensajes no llegan a Gladys.
Los mensajes de texto, los botones pulsados y los pies de foto van a Gladys. Las notas de voz, los stickers y otros medios reciben la respuesta «Por ahora Gladys solo lee mensajes de texto». Los mensajes de números no vinculados se ignoran sin respuesta.
Widget del panel: el widget WhatsApp muestra el nombre verificado del número, su calificación de calidad y su límite de envío, los mensajes enviados, recibidos y fallidos desde medianoche (UTC), el estado del número en Meta, el estado de la recepción, el último evento de Meta y el número de contactos vinculados.
Escenas:
- Disparador Mensaje de WhatsApp recibido: filtros por tipo de mensaje, carga útil de un botón, texto exacto. Variables:
from,contact_name,user,message_type,text,payload,latitude,longitude,emoji,message_id. - Disparador Mensaje de WhatsApp no entregado: el primer fallo para un número, y de nuevo solo después de que un mensaje haya pasado (una escena que le avisa por WhatsApp no puede entrar en bucle). Variables:
to,reason,error_code,error_title,message_id. - Acción Enviar una plantilla de WhatsApp: destinatario (vacío: todos los contactos vinculados), nombre de la plantilla, idioma, parámetros del cuerpo separados por
|(onombre=valorpara los parámetros con nombre). Las variables de escena funcionan en todos los campos.
Ejemplos: cuando se pulsa el botón de plantilla con la carga útil OPEN_GATE → abrir el portón; cuando salta la alarma → enviar la plantilla alerta_alarma a todos; cuando un mensaje no se entrega por el token → enviar un correo.
Solución de problemas
- Probar la conexión muestra el nombre, la calidad y el estado del número, y si la recepción funciona.
- «Meta ha rechazado el token de acceso»: el token ha caducado (token temporal) o se ha revocado. Genere un token permanente para el usuario del sistema.
- No llega nada a Gladys: compruebe que Gladys Plus está vinculado, que la clave Open API está guardada, que la URL y el token de verificación están pegados en Meta y que el campo messages está suscrito. El widget muestra «esperando a Meta» hasta el primer evento.
- Mensaje no entregado, fuera de la ventana (131047): configure una plantilla de respaldo aprobada.
- Número no permitido (131030): con el número de prueba de Meta, añada el destinatario en WhatsApp → Configuración de la API.
- Plantilla rechazada (132000, 132001): compruebe el nombre, el código de idioma y el número de parámetros.
- Pulse Diagnóstico y copie las líneas que empiezan por «WhatsApp diagnostic» de la pestaña Registros en una issue de GitHub: el token, la clave Open API y los números se omiten o se enmascaran.
Parámetros de configuración
Estos son los parámetros que WhatsApp te pide en su pantalla de configuración en Gladys.
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| Conectar su cuenta de WhatsApp Business | section | No | 1. Cree una aplicación de Meta de tipo Empresa y añádale el producto WhatsApp. 2. En WhatsApp → Configuración de la API, copie el identificador del número de teléfono y el de la cuenta de WhatsApp Business. 3. En la configuración del negocio, cree un usuario del sistema, asígnele la aplicación y la cuenta de WhatsApp y genere un token sin caducidad con los permisos whatsapp_business_messaging y whatsapp_business_management. |
| Identificador del número de teléfono | string | Sí | El identificador del número de empresa en WhatsApp → Configuración de la API (no el número en sí). |
| Token de acceso | secret | Sí | Token permanente del usuario del sistema. El token temporal de la página de configuración de la API caduca a las 24 horas. Se guarda cifrado y no se vuelve a mostrar. |
| Identificador de la cuenta de WhatsApp Business | string | No | Opcional. Con él, la integración dirige por sí misma el webhook de la cuenta hacia Gladys Plus, y el diagnóstico lista sus plantillas de mensaje. |
| Recibir mensajes (Gladys Plus) | section | No | Meta entrega los mensajes a una dirección HTTPS pública: Gladys Plus la proporciona. Guarde su clave Open API en el bloque «Webhooks de Gladys Plus» de abajo y, en la aplicación de Meta (WhatsApp → Configuración), pegue como URL de devolución de llamada la URL del webhook que aparece allí y el token de verificación de abajo, y suscríbase al campo «messages». Sin Gladys Plus, Gladys solo puede enviar. |
| Token de verificación | string | No | La integración lo genera si está vacío. Pegue el mismo valor en la aplicación de Meta (WhatsApp → Configuración → Token de verificación). |
| Registrar el webhook en Meta automáticamente | boolean | No | Necesita el identificador de la cuenta de WhatsApp Business. Se repite cada vez que cambia la URL de Gladys Plus. |
| Fuera de la ventana de 24 horas | section | No | WhatsApp solo permite a una empresa enviar texto libre en las 24 horas siguientes al último mensaje del usuario. Pasado ese plazo, solo pasa una plantilla de mensaje aprobada. Cree una plantilla de categoría Utilidad con una sola variable en el cuerpo, p. ej. «Gladys: {{1}}», e indique su nombre abajo: Gladys enviará entonces sus notificaciones con ella. |
| Plantilla de respaldo | string | No | Nombre de la plantilla aprobada (minúsculas, cifras, guiones bajos). Vacío: los mensajes fuera de la ventana no se entregan. |
| Idioma de la plantilla | string | No | Código de idioma de la plantilla, como en WhatsApp Manager: en_US, fr, de, es… |
| Marcar los mensajes recibidos como leídos | boolean | No | El remitente ve los dos checks azules en cuanto Gladys tiene el mensaje. |
| Idioma de las respuestas | select | No | Idioma de las pocas respuestas que la integración envía por sí misma antes de vincular un número (código de vinculación aceptado o rechazado). |
Cómo instalar WhatsApp en Gladys
- En Gladys, abre Integraciones: WhatsApp aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
- Haz clic en Instalar. Gladys descarga la imagen Docker (
ghcr.io/william-de71/gladys-whatsapp:0.1.0), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración). - Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
- También puedes instalarla directamente desde la URL de su repositorio: https://github.com/William-De71/gladys-whatsapp.
WhatsApp requiere Gladys >=5.1.0. El catálogo de Gladys se actualiza cada hora, así que una nueva versión está disponible como máximo una hora después de publicarse.
¿Todavía no usas Gladys? Es gratuito y de código abierto: sigue la guía de instalación para empezar.
Sobre las integraciones externas
WhatsApp es una integración externa: una integración comunitaria empaquetada como contenedor Docker y publicada en GitHub. Gladys la instala con un clic y la ejecuta en un entorno aislado del núcleo. La publica y mantiene William-De71, no el equipo principal de Gladys.
- Explorar todas las integraciones, nativas y de la comunidad
- Crear y publicar tu propia integración externa
- Código fuente en GitHub — fuente de esta documentación