API-запросы через сниппет

В данном руководстве демонстрируется процесс выполнения API-запроса к внешнему серверу для обогащения данных в реальном времени. В качестве примера используется задача определения информации по номеру телефона, однако представленный подход является универсальным и может быть адаптирован для обработки любых других данных, извлекаемых из пользовательского ввода.

Сферы применения

Автоматическая обработка и обогащение данных через внешние API является ключевым требованием для многих бизнес-процессов в таких отраслях, как телекоммуникации, финансы и электронная коммерция. Это позволяет решать следующие задачи:

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

• Персонализация: Предоставление кастомизированных предложений.

• Антифрод-анализ: Выявление подозрительной активности на основе обогащенных данных.

Например, по номеру телефона можно определить оператора связи, регион и другие параметры, которые затем могут быть использованы для ветвления логики сценария.

Алгоритм реализации

Ниже представлен алгоритм, описывающий логику работы сниппета для обогащения данных по номеру телефона:

1. Извлечение входных данных: Получение номера телефона из параметров вызова сниппета или из контекста диалога (например, из ранее распознанной сущности).

2. Нормализация данных: Валидация и очистка номера телефона от нерелевантных символов (пробелы, дефисы) и приведение к стандартному формату (например, удаление кода страны).

3. Формирование и отправка API-запроса: Инициализация HTTP-запроса к внешнему сервису с передачей нормализованного номера.

4. Обработка ответа: Анализ статуса ответа от API. В случае успеха — переход к следующему шагу. В случае ошибки — выполнение логики обработки исключений.

5. Сохранение данных в контекст: Запись полученных данных (оператор, регион и т.д.) в контекст диалога для их дальнейшего использования в сценарии.

6. Логирование (опционально): Вывод отладочной информации о результатах выполнения запроса.

7. Обработка исключений: Корректная обработка ошибок, возникших на любом из этапов, с информированием пользователя или системы.

Рекомендация: Отладочные вызовы, такие как core.sendText, следует использовать только на этапе разработки. Перед развертыванием в production-среде их необходимо удалить или закомментировать.

async function snippet (core = new Core(), context = new Context()) {
    // Измените на ваш URL API
    const apiUrl = 'https://api.example.com/v2/operator?number='; 
    // Переменные для хранения номера телефона
    let phone = null; 
    let inputPhone = null; 

    // Проверяем, был ли передан номер телефона
    if (inputPhone) {
        phone = inputPhone; // Если номер передан в параметре, используем его
    } else if (context && context.current && context.current.meta && 
               context.current.meta.entities && context.current.meta.entities.phone) {
        // Если номер телефона есть в контексте, извлекаем его
        phone = context.current.meta.entities.phone.raw;
    }
    
    // Проверяем, что номер телефона действительно найден (для отладки)
    if (!phone) {
        core.sendText('Номер телефона не указан в контексте');
        return null;
    }

    // Логируем номер телефона для тестирования (для отладки)
    core.sendText('Номер телефона в контексте: ' + phone);

    // Преобразуем номер в строку и удаляем все нецифровые символы 
    // (например, пробелы, скобки, дефисы)
    phone = String(phone); 
    phone = phone.replace(/\D/g, '');

    // Убираем код страны (например, 7 или 8 для России)
    if (phone.startsWith('7') || phone.startsWith('8')) {
        phone = phone.slice(1);
    }

    // Логируем номер для отправки запроса (для отладки)
    core.sendText(`Отправляем запрос с номером: ${phone}`);

    try {
        // Отправляем GET запрос к API с номером телефона
        // Запрос будет отличаться в зависимости от вашего API
        const response = await axios.get(apiUrl, {
            params: { number: phone }, // Передаем номер в параметре
            headers: {
                "Accept": "*/*", 
                "Accept-Language": "en,ru;q=0.9,en-GB;q=0.8,en-US;q=0.7",
                "Cache-Control": "no-cache",
                "Connection": "keep-alive",
                "Origin": "https://api.example.com/v2/operator?number=",
                "Pragma": "no-cache",
                "Referer": "https://api.example.com/v2/operator?number=",
                "Sec-Fetch-Dest": "empty",
                "Sec-Fetch-Mode": "cors",
                "Sec-Fetch-Site": "same-site",
                "User-Agent": ""
            }
        });

        // Получаем ответ от API
        const operatorInfo = response.data;

        // Проверяем код статуса ответа
        // statusCode возвращает 1001 - успех,  3003 - ошибка
        if (operatorInfo.statusCode && operatorInfo.statusCode !== 1001) {
           throw new Error(`Ошибка API: ${operatorInfo.statusCode}`);
        }

        // Сохраняем данные в контексте
        // Response
        context.set("operatorInfo", operatorInfo); 
        // Имя оператора
        context.set("operatorName", operatorInfo.operator); 
        // Регион
        context.set("region", operatorInfo.region);
        // Полное название оператора
        context.set("operatorTitle", operatorInfo.title);
         // Код оператора
        context.set("operatorCode", operatorInfo.code);

        // Логируем данные для отладки
        core.sendText("Ответ API получен и сохранен в контексте");
        
        // Название оператора
        // JSON.stringify превращает объект в строку формата JSON,
        // чтобы представить данные в текстовом виде.
        core.sendText(JSON.stringify(context.operatorInfo));
        return operatorInfo.code;

    } catch (error) {
        // Обработка ошибки
        core.sendText(`Ошибка при запросе: ${error.message}`);
        if (error.response && error.response.data) {
            core.sendText(JSON.stringify(error.response.data));
            return error.response.data;
        }
        core.sendText('Не удалось получить информацию о номере телефона');
    }
}