Иногда так хочется ненадолго вернуться в ранние нулевые. Ах, ностальгия! Сборная еще не взяла бронзу на Евро, сентябрь не сгорел, Бандурин и Вашуков выступают вместе, а SMS — отличное средство для быстрой коммуникации. И если все остальное похоже не вернуть, то вот на счет SMS я не буду столь категоричен. Нет, я не забыл принять свои таблетки, просто сегодня мы одним глазом посмотрим на новый SMS API от компании MTT. Придерживаясь немного шутливого стиля мы на простых примерах рассмотрим следующее: Пару примеров для быстрого старта с SMS API.  Пример скрипта для подсчета голосов, отправленных по SMS. Пример интеграции SMS API в простой бизнес-процесс Camunda community edition. В начале статьи важно уточнить, что ниже речь пойдет о новом SMS API от компании MTT.  Также сделаю ставший стандартным дисклеймер о том, что я не разработчик, поэтому программный код, изложенный в статье, может быть далек от самых лучших практик. Все, с формальностями покончено, теперь можем переходить к делу. Содержание: Общее описание SMS API Пример скрипта для подсчета голосов отправленных по SMS Пример интеграции SMS API в простой бизнес процесс Camunda community edition Этот раздел, будет полезен, тем кто плохо знаком с базовыми принципами использования Telecom API. Если вы опытный специалист, то можете смело его пролистать.  Ниже я покажу только несколько примеров использования API, для всего остального можно заглянуть в документацию и сделать по аналогии. Новый SMS API, в первую очередь, позволяет нам отправлять и принимать SMS сообщения, но естественно только этим его функции не ограничиваются. С помощью этого инструмента мы можем: Отправлять сообщения.  Принимать сообщения. Получать историю и общее количество отправленных сообщений. Получать уведомления об отправленных и полученных SMS. Управлять черным списком номеров. Просматривать и управлять настройками номеров для сервиса сообщений. Чтобы упростить процесс,  я сделал коллекцию и окружение для Postman. Вы можете их скачать и импортировать в Postman, а затем просто подставить в окружении ваше значения логина MTT и пароля (токена). После того, как вы успешно справитесь с импортом коллекции и окружения, необходимо задать значения переменным окружения. Самый простой путь — это нажать кнопку в правом верхнем углу окна приложения и вставить актуальные данные в поля раздела current value. Теперь мы можем перейти к примерам. Для начала убедимся, что всё работает. Выберите в коллекции метод GetNumbеrs и откройте вкладку body.Давайте расшифруем поля: customer_name — это ваш идентификатор пользователя, как я уже писал выше мы подставляем сюда переменную mtt_login (переменные в постман обрамляются двумя фигурными скобками) limit — количество записей, которое мы получим в ответе offset — страница с которой начнем просмотр(например, если limit = 10, offset = 1, то мы получим записи начиная с 11) Отправьте запрос. Если всё выполнялось корректно, вы получите ответ: Если перейти на вкладку Console, можно увидеть, как выглядит полностью адрес запроса. Теперь, когда мы уверены, что все работает корректно, давайте приступим к самому главному —  отправке SMS. Выберите в коллекции метод GetNumbеrs и откройте вкладку body.Давайте расшифруем поля: number — это номер, который будет отправлять и принимать SMS, мы подставляем сюда переменную mtt_number  destination — номер, на который мы отправляем SMS text — текст SMS (можно писать, как по-английски, так и по-русски) Отправьте запрос. Если всё выполнялось корректно, вы получите ответ: success — это статус отправки (если true, то все хорошо) mesage_id — идентификатор сообщения, его можно потом использовать в фильтрах для поиска конкретного сообщения. Давайте проверим, как это работает в обратную сторону. Отправьте со своего телефона SMS на номер, который вы ввели в переменную mtt_number После отправки выберите в коллекции метод GetMessagesHistoryList и откройте вкладку body.Давайте расшифруем поля: customer_name - это ваш идентификатор пользователя, как я уже писал выше мы подставляем сюда переменную mtt_login  Для простоты, я сейчас не стал указывать в запросе фильтры. Некоторые из них я объясню в разделе про голосование при помощи SMS.Но просто помните: если дополнить наш запрос, например, полем "event_date_gt":"2022-11-27T19:02:01.000Z", то будут показаны только сообщения отправленные после 19:02:01 27 ноября 2022 года. Отправьте запрос. Если всё выполнялось корректно, вы получите ответ: Пробежимся по полям ответа: message_id — ИД сообщения (разбирали выше) number — это наш mtt_number sender — номер отправителя (если вы послали сообщение через API то он будет такой же как в поле number) receiver - номер получателя (если вам послали сообщение через API то он будет такой же как в поле number) text — текст сообщения direction — тип сообщения: входящее (incoming) или исходящее (outgoing) segments_count - количество сегментов (помните раньше 1 смс было 70 символов на кириллице - это и есть 1 сегмент) billing_status - статус оплаты сообщения delivery_status - статус доставки сообщения event_date - дата отправки channel - канал (SMS) Вот мы и попробовали в блиц режиме SMS API. Как я говорил выше, это не все методы API, но для первого знакомства самое то. Мы могли бы с вами сегодня разобрать что-то современное и тривиальное, например, отправку кодов для проверки номера телефона или оповещение о статусе заказа, но это на мой взгляд скучно. Лучше продолжим погружаться в эстетику нулевых. Давайте вспомним такое явление как SMS голосование. Представьте, что вы работаете на региональной радиостанции, и в вашей программе есть интерактивная передача с SMS голосованием. Эфир передачи торжественно завершит песня в честь победителя голосования. Но как же нам узнать глас народа?  Интернет, знаете ли, может быть не у всех, обрабатывать звонки не удобно, а вот SMS — самое то! По легенде в нашем голосовании участвуют два участника котики и песики. Чтобы голос учли надо отправить смс с текстом “cat” или “dog” на номер радиостанции.  Следить за ходом голосования можно на сайте. Страница будет выглядеть вот так: Какая красота! Табличная верстка, нет ни всяческих новомодных AJAXов, ни CSSов, только теплые ламповые HTML + PHP. А поскольку на хостинг мы с вами тратиться сильно не хотим, то обойдемся без базы данных. Чтобы сэкономить средства и ресурсы, переложим хранение данных на плечи MTT, раз уж есть такая возможность. Прежде чем перейти к коду, еще раз напомню, что я не программист, поэтому мои программные решения могут быть далеки от идеала. Воспринимайте код ниже, как демонстрацию работы с SMS API. Также напомню, что все примеры можно скачать с GitHub. Начнем с главной страницы. Код страницы простой, там только HTML и вызов функции для голосования. Мы не будем его детально рассматривать. Листинг я спрячу под спойлер.  Как вы уже догадались из листинга index.php, основная логика запросов прячется в файле count.php. Под спойлером полный листинг файла.  Давайте на всякий случай разберем по логическим блокам.   Объявляем функцию с аргументами: $number — номер телефона на который принимаем SMS; $date_gt, $date_lt — верхняя и нижняя граница фильтра по дате в формате google.protobuf.Timestamp $first и $second — это строка для учета голосов, в нашем случае “cat” и “dog” (регистр не важен). Для простоты внутри функции встроены настройки запроса к SMS API $url — адрес метода $customer_name — логин МТТ $token — токен для входа. Подробнее эти параметры  мы с вами разбирали в предыдущей главе. Перейдем к следующей секции: Этот код  реализует запрос к API и сохраняет ответ в $response. Вам не обязательно писать его руками, достаточно выгрузить код из Postman и немного подправить: Тут все просто: мы преобразуем ответ в массив, а потом циклически пробегаем по нему. Если текст SMS равен слову “cat” или “dog” (в любом регистре), то мы увеличим счетчик. В конце возвращаем ответ. В начале статьи я обещал вам один скрипт на PHP, но я позволю себе воспользоваться приёмом “магазинов на диване” и сделаю вам предложение, от которого нельзя отказаться!  Если прямо сейчас вы продолжите чтение этой статьи, то совершенно бесплатно получите дополнительный пример кода. Не упустите свой шанс, читайте прямо сейчас, количество примеров ограничено! Предположим, что директор нашей радиостанции очень боится мышей, и любого, кто отправит SMS со словом «мышь», мы будем беспощадно банить навсегда. К счастью, и в этом случае нам не понадобится хранить телефоны забаненных в базе данных, потому что мы можем воспользоваться функцией управления черным списком SMS API. Для начала нам необходимо настроить адрес для получения уведомлений о сообщениях. Выберите в коллекции метод SetNumberSettings поле “number”  - номер телефона МТТ, для которого задаются настройки поле “event_url”  — это адрес скрипта, который будет обрабатывать уведомления поле “event_headers” — это заголовки, которые будут добавлены к уведомлению (если не знаете, что писать, можно просто опустить это поле) Теперь перейдем к коду файла bl.php. Под спойлером полный листинг файла.  Мы не будем разбирать этот скрипт по кускам, потому что он очень похож на предыдущий. По сути, мы проверяем наличие в поле text уведомления слова «мышь»  в любом регистре. И если мышка забежала в наше уведомление, то отправляем запрос на метод AddBlackList. Вы можете эмулировать отправку уведомления, чтобы проверить скрипт. Теперь, когда у нашего радио есть всё, что нужно для SMS голосования, пришло время перейти к следующему кейсу. В этой главе нам придется отказаться от воспоминаний о теплых ламповых нулевых, просто потому, что Camunda тогда  еще не была разработана.  Поэтому предлагаю заглянуть немного в будущее, а точнее в январские каникулы. Представим себе такой кейс. Каждый год персонал одной маленькой, но очень дружной компании уходит на новогодние каникулы. И только самый трудолюбивый в мире младший менеджер Игорь всегда остается дежурить в офисе. Одной из обязанностей Игоря является ежедневный полив редких и очень избалованных офисных растений. Но вот беда: Игорь очень забывчивый, и раньше приходилось постоянно ему напоминать про растения. Но этой зимой все изменится! Мы автоматизируем процесс напоминания Игорю с помощью SMS API  и Camunda. Поскольку я установил Camunda локально с помощью Docker, я не смогу получить уведомление о доставленной SMS. Но как говорится ― голь на выдумки хитра. Давайте рассмотрим схему процесса: На всякий случай уточним сценарий. Действующие лица: Игорь, Camunda. Цель Гарантированно напомнить Игорю про полив растений. Предусловия: Наступило 9:00 рабочего дня. Игорь вышел на работу. На балансе Telecom API есть средства. Игорь может отправить SMS в ответ. Основной путь: Camunda отправляет SMS Игорю с помощью SMS API. Игорь поливает цветы (или делает вид, что полил) Игорь отправляет любую SMS на определенный номер.  Camunda ожидает 10 минут. Camunda проверяет количество SMS с номера Игоря за последние 10 минут, с помощью SMS API. Если количество SMS не меньше 1, переходим к шагу 7. Процесс успешно завершен. Альтернативный путь:	 6а. Возврат к шагу 1. Результат Игорь отчитался, что полил цветы. Вы можете начертить самостоятельно такую схему, но проще скачать её в GitHub Если будете чертить самостоятельно, то в блоке “Отправить SMS Игорю” введите topic = send-sms, как на скриншоте. Для блока "Проверяем СМС от Игоря” введите topic = check-sms, как на скриншоте. Первому таймеру (на 9:00)  введитеtype = cycle, value = R9/2023-01-01T06:00:00Z/P1 Второму таймеру введите type = duration, value = PT10M Линии связи “Есть SMS” введите Condition expression = {sent} Вторую ветку сделайте веткой по умолчанию. Создайте node js проект аналогично инструкции. В нашем случае код файла worker.js будет отличаться от инструкции. Листинг я спрячу под спойлер. Также предупрежу, что в JS я не силён, поэтому решение получилось не самым элегантным.  Должен честно признаться, по большей части этот код “копипаста” из инструкции Camunda, Postman и Stackoverflow.  Давайте быстро пробежимся по блокам. Блок кода для сервиса “Отправить SMS Игорю”, здесь мы по сути вызываем метод отправки SMS Telecom API и говорим Camunda, что процесс успешно завершен (даже если SMS по факту не отправится). Это функции для подсчета SMS. Я не особо знаком с асинхронностью в JS, поэтому позаимствовал кусок кода на просторах Интернета и вставил в него вызов метода для определения количества SMS за период из Telecom API. Ну и последний блок кода, это непосредственно обработка сервиса “Проверяем SMS от Игоря”. В этом блоке мы вызываем функцию для подсчета SMS, которые нам послал Игорь, и если за 10 минут пришла хоть 1 SMS, то мы устанавливаем флаг sent = true, после чего процесс завершается. Диаграмму и код можно скачать в GitHub Несмотря на наличие современных мессенджеров, SMS по прежнему остается простым и надежным средством коммуникации. Сегодня мы рассмотрели почти все методы раздела SMS (NEW) в Telecom API. Если вас увлекла тема автоматизации в сфере телекоммуникаций с помощью Telecom API, ознакомьтесь с другими статьями раздела: «А у нас сиеста!» или как ресторану обрабатывать звонки клиентов с помощью API.  «Позвони мне позвони» или решаем проблему скрытия телефонного номера с помощью callback сервиса. «Смартфон и его команда» или скрываем номер звонящего и управляем вызовом с помощью MTT API. Спасибо вам большое за то, что дочитали до конца.  Всех с наступающими праздниками и успехов в Новом году!   Технический писатель / системный аналитик