Saltar al contenido principal

Integración domótica Twilio, gratuita y de código abierto

Integración Twilio para Gladys Assistant

SMS y llamadas de voz desde sus escenas de Gladys con su cuenta Twilio, con control de gastos.

Ver en GitHubTodas las integraciones

Envíe SMS y haga llamadas de voz desde sus escenas de Gladys con su propia cuenta Twilio: un SMS a la familia cuando salta el detector de fugas de agua, una llamada que lee la alarma en voz alta cuando nadie mira el teléfono, una llamada al vecino cuando un familiar mayor no contesta. Útil donde una notificación de aplicación no basta, o sin Internet móvil.

Esta integración no está afiliada a Twilio. Twilio factura cada SMS y cada llamada a su cuenta: un control de gastos limita lo que Gladys puede enviar por hora y por día.

Desarrollada sin el hardware: sus comentarios son bienvenidos (Developed without the hardware: feedback welcome). Esta integración se escribió a partir de la API documentada de Twilio, sin una cuenta Twilio real. Si algo no funciona como se describe, dígalo en el foro de Gladys o en las issues.

Lo que necesita​

  • Gladys Assistant 5.1.0 o posterior.
  • Una cuenta Twilio con saldo y un número Twilio capaz de enviar SMS y hacer llamadas a los países que necesite. Una cuenta de prueba funciona, con sus límites: solo llega a los números verificados en Twilio, y sus mensajes empiezan con un aviso de Twilio.
  • El Account SID (en la página de inicio de la consola de Twilio, AC…).
  • Preferiblemente una clave de API: en la consola de Twilio, Account → API keys & tokens → Create API key, tipo Standard. Anote su SID (SK…) y su secreto, que solo se muestra una vez. Sin clave de API, el Auth Token de la cuenta también funciona, pero da acceso completo a la cuenta.
  • En la consola de Twilio, los permisos geográficos de SMS y de voz deben autorizar los países de sus destinatarios.

Configuración​

  1. Instale la integración desde el catálogo de Gladys.
  2. En Configuración, indique el Account SID, el SID de la clave de API y el Secreto de la clave de API (o el Auth Token), y el Remitente: su número Twilio en formato internacional, p. ej. +34612345678.
  3. Destinatarios por defecto: los números que se usan cuando una acción no indica ninguno, separados por comas, el más importante primero. Siempre en formato internacional (+ y prefijo del país): 612 34 56 78 se rechaza, porque el país no se puede adivinar.
  4. Ajuste el control de gastos (ver más abajo), la Voz y el Tiempo de llamada de las llamadas, y el Idioma (francés por defecto).
  5. Guarde y pulse Probar la conexión: el mensaje bajo el botón indica la cuenta, su tipo, su saldo, si el remitente pertenece a la cuenta y el consumo del día.
  6. Pulse Enviar un SMS de prueba (a los destinatarios por defecto, o al número que escriba) para comprobar todo el recorrido.
  7. Abra la pestaña Descubrir y añada el dispositivo Cuenta Twilio.

El remitente también puede ser el SID de un Messaging Service (MG…) o un nombre de remitente alfanumérico (Gladys, 11 caracteres como máximo, donde el país de destino lo permita). Ambos solo sirven para SMS: una llamada siempre requiere un número Twilio.

Control de gastos​

Cuatro límites: Máximo de SMS por hora, Máximo de SMS por día, Máximo de llamadas por hora, Máximo de llamadas por día (10, 30, 5 y 10 por defecto). La hora es móvil, el día es el día natural en la zona horaria de Gladys. Cada destinatario cuenta como un SMS. Por encima de un límite no sale nada más hasta que se libere la ventana: los primeros destinatarios de una lista pasan primero, los demás se retienen. Un límite de 0 bloquea ese tipo de envío. Los contadores se guardan en /data y sobreviven a un reinicio. Solo cuentan los envíos aceptados por Twilio: una solicitud rechazada no se factura.

El dispositivo «Cuenta Twilio»​

FuncionalidadLo que muestra
SaldoEl saldo de la cuenta, en su moneda, leído cada 15 minutos.
SMS enviados hoyLos SMS aceptados por Twilio desde medianoche.
Llamadas de hoyLas llamadas aceptadas por Twilio desde medianoche.
Último falloFecha, SMS o llamada, número enmascarado y motivo del último fallo, o Ningún fallo.

Los euros, dólares y libras tienen su unidad; otra moneda muestra solo el importe. El saldo solo aparece cuando Twilio permite leerlo: una clave de API restringida puede no verlo, lo que no impide enviar.

Widget del panel​

