HTTP, HTTPS-протокол
SMS, Viber, VK, 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 сообщений, как самостоятельных, так и в составе «Каскада». Поля массива:
адрес отправителя будет взят из настроек в Личном кабинете или, при его отсутствии, подставлен общий системный адрес; тема письма будет взята из настроек в Личном кабинете или, при ее отсутствии, подставлено значение параметра 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.
|
Возможные варианты реализации на языке программирования PHP
Отправка одиночного сообщения
GET
$api_uri = 'https://auth.terasms.ru/outbox/send/';
$query_array = array(
'login' => 'login',
'password' => 'password',
'target' => 'target',
'message' => 'message',
'sender' => 'sender'
);
$get_string = http_build_query( $query_array );
$id = file_get_contents( $api_uri . '?' . $get_string);POST
$api_uri = 'https://auth.terasms.ru/outbox/send/';
$query_array = array(
'login' => 'login',
'password' => 'password',
'target' => 'target',
'message' => 'message',
'sender' => 'sender'
);
$context = stream_context_create(array(
'http' => array(
'method' => 'POST',
'content' =>http_build_query( $query_array ),
'timeout' => 10,
),
));
$id = file_get_contents( $api_uri, false, $context);JSON
$api_uri = 'https://auth.terasms.ru/outbox/send/json';
$query_array = array(
'login' => 'login',
'password' => 'password',
'target' => 'target',
'message' => 'message',
'sender' => 'sender'
);
$context = stream_context_create(array(
'http' => array(
'method' => 'POST',
'header' => "Content-Type: application/json\r\n",
'timeout' => 10,
'content' => json_encode( $query_array )
)
));
$response = file_get_contents( $api_uri, false, $context );
$responseData = json_decode( $response, true );XML
$api_uri = 'https://auth.terasms.ru/outbox/send/json';
$context = stream_context_create(array(
'http' => array (
'method' => "POST",
'content' => $query_xml,
'timeout' => 10,
'header' => "Content-Type: text/xml; charset=utf-8"
)
));
$response = file_get_contents( $api_uri, false, $context );$query_xml:
<?xml version="1.0"?>
<request>
<login>login</login>
<password>password</password>
<target>target</target>
<message>message</message>
<sender>sender</sender>
</request>Отправка сообщения нескольким абонентам
POST
$api_uri = 'https://auth.terasms.ru/outbox/send/';
$query_array = array(
'login' => 'login',
'password' => 'password',
'target' => 'target1, target2, target3',
'message' => 'message',
'sender' => 'sender'
);
$context = stream_context_create(array(
'http' => array(
'method' => 'POST',
'content' =>http_build_query( $query_array ),
'timeout' => 10,
),
));
$ids = file_get_contents( $api_uri, false, $context);id1, id2, id3
JSON
$api_uri = 'https://auth.terasms.ru/outbox/send/json';
$query_array = array(
'login' => 'login',
'password' => 'password',
'target' => 'target1, target2, target3',
'message' => 'message',
'sender' => 'sender'
);
$context = stream_context_create(array(
'http' => array(
'method' => 'POST',
'header' => "Content-Type: application/json\r\n",
'timeout' => 10,
'content' => json_encode( $query_array )
)
));
$response = file_get_contents( $api_uri, false, $context );
$responseData = json_decode( $response, true );
XML
$api_uri = 'https://auth.terasms.ru/outbox/send/xml';
$context = stream_context_create(array(
'http' => array (
'method' => "POST",
'content' => $query_xml,
'timeout' => 10,
'header' => "Content-Type: text/xml; charset=utf-8"
)
));
$response = file_get_contents( $api_uri, false, $context );$query_xml:
<?xml version="1.0"?>
<request>
<login>login</login>
<password>password</password>
<target>target1, target2, target3</target>
<message>message</message>
<sender>sender</sender>
</request>Отправка разных сообщений разным абонентам, mass_push
POST
$api_uri = 'https://auth.terasms.ru/outbox/send/';
$query_array = array(
'login' => 'login',
'password' => 'password',
'target' => 'target1 message1|target2 message2|target3 message3',
'message' => '',
'sender' => 'sender',
'mass_push' => '1',
'delimiter' => '|'
);
$context = stream_context_create(array(
'http' => array(
'method' => 'POST',
'content' =>http_build_query( $query_array ),
'timeout' => 10,
),
));
$id = file_get_contents( $api_uri, false, $context);id1, id2, id3
JSON
$api_uri = 'https://auth.terasms.ru/outbox/send/json';
$query_array = array(
'login' => 'login',
'password' => 'password',
'target' => 'target1 message1|target2 message2|target3 message3',
'message' => '',
'sender' => 'sender',
'mass_push' => '1',
'delimiter' => '|'
);
$context = stream_context_create(array(
'http' => array(
'method' => 'POST',
'header' => "Content-Type: application/json\r\n",
'timeout' => 10,
'content' => json_encode( $query_array )
)
));
$response = file_get_contents( $api_uri, false, $context );
$responseData = json_decode( $response, true );XML
$api_uri = 'https://auth.terasms.ru/outbox/send/xml';
$context = stream_context_create(array(
'http' => array (
'method' => "POST",
'content' => $query_xml,
'timeout' => 10,
'header' => "Content-Type: text/xml; charset=utf-8"
)
));
$response = file_get_contents( $api_uri, false, $context );$query_xml:
<?xml version="1.0"?>
<request>
<login>login</login>
<password>password</password>
<target>target1 message1|target2 message2|target3 message3</target>
<message></message>
<sender>sender</sender>
<mass_push>1</mass_push>
<delimiter>|</delimiter>
</request>Формирование запроса в формате 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.