lirax

LiraX telephony and CRM integration for n8n with full API coverage - Voice calls, SMS, IVR, contacts and call management. Supports Ukraine and Belarus regions.

Package Information

Downloads: 486 weekly / 486 monthly
Latest Version: 1.0.5
Author: PRAGMA Solutions

Available Nodes

LiraX icon
LiraX
Interact with LiraX Telephony and CRM API - Full integration with voice, SMS, contacts and calls management with enterprise-grade features
LiraX Trigger icon
LiraX Trigger
Starts workflow when events occur in LiraX PBX
LiraX Tool icon
LiraX Tool
Provides LiraX telephony operations as tools for AI Agent with standardized output format

Documentation

n8n Nodes для Интеграции с LiraX
Обзор
Этот проект предоставляет полную интеграцию между платформой автоматизации рабочих процессов n8n и системой телефонии и CRM LiraX. Он включает поддержку голосовых звонков, SMS-сообщений, IVR, контактов, управления звонками и расширенных операций CRM.

Версия: 1.0.0
Автор: PRAGMA (info@pragma.by)
Репозиторий: GitHub (предполагаемый URL на основе анализа проекта)
Лицензия: MIT

Основные возможности
Полная двусторонняя связь с LiraX через API и веб-хуки.

Поддержка телефонии: исходящие/входящие звонки, управление вызовами, записи разговоров и IVR.

Интеграция с CRM: контакты, сделки, задачи, заметки и аналитика.

Отправка/получение SMS, отслеживание статуса доставки.

Расширенный IVR с многоуровневыми меню и захватом ввода пользователя.

Безопасность: валидация токенов веб-хуков, проверка SSL-сертификатов, обработка ошибок.

Высокая доступность: повторные попытки (retry) с экспоненциальной задержкой, circuit breaker, кэширование и идемпотентность.

Автоматическая нормализация номеров телефонов и валидация параметров с использованием Zod-схем.

Кэширование для loadOptions (пользователи, магазины, статусы) с TTL.

Логирование с трассировкой стека ошибок и аналитикой производительности.

Требования
Node.js ≥ 18.17.0

n8n ≥ 1.112.6 (2025-09-26)

Доступ к LiraX API версии 4.45 (или совместимой)

Установка
Через Community Nodes (рекомендуется)
В n8n перейдите в Settings > Community Nodes.

Найдите n8n-nodes-lirax.

Нажмите Install и перезапустите n8n.

Ручная установка
Клонируйте репозиторий:

bash
git clone https://github.com/photobrand/n8n-nodes-lirax.git
cd n8n-nodes-lirax
Установите зависимости и соберите проект:

bash
npm install
npm run build
Перезапустите n8n для загрузки нод.

Конфигурация
Учетные данные (Credentials)
В n8n добавьте новые учетные данные типа LiraX API:

