Отправка смс сообщения
Функция: send
Адрес: https://mainsms.ru/api/mainsms/message/send
Параметры запроса:
|
Параметр
|
Описание
|
Обязательный / Viber
|
Формат
|
Пример
|
|
project
|
Имя проекта
|
Да
|
Строка
|
mainsms
|
|
recipients
|
Получатели
|
Да
|
Строка, список номеров через запятую. Международный формат номера E.164. Лимит 100 номеров.
|
89121231234,9121231235
|
|
message
|
Текст сообщения
|
Да
|
Строка в кодировке utf-8
|
Привет от mainsms.ru
|
|
sender
|
Имя отправителя
|
Нет
|
Строка (от 5 до 11 символов, латиница, цифры)
|
mainsms.ru
|
|
run_at
|
время отправки сообщения
|
Нет
|
Дата и время
|
03.10.2011 17:00
|
|
test
|
Тестовый режим
|
Нет
|
Число, 0 или 1
|
0
|
|
image
|
URL изображения в формате JPG, PNG. Размер обязательно 400х400 пикселей.
|
Нет / если указан, то обязательны button и button_url
|
URL обязательно должен начинаться со схемы http:// или https://
|
https://foobar.com/images/logo.jpg
|
|
button
|
Текст на кнопке
|
Нет / если указан, то обязательны image и button_url
|
до 20 символов
|
Перейти на мой сайт
|
|
button_url
|
Ссылка для кнопки
|
Нет / если указан, то обязательны image и button
|
Обязательно наличие схемы в URL http:// или https:// или tel:
|
https://foobar.com/catalog
|
|
viber
|
Режим:
не указан - Только SMS
1 - Только Viber
2 - Viber или SMS
|
Нет /
Настройки режима Viber должны быть отключены в API проекте.
|
Число, 1 или 2
|
1
|
|
viber_text
|
Текст сообщения Viber
|
Нет /
Если не указан, будет использован текст из message.
|
Строка максимум 1000 символов
|
Wow! I'ts VIBER MESSAGE :)
|
|
sign
|
Подпись запроса
|
Да, если не указан apikey
|
Строка, в нижнем регистре
|
e2271659a8b05d3c644ba8b47
|
Viber
Параметры image, button и button_url могут быть заданы для отправки сообщений по Viber, каждый из данных параметров зависит друг от друга и не может быть задан только один.
Отправка Viber сообщения возможна, только в случае, когда проект настроен на отправку сообщений по Viber в личном кабинете либо передан параметр viber
Лимит получателей.
В одном запросе возможно отправить только до 100 номеров получателей.
Если сообщение должно быть отправлено в определенное время заполните параметр
run_at.
Время должно быть указано в Вашем часовом поясе (посмотреть и поменять свой часовой пояс можно на
этой странице.
Пример запроса c использованием apikey:
curl -X GET https://mainsms.ru/api/message/send \
-H 'Accept: application/json' \
-F project=my_project_name \
-F recipients=79121231235 \
-F message="my api test" \
-F apikey=59a8b05d318b4b5
Пример безопасного запроса c использованием сигнатуры:
curl -X GET https://mainsms.ru/api/message/send \
-H 'Accept: application/json' \
-F project=my_project_name \
-F recipients=79121231235 \
-F message="secure api test" \
-F sign=4fb6b26d0403ddbd075d8db0652e3bfa
Пример отправки Viber или SMS сообщения с разным текстом:
# Внимание! Опция Viber или SMS в настройках проекта Выключена, используется параметр viber
curl -X GET https://mainsms.ru/api/message/send \
-H 'Accept: application/json' \
-F project=my_project_name \
-F recipients=79121231235 \
-F message="sms message" \
-F viber_text="viber message" \
-F viber=1 \
-F button="" \
-F button_url="" \
-F image="" \
-F sign=8862d178f59b47d203341819351aa7e5
Пример отправки Viber сообщения с картинкой:
# Включена опция Viber или SMS в настройках проекта.
curl -X GET https://mainsms.ru/api/message/send \
-H 'Accept: application/json' \
-F project=my_project_name \
-F recipients=79121231235 \
-F message="viber message with image" \
-F button="Buy" \
-F button_url="https://foo.bar/catalog" \
-F image="https://foo.bar/images/promo.png" \
-F sign=6263e4da2e7a0cef6f199edd3e4baa55
Варианты ответа:
Успех
|
Параметр
|
Описание
|
Формат
|
Пример
|
|
status
|
Статус
|
Строка, success
|
success
|
|
recipients
|
Номера получателей принятые к отправке, в формате E.164
|
Массив
|
["9121231234","9121231235"]
|
|
messages_id
|
Идентификаторы сообщений
|
Массив
|
[1567,1568]
|
|
parts
|
Количество частей в сообщении
|
Число
|
1
|
|
count
|
Общее количество отправленных сообщений
|
Число
|
2
|
|
price
|
Цена отправки
|
Число
|
0.7
|
|
balance
|
Остаток средств
|
Число
|
99.3
|
|
test
|
Тестовый режим
|
Число
|
0
|
Ошибка
|
Параметр
|
Описание
|
Формат
|
Пример
|
|
status
|
Статус
|
Строка, error
|
error
|
|
error
|
Код ошибки
|
Число
|
2
|
|
message
|
Текст ошибки
|
Строка
|
invalid signature or message encoding is not utf8
|
Возможные ошибки
|
Код
|
Текст
|
Описание
|
|
1
|
param project is blank
|
Параметр project пуст
|
|
2
|
invalid signature or message encoding is not utf8
|
Не верная подпись запроса(параметр sign) или кодировка текста сообщения не utf8
|
|
3
|
param message is blank
|
Параметр message пуст
|
|
4
|
param recipients is blank
|
Параметр recipients пуст
|
|
5
|
project not found
|
Проект с таким именем не найден
|
|
6
|
recipients not found or bad format
|
Параметр recipients не содержит ни одного получателя
|
|
7
|
not enough money
|
Не достаточно средств на счету
|
|
8
|
invalid sender
|
Параметр сендер пуст, содержит недопустимые символы или недопустимой длинны.
|
|
9
|
sender not verified
|
Имя отправителя не проверено
|
|
10
|
project is paused
|
Проект выключен
|
Статус смс сообщения
Функция: status
Адрес: https://mainsms.ru/api/mainsms/message/status
Параметры запроса:
|
Параметр
|
Описание
|
Обязательный
|
Формат
|
Пример
|
|
project
|
Имя проекта
|
Да
|
Строка
|
mainsms
|
|
messages_id
|
Идентификаторы сообщений
|
Да
|
Список идентификаторов сообщений через запятую
|
1567,1568
|
|
sign
|
Подпись запроса
|
Да
|
Строка, в нижнем регистре
|
a2271659a8b05d318b4b53c644ba8b99
|
Пример запроса c использованием apikey:
curl -X GET https://mainsms.ru/api/message/status \
-H 'Accept: application/json' \
-F project=mainsms \
-F messages_id=1567,1568 \
-F apikey=59a8b05d318b4b5
Пример безопасного запроса c использованием сигнатуры:
curl -X GET https://mainsms.ru/api/message/status \
-H 'Accept: application/json' \
-F project=mainsms \
-F messages_id=1567,1568 \
-F sign=cb9433871c4c5d2cacd7d9e60d7bad52
Варианты ответа:
Успех
|
Параметр
|
Описание
|
Формат
|
Пример
|
|
status
|
Статус
|
Строка, success
|
success
|
|
messages
|
Статус сообщений (идентификатор => статус)
|
Ассоциативный массив
|
{"1567" : "delivered", "1568" : "accepted"}
|
|
channels
|
Канал доставки сообщений (идентификатор => канал), значения: sms или viber
|
Ассоциативный массив
|
{"1567" : "sms", "1568" : "viber"}
|
Возможные значения status
| значение | Описание |
| enqueued | В очереди на отправление |
| accepted | Принято к отправлению |
| delivered | Доставлено |
| non-delivered | Отклонено |
| scheduled | Запланировано |
| canceled | Отменено |
| wait | Ожидает отправки |
| overdue | Просрочено* |
* Оператор может уменьшать время жизни сообщения для снижения нагрузок на свои сети, когда абонент долгое время находится не в сети.
Ошибка
|
Параметр
|
Описание
|
Формат
|
Пример
|
|
status
|
Статус
|
Строка, error
|
error
|
|
error
|
Код ошибки
|
Число
|
2
|
|
message
|
Текст ошибки
|
Строка
|
invalid signature
|
Возможные ошибки
|
Код
|
Текст
|
Описание
|
|
1
|
param project is blank
|
Параметр project пуст
|
|
5
|
project not found
|
Проект с таким именем не найден
|
|
2
|
invalid signature
|
Не верная подпись запроса(параметр sign)
|
|
9
|
messages_id is blank
|
Параметр messages_id пуст
|
Webhook статуса смс сообщения
Чтобы получать обновления статусов автоматически, укажите в настройках проекта URL обновления статуса.
При поступлении от оператора статуса, он будет перенаправлен на Ваш URL.
Запрос будет содержать информацию об ID сообщения в нашей платформе, а также номер получателя, статус сообщения и дату обновления статуса.
Метод: GET
Параметры запроса получаемого на ваш URL:
|
Параметр
|
Описание
|
Формат
|
Пример
|
| id | Идентификатор сообщения в нашей системе | число | 189228833 |
| phone | Номер телефона получателя | число | 70000000000 |
| status | Статус сообщения | строка | delivered |
| date | Дата обновления статуса | строка | 2018-02-23T12:46:20+00:00 |
Возможные значения параметра status
| Значение | Описание |
| enqueued | В очереди на отправление |
| accepted | Принято к отправлению |
| delivered | Доставлено |
| non-delivered | Отклонено |
| scheduled | Запланировано |
| canceled | Отменено |
| wait | Ожидает |
Отмена запланированных смс сообщений
Функция: cancel
Адрес: https://mainsms.ru/api/mainsms/message/cancel
Параметры запроса:
|
Параметр
|
Описание
|
Обязательный
|
Формат
|
Пример
|
|
project
|
Имя проекта
|
Да
|
Строка
|
mainsms
|
|
messages_id
|
Идентификаторы сообщений
|
Да
|
Список идентификаторов сообщений через запятую
|
1567,1568
|
|
sign
|
Подпись запроса
|
Да
|
Строка, в нижнем регистре
|
a2271659a8b05d318b4b53c644ba8b99
|
Пример запроса c использованием apikey:
curl -X GET https://mainsms.ru/api/message/cancel \
-H 'Accept: application/json' \
-F project=mainsms \
-F messages_id=1567,1568 \
-F apikey=59a8b05d318b4b5
Пример безопасного запроса c использованием сигнатуры:
curl -X GET https://mainsms.ru/api/message/cancel \
-H 'Accept: application/json' \
-F project=mainsms \
-F messages_id=1567,1568 \
-F sign=cb9433871c4c5d2cacd7d9e60d7bad52
Варианты ответа:
Успех
|
Параметр
|
Описание
|
Формат
|
Пример
|
|
status
|
Статус
|
Строка, success
|
success
|
|
messages
|
Массив статусов сообщений (идентификатор => статус)
|
Ассоциативный массив
|
{"1567" : "canceled", "1568" : "canceled"}
|
Цена смс сообщения
Функция: price
Адрес: https://mainsms.ru/api/mainsms/message/price
Параметры запроса:
|
Параметр
|
Описание
|
Обязательный
|
Формат
|
Пример
|
|
project
|
Имя проекта
|
Да
|
Строка
|
mainsms
|
|
recipients
|
Получатели
|
Да
|
Строка, список номеров через запятую в любом формате
|
89121231234,9121231235
|
|
message
|
Текст сообщения
|
Да
|
Строка в кодировке utf-8
|
Привет от mainsms.ru
|
|
sign
|
Подпись запроса
|
Да
|
Строка, в нижнем регистре
|
k2271659a8b05d318b4b53c644ba8b42
|
Пример запроса c использованием apikey:
curl -X GET https://mainsms.ru/api/message/price \
-H 'Accept: application/json' \
-F project=my_project_name \
-F recipients=79121231235 \
-F message="my api test" \
-F apikey=59a8b05d318b4b5
Пример безопасного запроса c использованием сигнатуры:
curl -X GET https://mainsms.ru/api/message/price \
-H 'Accept: application/json' \
-F project=my_project_name \
-F recipients=79121231235 \
-F message="secure api test" \
-F sign=4fb6b26d0403ddbd075d8db0652e3bfa
Варианты ответа:
Успех
|
Параметр
|
Описание
|
Формат
|
Пример
|
|
status
|
Статус
|
Строка, success
|
success
|
|
recipients
|
Корректные номера получателей
10 символов
|
Массив
|
["9121231234","9121231235"]
|
|
parts
|
Количество частей в сообщении
|
Число
|
1
|
|
count
|
Общее количество отправленных сообщений
|
Число
|
2
|
|
price
|
Цена отправки
|
Число
|
0.7
|
|
balance
|
Остаток средств
|
Число
|
99.3
|
Ошибка
|
Параметр
|
Описание
|
Формат
|
Пример
|
|
status
|
Статус
|
Строка, error
|
error
|
|
error
|
Код ошибки
|
Число
|
2
|
|
message
|
Текст ошибки
|
Строка
|
invalid signature
|
Возможные ошибки
|
Код
|
Текст
|
Описание
|
|
1
|
param project is blank
|
Параметр project пуст
|
|
2
|
invalid signature
|
Не верная подпись запроса(параметр sign)
|
|
3
|
param message is blank
|
Параметр message пуст
|
|
4
|
param recipients is blank
|
Параметр recipients пуст
|
|
5
|
project not found
|
Проект с таким именем не найден
|
|
6
|
recipients not found or bad format
|
Параметр recipients не содержит ни одного получателя
|
|
7
|
not enough money
|
Не достаточно средств на счету
Для калькуляции стоимости отправки сообщения используется значение баланса счета
|
Запрос остатка средств
Функция: balance
Адрес: https://mainsms.ru/api/mainsms/message/balance
Параметры запроса:
|
Параметр
|
Описание
|
Обязательный
|
Формат
|
Пример
|
|
project
|
Имя проекта
|
Да
|
Строка
|
mainsms
|
|
sign
|
Подпись запроса
|
Да
|
Строка, в нижнем регистре
|
y2271659a8b05d318b4b53c644ba8b0
|
Пример запроса c использованием apikey:
curl -X GET https://mainsms.ru/api/message/balance \
-H 'Accept: application/json' \
-F project=mainsms \
-F apikey=59a8b05d318b4b5
Пример безопасного запроса c использованием сигнатуры:
curl -X GET https://mainsms.ru/api/message/balance \
-H 'Accept: application/json' \
-F project=mainsms \
-F sign=6a21baeb724eb4921ff872206e5dc7e0
Варианты ответа:
Успех
|
Параметр
|
Описание
|
Формат
|
Пример
|
|
status
|
Статус
|
Строка, success
|
success
|
|
balance
|
Остаток средств на счете
|
Число
|
99.65
|
Ошибка
|
Параметр
|
Описание
|
Формат
|
Пример
|
|
status
|
Статус
|
Строка, error
|
error
|
|
error
|
Код ошибки
|
Число
|
2
|
|
message
|
Текст ошибки
|
Строка
|
invalid signature
|
Возможные ошибки
|
Код
|
Текст
|
Описание
|
|
1
|
param project is blank
|
Параметр project пуст
|
|
2
|
invalid signature
|
Не верная подпись запроса(параметр sign)
|
|
5
|
project not found
|
Проект с таким именем не найден
|
Запрос информации о номерах
Функция: info
Адрес: https://mainsms.ru/api/mainsms/message/info
Параметры запроса:
|
Параметр
|
Описание
|
Обязательный
|
Формат
|
Пример
|
|
project
|
Имя проекта
|
Да
|
Строка
|
mainsms
|
|
phones
|
Номера
|
Да
|
Строка, список номеров через запятую в любом формате
|
89121231234,9121231235
|
|
sign
|
Подпись запроса
|
Да
|
Строка, в нижнем регистре
|
k2271659a8b05d318b4b53c644ba8b42
|
Пример запроса c использованием apikey:
curl -X GET https://mainsms.ru/api/message/info \
-H 'Accept: application/json' \
-F project=mainsms \
-F recipients=89121231234,9121231235
-F apikey=59a8b05d318b4b5
Пример безопасного запроса c использованием сигнатуры:
curl -X GET https://mainsms.ru/api/message/info \
-H 'Accept: application/json' \
-F project=mainsms \
-F recipients=89121231234,9121231235 \
-F sign=c32a17012c1885a208874910462c44b8
Варианты ответа:
Успех
|
Параметр
|
Описание
|
Формат
|
Пример
|
|
status
|
Статус
|
Строка, success
|
success
|
|
info
|
Информация по запросу
|
Массив ответов
|
[["79121231234", {"code":"912", "region":"Сыктывкар Республика Коми", "name":"ОАО 'Мобильные ТелеСистемы'"}], ["79121231235", { "code":"912", "region":"Сыктывкар Республика Коми", "name":"ОАО 'Мобильные ТелеСистемы'"}]]
|
Как видно из примера выше, параметр Info это массив, каждый элемент которого так же является массивом из двух элементов. Первый элемент это запрашиваемый номер в формате "79*********", а второй элемент это хеш содержащий информацию об операторе которому принадлежит данный номер.
code
- код телефона(первые 3 цифры после цифры 7),
region
- регион оператора,
name
- название оператора
Ошибка
|
Параметр
|
Описание
|
Формат
|
Пример
|
|
status
|
Статус
|
Строка, error
|
error
|
|
error
|
Код ошибки
|
Число
|
2
|
|
message
|
Текст ошибки
|
Строка
|
invalid signature
|
Возможные ошибки
|
Код
|
Текст
|
Описание
|
|
1
|
param project is blank
|
Параметр project пуст
|
|
2
|
invalid signature
|
Не верная подпись запроса(параметр sign)
|
|
4
|
param phones is blank
|
Параметр phones пуст
|
|
5
|
project not found
|
Проект с таким именем не найден
|
|
6
|
phones not found or bad format
|
Параметр phones не содержит ни одного получателя
|