МТС Маркетолог

Документация REST API

📩 Если возникнут проблемы, пишите на supmarketolog@stream.ru 
В письмо добавьте подробности — так поможем быстрее
  • название компании
  • логин подключения
  • описание проблемы
  • пример сообщения: дата, время, system_id, имя отправителя, номер получателя, message_id, коды ошибок
  • tcpdump, логи с ошибкой, статистика по ошибке
     

Почему SMS могут не отправляться

  1. Не куплен пакет SMS. Если у вас тестовый период — пакет нужно подключать каждый день. Посмотреть пакеты можно в личном кабинете иконка кошелька → пакеты SMS
  2. Не подключено имя отправителя. Проверить статус имени можно в личном кабинете Инструменты → Имя отправителя
  3. Имя отправителя подключено не на всех операторов. Тогда SMS будут уходить только на подключённых операторов

 

Введение

Возможности API

Лимиты

Подготовка к интеграции

 

Работа по схеме базовой авторизации: по логину

Параметры аутентификации 

Отправка SMS

Методы 

Отправка SMS методом POST

Примеры запросов: JSON, 1С, Python, PHP

Отправка SMS методом GET

Примеры ответов

Получение статусов

Получение статусов методом POST

Получение статусов методом GET

Входящие SMS

Приём входящих SMS

 

Работа cхемы авторизации с токеном

Параметры аутентификации

Методы

 

Коллбэки

Callback

Коды и ошибки

Коды событий

Описание ошибок

 

 

 

API платформы позволяет

  • отправлять SMS
  • запрашивать статусы SMS
  • получать коллбэки по статусу отправленных SMS
  • получать входящие SMS

 

 

Лимиты платформы

— до 5 тысяч запросов в минуту в совокупности на отправку SMS и получение статусов

— до 10 тысяч сообщений в одном запросе

— пропускная способность подключения — 10 SMS в секунду. Если отправляете больше 10 SMS в секунду, используйте запрос на отправку в буфер, чтобы сообщения попадали в очередь. 

— максимальные размеры сообщений* для каналов: 10 сегментов (670 символов на кириллице и 1530 на латинице)**

* Кодировка текста сообщения — UTF-8 

** Можно отправить и больше сегментов, но чем больше сегментов — тем выше вероятность некорректной доставки.

 

 

Подготовка к интеграции

  1. Получите логин и пароль для авторизации: личный кабинет МТС Маркетолога → Инструменты → Интеграции → REST API → Создать подключение → сгенерируем логин и пароль — их нужно использовать в запросах. Логин и пароль от личного кабинета не подойдут
❔ Как получить логин и пароль 

Это скриншот из личного кабинета МТС Маркетолога, раздел Интеграции

2. Подключите имя отправителя

3. Подключите пакет SMS

Чтобы протестировать отправки, можно использовать бесплатное тестовое имя и пакет

 

Работа по схеме базовой авторизации: по логину и токену

 

С платформой можно взаимодействовать методами POST и GET

Метод URL Что делает
POSThttps://omnichannel.mts.ru/http-api/v1/messagesОтправка сообщений 
POSThttps://omnichannel.mts.ru/http-api/v1/b/messages/Отправка сообщений в буфер. Используйте этот URL, если отправляете более 10 SMS в одном запросе
POST https://omnichannel.mts.ru/http-api/v1/messages/info Запрос статусов сообщений
GEThttps://api-adapter.marketolog.mts.ru/get/send-smsОтправка сообщения
GEThttps://api-adapter.marketolog.mts.ru/get/sms-infoЗапрос статуса сообщения

 

 

 

Параметры аутентификации 

Чтобы пройти аутентификацию, при каждом запросе передавайте логин и пароль по схеме Basic Authentication

Параметр Тип данныхОписание 
Login string Логин
Password string Пароль

 

❔ Как получить логин и пароль 

В личном кабинете МТС Маркетолога: Инструменты → Интеграции → REST API → создать подключение — сгенерируем логин и пароль. 

 

 

Отправка сообщений методом POST

Запрос состоит из двух объектов

Параметр Тип данныхОписание 
messages array of objects Массив сообщений с детализацией. Описание структуры сообщения представлено ниже.
options object 

Включает в себя параметры, которые также могут присутствовать в каждом отдельном сообщении: "class" и объект "from".

⚠️ Если в объекте messages все сообщения относятся к одному имени отправителя, рекомендуем передавать вышеуказанные параметры один раз в общем для всех сообщений объекте "options". В этом случае для каждого сообщения в массиве messages эти параметры можно не передавать. Ниже есть примеры запросов для обоих случаев.

 

Структура сообщения: элемент массива "messages"

 Параметр Тип данных Описание Обязательность поля
1class integer Пользовательский класс сообщения. Используется опционально для управления маршрутизацией сообщений. Связь между параметром class и маршрутом настраивают администраторы по запросу Клиента. Пример: class: 1 — отправить в канал SMSНет
2from object Объект с именем отправителя/чата/приложенияДа, если данные не указаны в "options"
2.1 from => sms_addressstring Имя отправителя SMS (нейминг), которое видит получатель Да, если данные не указаны в "options"
3 toobject Массив объектов с информацией о получателеДа 
3.1 to => message_idstring Идентификатор сообщения клиентаНет 
3.2to => msisdnstring Номер телефона адресата. Формат: 79161234567 Да 
4contentobject Объект с информацией о сообщении.Да 
4.1content => short_text string string Текст сообщения. Рекомендуем отправлять до 8 сегментов в одном SMS: 536 символов на кириллице и 1224 на латинице. Кодировка — UTF-8.Да 

 

 