El widget Twilio muestra el saldo, los SMS y las llamadas del día frente a los límites diarios (en naranja una vez alcanzados), el estado de la cuenta y el último fallo, con un enlace a la consola de Twilio para recargar el saldo. No envía nada por sí mismo.

Escenas​

Acciones​

Enviar un SMS: un SMS a cada destinatario (10 como máximo). Destinatarios: números separados por comas, vacío para los destinatarios por defecto. Mensaje: hasta 1600 caracteres, con las variables de la escena (escriba {{ para insertar una). Resultados para los pasos siguientes: SMS enviados, Retenidos por el control de gastos, Rechazados por Twilio.

Hacer una llamada: llama a un número (vacío: el primer destinatario por defecto) y lee el Mensaje leído (hasta 1000 caracteres) con una voz sintética. El Idioma (inglés, francés, alemán o español) y la Voz (femenina o masculina) son por defecto los de la configuración; el mensaje se lee de 1 a 3 veces. Con Esperar la respuesta marcado (por defecto), la escena espera a saber si se contestó, como máximo el tiempo de llamada más 20 segundos. Resultados: Contestada (sí o no), Resultado de la llamada y SID de la llamada. El resultado es uno de:

  • answered: alguien (o un buzón de voz) contestó;
  • no-answer, busy, failed, canceled: la llamada no se completó (sin respuesta, ocupado, fallida, cancelada);
  • refused: Twilio rechazó la llamada (vea Último fallo);
  • blocked: retenida por el control de gastos;
  • pending: aún no se sabe (no se esperó, o sigue sonando al vencer el plazo).

Un fallo del lado de Twilio nunca detiene la escena: compruebe los resultados con una Condición sobre variables. Solo falla una acción que no puede ejecutarse (sin configuración, sin destinatario, mensaje vacío, un número que no está en formato internacional).

Disparadores​

SMS o llamada fallida: un SMS o una llamada no llegó a su destinatario. Filtros: SMS o llamada, Resultado (rechazado por Twilio, fallido, SMS no entregado, sin respuesta, línea ocupada, cancelado), Destinatario. Variables: SMS o llamada (sms o call), Destinatario, Resultado, Motivo (en el idioma configurado), Código de error de Twilio. Twilio confirma la entrega a posteriori: un SMS se vuelve a leer a los 1, 5 y 20 minutos, una llamada tras su tiempo de llamada.

Límite del control de gastos alcanzado: se retuvieron SMS o llamadas por un límite. Filtros: SMS o llamada, Límite (por hora o por día). Variables: el tipo, el límite (hour o day), su valor y el número de retenidos. Se dispara una vez por episodio, no en cada intento: puede avisarle por otro canal sin saturarlo.

Ideas de escenas​

  • Fuga de agua: con el detector de fugas, Enviar un SMS «¡Fuga de agua en el sótano!» a la familia, y luego Hacer una llamada al primer destinatario por defecto.
  • Nadie contesta: Hacer una llamada a un familiar con Esperar la respuesta, luego una Condición sobre variables: Contestada es falso, y luego Hacer una llamada al vecino.
  • Algo está en bucle: con Límite del control de gastos alcanzado, envíe un mensaje por la aplicación Gladys u otro canal para buscar qué escena envía tanto.

Costes y límites de Twilio​

  • Twilio factura cada SMS por segmento: 160 caracteres, o 70 en cuanto el texto contiene un carácter fuera del alfabeto GSM (ê, ç, œ, un emoji). Un texto de 1600 caracteres puede suponer 23 SMS. Las llamadas se facturan por minuto iniciado; una llamada se corta a los 3 minutos.
  • Las voces son voces estándar de Amazon Polly proporcionadas por Twilio; vea las tarifas de Twilio para la síntesis de voz.
  • Solicitudes a api.twilio.com: la cuenta y su saldo cada 15 minutos (dos lecturas), una solicitud por SMS o llamada, y luego algunas lecturas para seguir su resultado (cada 3 segundos mientras se espera una llamada). Muy por debajo de los límites de la API de Twilio; una respuesta 429 se indica como «demasiadas solicitudes».
  • Twilio hace como máximo una llamada por segundo y por cuenta, y pone los SMS en cola al ritmo del remitente: una lista de 10 destinatarios tarda unos segundos.
  • Se aplican la política de uso aceptable de Twilio y sus normas por país: escriba solo a personas que lo hayan aceptado; un destinatario que respondió STOP queda bloqueado por Twilio.

Solución de problemas​

  • «credenciales rechazadas por Twilio»: compruebe el Account SID y el secreto de la clave de API (o el Auth Token). Una clave de API debe pertenecer a la misma cuenta.
  • «cuenta de prueba: verifique primero este número en Twilio»: añada el destinatario a los números verificados de la consola de Twilio, o pase la cuenta a de pago.
  • «país no autorizado en los permisos geográficos de Twilio»: active el país en la consola de Twilio, para SMS y para voz.
  • «el remitente no es un número de su cuenta Twilio»: copie el número desde Phone Numbers → Active numbers, en formato internacional.
  • «no entregado (Twilio 30003)» y otros códigos 30xxx: el operador no pudo entregar el SMS (teléfono apagado, filtrado como spam, línea fija). El código se explica en https://www.twilio.com/docs/api/errors/<code>.
  • No sale nada y el widget muestra un contador en naranja: el control de gastos actúa; suba el límite o espere a que se libere la ventana.
  • Registros detallados: configure LOG_LEVEL=debug en la integración. Los números siempre se enmascaran en los registros, los secretos nunca se escriben.

Limitaciones​

  • Sin SMS entrantes. Twilio entrega los mensajes entrantes llamando a una URL pública; Gladys no está expuesto a Internet, y el relé de webhooks de Gladys Plus no transmite la cabecera X-Twilio-Signature, por lo que no se podría autenticar al remitente de un mensaje. Por eso no se admiten los SMS entrantes.
  • Un buzón de voz que contesta cuenta como answered: ajuste un Tiempo de llamada más corto para colgar antes.
  • Sin MMS (imágenes) ni WhatsApp: solo SMS y voz.
  • Los nombres de las funcionalidades se fijan al añadir el dispositivo, en el idioma configurado en ese momento.
  • Desarrollada sin cuenta Twilio: las respuestas de la API proceden de la documentación de Twilio, no de una cuenta real.

Parámetros de configuración​

Estos son los parámetros que Twilio te pide en su pantalla de configuración en Gladys.

ParámetroTipoObligatorioDescripción
Su cuenta TwiliosectionNoTwilio factura cada SMS y cada llamada a su cuenta: ajuste el control de gastos más abajo. El Account SID está en la página de inicio de la consola de Twilio; una clave de API es más segura que el Auth Token.
Account SIDstringSíEmpieza por AC y sigue con 32 caracteres.
SID de la clave de API (recomendado)stringNoUna clave de API Standard, que empieza por SK. Déjelo vacío para usar el Auth Token.
Secreto de la clave de APIsecretNoTwilio lo muestra una sola vez al crear la clave.
Auth TokensecretNoSolo sin clave de API. Da acceso completo a la cuenta.
RemitentestringSíSu número Twilio en formato internacional. Un nombre de remitente o un Messaging Service (MG…) solo sirve para SMS.
Destinatarios por defectostringNoNúmeros internacionales separados por comas, el más importante primero. Se usan cuando una acción no indica ninguno.
Control de gastossectionNoPor encima de estos límites no se envía nada hasta que se libere la ventana: una escena en bucle no puede vaciar su cuenta. Cada destinatario cuenta como un SMS. 0 bloquea.
Máximo de SMS por horanumberNo
Máximo de SMS por díanumberNo
Máximo de llamadas por horanumberNo
Máximo de llamadas por díanumberNo
Llamadas y textossectionNoUna llamada lee el mensaje con una voz sintética, en el idioma elegido en la acción o más abajo.
VozselectNo
Tiempo de llamadaselectNoColgar antes evita el buzón de voz, que cuenta como respuesta.
IdiomaselectNoDe las llamadas, del SMS de prueba, de los nombres del dispositivo y de los textos de fallo.

Cómo instalar Twilio en Gladys​

  1. En Gladys, abre Integraciones: Twilio aparece en el catálogo junto a las integraciones nativas, con una insignia de comunidad.
  2. Haz clic en Instalar. Gladys descarga la imagen Docker (ghcr.io/guim31/gladys-twilio:1.0.1), la ejecuta en un entorno aislado del núcleo y genera la interfaz de la integración (dispositivos, descubrimiento y configuración).
  3. Abre la pantalla de Configuración de la integración, rellena los parámetros y guarda.
  4. También puedes instalarla directamente desde la URL de su repositorio: https://github.com/guim31/gladys-twilio.

Twilio 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​

Twilio 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 guim31, no el equipo principal de Gladys.

Suscríbete a la newsletter de Gladys Assistant

Unos pocos correos al mes sobre nuevas versiones y novedades del proyecto. Enviados por Pierre-Gilles Leymarie, fundador del proyecto. Puedes darte de baja cuando quieras 🙂
Última actualización en