Интеграция с сервисом (API)

API позволяет рассылать сообщения через ваши проекты и сервисы по протоколам HTTP/HTTPS, SMTP и SMPP. Готовые библиотеки на разных языках программирования подключаются к вашему проекту и помогают отправлять сообщения из любого места с помощью одной команды. Для упрощенной авторизации вместо пары логин и пароль можно использовать специальный API-ключ.
HTTP/HTTPS SMTP SMPP SOAP OMS SMS-команды Библиотеки и примеры кода

ОТПРАВКА СООБЩЕНИЙ

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

Комментарии в SMS-сообщениях

Отправка на группу номеров

Отправка HLR-запроса

Отправка e-mail сообщения

Отправка голосового сообщения (звонок)

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

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

Отправка сообщения в чат-бот Telegram

Использование префиксов при отправке сообщений

Управление шаблонами сообщений

Управление шаблонами операторов

Виртуальная отправка (режим тестирования)

Уведомления о событиях

УПРАВЛЕНИЕ РАССЫЛКАМИ

СТАТУСЫ СООБЩЕНИЙ

ПРОВЕРКА СОСТОЯНИЯ БАЛАНСА

УПРАВЛЕНИЕ КОНТАКТАМИ

УПРАВЛЕНИЕ КЛИЕНТАМИ

УПРАВЛЕНИЕ ИМЕНАМИ ОТПРАВИТЕЛЕЙ (SENDER ID)

ПОЛУЧЕНИЕ ДАННЫХ

РАЗНОЕ

Управление контактами

Действия с контактами и группами

Для управления контактами или группами необходимо вызвать методом GET или POST соответствующий адрес с указанием требуемой команды и параметров.

Для создания контакта: https://smsc.ru/sys/phones.php?add=1&login=<login>&psw=<password>&phone=<phone>&name=<name>
Для создания новой группы: https://smsc.ru/sys/phones.php?add_group=1&login=<login>&psw=<password>&name=<name>
Для изменения номера телефона в контакте: https://smsc.ru/sys/phones.php?chg=1&login=<login>&psw=<password>&phone=<phone>&new_phone=<new_phone>
Для изменения названия группы: https://smsc.ru/sys/phones.php?chg_group=1&login=<login>&psw=<password>&grp=<group_id>&name=<name>
Для переноса контакта в новую группу: https://smsc.ru/sys/phones.php?move_group=1&login=<login>&psw=<password>&grp=<group_id>&phone=<phone>
Для добавления новой группы к контакту: https://smsc.ru/sys/phones.php?move_group=2&login=<login>&psw=<password>&grp=<group_id>&phone=<phone>
Для удаления контакта из группы: https://smsc.ru/sys/phones.php?move_group=3&login=<login>&psw=<password>&grp=<group_id>&phone=<phone>
Для удаления контакта: https://smsc.ru/sys/phones.php?del=1&login=<login>&psw=<password>&phone=<phone>
Для удаления группы: https://smsc.ru/sys/phones.php?del_group=1&login=<login>&psw=<password>&grp=<group_id>
Для вывода списка контактов: https://smsc.ru/sys/phones.php?get=1&login=<login>&psw=<password>
Для вывода списка групп: https://smsc.ru/sys/phones.php?get_group=1&login=<login>&psw=<password>
Для добавления записи в "черный" список: https://smsc.ru/sys/phones.php?add_black=1&login=<login>&psw=<password>&phone=<phone>
Для удаления записи из "черного" списка: https://smsc.ru/sys/phones.php?del_black=1&login=<login>&psw=<password>&phone=<phone>
Для получения элементов "черного" списка: https://smsc.ru/sys/phones.php?get_black=1&login=<login>&psw=<password>

Контакты и группы. Описание параметров

Описание параметров, передаваемых Серверу:

