Conectar cualquier proveedor de SMS (proveedor HTTP genérico)

MonoPbx envía y recibe SMS a través de un proveedor. Twilio viene integrado. Para cualquier otro proveedor que tenga una API HTTP no necesita código: en la consola de administración describe la solicitud que envía un mensaje, cómo leer la respuesta del proveedor y cómo leer sus callbacks (mensajes entrantes e informes de entrega). Todo lo siguiente se hace en la consola web; nada requiere la API.

Necesita el rol Propietario (o un rol personalizado con el permiso integrations:write). Enviar mensajes también requiere messaging:write.

:::info Las credenciales solo se escriben El token de API y el secreto del callback que escribe aquí se cifran con la clave de su empresa al guardar. Nunca se vuelven a mostrar, ni siquiera a usted, y nunca aparecen en la vista previa, en el registro de auditoría ni en un mensaje de error. Para cambiarlos debe escribirlos todos de nuevo. :::

El proveedor de ejemplo

El tutorial usa un proveedor ficticio, "ExampleSMS", con esta API:

POST https://api.examplesms.com/v2/messages
Authorization: Bearer <token>
{"from": "+15550100199", "to": "+15550100100", "text": "hi", "ref": "<your id>"}
-> 200 {"data": {"id": "msg_91"}}                      accepted
-> 400 {"error": {"code": "INVALID_DEST"}}             refused for good
-> 429 or 5xx                                          try later
Callbacks (POST, header X-Signature: sha256=<hex hmac of the body>):
{"events": [{"kind": "mo", "id": "in_5", "from": "15550100100", "to": "15550100199", "text": "yes"},
            {"kind": "dlr", "message": "msg_91", "state": "DELIVRD"}]}

1. Agregar el proveedor

Abra Consola de administración, SMS (la página se titula Proveedores de SMS) y elija Nuevo proveedor.

1. Nombre: ExampleSMS.
2. Tipo: Proveedor HTTP genérico. Se abre el formulario de la solicitud.

2. Describir la solicitud

En Solicitud al proveedor:

Campo	Valor
Método	POST
URL	https://api.examplesms.com/v2/messages
Nombre y valor del encabezado (elija Agregar encabezado)	Authorization y Bearer {{secret.api_token}}
Formato del cuerpo	json
Plantilla del cuerpo	{"from":"{{from}}","to":"{{to}}","text":"{{body}}","ref":"{{message_id}}"}

Los marcadores se escriben entre dobles llaves. Puede usar from, to, body, message_id, segments, timestamp y secret.NOMBRE para una credencial. El esquema, el host y el puerto de la URL deben ser texto plano (sin marcadores), y la dirección debe ser HTTPS público: las direcciones privadas y locales siempre se rechazan.

Cada secret.NOMBRE que use agrega un campo de contraseña en Credenciales, al final del formulario.

3. Describir la respuesta

En Lectura de la respuesta:

1. Ruta del id de mensaje del proveedor: $.data.id. Así los informes de entrega encuentran el mensaje después.
2. Elija Agregar regla y configure Estados HTTP como 400, Resultado como Rechazado definitivamente y Ruta del código como $.error.code.

Sin reglas, una respuesta 2xx se acepta, las respuestas 408, 425, 429 y 5xx se reintentan más tarde, y cualquier otra se rechaza.

4. Describir los callbacks

En Callbacks del proveedor, marque El proveedor nos llama de vuelta.

1. Firma: Provider HMAC-SHA256. Configure Encabezado de la firma como X-Signature, Texto antes de la firma como sha256= y deje la codificación en hex.
2. Si el proveedor también envía una marca de tiempo firmada, escriba su encabezado en Encabezado de la marca de tiempo. Mientras esté vacío, el formulario muestra una advertencia: sin una marca de tiempo firmada, un callback capturado puede reproducirse.
3. Ubicación de los eventos: $.events[*]. Ruta del tipo de evento: $.kind, con mo en Tipos que son mensajes entrantes y dlr en Tipos que son informes de entrega.
4. Marque Leer mensajes entrantes y configure las rutas $.id, $.from, $.to y $.text.
5. Marque Leer informes de entrega, configure Ruta del id del mensaje como $.message y Ruta del estado como $.state, y luego elija Agregar estado y traduzca DELIVRD a Entregado. Agregue UNDELIV a Fallido y ACCEPTD a Enviado de la misma forma.

