Перейти к основному содержимому

API, совместимый с Twilio

MonoPbx отвечает на самые распространённые REST-вызовы Twilio в форматах запросов и ответов Twilio и компилирует подмножество TwiML в сценарий звонка. Код, написанный для Twilio, можно перенести, заменив базовый URL и учётные данные. Всё, что вне подмножества, отклоняется с ошибкой и никогда не игнорируется молча, кроме параметра Url при создании звонка (см. ниже).

Справочник находится в документе OpenAPI под тегом twilio-compat.

Учётные данные и базовый URL​

TwilioMonoPbx
https://api.twilio.comhttps://<ваш PBX>/api/v1/twilio
Account SID (AC...)AC и следом id ключа API: 32 шестнадцатеричные цифры без дефисов. Это третья часть ключа mpbx_k1_<company>_<id>_<secret>.
Auth tokenСам ключ API (mpbx_k1_...)

Создайте ключ API в разделе Админ > Безопасность > API-ключи с правами, нужными для вызовов:

РесурсПраво
Звонки (создание, список, изменение)calls:control
Сообщения: создание / списокmessaging:write / messaging:read, на всю компанию
Список записейrecordings:read
Компиляция TwiMLcall_flows:read

Передавайте учётные данные через HTTP Basic, как это делают SDK Twilio. Ключ как токен Authorization: Bearer тоже работает. Account SID должен соответствовать ключу, а Account SID в пути должен быть вашим, иначе ответ 404 (20404). Ключ никогда не может больше, чем его владелец. Доступ по отделам, ограничения частоты, защита от телефонного мошенничества и журнал аудита действуют так же, как в собственном API. MonoPbx никогда не отправляет заголовок 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"

В SDK направьте HTTP-клиент на новый базовый URL. Тела запросов — application/x-www-form-urlencoded.

Ресурсы​

Все пути находятся под /api/v1/twilio/2010-04-01/Accounts/{AccountSid}.

ВызовПримечания
POST /Calls.jsonЗвонок по нажатию. From — внутренний номер пользователя. Сначала звонят устройства этого пользователя, затем To набирается от его имени по плану набора. Url принимается и игнорируется. Twiml, ApplicationSid и определение автоответчика отклоняются. Ответ: 201 со status=queued.
GET /Calls.jsonТекущие звонки, которыми вы вправе управлять. Фильтры: To, From, Status, PageSize (от 1 до 100).
POST /Calls/{CallSid}.jsonStatus=completed или canceled завершает звонок. Url, Twiml и Method (перенаправление текущего звонка) отклоняются.
POST /Messages.jsonFrom должен быть одним из ваших SMS-номеров. Повторите MediaUrl, чтобы отправить MMS. MessagingServiceSid, StatusCallback и отложенная отправка отклоняются. Ответ: 201 queued.
GET /Messages.jsonНовейшие сообщения 20 последних диалогов, одна страница. Фильтры: To, From, PageSize.
GET /Recordings.jsonФильтр CallSid, PageSize не более 100, сначала новые. media_url указывает на собственный маршрут подписанной ссылки.
POST /TwiML/compileТолько в MonoPbx. Компилирует TwiML в граф сценария звонка.

SID: CA + id звонка, SM + id сообщения и RE + id записи, каждый — UUID без дефисов. Время в формате RFC 2822, как в Twilio.

Ошибки используют тело Twilio {code, message, more_info, status} плюс mpbx_code — собственный код MonoPbx. Коды: 20003 (учётные данные), 20403 (запрещено), 20404 (не найдено), 20429 (превышена частота), 21200 (неверный или неподдерживаемый параметр), 20503 (сервис не настроен), 12100 (ошибка разбора TwiML) и 12200 (TwiML вне подмножества).

Подмножество TwiML​

POST /TwiML/compile принимает JSON {"twiml": "<Response>...</Response>", "record_mailbox": "101"} и возвращает {graph, tts}: граф сценария звонка и тексты Say. Ничего не сохраняется. Сохраните граф через API сценариев звонков и опубликуйте его. После этого номер или IVR могут направлять звонки в него, как в любой другой сценарий.

ГлаголПоддерживаетсяВыполняется как
Sayvoice, language, loopВоспроизведение приглашения компании tts/<lang>/<hash>.wav
Playloop; prompt:<path>, system:<path> или путь из библиотекиВоспроизведение
GathernumDigits, timeout, finishOnKey, action, вложенные Say и PlayСбор цифр в переменную Digits
Dialномер, <Number>, <Client> (внутренний номер), <Queue> (внутренний номер очереди), timeout, actionПеревод; внешние номера идут через план набора
RecordmaxLength (не более 600 с), playBeep, actionГолосовая почта в record_mailbox
Hangup, Rejectreason="busy"Завершение звонка
Redirectflow:<uuid> или адрес, оканчивающийся на /flows/<uuid>Перевод в этот сценарий
Pauselength (от 1 до 60 с)Ожидание

После последнего глагола звонок завершается. action и Redirect должны указывать на сценарий звонка вашей компании. MonoPbx никогда не загружает TwiML с вашего веб-сервера во время звонка.

Отличия​

  • TwiML во время выполнения. Url при создании звонка игнорируется, а Twiml, ApplicationSid, Url при изменении звонка и вебхуки action, которые вызывает Twilio, не поддерживаются. Скомпилируйте TwiML и опубликуйте его как сценарий.
  • Исходящие звонки, запускающие TwiML при ответе. Создание звонка — это звонок по нажатию: сначала звонит телефон пользователя.
  • Say требует приглашений. Компилятор возвращает тексты. Их озвучивание в библиотеку приглашений не автоматизировано. Удалённые медиа в Play не загружаются: загрузите файлы в библиотеку приглашений.
  • Глаголы. Enqueue, Leave, Conference, Sip, Sms и Message, Connect и Stream, Pay, Refer, Gather с речью, одновременный Dial и Play digits.
  • REST. StatusCallback (используйте вебхуки или WebSocket событий), MessagingServiceSid, отложенные сообщения, определение автоответчика, SendDigits, постраничный вывод дальше первой страницы, завершённые звонки в списке звонков (используйте API истории звонков), получение и удаление отдельного ресурса.