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

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

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

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

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

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

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

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

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

• Python 3
• rsync
• curl
• git

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

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

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

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

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

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

نصب روی سرور تلفن انجام می‌شود (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 برابر 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

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

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

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

/opt/HesabixTelephonyConnector/.env

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

hesabix-pbx test

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

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

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

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

hesabix-pbx status

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

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

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

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

hesabix-pbx update

این دستور:

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

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

hesabix-pbx status
hesabix-pbx test

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

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 دارد

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

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

با کاربر 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. 1. در حسابیکس توکن جدید بسازید
   2. روی سرور: hesabix-pbx configure
   3. سپس: hesabix-pbx restart

hesabix-pbx uninstall

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

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

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

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

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

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