HTTP, HTTPS-протокол

SMS, Viber, VK, WhatsApp, E-Mail, «каскад»

Метод outbox/send нашего API позволяет отправлять как обычные SMS, так и сообщения Viber и VK, «каскадные» сообщения.

Можно применять как GET-, так и POST-запросы.
По умолчанию предполагается, что текст SMS передается в кодировке utf-8. Если ваш текст в кодировке cp1251 (Windows-1251), нужно добавить параметр cp=1251.

Описание обычного GET/POST-запроса

Запросы передаются на адрес:
https://auth.terasms.ru/outbox/send

Пример запроса:
https://auth.terasms.ru/outbox/send?login=terasms&password=12345&target=79017654321&sender=terasms&message=test

Если все параметры верны, то сообщение добавляется в очередь на отправку и возвращается положительное целое число – идентификатор исходящего сообщения или несколько идентификаторов через запятую (если была попытка отправки сообщения на несколько номеров). В противном случае возвращается отрицательное число – код ошибки.

Коды ошибок

Описание параметров

Параметр Значение Описание
login строка обязательный параметр Логин на Платформе TERASMS
sign строка Подпись запроса. Процедура формирования подписи описана в разделе Авторизация при использовании HTTP API.
password строка Пароль партнёра на Платформе TERASMS. Может использоваться вместо параметра sign, однако использование подписи является рекомендуемым способом авторизации
target строка обязательный параметр
  • Для всех сообщений кроме e-mail — номер абонента в международном формате.
    Если необходимо отправить одно и то же сообщение нескольким абонентам, то номера абонентов можно задать через запятую.
    Пример: 79161111111
  • Для самостоятельных e-mail сообщений — почтовый адрес получателя. Также допускается указывать несколько получателей через запятую/точку с запятой.
    Пример: mailbox@domain.com
  • Для e-mail сообщений в составе «Каскада» — пара номер_телефона-почтовый_адрес, разделенные между собой двоеточием.
    В этом случае пара сохраняется в нашей системе и в дальнейшем можно указывать только номер телефона. Почтовый адрес, при необходимости, будет взят по этому номеру.
    Управление сохраненными связками также доступно по API и описано в разделе Отправка сообщений E-mail.
    Пример: 79161111111:mailbox@domain.com
sender строка обязательный параметр
Имя отправителя, зарегистрированное для вас на Платформе TERASMS. Имя отправителя, содержащее в себе латинские буквы (в любом регистре), может содержать от 2 до 11 символов, цифровое имя отправителя — от 2 до 15 символов.
message строка обязательный параметр
Текст сообщения. Текст 1 сообщения составляет 160 символов для латиницы и 70 символов для кириллицы. Сообщение, содержащее большее кол-во символов, разбивается на несколько сегментов и доставляется одним сообщением. Сообщение, состоящее более чем из 160 для латиницы или из 70 символов для кириллицы, разбивается на сегменты. Каждый сегмент составляет 153 для латиницы и 67 символов для кириллицы. По умолчанию сообщение может состоять максимум из 10 сегментов.
email_message массив необязательный параметр
Используется только при передаче в формате JSON.
Предназначен для передачи параметров при отправке e-mail сообщений, как самостоятельных, так и в составе «Каскада».

Поля массива:

  • template_id — идентификатор предварительно загруженного шаблона
  • from — почтовый адрес отправителя письма
  • title — тема письма
  • placeholders — массив подстановок, используемых в указанном шаблоне

Если не указан и передается e-mail сообщение, то:
адрес отправителя будет взят из настроек в Личном кабинете или, при его отсутствии, подставлен общий системный адрес;
тема письма будет взята из настроек в Личном кабинете или, при ее отсутствии, подставлено значение параметра sender;
шаблон текста письма — будет использован шаблон по умолчанию, настроенный в Личном кабинете. При его отсутствии будет отправлен просто текст, без использования шаблона.