Пример запроса JSON

POST /messages 

Content-type: application/json 

Пример с использованием одного имени отправителя: 2 сообщения отправляются от имени SMS Naming. В этом случае объект "from" (и, при необходимости, поле "class") прописываются один раз в объекте "options"

{
 "messages": [
{
"content": {
"short_text": "sms text #1"
},
"to": [
{
"msisdn": "79836362346",
"message_id": "10345678-f123-4694-91d7-233df79f65445"
}
]
},
{
"content": {
"short_text": "sms text #2"
},
"to": [
{
"msisdn": "79836362347",
"message_id": "10345678-f123-4694-91d7-233df79f65446"
}
]
}
 ],
 "options": {
"class": 22,
"from": {
"sms_address": "SMS Naming"
}
 }
}

 

Пример с использованием разных имён. В этом случае объект "from" (и, при необходимости, поле "class") присутствуют в каждом элементе массива "messages". 

{
 "messages": [
{
"content": {
"short_text": "sms text #1"
},
"from": {
"sms_address": "SMS Naming #1"
},
"to": [
{
"msisdn": "79836362346",
"message_id": "10345678-f123-4694-91d7-233df79f65445"
}
]
},
{
"content": {
"short_text": "sms text #2"
},
"from": {
"sms_address": "SMS Naming #2"
},
"to": [
{
"msisdn": "79836362347",
"message_id": "10345678-f123-4694-91d7-233df79f65446"
}
]
}
 ]
}
Пример запроса из 1С (для разработчиков 1С)
	              
               Текст = СтрЗаменить(ТекстСообщения, Символы.ПС, " ");
              
               СтруктураОтправки = Новый Структура;
              
               МассивСообщений = Новый Массив;
              
               Для каждого Адресат Из Адресаты Цикл
              
                              ОчередноеСообщение = Новый Структура;
                             
                              ОчередноеСообщение.Вставить("content", Новый Структура("short_text", Текст));
                              Если НЕ ИспользоватьПользовательскийКласс Тогда
                                            ОчередноеСообщение.Вставить("from",Новый Структура("sms_address", Отправитель));
                              КонецЕсли;
                             
                              МассивАдресата = Новый Массив;
                              Идентификатор1С = Строка(Новый УникальныйИдентификатор);
                              МассивАдресата.Добавить(Новый Структура("msisdn, message_id", Адресат.Значение, Идентификатор1С));
                             
                              ОчередноеСообщение.Вставить("to", МассивАдресата);
                             
                              МассивСообщений.Добавить(ОчередноеСообщение); 
                             
                              СохранитьСообщениеВОтправленных(Новый Структура("Адресат, ТекстСообщения, Идентификатор1С", Адресат.Значение, Текст, Идентификатор1С));
                             
               КонецЦикла;
              
               СтруктураОтправки.Вставить("messages", МассивСообщений);
              
               Если ИспользоватьПользовательскийКласс Тогда
                              СтруктураОтправки.Вставить("options", Новый Структура("class, from", Класс, Новый Структура("sms_address", Отправитель)));
               КонецЕсли;
               Запись = Новый ЗаписьJSON;
               Запись.УстановитьСтроку();
               ЗаписатьJSON(Запись, Данные);
               СтрокаJSON = Запись.Закрыть();
               Соединение = Новый HTTPСоединение(Сервер, 443, Логин, Пароль,,, Новый ЗащищенноеСоединениеOpenSSL());
               ЗапросHTTP = Новый HTTPЗапрос;

               ЗапросHTTP.Заголовки.Вставить("Content-type", "application/json");
               ЗапросHTTP.УстановитьТелоИзСтроки(СтрокаJSON);
               ЗапросHTTP.АдресРесурса = АдресЗапроса;
              
               Ответ = Соединение.ВызватьHTTPМетод("POST",ЗапросHTTP);
               

 

Текст полученного JSON-файла

{
"messages": [
{
"content": {
"short_text": "SMS text"
}
,
"from": {
"sms_address": "SMS Naming"
}
,
"to": [
{
"msisdn": "msisdn here",
"message_id": "UUID here"
}
]
}
]
}

Ошибка кодировки

Если в ответ на SMS приходит ответ

{"code":400,"message":"parsing body body from \"\" failed, because invalid character 'ï' looking for beginning of value"}

измените кодировку: в 1С вместо «UTF-8» установите «CESU-8».

Это исправление нужно внести в строчке «ЗапросHTTP.УстановитьТелоИзСтроки (Строка JSON)» 

 

Также вы можете интегрироваться с 1С с помощью специального расширения или обработки

Пример запроса на Python

Скачать файлом 

