¶ SMS API (архивный)
- ⚠️ Эта документация описывает устаревшую версию SMS API для личных кабинетов portal.plusofon.ru и new-portal.plusofon.ru .
Если адрес Вашего кабинета lk.plusofon.ru , то, пожалуйста, используйте документацию по актуальной версии SMS API.
¶ Введение
Добро пожаловать в документацию по SMS API !
Знаком 
отмечены обязательные параметры.
¶ Особенности предоставления SMS-сервиса и использование API
Сервис предназначен для использования мобильного номера как канала коммуникаций (как для SMS, так и для голоса) для предприятий малого бизнеса: уведомления, напоминания о записи в парикмахерскую или врачу с обратной связью, получение обратной связи по обслуживанию (где использование коротких номеров вредит конверсии) и т.д. Либо для персонализации коммуникаций в большом бизнесе – например, предоставление персональных мобильных номеров менеджерам автосалонов или агентств недвижимости.
Рассылки по списку номеров, не давших разрешение на получение сообщений, категорически запрещены.
Количество сообщений в месяц ограничено 10 000 (десятью тысячами штук). Данное число может быть увеличено только в случаях использования номера в качестве двустороннего канала взаимодействия с абонентами сети связи общего пользования (в разработке – количество сообщений автоматически увеличивается на число входящих сообщений на номер, но при соотношении входящих/исходящих 1/5 и более).
При массовой отправке SMS-уведомлений, сообщения устанавливаются в очередь, которая не позволяет отправлять более 20 сообщений в минуту (с вариативными задержками). Ограничение не работает на чат-номерах.
В начале месяца на каждый номер устанавливается регулярный пакет SMS, который может быть изменен на больший в течение расчетного периода.
Использование нескольких номеров для массовых неперсонализированных рассылок с целью обхода обозначенных выше ограничений не поможет – текст сообщений автоматически мониторится на идентичность, и после 10 одинаковых сообщений все номера блокируются на час.
¶ 
Postman
Вы можете проверить работу методов на готовой коллекции Postman:
-
в приложении Postman откройте меню File → Import → Link
-
вставьте ссылку:
https://docs.plusofon.ru/api/plusofon_sms_api.postman_collection.json -
нажмите Continue → Import
Для аутентификации укажите Ваш API-токен в настройках коллекции на вкладке Auth в поле Token.
Скачать сам клиент Postman можно на официальном сайте.
¶ Запрос
API работает по протоколу JSON-RPC (?). Название метода, как правило, состоит из названия модуля и названия метода в этом модуле, и разделяется символом /.
Структура запроса:
| Параметр | Описание | Пример |
|---|---|---|
jsonrpc |
версия протокола | 2.0 |
method |
название API-метода | user/about-me |
id |
ИД сообщения | f3gk6fsd56 |
params |
параметры метода (в теле запроса) | {} |
На данный момент API использует версию 2.0 и поддерживает вызов процедур только с именованными параметрами
¶ Ответ
В ответе всегда возвращается JSON-объект. Если запрос обработан успешно, параметр result будет содержать данные, которые вернул метод. Если произошла какая-либо ошибка, значение параметра result будет равняться NULL, а ответ будет содержать в себе параметр error, в котором будет указан код ошибки и ее описание.
| Параметр | Описание | Пример |
|---|---|---|
jsonrpc |
версия протокола | 2.0 |
id |
ИД сообщения | f3gk6fsd56 |
result |
данные, которые вернул метод или NULL | {"email":"user@mail.ru"} |
error |
NULL или код и описание ошибки | {"error": null} |
¶ Аутентификация
OAuth — открытый протокол авторизации, который позволяет предоставить третьей стороне ограниченный доступ к защищённым ресурсам пользователя без необходимости передавать ей (третьей стороне) логин и пароль.
Разработчики должны зарегистрировать свое приложение, чтобы использовать OAuth. Зарегистрированному приложению присваивается идентификатор клиента (oauth_id) и секретный ключ (access_token) или токен. Секретный ключ клиента должен храниться в тайне и использоваться только между приложением и сервером авторизации Плюсофон.
API-токен можно получить одним из двух вариантов:
-
в личном кабинете Плюсофон, в разделе API
-
специальным POST-запросом
¶ Получение токена
Метод позволяет получить токен для аутентификации при выполнении API-запросов.
Полученный токен необходимо использовать для авторизации во всех запросах как «Bearer Token».
¶ Запрос
POST
login
https://oauth.plusofon.ru/login/
| Параметр | Тип | Описание |
|---|---|---|
client_id |
integer | фиксированное значение 10553 |
type |
string | фиксированное значение login |
email |
string | email-адрес аккаунта (логин) |
password |
string | пароль аккаунта |
Пример:
curl -d "client_id=10553&type=login&email=user@mail.ru&password=12345" https://oauth.plusofon.ru/login/
¶ Ответ
В случае успеха возвращается набор параметров:
| Параметр | Описание |
|---|---|
email |
номер телефона |
number |
e-mail Вашего пользователя |
access_token |
токен |
oauth_id |
ИД Вашей аутентификации |
Пример:
{
"result":
{
"email": "user@mail.ru",
"phone": "79993332210",
"access_token": "987654321",
"oauth_id": "123"
}
}
¶ Управление пакетами SMS
¶ Получение номеров
Метод позволяет получить список мобильных номеров из личного кабинета, доступных для отправки и приёма SMS.
¶ Запрос
POST
sms/numbers
https://sms-api.plusofon.ru
| Параметр | Тип | Описание |
|---|---|---|
packet |
string | фильтр номеров по пакету SMS |
Варианты параметра packet:
| Значение | Описание |
|---|---|
A |
все номера |
Y |
номера с пакетами SMS |
N |
номера без пакетов SMS |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0", "method":"sms/numbers", "id":"1", "params":{"packet":"A"}}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
В случае успеха возвращается массив номеров со следующими параметрами:
| Параметр | Описание |
|---|---|
number |
номер телефона |
id_packet |
пакет SMS |
user_name |
имя пользователя (если есть) |
Пример:
{
"jsonrpc":"2.0",
"id":"1",
"result": [
{
"number": "79993332210",
"packet": {
"id": "1234",
"number": "79993332210",
"id_packet": "6ccf-87db-0df2-6ccf-87db",
"customer_id": "12345",
"created_at": "2022-06-06 10:51:58"
}
}
],
"error": null
}
¶ Получение доступных пакетов
Метод позволяет получить список пакетов SMS, доступных для подключения.
¶ Запрос
POST
sms/packets
https://sms-api.plusofon.ru
Не требует параметров.
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0", "method":"sms/packets", "id":"1", "params":{}}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
В случае успеха возвращается массив пакетов с параметрами:
| Параметр | Описание |
|---|---|
packages_id |
внутренний ИД пакета |
amount |
абонентская плата |
sms_count |
количество SMS в пакете |
name |
название пакета |
id |
ИД пакета (его нужно передавать в метод подключения пакета) |
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": [
{
"packages_id": "769.0000",
"amount": "600.0000",
"sms_count": "1000.0000",
"name": "Пакет СМС 1000",
"id": "16fade6a-1232-d42f-6012-624162c4c018"
},
{
...
}
],
"error": null
}
¶ Подключение пакета
Метод позволяет подключить пакет SMS на определённый мобильный номер.
¶ Запрос
POST
sms/add-packet
https://sms-api.plusofon.ru
| Параметр | Тип | Описание |
|---|---|---|
packet |
string | ИД пакета SMS (полученный методом sms/packets) |
number |
string | номер телефона |
Параметр
numberнеобходимо передавать как строку
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0", "method":"sms/add-packet", "id":"1", "params":{"packet":"16fade6a-1232-d42f-6012-624162c4c018", "number":"79993332210"}}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Метод возвращает "result": true если данные успешно сохранены (или ошибку, если входные параметры не прошли валидацию).
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": true,
"error": null
}
¶ Отключение пакета
Метод позволяет отключить пакет SMS на определённом мобильном номере.
¶ Запрос
POST
sms/delete-packet
https://sms-api.plusofon.ru
Параметры:
| Параметр | Тип | Описание |
|---|---|---|
number |
string | номер телефона |
Параметр
numberнеобходимо передавать как строку
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0", "method":"sms/delete-packet", "id":"1", "params":{"number":"79993332210"}}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Метод возвращает "result": true если данные успешно сохранены (или ошибку, если входные параметры не прошли валидацию).
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": true,
"error": null
}
¶ Остаток в пакете
Метод позволяет проверить остаток SMS в подключенном к определённому номеру пакете.
¶ Запрос
POST
sms/stay
https://sms-api.plusofon.ru
| Параметр | Тип | Описание |
|---|---|---|
number |
string | номер телефона |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0", "method":"sms/stay", "id":"1", "params":{"number":"79993332210"}}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Метод возвращает массив (или ошибку, если входные параметры не прошли валидацию):
| Параметр | Описание |
|---|---|
count |
количество оставшихся SMS |
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"count": 352
},
"error": null
}
¶ Просмотр SMS
¶ Получение списка SMS
Метод позволяет получить список входящих и исходящих SMS-сообщений, принятых или отправленных Вашими номерами.
¶ Запрос
POST
sms/list
https://sms-api.plusofon.ru
| Параметр | Тип | Описание | |
|---|---|---|---|
created_datetime_from |
string | начало периода |
'2022-06-08 00:00:00' |
created_datetime_to |
string | конец периода |
'2022-06-08 23:59:59' |
receiver |
array | массив Б-номеров (получателей) | ['79993332210', '79993332211'] |
sender |
array | массив А-номеров (отправителей) | ['79993332210', '79993332211'] |
incoming |
integer | направление: входящие (1), исходящие (0) или все (по умолчанию) |
1 |
offset |
integer | пропустить определённое количество | 0 |
limit |
integer | ограничение SMS в ответе | 10 |
В
receiverиsenderнеобходимо передавать номера из числа тех, которые получены с помощью методаsms/numbers(номера для получения и отправки SMS)
Для корректной фильрации по номерам поля
receiverиsenderдолжны быть заполнены (при необходимости в один из них можно указать несуществующий номер)
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/list",
"id": "1",
"params": {
"created_datetime_from": "2022-06-08 00:00:00",
"created_datetime_to": "2022-06-08 23:59:59",
"receiver": [
"79993332210",
"79993332211"
],
"sender": [
"79993332210",
"79993332211"
]
}
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Метод возвращает массив (или ошибку, если входные параметры не прошли валидацию):
| Параметр | Тип | Описание |
|---|---|---|
data |
object | объект с сообщениями |
count |
integer | всего SMS для данного запроса |
numbers |
array | номера пользователя |
Структура объекта data:
| Параметр | Описание |
|---|---|
id |
уникальный ИД сообщения |
created_datetime |
дата и время создания |
sent_datetime |
дата и время отправки |
sender |
номер отправителя |
receiver |
номер получателя |
msg |
текст сообщения |
incoming |
направление: исходящее (0) или входящее (1) |
pdu |
количество сегментов |
lvl1_status |
статус доставки исходящего SMS оператору |
lvl2_status |
статус доставки исходящего SMS на устройство |
donedate |
дата и время доставки |
Остальные поля, если они появляются, не несут каких-либо полезных данных.
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"data": [
{
"id": "101690574",
"created_datetime": "2022-06-08 15:48:02",
"sent_datetime": "2022-06-08 15:48:04",
"sender": "79993332210",
"receiver": "7999333123",
"msg": "привет, мир!",
"incoming": "0",
"readed": "0",
"pdu": "1",
"status": null,
"smpp_quueid": "625803ef-fa6e-4c90-a5fd-eda9fb3e43e0",
"lvl1_status": "ESME_ROK",
"lvl2_status": "DELIVRD",
"donedate": "2022-06-08 15:48:00",
"subdate": "2022-06-08 15:48:00",
"sub": "001",
"err": "000",
"id_smsc": "966466294B",
"dlvrd": "001"
},
{
"id": "1019506",
"created_datetime": "2022-06-08 17:46:02",
"sent_datetime": "2022-06-08 17:46:02",
"sender": "7999333123",
"receiver": "79993332210",
"msg": "Этот абонент снова в сети",
"incoming": "1",
"readed": "0",
"pdu": "1",
"status": null,
"smpp_quueid": "6f3ca8-8b34-7f4",
"lvl1_status": null,
"lvl2_status": null,
"donedate": null,
"subdate": null,
"sub": null,
"err": null,
"id_smsc": null,
"dlvrd": null
}
],
"count": "2",
"numbers": [
"79993332210",
"79993332211"
]
},
"error": null
}
¶ Исходящие SMS
¶ Отправка SMS
Метод позволяет отправить SMS-сообщение с одного из Ваших мобильных номеров.
¶ Запрос
POST
sms/send
https://sms-api.plusofon.ru
| Параметр | Тип | Описание |
|---|---|---|
from |
string | А-номер (отправитель) |
to |
string | Б-номер (получатель) |
text |
string | текст сообщения |
dlr_level |
integer | уведомление о доставке |
reject_long |
boolean | запрет отправки SMS длиннее одного сегмента: не отправлять (true) или отправлять (false, по умолчанию) |
count_pdu |
boolean | возврат в ответе количества сегментов SMS (pdu) |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/send",
"id": "1",
"params": {
"from": "79993332210",
"to": "79993332211",
"text": "привет, мир!"
}
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
По умолчанию в ответе возвращается идентификатор сообщения (или ошибка, если входные параметры не прошли валидацию):
| Значение | Описание |
|---|---|
result |
уникальный ИД сообщения |
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": "7322e11dc0f9f46da05e1",
"error": null
}
Если count_pdu = true в ответе возвращается массив (или ошибка, если входные параметры не прошли валидацию):
| Значение | Описание |
|---|---|
jmx_id |
уникальный ИД сообщения |
pdu |
количество сегментов SMS |
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"jmx_id": "9410432d2e7216f79efaa7",
"pdu": 1
},
"error": null
}
¶ Получение статуса SMS
Метод позволяет проверить статус доставки отправленного Вами SMS-сообщения.
¶ Запрос
POST
sms/get-status
https://sms-api.plusofon.ru
| Параметр | Тип | Описание | Пример |
|---|---|---|---|
jmx_id |
string | ИД сообщения |
'007e6b14b95d4bb99a388e5990c34611' |
Параметр
jmx_idнеобходимо передавать как строку
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "method": "sms/get-status", "id": "1", "params": { "jmx_id": "e66818de44cd95ab0b79eaa9" } }' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Метод возвращает отчёт о доставке сообщения (DLR) или ошибку, если сообщение не найдено. Структура DLR описана ниже, в разделе «Формат DLR».
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"message_status": "DELIVRD",
"donedate": 1654717620,
"sub": "001",
"err": "000",
"id_smsc": "9661F6294B",
"dlvrd": "001",
"subdate": 1654717620,
"id": "88c0-470f-7a99617ee",
"level": 2,
"jmx_id": "e66818de44cd95ab0b79eaa9"
},
"error": null
}
¶ Отчёты о доставке (DLR)
Отчеты о доставке приходят в форме POST-запросов с телом в формате JSON и типом контента "application/json".
¶ Старый формат DLR
{
"jmx_id": "48aed09d386e4b3ea762391483ed0498",
"status": "ESME_ROK"
}
| Поле ответа | Описание |
|---|---|
jmx_id |
уникальный ИД сообщения |
status |
статус доставки сообщения вышестоящему SMSC |
Если адрес DLR был обновлен или добавлен после 15 апреля 2019 г., то DLR будут приходить в новом формате (описан дальше)
¶ Формат DLR
Текущий формат DLR предполагает отправку на Ваш адрес DLR двух запросов, различить которые можно по значению поля level. Запрос с level = 1 содержит статус доставки сообщения от вышестоящего SMSC (SMS-центра), запрос с level = 2 — статус доставки сообщения конечному получателю (абонентскому устройству).
¶ Level 1
{
"message_status": "ESME_ROK",
"id": "9e5ab493-a66e-47e6-aec2-a22a1055ec65",
"level": "1",
"jmx_id": "c459163b8d6d489f82d6de6ee6e56397"
}
| Поле ответа | Описание |
|---|---|
message_status |
статус доставки сообщения вышестоящему SMSC |
id |
внутренний ИД сообщения |
level |
уровень отчёта о доставке |
jmx_id |
уникальный ИД сообщения |
Возможные значения message_status для level = 1:
| Значение | Описание |
|---|---|
ESME_ROK |
без ошибок |
ESME_RINVDSTADR |
неверный адрес доставки |
ESME_RINVSRCADR |
неверный адрес отправки |
ESME_RSUBMITFAIL |
ошибка перехвата сообщения |
ESME_RUNKNOWNERR |
неизвестная ошибка |
ESME_RX_T_APPN |
ошибка приложения |
¶ Level 2
{
"message_status": "DELIVRD",
"donedate": "1904161748",
"sub": "001",
"err": "ND",
"level": "2",
"id_smsc": "3299386",
"dlvrd": "001",
"subdate": "1904161748",
"id": "4a75068a-1477-4c4f-b75e-eedb66f6b4a6",
"jmx_id": "c459163b8d6d489f82d6de6ee6e56397"
}
| Поле ответа | Описание |
|---|---|
message_status |
статус доставки сообщения конечному получателю |
donedate |
дата и время финального статуса доставки |
sub |
количество изначально отправленных сообщений (при отправке списку получателей) |
err |
может содержать код ошибки от SMSC при неудачной попытке доставки |
level |
уровень отчета о доставке |
id_smsc |
ИД сообщения от вышестоящего SMSC |
dlvrd |
количество доставленных сообщений (при отправке списку получателей) |
subdate |
дата и время фактической отправки сообщения |
id |
внутренний ИД сообщения |
jmx_id |
уникальный ИД сообщения |
Возможные значения message_status для level = 2:
| Значение | Описание |
|---|---|
DELIVRD |
доставлено |
UNDELIV |
не доставлено |
ERROR |
ошибка |
Статус может меняться в течение трёх суток
¶ Требования к адресу DLR
Чтобы SMSC воспринял доставку DLR как успешную и не пытался доставить его повторно, необходимо чтобы Ваш URL возвращал код статуса HTTP 200 и строку ACK/Jasmin в теле ответа.
¶ Получение адреса DLR
Метод позволяет получить установленный адрес обработчика отчётов о доставке (DLR) SMS-сообщений, отправленных с Ваших номеров.
¶ Запрос
POST
sms/get-dlr-url
https://sms-api.plusofon.ru
| Параметр | Тип | Описание |
|---|---|---|
number |
string | номер телефона (если нужно посмотреть адрес на номере) |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/get-dlr-url",
"id": "1"
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Возвращается объект (или ошибка, если входные параметры не прошли валидацию):
| Параметр | Описание |
|---|---|
url |
адрес обработчика DLR-запросов |
number |
номер телефона (если запрос по номеру) |
params |
массив с POST-параметрами, которые будут переданы на URL (например, данные авторизации) |
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"url": "http://domen.my/sms_dlr",
"params": []
},
"error": null
}
¶ Добавление адреса DLR
Метод позволяет добавить новый адрес обработчика отчётов о доставке (DLR) SMS-сообщений, отправленных с Ваших номеров.
¶ Запрос
POST
sms/add-dlr-url
https://sms-api.plusofon.ru
| Параметр | Тип | Описание |
|---|---|---|
url |
string | адрес обработчика DLR-запросов |
number |
string | номер телефона, если указать, то адрес назначается только на него, иначе — на все номера |
params |
object | объект с POST-параметрами, которые будут переданы на URL (например, данные авторизации) |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/add-dlr-url",
"id": "1",
"params": {
"url": "http://domen.my/sms_dlr"
}
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Возвращается "result": true если данные успешно сохранены (или ошибка, если входные параметры не прошли валидацию).
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": true,
"error": null
}
Если указать несуществующий адрес, то SMS не будут отправляться с параметром
dlr_level
¶ Обновление адреса DLR
Метод позволяет обновить уже установленный адрес обработчика отчётов о доставке (DLR) SMS-сообщений, отправленных с Ваших номеров.
¶ Запрос
POST
sms/update-dlr-url
https://sms-api.plusofon.ru
| Параметр | Описание | Пример |
|---|---|---|
url |
string | адрес обработчика DLR-запросов |
number |
string | номер телефона, если указать, то адрес назначается только на него, иначе — на все номера |
params |
object | объект с POST-параметрами, которые будут переданы на URL (например, данные авторизации) |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/update-dlr-url",
"id": "1",
"params": {
"url": "http://domen.my/sms_dlr"
}
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Возвращается "result": true если данные успешно сохранены (или ошибка, если входные параметры не прошли валидацию).
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": true,
"error": null
}
¶ Удаление адреса DLR
Метод позволяет удалить установленный адрес обработчика отчётов о доставке (DLR) SMS-сообщений, отправленных с Ваших номеров.
¶ Запрос
POST
sms/delete-dlr-url
https://sms-api.plusofon.ru
| Параметр | Тип | Описание |
|---|---|---|
number |
string | номер телефона, если нужно удалить адрес, установленный на номере |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/delete-dlr-url",
"id": "1"
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Возвращается "result": true если данные успешно сохранены (или ошибка, если входные параметры не прошли валидацию).
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": true,
"error": null
}
¶ Входящие SMS
Вы можете получать SMS-сообщения на собственном оборудовании в режиме реального времени. Для этого необходимо указать URL-адрес обработчика входящих SMS, на который будут приходить вебхуки (POST-запросы) с SMS-сообщениями.
¶ Алгоритм работы очереди входящих SMS
Если с первой попытки вебхук доставить не удаётся (Ваш сервер недоступен или получен код ответа, отличный от 200), сообщение будет возвращено в очередь на доставку. Дальнейший алгоритм доставки этого сообщения выглядит следующим образом:
-
Время повторной доставки выставляется равным текущему + 1 минута. Счетчик неудачных доставок выставляется в значение
1. -
При следующей неудачной доставке время повторной доставки выставляется равным текущему + 1 минута. Счетчик неудачных доставок выставляется в значение
2. -
При следующей неудачной доставке время повторной доставки выставляется равным текущему + 1 минута. Счетчик неудачных доставок выставляется в
3. -
При следующей неудачной доставке время повторной доставки выставляется равным текущему + 1 час. Счетчик неудачных доставок выставляется в
4. -
При последующих неудачных доставках интервал повторной доставки выставляется равным 1 часу. Счетчик неудачных доставок увеличивается на 1.
-
Когда счетчик неудачных доставок достигнет значения
50(двое суток), сообщение будет удалено из очереди вебхуков, а попыток доставки этого сообщения более предприниматься не будет.
¶ Формат данных
На адрес обработчика приходят вебхуки (POST-запросы) со следующими параметрами:
| Параметр | Описание | Пример |
|---|---|---|
src_number |
А-номер (отправитель) | 79993332210 |
dst_number |
Б-номер (получатель) | 79993332211 |
content |
текст сообщения | привет! |
date |
дата и время сообщения | "2022-06-07 14:47:09" |
¶ Получение адреса обработчика входящих SMS
Метод позволяет получить текущий адрес обработчика входящих SMS-сообщений, отправленных на Ваши номера.
¶ Запрос
POST
sms/get-sms-url
https://sms-api.plusofon.ru
| Параметр | Тип | Описание |
|---|---|---|
number |
string | номер телефона, если необходимо получить адрес на номере |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/get-sms-url",
"id": "1"
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Возвращается массив (или ошибка, если входные параметры не прошли валидацию):
| Параметр | Пример |
|---|---|
url |
адрес обработчика |
number |
номер телефона (если запрос по номеру) |
params |
массив с POST-параметрами, которые будут переданы на URL (например данные авторизации) |
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"url": "http://domen.my/sms_in",
"params": []
},
"error": null
}
¶ Получение адреса обработчика входящих SMS по номеру телефона
Метод позволяет получить текущий адрес обработчика входящих SMS-сообщений, отправленных на Ваш конкретный номер.
POST
sms/get-sms-url-by-number
https://sms-api.plusofon.ru
| Параметр | Тип | Описание |
|---|---|---|
number |
string | номер телефона |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/get-sms-url-by-number",
"id": "1",
"params": {
"number": "79993332210"
}
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Возвращается возвращает массив (или ошибку, если входные параметры не прошли валидацию):
| Параметр | Описание |
|---|---|
url |
адрес обработчика |
params |
массив с POST-параметрами, которые будут переданы на URL (например данные авторизации) |
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"url": "https://new-portal.plusofon.ru/site/incoming-sms",
"params": [],
"customer_id": 1234
},
"error": null
}
¶ Получение списка адресов обработчиков по номеру
Метод позволяет получить список текущих адресов обработчиков входящих SMS-сообщений, отправленных на Ваши номера.
¶ Запрос
POST
sms/get-sms-url-by-number-list
https://sms-api.plusofon.ru
Параметры:
| Параметр | Тип | Описание |
|---|---|---|
number |
string | номер телефона |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/get-sms-url-by-number-list",
"id": "1",
"params": {
"number": "79993332210"
}
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Возвращается массив (или ошибка, если входные параметры не прошли валидацию):
| Параметр | Описание |
|---|---|
url |
массив адресов обработчиков |
params |
массив с POST-параметрами, которые будут переданы на URL (например данные авторизации) |
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"customer_id": 1234,
"params": [],
"url": [
"https://new-portal.plusofon.ru/site/incoming-sms"
]
},
"error": null
}
¶ Добавление адреса обработчика входящих SMS
Метод позволяет добавить новый адрес обработчика входящих SMS-сообщений, отправленных на Ваши номера.
¶ Запрос
POST
sms/add-sms-url
https://sms-api.plusofon.ru
| Параметр | Тип | Описание | |
|---|---|---|---|
url |
string | адрес обработчика входящих SMS |
http://domen.my/sms_in |
number |
string | номер телефона, если указать, то адрес назначается только на него, иначе — на все номера | |
params |
object | объект с POST-параметрами, которые будут переданы на URL (например, данные авторизации) |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/add-sms-url",
"id": "1",
"params": {
"url": "http://domen.my/sms_in"
}
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Возвращается "result": true если данные успешно сохранены (или ошибка, если входные параметры не прошли валидацию).
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": true,
"error": null
}
¶ Удаление адреса обработчика входящих SMS
Метод позволяет удалить адрес обработчика входящих SMS-сообщений, отправленных на Ваши номера.
¶ Запрос
POST
sms/delete-sms-url
https://sms-api.plusofon.ru
| Параметр | Описание | Пример |
|---|---|---|
number |
string | номер телефона, если необходимо удалить адрес на номере |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/delete-sms-url",
"id": "1"
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Возвращается "result": true если данные успешно сохранены (или ошибка, если входные параметры не прошли валидацию).
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": true,
"error": null
}
¶ Авторизация по токену к номеру телефона
Если Вы хотите дать кому-либо API-доступ к SMS-сообщениям только по определённым номерам, Вы можете воспользоваться методами SMS API с авторизацией по конкретному номеру телефона.
¶ Получение токена по номеру телефона
Метод позволяет получить токен доступа к управлению SMS-сообщениями на конкретном мобильном номере.
¶ Запрос
POST
sms/add-token
https://sms-api.plusofon.ru
| Параметр | Тип | Описание |
|---|---|---|
number |
string | номер телефона |
Пример:
curl -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "sms/add-token",
"id": "1",
"params": {
"number": "79993332210"
}
}' \
-X POST https://sms-api.plusofon.ru
¶ Ответ
Возвращается токен в поле result или ошибка.
Пример:
{
"jsonrpc": "2.0",
"id": "1",
"result": "nWm2b77omiJXRtck1VfkK",
"error": null
}
¶ Методы при авторизации по токену к номеру телефона
Описание методов