5. Revisar antes de guardar

La sección Vista previa, al final, la llena el servidor mientras escribe. No se envía nada ni se usa ninguna credencial.

• Muestra la solicitud exacta que se enviaría, con las credenciales como marcadores, por ejemplo <secret.api_token>.
• Pegue la respuesta de ejemplo del proveedor en Cuerpo de la respuesta de ejemplo, por ejemplo {"data": {"id": "msg_91"}}, y la vista previa muestra cómo se lee: aceptado, con el id del proveedor msg_91.
• Pegue un callback de ejemplo en Cuerpo del callback de ejemplo para ver los eventos que produce.
• Los errores aparecen en una lista con el nombre del campo, por ejemplo send.url. Un recuadro amarillo enumera los ajustes que son válidos pero probablemente no son los que quiere, por ejemplo que el id del mensaje no forma parte de la solicitud.

6. Escribir las credenciales y guardar

Complete los dos campos de contraseña que pide el formulario:

• Secreto: api_token: su token de API de ExampleSMS.
• Secreto para firmar el webhook: un secreto de al menos 16 caracteres que también escribe en el proveedor como la clave que firma los callbacks.

Elija Guardar. El proveedor aparece en la lista con sus credenciales marcadas como Almacenadas.

7. Agregar un número

Abra Números en las pestañas de SMS y elija Agregar número. Escriba el número en formato internacional (+15550100199), elija ExampleSMS como proveedor y, opcionalmente, una etiqueta y la ruta que siguen las conversaciones nuevas (un usuario, una extensión, una cola o un grupo de timbrado).

8. Apuntar el proveedor a MonoPbx

De regreso en Proveedores, copie la Dirección de callback de ExampleSMS (https://<su dirección>/hooks/sms/...) en la consola del proveedor como URL de callback, y configure allí el mismo secreto de firma. La dirección es secreta y no se puede adivinar. Si se filtra, elija Nueva dirección en el proveedor: la anterior deja de funcionar de inmediato.

Su instalación debe ser accesible por HTTPS público para que el proveedor pueda llamarla.

9. Probar

Elija Probar en el proveedor, seleccione uno de sus números como remitente, escriba su propio número móvil y elija Enviar prueba. El resultado muestra lo que respondió el proveedor:

• Aceptado por el proveedor, con su id de mensaje;
• Rechazado por el proveedor, con el código de sus reglas (por ejemplo INVALID_DEST);
• Error temporal, que un mensaje real volvería a intentar.

La prueba envía un mensaje real. No crea ninguna conversación, se registra en el registro de auditoría sin números ni texto, y está limitada a 10 por minuto para la empresa y 3 por destinatario. Solo los números del proveedor pueden ser el remitente.

Después envíe un mensaje real desde SMS en la navegación principal, y observe cómo su estado de entrega cambia de En cola a Enviado y Entregado.

Cambiar la configuración después

Abra el proveedor con Editar. Las credenciales no se muestran; deje vacíos todos los campos de contraseña para conservarlas.

Si su cambio enviara las credenciales guardadas a otro lugar (otra URL, otro método, otro encabezado, o una credencial colocada en otra parte de la solicitud), la consola lo rechaza y le pide escribir las credenciales de nuevo, para que nadie que pueda editar la configuración pueda leer las credenciales apuntando el proveedor a un servidor propio.

Uso

Uso en las pestañas de SMS muestra los mensajes y segmentos por día, proveedor y dirección. Los proveedores cobran por segmento: 160 caracteres en el alfabeto GSM (153 por parte de un texto más largo), o 70 (67) cuando el texto tiene otros caracteres.