API compatible con Twilio
MonoPbx responde las llamadas REST más comunes de Twilio con las mismas formas de solicitud y respuesta, y compila un subconjunto de TwiML en un flujo de llamadas. El código escrito para Twilio puede migrar cambiando la URL base y las credenciales. Lo que queda fuera del subconjunto se rechaza con un error, nunca se ignora en silencio, salvo el parámetro Url de Calls create (vea abajo).
La referencia está en el documento OpenAPI bajo la etiqueta twilio-compat.
Credenciales y URL base
| Twilio | MonoPbx |
|---|---|
https://api.twilio.com | https://<su PBX>/api/v1/twilio |
Account SID (AC...) | AC seguido del id de una clave de API: 32 dígitos hexadecimales sin guiones. Es la tercera parte de la clave mpbx_k1_<company>_<id>_<secret>. |
| Auth token | La propia clave de API (mpbx_k1_...) |
Cree una clave de API en Admin > Seguridad > Claves de API con los permisos que necesitan las llamadas:
| Recurso | Permiso |
|---|---|
| Calls (create, list, update) | calls:control |
| Messages create / list | messaging:write / messaging:read, para toda la empresa |
| Recordings list | recordings:read |
| TwiML compile | call_flows:read |
Envíe las credenciales como HTTP Basic, como hacen los SDK de Twilio. La clave como token Authorization: Bearer también funciona. El Account SID debe coincidir con la clave, y el Account SID de la ruta debe ser el suyo; de lo contrario la respuesta es 404 (20404). Una clave nunca hace más de lo que puede hacer su propietario. El alcance por departamento, los límites de frecuencia, la compuerta contra fraude telefónico y la auditoría se aplican como en la API nativa. MonoPbx nunca envía un desafío WWW-Authenticate.
curl -u "AC$KEY_ID:$MPBX_API_KEY" \
https://pbx.example.com/api/v1/twilio/2010-04-01/Accounts/AC$KEY_ID/Messages.json \
--data-urlencode "To=+15550100100" --data-urlencode "From=+15550100001" \
--data-urlencode "Body=Hello"
Con un SDK, apunte su cliente HTTP a la nueva URL base. Los cuerpos son application/x-www-form-urlencoded.
Recursos
Todas las rutas están bajo /api/v1/twilio/2010-04-01/Accounts/{AccountSid}.
| Llamada | Notas |
|---|---|
POST /Calls.json | Clic para llamar. From es el número de extensión de un usuario. Primero suenan los dispositivos de ese usuario y luego se marca To como ese usuario a través del plan de marcación. Url se acepta y se ignora. Twiml, ApplicationSid y la detección de contestadora se rechazan. Respuesta: 201 con status=queued. |
GET /Calls.json | Las llamadas en vivo que puede controlar. Filtros: To, From, Status, PageSize (1 a 100). |
POST /Calls/{CallSid}.json | Status=completed o canceled cuelga. Url, Twiml y Method (redirigir una llamada en vivo) se rechazan. |
POST /Messages.json | From debe ser uno de sus números SMS. Repita MediaUrl para enviar un MMS. MessagingServiceSid, StatusCallback y la programación se rechazan. Respuesta: 201 queued. |
GET /Messages.json | Los mensajes más recientes de las 20 conversaciones más recientes, una página. Filtros: To, From, PageSize. |
GET /Recordings.json | Filtro CallSid, PageSize máximo 100, las más nuevas primero. media_url apunta a la ruta nativa de enlace firmado. |
POST /TwiML/compile | Solo MonoPbx. Compila TwiML en un grafo de flujo de llamadas. |
Los SID son CA + el id de la llamada, SM + el id del mensaje y RE + el id de la grabación, cada uno un UUID sin guiones. Las horas están en RFC 2822, como en Twilio.
Los errores usan el cuerpo de Twilio {code, message, more_info, status} más mpbx_code, el código nativo de MonoPbx. Códigos: 20003 (credenciales), 20403 (prohibido), 20404 (no encontrado), 20429 (límite de frecuencia), 21200 (parámetro inválido o no soportado), 20503 (servicio no configurado), 12100 (error de análisis de TwiML) y 12200 (TwiML fuera del subconjunto).
Subconjunto de TwiML
POST /TwiML/compile recibe JSON {"twiml": "<Response>...</Response>", "record_mailbox": "101"} y devuelve {graph, tts}: un grafo de flujo de llamadas y los textos de Say. No se guarda nada. Guarde el grafo con la API de flujos de llamadas y publíquelo. Un número o un IVR pueden entonces enrutar hacia él como a cualquier otro flujo.
| Verbo | Soportado | Se ejecuta como |
|---|---|---|
Say | voice, language, loop | Reproducción del aviso de la empresa tts/<lang>/<hash>.wav |
Play | loop; prompt:<path>, system:<path> o una ruta de biblioteca simple | Reproducción |
Gather | numDigits, timeout, finishOnKey, action, Say y Play anidados | Recolección en la variable Digits |
Dial | un número, <Number>, <Client> (extensión), <Queue> (extensión de cola), timeout, action | Transferencia; los números externos pasan por el plan de marcación |
Record | maxLength (máximo 600 s), playBeep, action | Buzón de voz en record_mailbox |
Hangup, Reject | reason="busy" | Colgar |
Redirect | flow:<uuid> o una dirección que termina en /flows/<uuid> | Transferencia a ese flujo |
Pause | length (1 a 60 s) | Espera |
Tras el último verbo la llamada se cuelga. Un action y un Redirect deben nombrar un flujo de llamadas de su empresa. MonoPbx nunca obtiene TwiML de su servidor web durante una llamada.
Diferencias
- TwiML en tiempo de ejecución.
Urlen Calls create se ignora, yTwiml,ApplicationSid,Urlen la actualización de llamada y los webhooksactionque llama Twilio no están soportados. Compile su TwiML y publíquelo como flujo. - Llamadas salientes que ejecutan TwiML al contestar. Calls create es clic para llamar: primero suena el teléfono de un usuario.
Saynecesita avisos. El compilador devuelve los textos. Generarlos en la biblioteca de avisos no es automático. No se descargan medios remotos dePlay: suba los archivos a la biblioteca de avisos.- Verbos.
Enqueue,Leave,Conference,Sip,SmsyMessage,ConnectyStream,Pay,Refer,Gatherpor voz,Dialsimultáneo yPlay digits. - REST.
StatusCallback(use los webhooks o el WebSocket de eventos),MessagingServiceSid, mensajes programados, detección de contestadora,SendDigits, paginación más allá de la primera página, llamadas terminadas en la lista de Calls (use la API de historial de llamadas) y obtener o eliminar un solo recurso.