ПараметрЗначение
loginЛогин Клиента.
pswПароль Клиента (можно добавить или изменить на данной странице).
apikeyСпециальный API-ключ, используемый для упрощенной авторизации вместо пары "логин+пароль" (можно создать на данной странице).
nameНазвание контакта или группы.
grpИдентификатор группы, которой принадлежит создаваемый контакт. Можно привязать контакт сразу к нескольким группам, указав их идентификаторы через запятую.
numНомер группы для рассылок сообщений.
phoneСписок номеров телефонов через любой разделитель (команда add), либо номер телефона (команды move_group, add_black). Используется для операций с номерами телефонов в скрипте phones.php.
mailСписок e-mail адресов через любой разделитель (команда add), либо e-mail адрес (команды move_group, add_black). Используется для операций с e-mail адресами в скрипте mails.php. Формат запросов аналогичен формату для phones.php.
new_phoneНовый список номеров телефонов через любой разделитель (команда chg).
new_mailНовый список e-mail адресов через любой разделитель (команда chg).
lnmФамилия.
fnmИмя.
mnmОтчество.
fioФИО контакта. Данный параметр используется в команде get для получения списка контактов по любому из инициалов (фамилии, имени и (или) отчеству).
searchВыборка контактов для команды get по названию контакта и (или) номеру телефона.
after_idИдентификатор контакта (int_id), начиная с которого необходимо вернуть список контактов (команда get, формат fmt=3), за исключением самого after_id.
bdДата рождения в формате дд.мм.гггг.
myidID контакта, назначенный Клиентом.
cmtКомментарии.
tagsТеги (метки).
phoДругие номера телефонов. По данным номерам рассылка SMS-сообщений не выполняется.
typeТип блокировки (команды add_black):
0 – все сообщения.
1 – массовые рассылки.
2 – одиночные сообщения.
Либо тип группы (команды add_group и get_group):
0 – группа для номеров телефонов.
1 – группа для e-mail адресов.
prev_idГлобальный идентификатор элемента "черного" списка (параметр id в ответе Сервера), назначаемый Сервером автоматически. Используется в команде get_black для запроса элементов "черного списка", добавленных ранее до данного элемента.
cntКоличество записей, возвращаемых в ответе Сервера. Максимальное значение равно 1000.
fmtФормат ответа сервера:
0 – (по умолчанию) в виде строки (ID = 12345).
1 – в виде строки (12345).
2 – в xml формате.
3 – в json формате.

Контакты и группы. Ответ сервера и коды ошибок

В случае ошибки Сервер возвращает следующую строку:
  • ERROR = N (описание)

  • При fmt = 1:
    0,-N

  • При fmt = 2:
    <result>
    <error>описание</error>
    <error_code>N</error_code>
    </result>

  • При fmt = 3:
    {
    "error": "описание",
    "error_code": N
    }
N – номер ошибки, может принимать следующие значения:

ЗначениеОписание
1Ошибка в параметрах.
2Неверный логин или пароль. Также возникает при попытке отправки сообщения с IP-адреса, не входящего в список разрешенных Клиентом (если такой список был настроен Клиентом ранее).
3Записи не найдены.
4IP-адрес временно заблокирован.
5Ошибка выполнения операции.
9Попытка отправки более трех одинаковых запросов на операции с группами, контактами или записями "черного" списка в течение минуты.
Данная ошибка возникает также при попытке отправки пятнадцати и более запросов одновременно с разных подключений под одним логином (too many concurrent requests).

В случае успешного запроса Сервер возвращает ответ в виде строки.

При создании контакта, группы контактов, записи "черного" списка:
  • при fmt = 0: ID = <id>

  • при fmt = 1: <id>

  • при fmt = 2 (создание контакта, записи "черного" списка):
    <phone>
    <id>id</id>
    </phone>

  • при fmt = 2 (создание группы):
    <group>
    <id>id</id>
    </group>

  • при fmt = 3:
    {
    "id": <id>
    }

Где <id> – идентификатор контакта, группы или записи "черного" списка, назначенный Сервером автоматически.

При изменении или удалении контакта (группы), удалении записи "черного" списка:
  • при fmt = 0,1: OK

  • при fmt = 2: <result>OK</result>

  • при fmt = 3:
    {
    "result": "OK"
    }


При запросе списка контактов:
  • при fmt = 0:
    phone = <phone>, name = <name>, group = <group>, first_name = <first_name>, last_name = <last_name>, middle_name = <middle_name>, birthday = <birthday>, id = <id>, comments = <comments>, tags = <tags>, phone_other = <phone_other>
    ...

  • при fmt = 1:
    <phone>,<name>,<group>,<first_name>,<last_name>,<middle_name>,<birthday>,<id>,<comments>,<tags>,<phone_other>
    ...

  • при fmt = 2:
    <list>
    <contact>
    <phone>phone</phone>
    <name>name</name>
    <group>group</group>
    <first_name>first_name</first_name>
    <last_name>last_name</last_name>
    <middle_name>middle_name</middle_name>
    <birthday>birthday</birthday>
    <id>id</id>
    <comments>comments</comments>
    <tags>tags</tags>
    <phone_other>phone_other</phone_other>
    </contact>
    ...
    </list>

  • при fmt = 3:
    [{
    "phone": "<phone>",
    "name": "<name>",
    "group": <group>,
    "first_name": "<first_name>",
    "last_name": "<last_name>",
    "middle_name": "<middle_name>",
    "birthday": "<birthday>",
    "id": "<id>",
    "comments": "<comments>",
    "tags": "<tags>",
    "phone_other": "<phone_other>"
    },
    ...]

