Отправка смс сообщения

Функция: 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 Режим:
      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
Возможные ошибки
Код Текст Описание
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 Не достаточно средств на счету
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 не содержит ни одного получателя