پرش به محتوا

راهنمای اتصال مرکز تلفن ایزابل و استریکس به حسابیکس

از ویکی حسابیکس

راهنمای اتصال مرکز تلفن به حسابیکس (Hesabix Telephony Connector)

این راهنما برای مدیران سیستم، مدیران تلفن و کاربران نهایی نوشته شده است. هدف آن توضیح سادهٔ نصب، پیکربندی و استفاده از کانکتور تلفنی حسابیکس روی سرور Issabel یا Asterisk است.

این راهنما برای توسعه‌دهندگان نیست.

کانکتور چیست و چه کاری انجام می‌دهد؟

Hesabix Telephony Connector یک برنامهٔ سبک است که روی سرور تلفن شما (Issabel/Asterisk) نصب می‌شود و آن را به حسابیکس وصل می‌کند.

بدون کانکتور

  • حسابیکس نمی‌تواند تماس‌های ورودی/خروجی را ببیند
  • Screen Pop، Click-to-Call و تاریخچه تماس کار نمی‌کند
  • وضعیت مرکز تلفن در حسابیکس «آفلاین» می‌ماند

با کانکتور

  • رویدادهای تماس از Asterisk به حسابیکس ارسال می‌شود
  • حسابیکس می‌تواند دستور تماس (مثل برقراری تماس خروجی) را به سرور تلفن بفرستد
  • اپراتورها در وب، موبایل و دسکتاپ می‌توانند:
    • هنگام زنگ خوردن، اطلاعات تماس‌گیرنده را ببینند (Screen Pop)
    • از روی پروفایل مشتری تماس خروجی بگیرند (Click-to-Call)
    • تاریخچه تماس را ببینند
    • وضعیت آنلاین/آفلاین مرکز تلفن را مشاهده کنند

نکته مهم درباره معماری

کانکتور روی سرور تلفن شما نصب می‌شود، نه روی سرور حسابیکس.

نمای ساده اتصال
کاربر (اپراتور) ← → حسابیکس (ابر/سرور شما)
کانکتور ← → Issabel / Asterisk (سرور تلفن)

کانکتور فقط از سرور تلفن به سمت حسابیکس خروجی HTTPS می‌زند؛ معمولاً نیازی به باز کردن پورت ورودی روی فایروال سرور تلفن نیست.

پیش‌نیازها

سخت‌افزار و شبکه

  • یک سرور Issabel یا Asterisk فعال
  • دسترسی root به سرور تلفن (با یا بدون دستور sudo)
  • اتصال اینترنت از سرور تلفن به آدرس API حسابیکس (پورت ۴۴۳ / HTTPS)
  • Asterisk AMI فعال (پورت پیش‌فرض: ۵۰۳۸)

نرم‌افزار

اسکریپت نصب در صورت نبود، این موارد را خودکار نصب می‌کند:

  • Python 3
  • rsync
  • curl
  • git

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

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

دسترسی‌های لازم در حسابیکس

قبل از نصب کانکتور، در پنل حسابیکس این کارها انجام شود:

  1. افزونه تلفنی / Telephony برای کسب‌وکار فعال باشد
  2. یک مرکز تلفن (PBX) ساخته شود
  3. توکن Connector از تنظیمات مرکز تلفن کپی شود
  4. (در صورت نیاز) شناسه کسب‌وکار و شناسه مرکز تلفن یادداشت شود

آماده‌سازی در حسابیکس (قبل از نصب)

گام ۱: فعال‌سازی افزونه

  1. وارد حسابیکس شوید
  2. به بخش مارکت‌پلیس / افزونه‌ها بروید
  3. افزونه تلفنی (Telephony) را برای کسب‌وکار خود فعال کنید

گام ۲: ساخت مرکز تلفن

  1. به بخش مرکز تلفن / Telephony بروید
  2. یک مرکز تلفن جدید بسازید (نام، توضیحات و …)
  3. نوع اتصال: Issabel / Asterisk (یا معادل آن در رابط کاربری)

گام ۳: دریافت اطلاعات اتصال

از صفحهٔ تنظیمات مرکز تلفن این موارد را یادداشت کنید:

مورد توضیح مثال
آدرس API حسابیکس آدرس سرویس حسابیکس شما https://hsxn.hesabix.ir
شناسه کسب‌وکار (Business ID) عدد شناسه کسب‌وکار 12
شناسه مرکز تلفن (PBX ID) عدد شناسه مرکز تلفن 3
توکن Connector رشتهٔ امن اتصال hsx_tel_...

هشدار امنیتی: توکن را مثل رمز عبور نگه دارید. در اختیار کسی قرار ندهید.

نصب کانکتور

نصب روی سرور تلفن انجام می‌شود (SSH به Issabel/Asterisk).

روش پیشنهادی: نصب یک‌خطی

اگر سیستم شما 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 هنگام نصب

