Seyyed/Seyyed_arc
Watch
1
0
Fork
You've already forked Seyyed_arc
 0
forked from hesabix/arc
Code Pull requests Activity
Seyyed_arc/extraScripts/HesabixTelephonyConnector/README.md
Babak Alizadeh 5ea784e6ff fix: require Python ≥3.8 for Issabel telephony connector 
Issabel/Rocky 8 ships Python 3.6 which crashes the connector; install/update now detect or install python39 and point systemd at it.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 08:44:46 +00:00

7.1 KiB
Raw Permalink Blame History

Hesabix Telephony Connector

عامل سبک برای اتصال Issabel / Asterisk به حسابیکس.

مخزن: extraScripts/HesabixTelephonyConnector

نصب یک‌خطی (پیشنهادی)

روی سرور Issabel/Asterisk با root:

# اگر sudo دارید (مثلاً Ubuntu):
curl -fsSL https://source.hesabix.ir/hesabix/arc/raw/branch/master/extraScripts/HesabixTelephonyConnector/install.sh | sudo bash

# اگر sudo ندارید (مثلاً Debian یا Issabel با ورود root):
curl -fsSL https://source.hesabix.ir/hesabix/arc/raw/branch/master/extraScripts/HesabixTelephonyConnector/install.sh | bash

آدرس API پیش‌فرض https://hsxn.hesabix.ir است. برای تغییر از همان لحظهٔ نصب:

curl -fsSL https://source.hesabix.ir/hesabix/arc/raw/branch/master/extraScripts/HesabixTelephonyConnector/install.sh \
  | HESABIX_API_URL=https://my-api.example.com bash

اسکریپت:

  1. توزیع را تشخیص می‌دهد (Debian/Ubuntu با apt، Issabel/CentOS/RHEL با yum یا dnf)
  2. پیش‌نیازها را نصب می‌کند (python3, rsync, curl, git)
  3. کانکتور را از مخزن حسابیکس می‌گیرد
  4. دستور hesabix-pbx را در سیستم نصب می‌کند
  5. ویزارد پیکربندی (API / توکن / AMI) را اجرا می‌کند — آدرس API قابل تغییر است
  6. سرویس systemd را فعال می‌کند

قبل از نصب، در حسابیکس: افزونه را فعال کنید → مرکز تلفن بسازید → توکن را کپی کنید.

دستورات روزمره

hesabix-pbx status      # وضعیت سرویس، سیستم‌عامل و پیکربندی
hesabix-pbx test        # تست AMI + اتصال به حسابیکس
hesabix-pbx update      # به‌روزرسانی از مخزن (+ تلاش برای نصب Softphone deps)
hesabix-pbx softphone-setup  # نصب خودکار Softphone Relay
hesabix-pbx restart     # ری‌استارت
hesabix-pbx stop
hesabix-pbx start
hesabix-pbx configure   # تغییر توکن / AMI / آدرس API
hesabix-pbx logs        # آخرین لاگ‌ها
hesabix-pbx follow      # لاگ زنده
hesabix-pbx uninstall   # حذف سرویس
hesabix-pbx help

نیازمندی‌ها

  • دسترسی root روی سرور تلفن (با یا بدون sudo)
  • خروجی HTTPS از سرور تلفن به API حسابیکس (پورت ورودی لازم نیست)
  • کاربر AMI روی Asterisk (اسکریپت در صورت تمایل می‌سازد)
  • Python ≥ 3.8 برای اجرای Connector (کد از from __future__ import annotations و typing مدرن استفاده می‌کند)

پیش‌نیازهای نرم‌افزاری در صورت نبود، هنگام install/update خودکار نصب می‌شوند.

پایتون روی Issabel / Rocky / CentOS 8

روی این توزیع‌ها python3 سیستم اغلب 3.6 است و سرویس با SyntaxError کرش می‌کند. از نسخهٔ 1.3.1 اسکریپت hesabix-pbx خودش:

  1. مفسر ≥3.8 را پیدا می‌کند (python3.9 / python3.8 / …)
  2. در صورت نبود، بستهٔ python39 (یا معادل) را با dnf/yum/apt نصب می‌کند
  3. یونیت systemd را به همان مفسر اشاره می‌دهد (نه /usr/bin/python3 سیستم)
  4. مسیر را در /opt/HesabixTelephonyConnector/.python-bin ذخیره می‌کند