import requests
from requests.auth import HTTPBasicAuth
def sent_message(login, password, naming, to, text_message):
   url = 'https://omnichannel.mts.ru/http-api/v1/messages'
   body = {
   "messages": [
   {
   "content": {
   "short_text": text_message
   },
   "from": {
   "sms_address": naming
   },
   "to": [
   {
   "msisdn": to
   }
   ]
   }]
   }
   resp = requests.post(url , json=body, auth = HTTPBasicAuth(login, password)) 
   return resp
     
def check_message(login, password, message_id):
   url = 'https://omnichannel.mts.ru/http-api/v1/messages/info'
   body = {"int_ids": [message_id]}
   resp_info = requests.post(url , json=body, auth = HTTPBasicAuth(login, password))      
   return resp_info  
   
# Параметры отправки
login = 'ЛОГИН_из_личного_кабинета_раздел_интеграции'
password = 'ПАРОЛЬ_из_личного_кабинета_раздел_интеграции'
naming = 'НЕЙМИНГ_согласованное_имя_отправителя_из_ЛК_Маркетолога'
text_message = 'Текст сообщения'
to = '79001111111'
# Отправка сообщения
sent_message(login, password, naming, to, text_message)
# Проверка статуса
if resp.status_code == 200:
   message_id = resp.json()['messages'][0]["internal_id"]
   print("Запрос отработал успешно message_id = " + message_id)
   resp_info = check_message(login, password, message_id)
   if resp_info.status_code == 200:
       event_code = resp_info.json()["events_info"][0]["events_info"][0]["status"]
       if event_code == 200:
           print("SMS отправлено получателю " + to + ". message_id = " + message_id)
       elif event_code == 201:
           print("SMS НЕ отправлено message_id = " + message_id + " Детали см по кодам ошибок в документации " + str(resp_info.content))
else:
   print("Запрос не отработал. Детали: " + str(resp.content))
Пример запроса на PHP

Скачать файлом

<?php

class Client
{
    /**
     * @var string
     */
    var $host;
    /**
     * @var string
     */
    var $auth;

    var $timeout;

    /**
     * @param $host string
     * @param $login string
     * @param $password string
     */
    function __construct($host, $login, $password, $timeout = 60)
    {
        $this->host = $host;
        $this->auth = "Basic " . base64_encode($login . ":" . $password);

        $this->timeout = $timeout;
    }

    /**
     * @param $naming string
     * @param $text string
     * @param $phone string
     * @return $id string
     */
    function sendSms($naming, $text, $phone)
    {
        $req = [
            "messages" => [
                [
                    "content" => [
                        "short_text" => $text
                    ],
                    "to" => [
                        [
                            "msisdn" => $phone
                        ]
                    ],
                ]
            ],
            "options" => [
                "class" => 1,
                "from" => [
                    "sms_address" => $naming,
                ],
            ]
        ];
        $respStr = $this->curlRequest("messages", json_encode($req), [], "POST");

        $resp = json_decode($respStr, true);

        if (isset($resp["code"])) {
            var_dump($respStr);
            return "0";
        }


        if (!isset($resp["messages"][0]["internal_id"])) {
            var_dump($respStr);
            return "0";
        }

        var_dump("successes response:", $respStr);

        return $resp["messages"][0]["internal_id"];
    }

    /**
     * @param $ids []string
     * @return array []
     */
    function getSmsInfo($ids)
    {

        $respStr = $this->curlRequest("messages/info", json_encode(["int_ids" => $ids]), [], "POST");

        $resp = json_decode($respStr, true);

        if (isset($resp["code"])) {
            var_dump($respStr);
            return [];
        }

        var_dump("successes response:", $respStr);

        return $resp;
    }

    /**
     * @param $url
     * @param $data
     * @param $headers
     * @return bool|string
     */
    function curlRequest($url, $data = NULL, $headers = NULL, $method = "GET")
    {
        $ch = curl_init();

        curl_setopt($ch, CURLOPT_URL, $this->host . $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, $this->timeout);

        if (!empty($data)) {
            curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        }

        $headers = array_merge($headers, ["Authorization: " . $this->auth, "Content-Type: application/json; charset=utf-8"]);

        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);

        $response = curl_exec($ch);

        if (curl_error($ch)) {
            trigger_error('Curl Error:' . curl_error($ch));
        }


        curl_close($ch);
        return $response;
    }
}


$client = new Client("https://omnichannel.mts.ru/http-api/v1/", "ЛОГИН", "ПАРОЛЬ");

// отправка сообщения
$id = $client->sendSms("НЕЙМИНГ", "ТЕКСТ СООБЩЕНИЯ", "79999999999"); // отправка смс
// если $id == 0, то была ошибка запроса

if ($id != "0") {
    // получение статуса по id сообщения
    $status = $client->getSmsInfo([$id]);
    var_dump($status);
}

 

 

 

Отправка сообщений методом GET

Чтобы использовать GET-запросы, напишите нам в поддержку на supmarketolog@stream.ru. Мы откроем сетевые доступы до вашего IP-адреса

Тема письма
Доступ для GET запроса [ИНН организации]

Текст
Название организации, ИНН, логин от  подключения, IP-адрес, до которого нужно открыть доступ