پیش‌فرض آدرس 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 یا Issabel/CentOS/RHEL)
  2. نصب پیش‌نیازها در صورت نیاز
  3. دانلود کانکتور از مخزن حسابیکس
  4. نصب دستور hesabix-pbx در سیستم
  5. اجرای ویزارد پیکربندی
  6. ثبت و فعال‌سازی سرویس systemd

مسیر نصب پیش‌فرض

/opt/HesabixTelephonyConnector

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

بعد از نصب، ویزارد از شما می‌پرسد:

سؤال توضیح پیش‌فرض
آدرس API حسابیکس آدرس سرویس حسابیکس https://hsxn.hesabix.ir
شناسه کسب‌وکار Business ID از حسابیکس —
شناسه مرکز تلفن PBX ID از حسابیکس —
توکن Connector از تنظیمات مرکز تلفن —
آدرس AMI معمولاً همان سرور محلی 127.0.0.1
پورت AMI پورت Asterisk Manager 5038
کاربر AMI نام کاربری AMI hesabix
رمز AMI رمز کاربر AMI —
ساخت کاربر AMI؟ آیا کانکتور کاربر را در manager.conf بسازد؟ معمولاً N مگر مطمئن نباشید

نکته: اگر Issabel از قبل کاربر AMI دارد، همان را وارد کنید. در غیر این صورت می‌توانید با پاسخ y اجازه دهید کانکتور کاربر را بسازد.

پیکربندی در این فایل ذخیره می‌شود:

/opt/HesabixTelephonyConnector/.env

تست اتصال

بعد از نصب، حتماً تست کنید:

hesabix-pbx test

این دستور دو تست انجام می‌دهد:

  1. تست AMI — اتصال به Asterisk و ورود با کاربر AMI
  2. تست Heartbeat حسابیکس — ارسال سیگنال زنده به API حسابیکس

اگر هر دو موفق باشند، در حسابیکس وضعیت مرکز تلفن باید آنلاین (Online) شود.

برای مشاهده وضعیت کلی:

hesabix-pbx status

دستورات روزمره (CLI)

همهٔ دستورات زیر روی سرور تلفن و با دسترسی root اجرا می‌شوند.

دستور کاربرد
hesabix-pbx status نمایش وضعیت سرویس، سیستم‌عامل، API، AMI و …
hesabix-pbx test تست AMI و اتصال به حسابیکس
hesabix-pbx configure تغییر توکن، آدرس API، تنظیمات AMI
hesabix-pbx start شروع سرویس کانکتور
hesabix-pbx stop توقف سرویس
hesabix-pbx restart ری‌استارت سرویس
hesabix-pbx update به‌روزرسانی کانکتور از مخزن حسابیکس
hesabix-pbx reinstall نصب مجدد (فایل .env حفظ می‌شود)
hesabix-pbx logs مشاهده آخرین لاگ‌ها (پیش‌فرض ۸۰ خط)
hesabix-pbx logs 200 مشاهده ۲۰۰ خط آخر لاگ
hesabix-pbx follow مشاهده زندهٔ لاگ (مثل tail -f)
hesabix-pbx uninstall حذف سرویس و دستور CLI
hesabix-pbx help نمایش راهنمای دستورات

مثال: اجرا با sudo

sudo hesabix-pbx status
sudo hesabix-pbx test
sudo hesabix-pbx update

مثال: اجرا بدون sudo (کاربر root)

hesabix-pbx status
hesabix-pbx test
hesabix-pbx update

به‌روزرسانی کانکتور

برای دریافت آخرین نسخه:

hesabix-pbx update

این دستور:

  • پیش‌نیازها را بررسی می‌کند
  • فایل‌های جدید را دانلود می‌کند
  • سرویس را ری‌استارت می‌کند
  • فایل .env شما را حفظ می‌کند

بعد از به‌روزرسانی:

hesabix-pbx status
hesabix-pbx test

تغییر تنظیمات بعد از نصب

تغییر توکن، API یا AMI

hesabix-pbx configure
hesabix-pbx restart
hesabix-pbx test

موارد رایج تغییر

  • توکن جدید بعد از لو رفتن توکن قبلی
  • آدرس API بعد از تغییر دامنه حسابیکس
  • رمز AMI بعد از تغییر در Asterisk

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

اگر ترجیح می‌دهید فایل را مستقیم ویرایش کنید:

cp /opt/HesabixTelephonyConnector/config.example.env /opt/HesabixTelephonyConnector/.env
nano /opt/HesabixTelephonyConnector/.env
hesabix-pbx restart
hesabix-pbx test

نمونه محتوای فایل .env

HESABIX_API_URL=https://hsxn.hesabix.ir
HESABIX_BUSINESS_ID=1
HESABIX_PBX_ID=1
HESABIX_CONNECTOR_TOKEN=hsx_tel_replace_me
AMI_HOST=127.0.0.1
AMI_PORT=5038
AMI_USER=hesabix
AMI_SECRET=change_me

کاربرد برای کاربران حسابیکس

بعد از اتصال موفق، این امکانات (بسته به فعال بودن افزونه و دسترسی کاربر) در دسترس است:

برای اپراتور (فروش / پشتیبانی)

  • Screen Pop: هنگام زنگ خوردن، نام مشتری، مانده حساب و اطلاعات مرتبط نمایش داده می‌شود
  • Click-to-Call: از پروفایل مشتری می‌توان تماس خروجی گرفت
  • تاریخچه تماس: مشاهده تماس‌های قبلی هر مشتری
  • ثبت نتیجه تماس: یادداشت و پیگیری بعد از مکالمه

برای مدیر تلفن

  • مشاهده وضعیت آنلاین/آفلاین مرکز تلفن
  • نگاشت کاربر حسابیکس ↔ داخلی تلفن
  • تنظیمات شناسایی شماره و رفتار Screen Pop

برای مدیر سیستم

  • مانیتورینگ اتصال از طریق hesabix-pbx status
  • بررسی لاگ‌ها با hesabix-pbx logs
  • به‌روزرسانی و نگهداری با hesabix-pbx update

عیب‌یابی (مشکلات رایج)

۱. مرکز تلفن در حسابیکس آفلاین است

  1. روی سرور تلفن: hesabix-pbx status
  2. تست اتصال: hesabix-pbx test
  3. بررسی لاگ: hesabix-pbx logs
  4. مطمئن شوید توکن، Business ID و PBX ID درست است
  5. مطمئن شوید سرور تلفن به آدرس API دسترسی HTTPS دارد

۲. تست AMI ناموفق است

  • Asterisk در حال اجرا باشد
  • پورت AMI (معمولاً ۵۰۳۸) باز باشد — فقط روی localhost کافی است
  • کاربر و رمز AMI درست باشد
  • در صورت نیاز: asterisk -rx "manager reload"

۳. تست API حسابیکس ناموفق است

  • آدرس HESABIX_API_URL را بررسی کنید (بدون اسلش اضافه در انتها)
  • DNS و فایروال سرور تلفن را بررسی کنید
  • توکن را در حسابیکس تجدید کنید و با hesabix-pbx configure وارد کنید

۴. دستور sudo شناخته نمی‌شود

با کاربر root وارد شوید و دستور را بدون sudo اجرا کنید:

hesabix-pbx status

۵. بعد از به‌روزرسانی مشکل پیش آمد

hesabix-pbx reinstall
hesabix-pbx test

۶. سرویس اجرا نمی‌شود

hesabix-pbx status
hesabix-pbx logs
systemctl status hesabix-telephony-connector

نکات امنیتی

  • کانکتور فقط به حسابیکس خروجی HTTPS می‌زند — نیازی به باز کردن پورت ورودی روی اینترنت نیست
  • پورت AMI (۵۰۳۸) را به اینترنت باز نکنید — فقط localhost یا شبکه داخلی
  • فایل .env حاوی توکن و رمز AMI است؛ مجوز آن 600 است
  • اگر توکن لو رفت:
    1. در حسابیکس توکن جدید بسازید
    2. روی سرور: hesabix-pbx configure
    3. سپس: hesabix-pbx restart

حذف کانکتور

hesabix-pbx uninstall

در پایان از شما پرسیده می‌شود آیا فایل .env نگه داشته شود یا نه.

  • نگه داشتن .env — برای نصب مجدد بعدی مفید است
  • حذف کامل — همهٔ فایل‌ها پاک می‌شود

سوالات متداول (FAQ)

آیا کانکتور روی سرور حسابیکس نصب می‌شود؟

خیر. روی سرور Issabel/Asterisk نصب می‌شود.

آیا باید پورت جدیدی روی فایروال باز کنم؟

معمولاً خیر. فقط خروجی HTTPS به حسابیکس لازم است.

آیا با FreePBX هم کار می‌کند؟

اگر Asterisk AMI استاندارد داشته باشد، معمولاً بله. تمرکز رسمی روی Issabel است.

آدرس پیش‌فرض API چیست؟

https://hsxn.hesabix.ir

چطور بفهمم همه‌چیز درست کار می‌کند؟

  1. hesabix-pbx test هر دو تست را پاس کند
  2. در حسابیکس وضعیت مرکز تلفن «آنلاین» باشد
  3. یک تماس تست بگیرید و Screen Pop را در حسابیکس ببینید

خلاصه دستورات پرکاربرد

# نصب (یک‌خطی)
curl -fsSL https://source.hesabix.ir/hesabix/arc/raw/branch/master/extraScripts/HesabixTelephonyConnector/install.sh | bash

# وضعیت و تست
hesabix-pbx status
hesabix-pbx test

# تغییر تنظیمات
hesabix-pbx configure
hesabix-pbx restart

# به‌روزرسانی
hesabix-pbx update

# لاگ
hesabix-pbx logs
hesabix-pbx follow
برگرفته از «https://wiki.hesabix.ir/index.php?title=راهنمای_اتصال_مرکز_تلفن_ایزابل_و_استریکس_به_حسابیکس&oldid=52»