دستی (اگر لازم شد):

dnf install -y python39 python39-pip   # Rocky/Issabel 8
hesabix-pbx update
hesabix-pbx softphone-setup

توزیع‌های پشتیبانی‌شده

خانواده نمونه‌ها مدیر بسته
Debian Debian، Ubuntu apt-get
RHEL CentOS، Rocky، Alma، Issabel yum یا dnf

پیکربندی (ویزارد)

hesabix-pbx configure

از شما فقط می‌پرسد:

  1. آدرس API (پیش‌فرض https://hsxn.hesabix.ir)
  2. کلید API از حسابیکس: پروفایل ← کلیدهای API
  3. انتخاب کسب‌وکار از لیست
  4. انتخاب یا ایجاد مرکز تلفن (توکن Connector خودکار گرفته می‌شود)
  5. تنظیمات AMI محلی

دیگر نیازی به وارد کردن دستی Business ID / PBX ID نیست.

مقدار پیش‌فرض HESABIX_API_URL برابر https://hsxn.hesabix.ir است.

Softphone Media Relay

از نسخهٔ دارای Softphone، Connector علاوه بر AMI یک تونل رسانه خروجی (WSS) به حسابیکس و یک AudioSocket محلی (127.0.0.1:9092) دارد.

نصب خودکار (پیشنهادی)

روی سرور PBX با root:

hesabix-pbx update
hesabix-pbx softphone-setup

softphone-setup این کارها را خودش انجام می‌دهد:

  1. نصب websocket-client (pip)
  2. افزودن کلیدهای Softphone به .env (MEDIA_TUNNEL_ENABLED, AUDIOSOCKET_*)
  3. ری‌استارت سرویس
  4. بررسی آمادگی

از نسخهٔ 1.3.0 به بعد، خودِ hesabix-pbx update هم تلاش می‌کند websocket-client را نصب کند.

نصب دستی (در صورت نیاز)

pip3 install -r /opt/HesabixTelephonyConnector/requirements-softphone.txt
# یا:
pip3 install websocket-client

متغیرهای .env:

AUDIOSOCKET_HOST=127.0.0.1
AUDIOSOCKET_PORT=9092
MEDIA_TUNNEL_ENABLED=1

نمونه دیال‌پلن: dialplan/hesabix-softphone-relay.conf.sample

در حسابیکس: نگاشت کاربر↔داخلی را روی endpoint_mode=relay بگذارید، سپس از صفحه Softphone «آنلاین شدن» را بزنید.

امنیت: همچنان هیچ پورت ورودی روی PBX لازم نیست؛ فقط خروجی HTTPS/WSS به API حسابیکس.

عیب‌یابی: Handshake status 403 Forbidden

اگر AMI و AudioSocket بالا می‌آیند ولی تونل رسانه با 403 قطع می‌شود:

  1. روی خودِ PBX تست کنید (باید 101 Switching Protocols ببینید، نه 403):
python3 - <<'PY'
from websocket import create_connection
url = "wss://hsxn.hesabix.ir/ws/telephony/connector/media"
ws = create_connection(url, timeout=10, suppress_origin=True)
print("OK", ws.connected)
ws.close()
PY
  1. اگر همین تست روی PBX 403 است ولی از جای دیگر OK است → معمولاً WAF آروان IP عمومی سرور PBX را برای Upgrade وب‌سوکت مسدود کرده. IP را در پنل آروان whitelist کنید، یا تونل را به origin مستقیم بزنید:
# در /opt/HesabixTelephonyConnector/.env
HESABIX_MEDIA_WS_URL=wss://YOUR_ORIGIN_HOST/ws/telephony/connector/media
systemctl restart hesabix-telephony-connector
  1. اگر تست OK است ولی سرویس هنوز 403 می‌دهد → hesabix-pbx update و ری‌استارت سرویس.