Логин от подключения указан в личном кабинете: Инструменты → Интеграции → REST API

 

 

Параметры запроса 

Query ParametrsТип данныхКомментарий
loginstringЛогин
passwordstringПароль
msisdnstringНомер телефона адресата. Формат: 79161234567 
fromstringИмя отправителя, которое видит получатель
messagestringТекст сообщения. Рекомендуем отправлять до 8 сегментов в одном SMS: 536 символов на кириллице и 1224 на латинице. Кодировка — UTF-8.

 

Пример запроса

GET /get/send-sms 

Content-type: application/json

https://api-adapter.marketolog.mts.ru/get/send-sms?login=g_tRW134CVLgdPe4&password=ERGfdg4WK&msisdn=79161234567&from=test_naming&message=test

 

 

Примеры ответов

Успешный ответ

Код https-ответа — 200 

⚠️Успешный ответ означает, что сообщение принято платформой для обработки. HTTPS-код ответа 200 не связан со статусом сообщения 200 и не означает, что сообщение отправлено.

ПараметрТип данныхОписание 
msisdn string Номер телефона адресата 
email string Email адресата — для сообщений на email
message_idstringИдентификатор сообщения клиента   
internal_idstring Внутренний идентификатор сообщения

 

{
 "messages": [
 {
"msisdn": "79117903795",
"email": "example@mail.ru",
"message_id": "uuid",
"internal_id": "uuid2"
 }
 ]
}
Ответ c ошибкой

Параметры

Параметр Тип данныхОписание
code integer Код ошибки — смотрите  коды ошибок в ответе на запрос отправки сообщения — ниже
 message string Описание ошибки — смотрите коды ошибок в ответе на запрос отправки сообщения ниже

 

Код http-ответа — 400 

{ "code": 802, "message": "Bad credentials" }

Коды ошибок в ответе на запрос отправки сообщения 

Код http-ответа 200 возвращается, когда общая структура запроса и авторизация корректны. Если при обработке сообщения из списка возникла ошибка — она будет описана в полях «code» и «message». 

Если получите код http-ответа, которого нет в списке — напишите в техподдержку

Код http-ответа Код ошибкиНаименование ошибкиОписание 
200806  recipient is requiredНе указан получатель сообщения в соответствующем параметре msisdn/email, либо пустое поле "to"
200 807 msisdn validation failedВведен некорректный номер получателя (например, начинается с символа "+") 
400 802 bad credentialsНеверный логин или пароль. 
400 803 MessageLimit has been expiredПревышен лимит на отправку сообщений. Максимальная пропускная способность подключения — 10 SMS в секунду 
400 804 content is required Отсутствует текст сообщения в соответствующем параметре short_text / rich_text / email_template_id / vk_template_name / ok_template_name
400 805 Template info unavailableНедоступен сервис макетов
400 808 Template info not found Шаблон с указанным email_template_id не найден
401 401 unauthenticated for invalid credentialsЗаголовок авторизации отсутствует, либо нет токена/не валидный формат токена
422 602 {param_name} in body is required Отсутствует обязательный параметр {param_name}

 

 

 

Получение статусов сообщений методом POST
 

Запрос

POST /messages/info 

Content-type: application/json

Параметр Тип ОписаниеОбязательность 
 msg_ids array of stringsВнешний (клиентский) идентификатор сообщенияДолжно присутствовать хотя бы одно из полей
int_ids array ofstrings   Внутренний идентификатор сообщения платформы. Рекомендуется делать запросы по статусам сообщений с использованием данного поля 

 

Ответ

Ответ представляет из себя массив "events_info", внутри которого будут объекты со списком событий по каждому сообщению (отправка, доставка и т.д.). Структура элемента массива "events_info":

Параметр Тип Описание 
events_info array of objectsМассив объектов с информацией по каждому событию сообщения 
key string Внутренний идентификатор сообщения (такой же как в поле "internal_id" в объекте события) 
error bool Необязательное поле. Приходит значение true если во время обработки событий по сообщениям возникли ошибки. 
 error_description string Необязательное поле. Текстовое описание ошибки, возникшей во время обработки событий по сообщениям.

 

Структура объекта события

Параметр Тип Описание 
 message_idstring Идентификатор сообщения клиента 
 namingstring Нейминг сообщения 
destinationstring Номер отправителя
status uint32Код события. Смотрит список статусов
channel uint32Идентификатор исходящего канала. Cм. Справочник каналов 
total_partsuint32Кол-во сегментов сообщения
 received_at stringДата и время, когда сообщение было принято http-шлюзом
 event_at string Дата и время события (отправки, доставки и т.д.) 
 internal_errorsarray(dtype=uint32)  Массив внутренних кодов ошибок. Null, если ошибок нет
 internal_id stringВнутренний идентификатор сообщения
