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 | строка | обязательный параметр
|
sender | строка | обязательный параметр Имя отправителя, зарегистрированное для вас на Платформе TERASMS. Имя отправителя, содержащее в себе латинские буквы (в любом регистре), может содержать от 2 до 11 символов, цифровое имя отправителя — от 2 до 15 символов. |
message | строка | обязательный параметр Текст сообщения. Текст 1 сообщения составляет 160 символов для латиницы и 70 символов для кириллицы. Сообщение, содержащее большее кол-во символов, разбивается на несколько сегментов и доставляется одним сообщением. Сообщение, состоящее более чем из 160 для латиницы или из 70 символов для кириллицы, разбивается на сегменты. Каждый сегмент составляет 153 для латиницы и 67 символов для кириллицы. По умолчанию сообщение может состоять максимум из 10 сегментов. |
email_message | массив | необязательный параметр Используется только при передаче в формате JSON. Предназначен для передачи параметров при отправке e-mail сообщений, как самостоятельных, так и в составе «Каскада». Поля массива:
Если не указан и передается e-mail сообщение, то: Более подробное описание находится в разделе Отправка сообщений 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.
|
Возможные варианты реализации на языке программирования PHP
Формирование запроса в формате 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.