Skip to content

Latest commit

 

History

History
196 lines (141 loc) · 8.04 KB

README.ru.md

File metadata and controls

196 lines (141 loc) · 8.04 KB

Модуль телефонной книги для MikoPBX

GitHub release License: GPL v3

Русская версия | English

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

Возможности

  • Определение имени звонящего — автоматический показ имени при входящих и исходящих звонках
  • Интеграция с внешним API — поиск имени через внешние сервисы с кэшированием
  • Импорт из Excel — массовая загрузка контактов из файлов Excel (.xlsx, .xls)
  • Веб-интерфейс — управление контактами через DataTable с поиском и пагинацией
  • Маска ввода — автоматическое форматирование номеров телефонов (опционально)
  • Мультиязычность — поддержка 26 языков

Требования

  • MikoPBX версии 2024.1.114 или выше

Установка

  1. Перейдите в Модули → Маркетплейс в панели администрирования MikoPBX
  2. Найдите модуль Телефонная книга
  3. Нажмите Установить

Или установите из GitHub релиза:

  1. Скачайте последний .zip релиз
  2. Перейдите в Модули → Установка модуля
  3. Загрузите архив

Использование

Добавление контактов

  1. Откройте модуль Телефонная книга
  2. Нажмите кнопку Добавить
  3. Введите имя и номер телефона
  4. Нажмите Enter или кликните вне поля для сохранения

Импорт из Excel

Подготовьте Excel файл с двумя колонками:

Имя Номер телефона
Иван Петров +7 906 555-43-43
ООО Компания 84951234567
  1. Перейдите на вкладку Импорт
  2. Выберите Excel файл
  3. Нажмите Импортировать

Номера телефонов нормализуются автоматически — принимается любой формат.

Поиск через внешний API

Настройте внешний API для определения имени звонящего:

  1. Перейдите на вкладку Настройки
  2. Введите URL API с плейсхолдером %number%: 
    https://api.example.com/lookup?phone=%number%
  3. Установите время жизни кэша (в секундах, 0 = без кэша)
  4. Нажмите Сохранить

API должен возвращать текст с именем контакта.

Пример запроса и ответа API

При входящем звонке с номера +7 (906) 555-43-43, модуль нормализует его в 1065554343 и выполняет HTTP GET запрос:

Запрос:

GET https://api.example.com/lookup?phone=1065554343

Ответ (обычный текст):

Иван Петров

Имя "Иван Петров" будет отображаться как определитель номера на телефоне. Если API вернет пустой ответ или ошибку, модуль продолжит работу без отображения имени.

Пример с названием компании:

GET https://api.example.com/lookup?phone=1495123456

Ответ:

ООО Рога и Копыта

Кэш сохраняет ответ на настроенное время жизни, чтобы сократить количество запросов к API для повторяющихся номеров.

Как это работает

Нормализация номеров

Номера нормализуются для единообразного хранения и быстрого поиска:

Ввод:   +7 (906) 555-43-43
Шаг 1:  79065554343      (только цифры)
Шаг 2:  065554343        (последние 9 цифр)
Шаг 3:  1065554343       (добавлен префикс "1")

Это обеспечивает корректное сопоставление независимо от формата набора номера.

Поток вызовов

Входящие звонки:

Asterisk → AGI скрипт → Поиск в PhoneBook → Установка CALLERID(name)

Исходящие звонки:

Asterisk → CONNECTED_LINE_SEND_SUB → Поиск в PhoneBook → Установка CONNECTEDLINE(name)

Архитектура

ModulePhoneBook/
├── agi-bin/
│   └── agi_phone_book.php      # Точка входа AGI для Asterisk
├── App/
│   ├── Controllers/            # Контроллеры Phalcon MVC
│   ├── Forms/                  # Определения форм
│   └── Views/                  # Шаблоны Volt
├── Lib/
│   ├── PhoneBookConf.php       # Интеграция с диалпланом Asterisk
│   ├── PhoneBookAgi.php        # Обработчик AGI для Caller ID
│   ├── PhoneBookFind.php       # Поиск через внешний API
│   └── PhoneBookImport.php     # Обработчик импорта Excel
├── Models/
│   ├── PhoneBook.php           # Модель контакта
│   └── Settings.php            # Модель настроек
├── public/assets/
│   ├── css/                    # Стили модуля
│   └── js/                     # JavaScript (исходники ES6 + скомпилированные)
└── Messages/                   # Переводы (26 языков)

База данных

SQLite база данных: /storage/usbdisk1/mikopbx/custom_modules/ModulePhoneBook/db/module.db

m_PhoneBook — контакты:

  • id — первичный ключ
  • number — нормализованный номер для поиска
  • number_rep — отображаемый формат
  • call_id — имя контакта
  • search_index — поле для полнотекстового поиска
  • created — временная метка (для истечения кэша API)

m_ModulePhoneBook — настройки:

  • disableInputMask — переключатель маски ввода
  • phoneBookApiUrl — URL внешнего API
  • phoneBookLifeTime — время жизни кэша в секундах

Разработка

Сборка JavaScript

# Компиляция ES6 в ES5 с помощью Babel
docker run --rm -v ~/mikopbx:/workspace ghcr.io/mikopbx/babel-compiler:latest /workspace/Extensions/[module]/public/assets/js/src/[file] extension`

Проверка синтаксиса PHP

php -l Lib/PhoneBookConf.php

Ссылки

Поддержка

Лицензия

GPL-3.0 — см. файл LICENSE.