Пример запроса 
{
 "msg_ids": [
 "string"
 ],
 "int_ids": [
 "string"
 ]
}
Пример запроса с идентификаторами
{
"int_ids": [
"88b1-4622-9308", "88b1-4646-9109"
]
}
Пример ответа
{
 "events_info": [
{
"events_info": [
{
"channel": 4,
"destination": "79870061042",
"event_at": "2021-05-18T13:45:01.000+03:00",
"internal_errors": null,
"internal_id": "c128187b-145f-4b86-b47f-8e99cf513a59",
"message_id": "10345678-f123-4694-91d7-233df79f65445",
"naming": "viber_naming",
"received_at": "2021-05-18T13:45:00.000+03:00",
"status": 200,
"total_parts": 1
},
{
"channel": 4,
"destination": "79870061042",
"event_at": "2021-05-18T13:45:05.000+03:00",
"internal_errors": null,
"internal_id": "c128187b-145f-4b86-b47f-8e99cf513a59",
"message_id": "10345678-f123-4694-91d7-233df79f65445",
"naming": "viber_naming",
"received_at": "2021-05-18T13:45:00.000+03:00",
"status": 300,
"total_parts": 1
}
],
"key": "c128187b-145f-4b86-b47f-8e99cf513a59"
}
 ]
}

 

 

Получение статусов методом GET

Параметры запроса

Query ParametrsТип данныхКомментарий
loginstringЛогин
passwordstringПароль
msg_idsstringВнешний (клиентский) идентификатор сообщения
from stringИмя отправителя SMS (нейминг), которое видит получатель

Пример запроса получения статусов сообщений

GET /get/sms-info Content-type: application/json

https://api-adapter.marketolog.mts.ru/get/sms-info?&login=g_tRWasertVLgdPe4&password=sd3RVaOyWK&msg_ids=6eca893e2f-19e2-4118-b706-7168e75cd57f&from=test_naming

Пример успешного ответа 

{
    "events_info": [
        {
            "key": "b9b9d951-ccb4-4bc8-8aba-c50bfdada6be",
            "events_info": [
                {
                    "message_id": "b9b9d951-ccb4-4bc8-8aba-c50bfdada6be",
                    "naming": "mtscom_t",
                    "destination": "79870061042",
                    "status": 200,
                    "channel": 1,
                    "total_parts": 1,
                    "received_at": "2022-07-26T10:43:39+03:00",
                    "event_at": "2022-07-26T10:43:39+03:00",
                    "internal_errors": null,
                    "internal_id": "7bbbe11e-13f0-40cc-a166-7192bf2d7199"
                },
                {
                    "message_id": "b9b9d951-ccb4-4bc8-8aba-c50bfdada6be",
                    "naming": "mtscom_t",
                    "destination": "79870061042",
                    "status": 300,
                    "channel": 1,
                    "total_parts": 1,
                    "received_at": "2022-07-26T10:43:39+03:00",
                    "event_at": "2022-07-26T10:43:41+03:00",
                    "internal_errors": null,
                    "internal_id": "7bbbe11e-13f0-40cc-a166-7192bf2d7199"
                }
            ]
        }
    ]
}


 

Приём входящих SMS

Платформа может принимать входящие SMS и отправлять их в вашу систему.
⚠️ Чтобы получать входящие  отправьте запрос на templates@mts.ru

 

Структура входящего сообщения 

Параметр                   Тип данныхОписание
1fromobjectОбъект, содержащий имя отправителя
2from.received_atdatetimeВремя, когда пришло сообщение от пользователя в платформу
3from.user_contactstringНомер телефона отправителя 
4from.namingstringНомер для входящих SMS (ваше имя отправителя)
5contentobjectОбъект, содержащий контент
6content.content_typestringТип контента
7content.textstringТекст сообщения
8file_urlstringURL картинки/файла. Не используется в SMS
9file_namestringНаименование файла. Не используется в SMS
10channel_idintКанал, из которого пришло сообщение. Для SMS = 1
11internal_idstringid сообщения 

 

Пример запроса для входящего SMS
{
  "messages": [
    {
      "content": {
        "text": "some message"
      },
      "from": {
        "naming": "4444",
        "user_contact": "79117903795",
        "received_at": "2022-02-04T00:00:00Z"
      },
      "channel_id": 1,
      "internal_id": "10345678-f123-4694-91d7-233df79f65445"
    }
  ]
}
Ответы клиентской системы на входящие сообщения

Код HTTP-ответа должен быть:

  • 200   OK,
  • 400  — ошибки обработки параметров,
  • 500 — недоступность сервисов.

 

Работа cхемы авторизации с токеном

 

Параметры аутентификации

Получите токен в личном кабинете МТС Маркетолога: Инструменты → Интеграции → REST API → Создать подключение → Создать токен. Чтобы авторизоваться, передавайте токен в заголовках запроса (Authorization: Bearer token). Полученный токен действует год, после этого автоматически обновляется.

Методы

Отправка сообщений методом POST

POST https://api.mts.ru/client-omni-adapter_production/1.0.2/mcom/messageManagement/messages

Тело запроса

Запрос состоит из массива сообщений(submits) и необязательного параметра naming.

ПараметрТип данныхОбязательностьОписание
submitsarrayДа

Данные для отправки сообщений. Максимальное количество

элементов:1000

namingstringНетИмя отправителя

Структура сообщения: элемент массива "submits"

ПараметрТип данныхОбязательностьОписание
msidstringДаНомер получателя
messagestringДаТекст сообщения.
Максимальная поддерживаемая длина: 2000 символов