Более подробное описание находится в разделе Отправка сообщений E-mail.
cp 1251 необязательный параметр
По умолчанию предполагается, что текст SMS передается в кодировке utf-8. Если ваш текст в кодировке cp1251 (Windows-1251), нужно добавить параметр cp=1251.
mass_push 1 или 0 необязательный параметр
Если необходимо отправить разный текст сообщения каждому абоненту, необходимо добавить параметр mass_push=1, поле message оставить пустым, а в поле target передать номера абонентов и тексты сообщений. В этом случае номер телефона и сообщение разделяются одним пробелом, а символ для разделения сообщений можно задать с помощью параметра delimiter.
delimiter символ необязательный параметр
Символ для разделения сообщений в поле target. По умолчанию принимается символ перевода на новую строку \n.
flash 1 или 0 необязательный параметр
Для отправки сообщений в формате flash.
relative_time число необязательный параметр
Время в секундах, в течение которого предпринимаются попытки доставить сообщение. Если параметр не задан, по умолчанию от 24 до 72 часов в зависимости от оператора.
relative_time_read число необязательный параметр
Время в секундах, в течение которого ожидается отчет о просмотре/прочтении сообщения, где это применимо (мессенджеры Viber, Telegram и т.п.).
date_schedule строка необязательный параметр
Дата и время отложенной отправки сообщения, задается в формате Y-m-d H:i:s. Если задан параметр timezone=1, то платформа сама определит часовой пояс абонента и скорректирует время отправки с учетом этих данных. Время отложенной отправки не должно превышать 30 дней от текущего времени. Если timezone не задан, отправка производится в по московскому времени (GMT +3).
timezone 1 необязательный параметр
Указывает учитывать ли часовой пояс абонента при отложенной отправке. Для определения часового пояса абонента номер должен принадлежать российским сотовым операторам, в противном случае планирование идет по московскому времени (GMT +3).
time_from дата и время в формате Y-m-d H:i:s (пример 2017-06-01 17:30:00) необязательный параметр (требует time_to)
Вместе с time_to задает временное окно для отправки смс абоненту с учетом часового пояса. Номер должен принадлежать российским сотовым операторам, если не удалось определить часовой пояс абонента сообщение отправляется сразу
В случае неверного формата даты возвращается код ошибки -130.
Если указанное время в регионе абонента еще не наступило, дата отправки откладывается на дату старта (time_from)
Если временное окно в регионе абонента уже прошло, но мы попадаем в рамки по времени на текущюю дату, то смс уходит сразу. Если смс не попадает в рамки и время прошло, переносим на дату старта на следующие сутки Если смс не попадает в рамки и время не наступило, оставляем текущую дату в регионе и время старта из time_from.
time_to дата и время в формате Y-m-d H:i:s (пример 2017-06-01 20:30:30) необязательный параметр (требует time_from)
Вместе с time_from задает временное окно для отправки смс абоненту с учетом часового пояса.
schedule_id ID рассылки, созданной с помощью метода add_delivery необязательный параметр
Позволяет указать ID именованной рассылки для группировки сообщений. Подробнее об именованных рассылках можно прочитать в описании HTTP API.
type строка необязательный параметр
Тип сообщения. Когда не задан, сообщение будет отправлено как обычное SMS.

Формирование запроса в формате JSON

Пример запроса
> POST auth.terasms.ru/outbox/send/json

{
	"login": "login",
	"password": "secret",
	"target": 71234567890,
	"message": "ку-ку",
	"sender": "terasms.ru"
}
Пример ответа
{
  "status": 0,
  "status_description": "OK",
  "message_infos": [
    {
      "msisdn": "78001234567890",
      "id": "566668915",
      "status": 0
    }
  ]
}

Формирование запроса в формате XML

Пример запроса
> POST auth.terasms.ru/outbox/send/xml
<?xml version="1.0"?>
<request>
    <login>login</login>
    <password>password</password>
    <target>71234567890</target>
    <message>ку-ку</message>
    <sender>terasms.ru</sender>
</request>
Пример ответа
<?xml version="1.0"?>
<response>
    <status>0</status>
    <status_description>OK</status_description>
    <message_infos>
        <message_info>
            <msisdn>71234567890</msisdn>
            <status>0</status>
        </message_info>
    </message_infos>
</response>

Группировка сообщений в рассылки

Вы можете группировать сообщения в именованные рассылки — это даёт возможность получать отчёты, сгруппированные по этим рассылкам.

Для этого необходимо создать рассылку, отправив следующий запрос: https://auth.terasms.ru/outbox/add_delivery?login=terasms&password=12345&name=Имя%рассылки

В качестве ответа Вам придёт ID рассылки. В системе будет создана рассылка с именем "Имя рассылки". Если параметр name не указан, то в качестве имени рассылки будет использоваться текущая дата. Вы сможете увидеть свою рассылку в личном кабинете на странице График рассылки. Кроме того, на странице "Отчёты" будет отображена статистика по именованным рассылкам.
Обращаем Ваше внимание на то, что данные по рассылкам в системе обновляются не в режиме реального времени, а в течении 5-10 минут.

Затем при отправке сообщения необходимо добавлять параметр schedule_id со значением, полученным при создании рассылки: https://auth.terasms.ru/outbox/send/?login=terasms&password=12345&target=79017654321&sender=terasms&message=test&schedule_id=1234

Каждое отправленное таким образом сообщение будет добавлено к Вашей рассылке "Имя рассылки"

Отправка нескольких сообщений одним запросом

Для отправки нескольких сообщений одним запросом существует метод msend_json. При использовании метода тело запроса должно быть в формате JSON, ответ также приходит в JSON. Параметры сообщения совпадают с параметрами, используемыми в методе outbox/send. Так же существует параметр sms_id, в котором вы можете указать любой идентификатор сообщения. Этот идентификатор будет присутствовать в ответе платформы вместе с остальной информацией о сообщении.

Пример запроса
> POST https://auth.terasms.ru/outbox/msend_json
{
	"login": "login",
	"password": "password",
	"smsPackage": [
		{
			"target": 78002223344,
            "sms_id": 1,
			"sender": "terasms.ru",
			"message": "test"
		},
		{
			"target": 78002223345,
            "sms_id": 2,
			"sender": "terasms.ru",
			"message": "test2"
		}
	]
}
Пример ответа
[
    {
        "sms_id": 1,
        "message_id": "365214379"
    },
    {
        "sms_id": 2,
        "message_id":"365214380"
    }
]

Получение статусов нескольких сообщений одним запросом

Существует возможность получать статусы нескольких сообщений одним запросом. Метод описан в разделе Получение статусов SMS.