Base URL: URL вашего экземпляра LiraX (например, https://your-lirax-instance.com/api).

API Token: Токен для аутентифицированных запросов (Bearer-токен).

Webhook Token: Секретный токен для валидации входящих веб-хуков.

SSL Verification: Включите для проверки SSL-сертификатов (рекомендуется в продакшене).

Retry Policy: Настройки повторных попыток (количество, задержка).

Timeout: Таймаут запросов (по умолчанию 30 секунд).

Настройка веб-хуков в LiraX
В админ-панели LiraX перейдите в настройки интеграций.

Укажите URL веб-хука из триггер-ноды n8n.

Укажите webhook token для безопасности.

Использование
Триггер-нода (LiraX Trigger)
Используйте для прослушивания событий от LiraX: входящие звонки (event), записи разговоров (record), полученные SMS (smsReceived), завершение вызовов (makecall_finished) и т.д.

Пример: Подключите к ноде для обработки события и запуска workflow.

Основная нода (LiraX Node)
Выберите ресурс (telephony, crm, messaging и т.д.) и операцию из выпадающего списка.

Поддерживаемые операции (соответствуют API LiraX 4.45):

Telephony: makeCall, killCall, make2Calls, get_calls, set_call_lost, get_makecall_data.

Messaging: sendSMS, checkSMS, send_cloud_message.

CRM: createTask, AddTaskResult, createNote, createDeal, checkContact.

Utility: getUsers, getShops, getStages, getUserStatuses, getUserSips.

И другие: blacklist, campaigns, presence.

Параметры вводятся в UI ноды и валидируются Zod-схемами.

Пример workflow: LiraX Node (makeCall) → If (проверка статуса) → LiraX Node (createTask).

Примеры workflow
Исходящий звонок с созданием задачи в CRM:

LiraX Node: makeCall (ani: "101", dnis: "380501234567").

If: Проверка успеха.

LiraX Node: createTask (ext_contact: "380501234567", text: "Follow-up call").

Обработка входящего SMS:

LiraX Trigger (event: smsReceived).

LiraX Node: createNote (ext_contact: "{{$json.from}}", text: "{{$json.text}}").

Получение списка звонков:

LiraX Node: get_calls (date_start: "2025-10-01 00:00:00", date_finish: "2025-10-02 23:59:59").

Детали API
Интеграция строго следует спецификации LiraX API v4.45:

Все запросы: POST на /api с application/x-www-form-urlencoded.

Аутентификация: Заголовок Authorization: Bearer .

Имена команд: snake_case (например, get_calls, set_call_lost).

Параметры: Строки для чисел/булев ("0" или "1" для булевых).

Даты: Формат YYYY-MM-DD HH:MM:SS.

Ограничения: Для get_calls — не более 48 часов; для SMS — не чаще 1 в 5 секунд на модем.

Нормализация: Телефонные номера преобразуются в цифры без пробелов/символов.

Важные замечания по использованию
Валидация: Не превышайте 48 часов для запросов логов звонков.

Троттлинг: Для sendSMS/checkSMS добавлена задержка 5 секунд.

Безопасность: Используйте timing-safe сравнение токенов для предотвращения атак.

Кэширование: Активировано для loadOptions (TTL: 3600 секунд).

Идемпотентность: Включена для предотвращения дубликатов при ретраях.

Обработка ошибок
Автоматические повторные попытки (до 3) с экспоненциальной задержкой для временных сбоев (5xx, таймауты).

Circuit Breaker: Блокировка запросов при повторяющихся ошибках (привязано к учетным данным).

Логи: Детальные сообщения с трассировкой стека в catch-блоках.

В UI: Пользовательские сообщения об ошибках (например, "Invalid parameters" для 400).

Разработка и тестирование
Язык: TypeScript с строгой типизацией (Zod для схем, ESLint для линтинга).

Структура:

src/index.ts: Точка входа.

nodes/LiraX.node.ts: Основная нода.

nodes/LiraXTrigger.node.ts: Триггер.

shared/LiraX.utils.ts: Утилиты (liraxRequest, normalizePhoneDigits и т.д.).

Тестирование: Unit- и integration-тесты с Jest и mocks (npm test).

Сборка: npm run build (tsconfig.json с outDir: dist).

Установка

Метод 1: Через Community Nodes в n8n UI (рекомендуется)

Это самый простой способ для облачной и коробочной версии n8n:

  1. Откройте ваш n8n
  2. Перейдите в Settings (Настройки) → Community Nodes
  3. Нажмите Install
  4. В поле Enter npm package name введите: n8n-nodes-lirax
  5. Нажмите Install
  6. Дождитесь завершения установки
  7. Готово! Ноды LiraX появятся в списке нод

Метод 2: Ручная установка (для продвинутых пользователей)

Для self-hosted версии n8n:

  1. Клонируйте репозиторий
    git clone https://github.com/photobrand/n8n-nodes-lirax.git
    cd n8n-nodes-lirax

  2. Установите зависимости
    npm install

  3. Соберите проект
    npm run build

  4. Создайте символическую ссылку (или скопируйте в custom nodes папку)
    npm link

  5. В папке с n8n выполните
    npm link n8n-nodes-lirax

  6. Перезапустите n8n

=====================================================================================================

Настройка региона и эндпойнтов

LiraX работает в двух основных регионах:

Украина (lirax.ua)

  • Выберите Ukraine (lirax.ua) в поле Region
  • Эндпойнты настраиваются автоматически:
    • Основной: https://lira.voip.com.ua:8482/general
    • Резервный: https://api.lirax.net/general

Беларусь (lirax.by)

  • Выберите Belarus (lirax.by) в поле Region
  • Эндпойнты настраиваются автоматически:
    • Основной: https://api.lirax.by/general
    • Резервный: https://lira.voip.com.by:8482/general

Собственный эндпойнт

  • Выберите Custom URL в поле Region
  • Укажите ваш URL в поле Base URL
  • Опционально укажите резервный URL в Secondary Base URL

Важно: Нода автоматически попробует резервный эндпойнт если основной недоступен

Внесение вклада
Форкните репозиторий и создайте pull request.

Соблюдайте стиль кода (ESLint) и добавляйте тесты для новых фич/фиксов.

Сообщайте об ошибках в Issues.

Discussion