Как настроить интеграцию по REST API

• Не куплен тариф. Если у вас тестовый пакет SMS, его нужно подключать каждый день. Посмотреть тариф можно в личном кабинете, в разделе Тарифы
• Не подключено имя отправителя. Проверить статус имени можно в личном кабинете, в разделе Имена отправителя
• Имя отправителя подключено не на всех операторов — SMS отправляются только на подключённых операторов
• Из личного кабинета удалили пользователя, который создавал подключение. Если удалить пользователя, все созданные подключения удалятся вместе с ним — рассылка через них невозможна

Если возникнут проблемы с интеграцией, напишите на supmarketolog@mts.ru. Чтобы мы могли помочь быстрее, добавьте в письмо подробности:

• название компании
• логин подключения
• описание проблемы
• пример сообщения: дата, время, system_id, имя отправителя, номер получателя, message_id, коды ошибок
• tcpdump, логи с ошибкой, статистика по ошибке 

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

https://omnichannel.mts.ru/http-api/v1/b/messages/

• Максимальные размеры сообщений для каналов: 10 сегментов — 670 символов на кириллице и 1530 на латинице. Кодировка текста сообщения — UTF-8. Можно отправить и больше сегментов, но чем больше сегментов — тем выше вероятность некорректной доставки

1. Получите данные для авторизации: Личный кабинет МТС Маркетолога > Рассылки по своей базе PRO > Интеграции > API > Создать подключение
2. Подключите имя отправителя
3. Подключите тариф 

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

https://omnichannel.mts.ru/http-api/v1/messages

Описание объектов запроса

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

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

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

POST /messages 
Content-type: application/json 
Пример с использованием одного имени отправителя: два сообщения отправляются от имени SMS Naming. В этом случае объект "from" и, при необходимости, поле "class", прописываются один раз в объекте "options":
{
 "messages": [
{
"ttl_sec":5,
"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С

 Текст = СтрЗаменить(ТекстСообщения, Символы.ПС, " ");
          	
           	СтруктураОтправки = Новый Структура;
          	
           	МассивСообщений = Новый Массив;
          	
           	Для каждого Адресат Из Адресаты Цикл
          	
                          	ОчередноеСообщение = Новый Структура;
                         	
                          	ОчередноеСообщение.Вставить("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);
}

https://api-adapter.marketolog.mts.ru/get/send-sms

Чтобы использовать GET-запросы, напишите нам supmarketolog@mts.ru. Мы откроем сетевые доступы до вашего IP-адреса. Темой письма укажите «Доступ для GET-запроса [ИНН организации]». В тексте письма напишите название организации, ИНН, логин от подключения и IP-адрес, до которого нужно открыть доступ. Логин от подключения указан в личном кабинете: Рассылки по своей базе PRO > Интеграции > API

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

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

GET /get/send-sms 

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 и не означает, что сообщение отправлено.

{
 "messages": [
 {
"msisdn": "79117903795",
"email": "example@mail.ru",
"message_id": "uuid",
"internal_id": "uuid2"
 }
 ]
}

• Ответ c ошибкой

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

Если получите код http-ответа, которого нет в списке — напишите нам supmarketolog@mts.ru 

https://omnichannel.mts.ru/http-api/v1/messages/info

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

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

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

Структура элемента массива events_info

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

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

{
 "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": "MTS_A2P_PRO",
"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": "MTS_A2P_PRO",
"received_at": "2021-05-18T13:45:00.000+03:00",
"status": 300,
"total_parts": 1
}
],
"key": "c128187b-145f-4b86-b47f-8e99cf513a59"
}
 ]
}

https://api-adapter.marketolog.mts.ru/get/sms-info

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

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

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 и отправлять их в вашу систему. Чтобы получать входящие, отправьте запрос на templates@mts.ru 

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

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

{
  "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 — недоступность сервисов

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

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

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

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

{
	"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"
  ]
}

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

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

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

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

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": "2025-03-15T14:30:22Z",
          "userDeliveryDate": "2025-03-15T14:30:25Z",
          "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

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

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

{
  "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"
  ]
}

GET balanceManagement/balance/full

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

https://api.mts.ru/client-omni-adapter_production/1.0.2/balanceManagement/balance/full

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

{
  "balance": 4972.85,
  "creditLimit": 100.85
}

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

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

POST /mcom/messageManagement/info

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

Ограничение: не более 1 000 параметров.

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

{
 "messageIds": [
   "171e0ccf-afa3-4a8c-bf2d-474ae3b5133c",
   "671e0fcf-aca3-3a8c-ba3d-474ae3b5267d"
 ]
}

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

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

[
  {
    "messageId": "171e0ccf-afa3-4a8c-bf2d-474ae3b5133c",
    "cost": "1.75",
    "trafficPatternType": "A"
  }
]

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

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

GET mcom/messageManagement/statistics 

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

Если query params не переданы, метод вернёт статистику за текущий период.

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

https://api.mts.ru/client-omni-adapter_production/1.0.2/mcom/messageManagement/statistics?year=2023&month=06

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

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

{
"year": 2023,
"month": 6,
"packetSizeNonTemplateMts": 4,
"packetSizeNonTemplateAll": 4,
"packetSizeTemplateMts": 2,
"packetSizeTemplateAll": 2,
"packetSizeAuthMts": 2,
"packetNonTemplateMtsRemainder": 2,
"packetNonTemplateAllRemainder": 2,
"packetTemplateMtsRemainder": 0,
"packetTemplateAllRemainder": 0,
"packetAuthMtsRemainder": 0,
"quantityNonTemplateSmsOverPacketMts": 2,
"quantityNonTemplateSmsOverPacketAll":2,
"quantityServiceSmsOverPacketAll": 3,
"quantityAuthSmsOverPacketAll": 3,
"quantityTemplateSmsOverPacketAll": 3,
"quantityIncoming": 3,
"quantityInternational": 5,
"totallyQuantitySms": 32
}

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

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

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