Пример тела запроса:

{
	"submits": [
	  {
		"msid": "79042807645",
		"message": "Текст сообщения"
	  }
	],
	"naming": "Taxi"
}

Пример ответа:

{
  "code": 2147483647,
  "description": "string",
  "data": {
    "submitResults": [
      {
        "msid": "string",
        "messageID": 99999999999,
        "code": "OK"
      }
    ]
  }
}

Пример ответа с ошибкой:

{
  "status": 1000,
  "code": 2147483647,
  "description": "string",
  "validationErrors": [
    "string"
  ]
}

Получение конкретного сообщения методом 

GET/mcom/messageManagement/messages/{messageID}

Пример запроса:

https://api.mts.ru/client-omni-adapter_production/1.0.2/mcom/messageManagement/messages/13

Пример ответа:

{
  "code": 2147483647,
  "description": "string",
  "data": [
    {
      "messageID": 99999999999,
      "creationDate": "string",
      "Type": "MO",
      "text": "string",
      "senderMsid": "string",
      "senderName": "string",
      "targetMsid": "string",
      "targetName": "string"
    }
  ]
}

Пример ответа с ошибкой:

{
  "status": 1000,
  "code": 2147483647,
  "description": "string",
  "validationErrors": [
    "string"
  ]
}

Получение статусов сообщений методом 

GET/mcom/messageManagement/messages/status

Входные параметры

Query ParametrsТип данныхОбязательностьОписание
messageIDsstringДаИдентификаторы сообщений. Максимальное количество записей: 1000. Передаем через запятую: 1,2,3

Пример запроса

https://api.mts.ru/client-omni-adapter_production/1.0.2/mcom/messageManagement/messages/status?messageIDs=1

Пример ответа:

{
  "code": 2147483647,
  "description": "string",
  "data": [
    {
      "messageID": 999999999999999,
      "statuses": [
        {
          "msid": "string",
          "status": "Pending",
          "date": "2132-16-36T85:91:71",
          "userDeliveryDate": "6179-74-91T24:00:70u44",
          "partCount": 2147483647
        }
      ]
    }
  ]
}

Пример ответа с ошибкой:

{
  "status": 1000,
  "code": 2147483647,
  "description": "string",
  "validationErrors": [
    "string"
  ]
}

Получение статусов сообщения методом 

GET/mcom/messageManagement/messages/{messageID}/status

Пример запроса:

https://api.mts.ru/client-omni-adapter_production/1.0.2/mcom/messageManagement/messages/13/status

Входные параметры

Query ParametrsТип данныхОбязательностьОписание
messageID integerДаИдентификатор сообщения

Пример ответа:

{
  "code": 2147483647,
  "description": "string",
  "data": [
    {
      "messageID": 999999999999999,
      "statuses": [
        {
          "msid": "string",
          "status": "Pending",
          "date": "6679-27-05T20:27:60K96",
          "userDeliveryDate": "0648-01-13T55:38:73",
          "partCount": 2147483647
        }
      ]
    }
  ]
}

Пример ответа с ошибкой:

{
  "status": 1000,
  "code": 2147483647,
  "description": "string",
  "validationErrors": [
    "string"
  ]
}

Callback

Платформа может возвращать статусы отправленных сообщений

⚠️ Чтобы получать коллбеки отправьте запрос на supmarketolog@stream.ru 

Тема письма
[ИНН организации]. Одобрить адрес для коллбэков, Маркетолог

Текст

Здравствуйте! 
Название организации, ИНН
Добавьте наш адрес для колбеков в одобренные: [адрес]

 

Параметры callback 

Название Тип Описание 
message_idstring Идентификатор сообщения клиента
destination string 

Номер отправителя. 

⚠️Если в клиентском URL используется протокол HTTPS (не HTTPS), данное поле не передается

naming stringНейминг, использованный в сообщении 
status uint32 Код события. Cм. Список статусов 
 channel uint32Идентификатор исходящего канала. Cм. Справочник каналов
total_parts uint32Кол-во сегментов сообщения 
received_atstring  Дата и время, когда сообщение было принято http-шлюзом 
 event_atstring  Дата и время последнего события.
internal_errorsarray(dtype=uint32)  Массив внутренних кодов ошибок. Null, если ошибок нет
internal_id string Внутренний идентификатор сообщения 

 

Пример callback 
{
 "items": [
 {
"message_id": "uuid",
"internal_id": "76305352-7994-4f2e-984a-95a39432d777",
"naming": "string",
"destination": "79117903795",
"status": 300,
"channel": 1,
"total_parts": 1,
"received_at": "2020-02-04T00:00:00Z",
"event_at": "2020-02-04T00:00:00Z",
"internal_errors": [
10100,
10801
]
 }
 ]
}
Ответ клиентской системы на callback

Код HTTPS-ответа должен быть 204 (No Content)

Коды событий

Коды событий Status

Код статусаПравило использованияКонечный статус?
200Сообщение успешно отправлено, но еще не доставленоНет
201Сообщение не отправленоДа
202В сообщении, состоящем из нескольких сегментов, была успешно отправлена лишь их часть. Например, 2 из 3 сегментовНет
300 Сообщение было доставленоДа
301Сообщение не было доставленоДа
 302Пользователь получил только часть сообщения. Например, 2 из 3 сегментовДа

