Saltar al contenido principal

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​

TwilioMonoPbx
https://api.twilio.comhttps://<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 tokenLa propia clave de API (mpbx_k1_...)

Cree una clave de API en Admin > Seguridad > Claves de API con los permisos que necesitan las llamadas:

RecursoPermiso
Calls (create, list, update)calls:control
Messages create / listmessaging:write / messaging:read, para toda la empresa
Recordings listrecordings:read
TwiML compilecall_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}.

LlamadaNotas
POST /Calls.jsonClic 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.jsonLas llamadas en vivo que puede controlar. Filtros: To, From, Status, PageSize (1 a 100).
POST /Calls/{CallSid}.jsonStatus=completed o canceled cuelga. Url, Twiml y Method (redirigir una llamada en vivo) se rechazan.
POST /Messages.jsonFrom 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.jsonLos mensajes más recientes de las 20 conversaciones más recientes, una página. Filtros: To, From, PageSize.
GET /Recordings.jsonFiltro CallSid, PageSize máximo 100, las más nuevas primero. media_url apunta a la ruta nativa de enlace firmado.
POST /TwiML/compileSolo 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.

VerboSoportadoSe ejecuta como
Sayvoice, language, loopReproducción del aviso de la empresa tts/<lang>/<hash>.wav
Playloop; prompt:<path>, system:<path> o una ruta de biblioteca simpleReproducción
GathernumDigits, timeout, finishOnKey, action, Say y Play anidadosRecolección en la variable Digits
Dialun número, <Number>, <Client> (extensión), <Queue> (extensión de cola), timeout, actionTransferencia; los números externos pasan por el plan de marcación
RecordmaxLength (máximo 600 s), playBeep, actionBuzón de voz en record_mailbox
Hangup, Rejectreason="busy"Colgar
Redirectflow:<uuid> o una dirección que termina en /flows/<uuid>Transferencia a ese flujo
Pauselength (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. Url en Calls create se ignora, y Twiml, ApplicationSid, Url en la actualización de llamada y los webhooks action que 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.
  • Say necesita avisos. El compilador devuelve los textos. Generarlos en la biblioteca de avisos no es automático. No se descargan medios remotos de Play: suba los archivos a la biblioteca de avisos.
  • Verbos. Enqueue, Leave, Conference, Sip, Sms y Message, Connect y Stream, Pay, Refer, Gather por voz, Dial simultáneo y Play 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.