SMS

MonoPbx tiene un núcleo de SMS: configuraciones de proveedores, números, una bandeja compartida (conversaciones y mensajes), envío con seguimiento de entrega, webhooks entrantes firmados y conteos de uso. Se configura a través de la API (/sms/...); todavía no hay una página de SMS en la consola web.

:::caution Su responsabilidad El cumplimiento de la normativa de SMS (consentimiento, baja y regulaciones locales) es responsabilidad del cliente. El manejo automático de las palabras clave STOP y de baja está planeado para Beta y no está activo hoy: los ganchos existen, pero no hacen nada por omisión. :::

Modelo

provider (kind, settings, sealed credentials, webhook address)
  └── number (E.164; where its conversations are routed)
        └── conversation (company number + remote number)
              └── message (inbound or outbound, status, segments)

Estados del mensaje: queued, luego sent y después delivered, o failed. Los mensajes entrantes son received.

Proveedores

La página de proveedores de SMS.

Los tipos de proveedor disponibles dependen de la versión; GET /api/v1/sms/providers lista available_kinds. En main:

• Twilio (twilio).
• Plantilla HTTP genérica (http_template): cualquier API HTTP de SMS configurada sin código. Se niega a llamar a direcciones privadas, de loopback o de enlace local, y a http sin cifrar, salvo que se permita.

POST /api/v1/sms/providers
{"name": "Twilio", "kind": "twilio",
 "config": {"public_base_url": "https://pbx.example.com"},
 "credentials": {"account_sid": "AC...", "auth_token": "..."}}

Las credenciales se cifran con la clave de la empresa y nunca se devuelven; la API solo muestra auth_configured: true. Al actualizar las credenciales se reemplazan todas las guardadas. Las rutas que llevan credenciales ignoran Idempotency-Key.

Cada proveedor tiene una dirección de webhook con la forma /hooks/sms/<key> (se muestra como webhook_path en el proveedor; POST /sms/providers/{id}/webhook-address la rota, y después la dirección anterior responde 404). Configúrela en su proveedor como la URL de mensajes entrantes e informes de entrega. Para Twilio, configure el webhook "Cuando llega un mensaje" del número como https://<your address>/hooks/sms/<key> con HTTP POST. Los informes de entrega de Twilio no necesitan configuración en la consola, porque el callback de estado se envía con cada mensaje.

La dirección del webhook, por sí sola, no autentica nada. Cada webhook se verifica con la firma del proveedor (X-Twilio-Signature de Twilio, o el HMAC genérico X-Mpbx-Signature) antes de analizarlo, y una verificación fallida responde 401 MPBX-SMS-WEBHOOK-UNAUTHORIZED. La empresa se toma del registro del proveedor que corresponde a la dirección, nunca de la solicitud.

Números

La página de números de SMS.

POST /api/v1/sms/numbers agrega un número en formato internacional (+15550100) a un proveedor y define a dónde van sus conversaciones (route: un usuario, una extensión, una cola o un grupo de timbrado; {"kind":"none"} para ningún destino). Un número se puede desactivar con enabled: false. Los proveedores y números que todavía tienen historial no se pueden eliminar; desactívelos.

Envío

POST /api/v1/sms/messages     {"from": "+15550100199", "to": "+15550100100", "body": "..."}

La respuesta es 202 con el mensaje en estado queued. from debe ser uno de los números habilitados de la empresa, lo cual también selecciona el proveedor. Los textos tienen de 1 a 1600 caracteres. Los segmentos se cuentan como los cobran los proveedores (160 caracteres por segmento GSM-7, 70 por segmento UCS-2, y 153 y 67 cuando un mensaje se divide).

• Un rechazo permanente marca el mensaje como fallido de inmediato con el código del proveedor (MPBX-SMS-PROVIDER-REJECTED si no envía ninguno).
• Un error temporal se reintenta con retrasos que se duplican desde 30 segundos, hasta 5 intentos; después falla con MPBX-SMS-PROVIDER-UNAVAILABLE.
• La entrega es de al menos una vez: en casos raros de fallo, un mensaje puede enviarse dos veces.

Lea la bandeja con GET /sms/conversations, GET /sms/conversations/{id}/messages, y marque un hilo como leído con POST /sms/conversations/{id}/read. GET /sms/usage devuelve los conteos diarios de mensajes y segmentos por proveedor y dirección.

Permisos

Operación	Permiso
Proveedores y números	integrations:read / integrations:write
Conversaciones, mensajes, envío y uso	messaging:read / messaging:write

Ambos se verifican en toda la empresa. Un titular que tiene el permiso solo para algunos departamentos recibe un rechazo (403), porque las conversaciones todavía no tienen departamento.

Eventos y auditoría

Cada cambio de estado genera un evento sms.* (sms.queued, sms.sent, sms.delivered, sms.failed, sms.received) que lleva ids, números, estado y segmentos, pero nunca el texto del mensaje. Los cambios de proveedores y números se auditan sin credenciales. Vea Actividad, historial y auditoría.

Los códigos de error aparecen en el repositorio en docs/errors/sms.md.