Подключение любого SMS-провайдера (универсальный HTTP-провайдер)

MonoPbx отправляет и принимает SMS через провайдера. Twilio встроен. Для любого другого провайдера, у которого есть HTTP API, код не нужен: в консоли администратора вы описываете запрос, отправляющий сообщение, способ чтения ответа провайдера и способ чтения его обратных вызовов (входящих сообщений и отчётов о доставке). Всё ниже выполняется в веб-консоли; API для этого не нужен.

Вам нужна роль Владелец (или пользовательская роль с правом integrations:write). Для отправки также нужно право messaging:write.

:::info Учётные данные только для записи Токен API и секрет обратного вызова, которые вы вводите здесь, запечатываются ключом вашей компании при сохранении. Их больше никогда не показывают, даже вам, и они не появляются в предпросмотре, журнале аудита или сообщении об ошибке. Чтобы их изменить, введите все учётные данные заново. :::

Пример провайдера

В руководстве используется вымышленный провайдер «ExampleSMS» с таким 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. Добавьте провайдера

Откройте Консоль администратора, SMS (страница называется SMS-провайдеры) и выберите Новый провайдер.

1. Название: ExampleSMS.
2. Тип: Generic HTTP provider. Откроется форма запроса.

2. Опишите запрос

В разделе Запрос к провайдеру:

Поле	Значение
Метод	POST
URL	https://api.examplesms.com/v2/messages
Название и значение заголовка (выберите Добавить заголовок)	Authorization и Bearer {{secret.api_token}}
Формат тела	json
Шаблон тела	{"from":"{{from}}","to":"{{to}}","text":"{{body}}","ref":"{{message_id}}"}

Заполнители записываются в двойных фигурных скобках. Можно использовать from, to, body, message_id, segments, timestamp и secret.NAME для учётных данных. Схема, хост и порт URL должны быть обычным текстом (без заполнителей), а адрес должен быть публичным HTTPS: частные и локальные адреса всегда отклоняются.

Каждый используемый вами secret.NAME добавляет поле пароля в разделе Учётные данные внизу формы.

3. Опишите ответ

В разделе Разбор ответа:

1. Путь к идентификатору сообщения у провайдера: $.data.id. По нему отчёты о доставке позже найдут сообщение.
2. Выберите Добавить правило и установите HTTP-статусы в 400, Результат в Refused for good, а Путь к коду в $.error.code.

Без правил ответ 2xx принимается, ответы 408, 425, 429 и 5xx повторяются позже, а всё остальное отклоняется.

4. Опишите обратные вызовы

В разделе Обратные вызовы от провайдера отметьте Провайдер обращается к нам.

1. Подпись: Provider HMAC-SHA256. Установите Заголовок подписи в X-Signature, Текст перед подписью в sha256=, а кодировку оставьте hex.
2. Если провайдер также присылает подписанную временную метку, укажите её заголовок в поле Заголовок временной метки. Пока оно пусто, форма показывает предупреждение: без подписанной временной метки перехваченный обратный вызов можно воспроизвести повторно.
3. Где находятся события: $.events[*]. Путь типа события: $.kind, при этом mo в поле Типы, обозначающие входящие сообщения, а dlr в поле Типы, обозначающие отчёты о доставке.
4. Отметьте Читать входящие сообщения и укажите пути $.id, $.from, $.to и $.text.
5. Отметьте Читать отчёты о доставке, укажите Путь идентификатора сообщения $.message и Путь статуса $.state, затем выберите Добавить статус и сопоставьте DELIVRD со значением Delivered. Аналогично добавьте UNDELIV → Failed и ACCEPTD → Sent.

5. Проверьте перед сохранением

Раздел Предпросмотр внизу страницы заполняется сервером по мере ввода. Ничего не отправляется и учётные данные не используются.

• Показывает точный запрос, который был бы отправлен, с учётными данными в виде заполнителей, например <secret.api_token>.
• Вставьте пример ответа провайдера в поле Тело примера ответа, например {"data": {"id": "msg_91"}}, и предпросмотр покажет, как он читается: принят, с идентификатором провайдера msg_91.
• Вставьте пример обратного вызова в поле Тело примера обратного вызова, чтобы увидеть события, которые он создаёт.
• Ошибки выводятся списком с названием поля, например send.url. Жёлтый блок перечисляет настройки, которые допустимы, но, вероятно, не являются тем, что вы хотели, например то, что идентификатор сообщения не входит в запрос.

6. Введите учётные данные и сохраните

Заполните два поля пароля, которые запрашивает форма:

• Секрет: api_token: ваш токен API ExampleSMS.
• Секрет подписи вебхука: секрет длиной не менее 16 символов, который вы также указываете у провайдера как ключ для подписи обратных вызовов.

Выберите Сохранить. Провайдер появится в списке, а его учётные данные будут отмечены как Сохранены.

7. Добавьте номер

Откройте Номера на вкладках SMS и выберите Добавить номер. Введите номер в международном формате (+15550100199), выберите ExampleSMS в качестве провайдера, а при желании укажите метку и маршрут, по которому пойдут новые переписки (пользователь, внутренний номер, очередь или группа вызова).

8. Укажите провайдеру адрес MonoPbx

Вернитесь в Провайдеры, скопируйте Адрес обратного вызова ExampleSMS (https://<your address>/hooks/sms/...) и укажите его в консоли провайдера как URL обратного вызова, а также задайте там тот же секрет подписи. Адрес секретный и его невозможно угадать. Если он утёк, выберите у провайдера Новый адрес: старый адрес перестанет работать сразу.

Чтобы провайдер мог обращаться к вашей установке, она должна быть доступна по публичному HTTPS.

9. Проверьте

Выберите Проверка у провайдера, выберите один из его номеров в качестве отправителя, введите свой мобильный номер и нажмите Отправить тест. Результат показывает ответ провайдера:

• Принято провайдером, с его идентификатором сообщения;
• Отклонено провайдером, с кодом из ваших правил (например, INVALID_DEST);
• Временная ошибка, которую реальное сообщение повторило бы.

Тест отправляет одно настоящее сообщение. Он не создаёт переписку, записывается в журнал аудита без номеров и текста и ограничен 10 отправками в минуту на компанию и 3 на получателя. Отправителем может быть только номер самого провайдера.

Затем отправьте настоящее сообщение из раздела SMS в главной навигации и проследите, как его статус доставки меняется с В очереди на Отправлено и Доставлено.

Изменение настроек позже

Откройте провайдера кнопкой Изменить. Учётные данные не показываются; оставьте все поля пароля пустыми, чтобы сохранить их.

Если ваше изменение отправит сохранённые учётные данные куда-то ещё (на другой URL, метод, заголовок или разместит учётные данные в другом месте запроса), консоль его отклонит и попросит ввести учётные данные заново. Так никто, кто может редактировать настройки, не сможет прочитать учётные данные, указав провайдеру собственный сервер.

Использование

Использование на вкладках SMS показывает сообщения и сегменты по дням, провайдерам и направлениям. Провайдеры тарифицируют по сегментам: 160 символов в алфавите GSM (153 на часть более длинного текста) или 70 (67), если в тексте есть другие символы.