Добавляем номер в чёрный список с помощью API

Привет, Хабр! Меня зовут Анастасия Иванова, я технический писатель МТС Exolve. В этой статье я расскажу, как можно реализовать автоматическое добавление номеров в чёрный список после нескольких входящих звонков в веб-приложении на NodeJS.

Мы привыкли видеть возможность контролировать и ограничивать нежелательные звонки и контакты повсюду. Многие маркетплейсы и приложения разрабатывают функции автоматического добавления номеров в чёрный список после нескольких звонков продавцам или пользователям. Такая опция помогает:

• обеспечить пользователям защиту от нежелательных контактов: это может быть связано с маркетинговыми звонками, спамом или домогательством со стороны некоторых пользователей

• защитить пользователей от потенциальных угроз со стороны мошенников: мошенники могут пытаться получить доступ к личным данным или финансовым счетам, представляясь различными организациями или услугами

• сфокусироваться на значимых клиентах и улучшить опыт работы: позволяет избежать потери времени на нежелательные или назойливые контакты со стороны «потенциальных» покупателей, которые на самом деле не заинтересованы в покупке товара

Что нам понадобится

• Аккаунт разработчика в MTC Exolve

• API-ключ приложения в аккаунте разработчика. Инструкции о том, как создать приложение и найти его API-ключ, вы можете найти в статьях «Создание приложения» и «API-ключ приложения»

• Номер Exolve, на который можно позвонить. Инструкцию о том, как купить номер, вы можете найти в статье «Покупка номера»

• Node.js и следующие библиотеки:

  • express (создание сервера веб-приложения)

  • body-parser (парсинг тела входящих HTTP-запросов, которые отправляет Exolve на Event URL во время входящих вызовов)

  • axios (отправка HTTP-запроса в Exolve API для добавления номера в чёрный список)

Установка библиотек

Установите библиотеки, необходимые для работы Node.js-приложения. Если у вас ещё нет Node.js, вы можете скачать его с официального сайта. Вместе с ним установится npm — пакетный менеджер для скачивания внешних библиотек.

Создайте проект для приложения. Для этого выполните команду инициализации в консоли:

npm init

После выполнения команды введите название приложения, описание, имя автора и другие данные. После ввода и подтверждения всех данных будет создан package.json-файл с информацией о приложении и зависимостях — сторонних библиотеках для его работы.

Установите библиотеки, которые понадобятся далее. Выполните следующую команду в консоли:

npm i -s express body-parser axios

Она установит библиотеки, указанные в пункте «Что нам понадобится». После успешной установки в package.json-файле должны появиться зависимости от библиотек. Пример файла:

{   "name": "blacklist",   "version": "1.0.0",   "description": "",   "main": "index.js",   "scripts": {     "test": "echo \"Error: no test specified\" && exit 1"   },   "author": "Anastasia Ivanova",   "license": "ISC",   "dependencies": {     "axios": "^1.4.0",     "body-parser": "^1.20.2",     "express": "^4.18.2"   } }

Основа Express.js сервера приложения

Создайте основу Express приложения:

1. Подключите установленные библиотеки и укажите, что приложение их использует.

2. Укажите порт приложения.

3. Укажите, что приложение слушает запросы на указанном порте, и сделайте вывод соответствующего сообщения в консоль.

Для этого создайте index.js-файл в корне проекта и добавьте туда следующий код:

// Подключение библиотек const app = require('express')(); // приложение app работает на базе Express const bodyParser = require("body-parser"); const axios = require('axios');  // Входящие HTTP-запросы обрабатываются библиотекой body-parser app.use(bodyParser.json()); app.use(bodyParser.urlencoded( {extended: false} ))  // Порт, на котором работает наше приложение const port = 3001;  // Приложение будет слушать запросы на указанном выше порте app.listen(port, () => {     console.log(`App listening at http://localhost:${port}`) });

Сохраните изменения и запустите приложение. Для этого выполните в консоли команду:

node index.js

Далее появится сообщение о том, что приложение доступно по адресу http://localhost:3001.

Добавление номера в чёрный список

Приложение будет добавлять номера телефонов в чёрный список. Для этого нужно отправить POST-запрос к Exolve Blacklist API, в котором понадобятся API-ключ, URL подключения и номер, который нужно заблокировать.

В «боевом» режиме API-ключ стоит хранить в переменных окружения для безопасности. Для простоты демонстрации в нашем примере мы объявим и URL, и API-ключ как константы в index.js-файле. Добавьте следующий код:

const url = 'https://api.exolve.ru/list/blacklist/v1/Add'; // Точка доступа Exolve API для добавления номера в чёрный список const apiKey = 'YOUR_API_KEY'; // API-ключ

Задача приложения — добавлять номер в чёрный список, если с него поступило определённое количество входящих звонков. Приложение должно выполнять следующие функции:

1. Получать и обрабатывать уведомления от МТС Exolve о входящих звонках.

2. Запоминать пару номер телефона и количество входящих вызовов с этого номера.

3. Добавлять номер в чёрный список, если количество звонков превышает установленное значение.

Настройка уведомлений о событиях в Личном кабинете МТС Exolve

МТС Exolve позволяет установить URL в Личном кабинете, на который вы будете получать уведомления (POST-запросы) с данными о входящих звонках. Чтобы установить URL:

1. В Личном кабинете откройте приложение, по номерам которого хотите получать уведомления.

2. Перейдите во вкладку «Настройки» в левом меню.

3. Активируйте настройку «Переадресация вхд. вызовов на URL» в блоке «Уведомления о событиях».

В появившемся поле нужно ввести точку доступа приложения, на которую Exolve будет отправлять POST-запрос с данными. Во время локальной разработки вам понадобится сервис, чтобы сделать ваш localhost доступным из интернета, например ngrok. 

Ngrok и подобные сервисы создают туннель между вашим локальным сервером и удалённым сервером и предоставляет доступ к нему с уникального домена, который вы можете прописать в Личном кабинете Exolve, как URL для получения уведомлений.

Например, при запуске сервиса я получила URL https://d3da-88-201-206-8.ngrok-free.app, который переадресовывает HTTP-запросы на мой localhost:3001.

Сохранение пары номер телефона и количество входящих вызовов

В «боевом» режиме стоит сохранять пару номер телефона и количество входящих с него звонков в базу данных. Для простоты будем записывать данные в объект и добавлять в массив.

Создайте пустой массив callers:

var callers = []; // массив для хранения пар номер телефона + количество входящих звонков

Теперь добавьте функцию для сохранения объекта с номером телефона и количеством входящих звонков в массив:

function addCaller(phoneNumber) {   // создаём объект для номера звонившего   const caller = {     phoneNumber: phoneNumber,     numberOfCalls: 1,   };   // Проверяем, есть ли в массиве callers объект с указанным номером   callerIndex = callers.findIndex((el) => el.phoneNumber == phoneNumber);    if (callerIndex == -1) {     // Если нет, добавляем созданный объект в массив     callers.push(caller);     return 1;   } else {     // Если есть, увеличиваем количество звонков на 1     callers[callerIndex].numberOfCalls += 1;     return callers[callerIndex].numberOfCalls;   } }

Добавление номера в чёрный список

Далее напишите функцию для добавления номера в чёрный список c помощью библиотеки axios:

async function addToBlacklist(number) {   // пробуем добавить номер в чёрный список   try {     await axios({       method: 'post',       url: url,       headers: { Authorization: 'Bearer ' + apiKey },       data: {         numbers: [`${number}`],         comment: 'calls limit exceeded',       },     }).then((response) => {       responseStatus = response.status; //записываем ответ от Exolve API в переменную     });   } catch (error) {     return error.response.data.error; // возвращаем текст ошибки, если номер не был добавлен в чёрный список   }   return responseStatus; // возвращаем ответ от Exolve API (200 OК — статус при успешном добавлении номера в чёрный список) } 

Обработка POST-запроса от Exolve с данными о входящем звонке

Далее напишите функцию, которая будет обрабатывать POST-запрос от Exolve на URL приложения:

app.post('/', async (req, res) => {   const phoneNumber = req.body.number_a; // Получаем номер звонящего из POST-запроса от Exolve   const numberOfCalls = addCaller(phoneNumber); // Добавляем номер в массив данных / заменяем количество входящих звонков у существующего номера   console.log(numberOfCalls);   if (numberOfCalls == 2) { // Если количество звонков стало 2 (можно установить любое число по желанию)     const isAdded = await addToBlacklist(phoneNumber); // Добавляем номер в чёрный список     console.log(isAdded);   } });

Таким образом мы реализовали функцию автоматического добавления номеров в чёрный список после определённого количества входящих звонков, что позволит обезопасить пользователей от нежелательных контактов. Полный код приложения вы можете найти на GitHub.