В течение 3 дней после отправки SMS продолжаются попытки доставить его. После 3 дней статус сообщения будет окончательным.

 

Описание ошибок

Внешний кодВнутренний кодОписание
00Сигнальная сеть оператора не вернула расширенный статус.
11Получатель был не в сети или в момент отправки SMS номер никому не принадлежал
22Получатель был не в сети всё время, пока мы пытались доставить SMS
33Абонент заблокирован, поставил блокировку на прием SMS, либо находится в роуминге и не может получить SMS
44Ошибка в процессе доставки, попробуйте ещё раз
55Неизвестный абонент, проверьте номер получателя 
66У получателя не подключена услуга приема SMS
77Коммутационное оборудование, на котором зарегистрирован абонент не отвечает
88Номер указан некорректно либо телефон получателя выключен уже очень давно. Правильный формат для номеров РФ: 70000000000
99Запрещенный абонент
1010Имя отправителя не согласовано у оператора получателя
1111У получателя не подключен приём SMS
1212Ошибка на уровне мобильного устройства абонента.
1313У получателя ограничены услуги связи
1414Указанное имя отправителя не согласовано или не подключено
1515CUG reject
2121Not Supported facility
2222Not Supported roaming
3131Busy subscriber
3232Busy subscriber over GPRS
3434Ошибка в SMS-центре
3535Data Missing
3636Unexpected Data Value
4040Скорее всего у получателя нет памяти в телефоне, чтобы принять сообщение
4141Ошибка в SMS-центре
4242Not Supported by equipment
4343Not Supported by equipment
4444Message Raplace Failure
4545Unspecific PID Error
4646Message Class Not Supported
4747DCS Error
4848TPDU Not Supported
4949SIM Full
5050No SMS Storage in SIM
5353Busy SIM Application Toolkit
5454Data Download Error
6060Absent subscriber
6161Absent subscriber Detached
6262Оператор получателя не нашёл абонента в своей базе. Скорее всего получатель в процессе смены оператора. Отправьте SMS ещё раз
6363У получателя временно ограничен приём SMS. Попробуйте ещё раз
6464Absent subscriber Deregistered
6565Absent subscriber Purged
6666Absent subscriber over GPRS Page Fail
6767Absent subscriber over GPRS Detached
6868Absent subscriber over GPRS Deregistered
6969Absent subscriber over GPRS Purged
7070Absent subscriber unidentified over MSC
7171Absent subscriber unidentified over GPRS
128128Абонент не существует или у него не подключена функция приема SMS
148148Получатель был недоступен
170170Внутренняя ошибка сервера. Обратиться в службу поддержки
171171Запрещена отправка дубликатов. Не повторяйте отправку сообщений на которые возвращается данная ошибка
172172Некорректная кодировка для многосоставного сообщения. Необходимо передавать все части многосоставного сообщения в едином data_coding
245245Время ожидания от SMS-центра оператора истекло
252252Запрещена отправка сообщений на данному абоненту.
253253Текст сообщения содержит запрещенные слова.
254254Запрещена отправка сообщений с данного имени отправителя.
255255Внутренняя ошибка оператора получателя
601601Недопустимая Длина Сообщения.
608608Системная ошибка в SMS-центре, отправьте SMS ещё раз
610610Имя отправителя не согласовано у этого оператора
611611Номер телефона указан некорректно. Правильный формат для номеров РФ: 70000000000
688688Троттлинг
698698Истек период валидности сообщения.
700700Код временной ошибки приложения ESME
701701Код ошибки постоянного приложения приемника ESME
857857ESME Запрещено использовать указанную операцию
950950Приостанавливается доставка смс сообщений от банковских номеров на 24 ч
10581058Слишком длинное SMS
10781078На SMSC UMS Huawei ошибка означает, что не был найден маршрут для отправки смс на указанный номер получателя, или формат номера «Б» неправильно задан
12811281PDU запрещена по правилам роутинга (invalid sender). С этой ошибкой лучше обратиться в поддержку: supmarketolog@stream.ru.
12831283Шаблон сообщения не соответствует согласованным
12841284В тексте сообщения найдены запрещенные слова или части слов.
12991299Ошибка отправки многосоставного сообщения
13011301Оператор получателя определил SMS как спам
15371537Заданное имя отправителя у получателя находится в черных списках.
1010100Указанное имя отправителя не согласовано или не подключено
1010110Имя отправителя содержит некорректные символы
1010111Нет данных в OmniMessage о client_connection_id
1010112Имя отправителя не согласовано у оператора получателя
1010113Неизвестный CallDirection
1010114Нет данных в OmniRoute о ChannelTypeId
90110600В подключении не указан маршрут, обратитесь в техподдержку
90110601Ошибка в настройке маршрута
90110602Не найдено подходящее правило в маршруте
90110603Имя отправителя не согласовано у оператора получателя
90110604Шаблон не согласован с оператором получателя
90110605Запрет отправки пользователем.
90110606Превышен лимит ожидания от одного из сервисов платформы, попробуйте отправить SMS ещё раз
90110607gRPC запрос на отправку сообщения закрыт со стороны клиентского шлюза.
90110608Превышен лимит сообщений в месяц, установленный в настройках подключения (month_message_limit)
90110609Не найдена резервная группа.
90010700Превышен лимит ожидания от одного из сервисов платформы, отправьте SMS ещё раз
90010701Ошибка транслитерации.
1110800Не указан номер телефона получателя
1110801Пустой параметр dst_naming в OmniRoute
1110802Номер телефона указан некорректно. Правильный формат для номеров РФ: 70000000000
1110803Не определился оператор и регион получателя. Проверьте номер — вероятно, он некорректный
1110900Блокировка по услуге 'Оптимизация трафика'.
1010901Блокировка по услуге 'Мониторинг клиента'.
1110902Блокировка по услуге 'Мониторинг абонента'.
1110903Блокировка по услуге 'Мониторинг всех абонентов'.
1110904Абонент в глобальном стоп-листе (BlockBlacklistGlobal).
1110905Получатель у вас в черном списке 
1110906Абонент не в белом списке (BlockWhitelistPersonal).
1110908Изменен владелец номера лицевого счета
1110909Смена владельца номера
1110910Финансовая блокировка клиента
90411000Не удалось создать Firebase приложение на основе авторизационных данных
90411001Не удалось создать приложение для отправки сообщений через Firebase
90411002Возникли проблемы при установке прокси для Firebase
90411003Сообщение не отправлено получателю через Firebase
90411010Сертификат p12 для APNs не расшифрован
90411011Сертификат p8 для APNs не расшифрован
90411012Возникли проблемы с использованием прокси-сервера для APNs
90411013Сообщение не отправлено получателю
90411021Возникли ошибки при запросе к БД
90411022Возникли ошибки при запросе к БД
90411023Указан некорректный тип платформы клиента
90411024Сертификат не обработан/не сохранен
90411025Отсутствуют данные для типа платформы
90411040Неизвестный тип платформы (aPNS/Firebase/HMS)
90411050По указанному номеру телефона пользователя не найдены активные подписчики
90411051Возникли ошибки при запросе к базе данных
90411052Указан неверный тип платформы в базе данных
90411060Ошибка преобразования сообщения
90411061Отсутствуют данные о сообщении
90411062Не указан текст сообщения для отправки
91011100Не получено уведомление о доставке.
91011110Ошибка преобразования proto сообщения.
91011120Ошибка загрузки данных из БД при старте сервиса.
91011121Ошибка загрузки данных в БД при остановке сервиса.
91011130Неизвестный тип события
91011131Ошибка обработки Submit_ok
91011132Ошибка обработки Delivery_ok
90311200Причина неизвестна, истёк срок доставки SMS
90311201Сегмент не отправлен
90311203Один из сегментов SMS не отправлен — клиент получил не полное сообщение
90511300Не удалось отправить сообщение через sms-t
90511301Невалидный формат url для sms-t
90511302Невалидный формат url для proxy
90511303Невалидный ответ от sms-t
90511304Ошибки от сервиса sms-t
90511305Не удалось отправить сообщение в прямой Viber
90511306Невалидный формат url для Direct Viber
90511307Невалидный формат url для proxy
90511308Невалидный ответ от Direct Viber
90511310Необработанная ошибка
90511311Не смогли преобразовать данные к типу AuthData
90511312Не найден билдер
90511313Не найден yaml-файл
90511314Не смогли распарсить yaml-файл
90511315В yaml-файле нет нужной информации
90511316Невалидные данные для Divect Viber
90511317Не удалось определить тип сообщения для Direct Viber
90511340Ошибка преобразования proto сообщения
90511341В сообщении отсутствует поле MessageParams
90511342В сообщении отсутствуют данные необходимые для сервиса
90511350Неизвестная ошибка при отправке
90511351Достигнут предел переповторов отправки
90511352Неподдерживаемая ChannelGroupID
90511380Неизвестная ошибка при колбеке
90511381Клиент не подписан на канал
90511382Ошибка на стороне Viber-провайдера
90511383Неверные настройки аккаунта
90511384Ошибочный формат сообщения
90511385У пользователя не установлен Viber
90511386Устройство не поддерживает Viber
90511387Платежные ошибки
90511388Время жизни сообщения истекло (на стороне Viber).
90511389Ожидается ответ пользователя.
90511390Не смогли определить нейминг для sms-t чата (МО трафик).
90611400Ошибка чтения сообщения из очереди обмена
90611401Ошибка преобразования внутреннего формата сообщения
90611410Ошибка парсинга URL прокси-сервера
90611411Ошибка аутентификации на стороне email-провайдера
90611412Ошибка отправки запроса в сторону email-провайдера
90611413Ошибки валидации сообщения
90611420Ответ от email-провайдера содержит ошибки
90611430Ошибка при записи события во внутреннюю очередь
90111700Дубликат сообщения (услуга дедубликации).
90111900Не подключен пакет SMS
90111901Пакет SMS закончился
90111902Пакет закончился. По всем сообщениям получено подтверждение корректной отправки
90111903Нет подходящего пакета SMS
© 0 ПАО «МТС» 18+