Где:
<phone> – список номеров телефонов через любой разделитель. Для e-mail адресов заменяется на <mail>.
<name> – название контакта.
<group> – идентификатор группы, к которой принадлежит контакт.
<first_name> – имя.
<last_name> – фамилия.
<middle_name> – отчество.
<birthday> – дата рождения в формате дд.мм.гггг.
<id> – id контакта, назначенный Клиентом.
<comments> – комментарии.
<tags> – теги (метки).
<phone_other> – другие номера телефонов. По данным номерам рассылка сообщений не выполняется. Для e-mail адресов заменяется на <mail_other>.

При запросе списка групп:
  • при fmt = 0:
    id = <id>, name = <name>, number = <number>, cnt = <cnt>
    ...

  • при fmt = 1:
    <id>,<name>,<number>,<cnt>
    ...

  • при fmt = 2:
    <list>
    <group>
    <id>id</id>
    <name>name</name>
    <number>number</number>
    <cnt>number</cnt>
    </group>
    ...
    </list>

  • при fmt = 3:
    [{
    "id": <id>,
    "name": "<name>",
    "number": <number>,
    "cnt": "<cnt>"
    },
    ...]

Где:
<id> – идентификатор группы, назначенный Сервером при создании.
<name> – название группы.
<number> – номер группы для рассылок.
<cnt> – количество контактов в группе.

При запросе элементов "черного" списка:
  • при fmt = 0:
    id = <id>, phone = <phone>, type = <type>, comment = <comment>
    ...

  • при fmt = 1:
    <id>,<phone>,<type>,<comment>
    ...

  • при fmt = 2:
    <list>
    <record>
    <id>id</id>
    <phone>phone</phone>
    <type>type</type>
    <comment>comment</comment>
    </record>
    ...
    </list>

  • при fmt = 3:
    [{
    "id": <id>,
    "phone": "<phone>",
    "type": <type>,
    "comment": "<comment>"
    },
    ...]

Где:
<id> – идентификатор элемента, назначенный Сервером при создании.
<phone> – номер телефона (или <email> при запросе "черного" списка e-mail).
<type> – тип блокировки: 0 – все сообщения, 1 – массовые рассылки, 2 – одиночные сообщения.
<comment> – комментарии.

Примеры операций с контактами

Примеры:

Создание контакта с именем "Contact", принадлежащего группе с ID = 321:

https://smsc.ru/sys/phones.php?add=1&login=alex&psw=123&phone=79999999999&name=Contact&grp=321
Создание группы с именем "Group":

https://smsc.ru/sys/phones.php?add_group=1&login=alex&psw=123&name=Group
Изменение имени контакта с номером телефона "79999999999" на новое имя "Contact1":

https://smsc.ru/sys/phones.php?chg=1&login=alex&psw=123&phone=79999999999&name=Contact1
Изменение названия группы с ID = 321 на новое название "Group1":

https://smsc.ru/sys/phones.php?chg_group=1&login=alex&psw=123&grp=321&name=Group1
Удаление контакта с номером телефона "79999999999":

https://smsc.ru/sys/phones.php?del=1&login=alex&psw=123&phone=79999999999
Удаление группы с ID = 321:

https://smsc.ru/sys/phones.php?del_group=1&login=alex&psw=123&grp=321
Получение списка контактов, принадлежащих группе с ID = 321:

https://smsc.ru/sys/phones.php?get=1&login=alex&psw=123&grp=321
Получение данных контакта с номером телефона "79999999999":

https://smsc.ru/sys/phones.php?get=1&login=alex&psw=123&phone=79999999999
Получение списка всех групп:

https://smsc.ru/sys/phones.php?get_group=1&login=alex&psw=123
Добавление телефона "79999999999" в "черный" список с блокировкой только массовых рассылок:

https://smsc.ru/sys/phones.php?add_black=1&login=alex&psw=123&phone=79999999999&type=1
Удаление телефона "79999999999" из "черного" списка:

https://smsc.ru/sys/phones.php?del_black=1&login=alex&psw=123&phone=79999999999

Сервер не принимает более трех одинаковых запросов в течение минуты на операции с группами, контактами или записями "черного" списка для снижения нагрузки и защиты от ошибок и зацикливаний в программе на стороне Клиента.