📞 Simotel Connect (کتابخانه پایتون و جنگو برای سیموتل)

یک پکیج پایتونی و ماژول Reusable Django حرفه‌ای، مقیاس‌پذیر و تمیز برای ارتباط با وب‌سرویس مرکز تلفن سیموتل (Simotel PBX API v4).

---

🌟 ویژگی‌ها

• 🔐 پشتیبانی کامل از احراز هویت دوگانه سیموتل (X-APIKEY به همراه HTTP Basic Auth)
• ⚙️ سیستم کانفیگ انعطاف‌پذیر و سه لایه (Django settings.py > متغیرهای محیطی .env > ورودی مستقیم سازنده)
• 🏗️ طراحی ماژولار با الگوهای Facade و Manager: تمام متدها دسته‌بندی‌شده و خوانا
• 🔄 مکانیزم Retry و Connection Pooling خودکار با Session پایدار
• 🛡️ مدیریت خطای جامع (Exception Handling) با خطاهای اختصاصی
• 📊 پوشش کامل بیش از ۸۰ اندپوینت سیموتل:
  • مدیریت کاربران و داخلی‌ها (users)
  • ترانک‌ها (trunks)
  • صف‌ها و اپراتورها به صورت تک و گروهی (queues, agents)
  • لیست سیاه و سفید (blacklists, whitelists)
  • فایل‌های صوتی و اعلامیه‌ها (announcements)
  • موسیقی انتظار (musiconholds)
  • ارسال، دریافت و دانلود فکس (faxes)
  • برقراری تماس خودکار (Click-to-Call / originate)
  • صندوق‌های صوتی و دانلود پیام (voicemails)
  • گزارشات کامل CDR، صف، اپراتور، نظرسنجی و دانلود فایل صوتی مکالمه تک و دو کاناله (reports)
  • ماژول تماس انبوه و کمپین‌ها (autodialer)
  • بررسی وضعیت اتصال (ping)

---

📦 نصب

نصب در محیط پروژه:

pip install simotel-connect

یا برای توسعه به صورت Editable:

git clone https://github.com/yourusername/simotel-django-app.git
cd simotel-django-app
pip install -e ".[dev]"

---

⚙️ راه‌اندازی و کانفیگ

روش ۱: از طریق Django settings.py (توصیه‌شده برای پروژه‌های جنگو)

در فایل settings.py پروژه جنگو:

# settings.py

INSTALLED_APPS = [
    ...,
    "simotel_connect",
]

SIMOTEL = {
    "HOST": "192.168.1.10",             # آدرس IP یا دامنه سرور سیموتل
    "API_KEY": "YOUR_SIMOTEL_API_KEY",  # از مسیر Maintenance > API Accounts
    "USERNAME": "admin",                # نام کاربری پنل سیموتل
    "PASSWORD": "your_password",        # رمز عبور سیموتل
    "PORT": 80,                         # اختیاری (پیش‌فرض 80)
    "SCHEME": "http",                   # اختیاری (پیش‌فرض http)
    "TIMEOUT": 30,                      # اختیاری (پیش‌فرض 30 ثانیه)
    "VERIFY_SSL": True,                 # اختیاری
}

سپس در هر کجای پروژه (Views, Celery Tasks, Services):

from simotel_connect import Simotel

# به صورت خودکار مقادیر را از settings.py می‌خواند
sm = Simotel()

---

روش ۲: از طریق متغیرهای محیطی (.env)

SIMOTEL_HOST=192.168.1.10
SIMOTEL_API_KEY=YOUR_SIMOTEL_API_KEY
SIMOTEL_USERNAME=admin
SIMOTEL_PASSWORD=your_password
SIMOTEL_TIMEOUT=30

from simotel_connect import Simotel

sm = Simotel()

---

روش ۳: مقداردهی مستقیم (بدون جنگو یا چند سروری)

from simotel_connect import Simotel

sm = Simotel(
    host="192.168.1.10",
    api_key="YOUR_SIMOTEL_API_KEY",
    username="admin",
    password="your_password",
    timeout=15,
)

---

🚀 راهنمای کاربردی و مثال‌ها

۱. تست وضعیت اتصال (Health Check)

response = sm.setting.ping()
if response.success:
    print("اتصال به سیموتل برقرار است:", response.message)

---

۲. برقراری تماس (Click-to-Call / Originate)

ارسال درخواست تماس به صورت متد POST به اندپوینت /call/originate/act:

# تماس بین یک داخلی و شماره موبایل
resp = sm.call.originate(
    caller="1001",
    callee="09121234567",
    context="default",
    caller_id="1001",
    timeout=30,
)

# تماس بین دو داخلی
resp = sm.call.originate(
    caller="1001",
    callee="1002",
    context="default",
)

---

۳. مدیریت کاربران و داخلی‌ها (Users)

# افزودن داخلی جدید
sm.pbx.users.add(
    extension="1001",
    name="علی رضایی",
    password="StrongPassword123",
    email="ali@example.com",
    mobile="09121234567"
)

# جستجوی کاربران
users = sm.pbx.users.search(extension="1001")
print(users.data)

# ویرایش کاربر
sm.pbx.users.update(extension="1001", name="علی رضایی (پشتیبانی)")

# حذف کاربر
sm.pbx.users.remove(extension="1001")

---

۴. مدیریت صف‌ها و اپراتورها (Queues)

# ایجاد صف جدید
sm.pbx.queues.add(name="2000", strategy="leastrecent", timeout=30)

# افزودن اپراتور به صف
sm.pbx.queues.add_agent(queue="2000", agent="1001", penalty=0)

# شروع استراحت اپراتور (Pause)
sm.pbx.queues.pause_agent(queue="2000", agent="1001", reason="استراحت ناهار")

# پایان استراحت اپراتور (Resume)
sm.pbx.queues.resume_agent(queue="2000", agent="1001")

# افزودن دسته‌ای اپراتورها
sm.pbx.queues.batch_add_agent(queue="2000", agents=["1001", "1002", "1003"])

# توقف دسته‌ای اپراتورها
sm.pbx.queues.batch_pause_agent(queue="2000", agents=["1001", "1002"])

# خروج اپراتور از صف
sm.pbx.queues.remove_agent(queue="2000", agent="1001")

---

۵. گزارشات و دانلود صوت مکالمات (Reports)

# گزارش CDR تماس‌ها در بازه زمانی
cdr = sm.reports.cdr_search(
    from_date="2024-01-01 08:00:00",
    to_date="2024-01-31 18:00:00",
    limit=50
)
for call in cdr.data:
    print(call)

# گزارش صف‌ها
queue_report = sm.reports.queue_search(queue="2000")

# گزارش عملکرد اپراتورها
agent_report = sm.reports.agent_search(agent="1001")

# دانلود فایل صوتی مکالمه ضبط‌شده
audio_bytes = sm.reports.download_audio(call_id="unique_call_id_123")
with open("recorded_call.wav", "wb") as f:
    f.write(audio_bytes)

# دانلود مکالمه دو کاناله (کانال اپراتور و مشتری مجزا)
dual_audio = sm.reports.download_audio_dual_channel(call_id="unique_call_id_123")
with open("dual_call.wav", "wb") as f:
    f.write(dual_audio)

---

۶. لیست سیاه و سفید (Blacklist & Whitelist)

# مسدود کردن شماره مزاحم
sm.pbx.blacklists.add(number="09999999999", description="مزاحم تلفنی")

# رفع مسدودیت
sm.pbx.blacklists.remove(number="09999999999")

# افزودن به لیست سفید (مشتری VIP)
sm.pbx.whitelists.add(number="09120000000", description="مدیرعامل")

---

۷. تماس خودکار و کمپین‌ها (Autodialer)

# آپلود فایل صوتی کمپین
sm.autodialer.announcements.upload(
    file_path="/path/to/promo.wav",
    name="جشنواره_نوروزی"
)

# ایجاد گروه مخاطبین
sm.autodialer.groups.add(name="مشتریان_ویژه")

# افزودن مخاطب به گروه
sm.autodialer.contacts.add(
    number="09121234567",
    name="محمد محمدی",
    group="مشتریان_ویژه"
)

# ایجاد کمپین تماس انبوه
sm.autodialer.campaigns.add(
    name="کمپین عیدانه",
    announcement="جشنواره_نوروزی",
    group="مشتریان_ویژه",
    trunk="main_trunk"
)

# مشاهده گزارشات کمپین
reports = sm.autodialer.reports.search(campaign="کمپین عیدانه")

---

⚠️ مدیریت خطاها (Exception Handling)

تمام خطاهای پکیج از SimotelError ارث‌بری دارند:

from simotel_connect import (
    Simotel,
    SimotelError,
    SimotelAuthError,
    SimotelAPIError,
    SimotelConnectionError,
    SimotelTimeoutError,
)

sm = Simotel()

try:
    sm.call.originate(src_type="internal", src_number="1001", dst_type="internal", dst_number="1002")
except SimotelAuthError:
    print("خطا در نام کاربری، رمز عبور یا API Key سیموتل")
except SimotelAPIError as e:
    print(f"سیموتل با پیام خطا پاسخ داد: {e.args[0]}")
    print(f"اطلاعات خطا: {e.data}")
except SimotelConnectionError:
    print("ارتباط با سرور سیموتل برقرار نشد (بررسی شبکه یا IP)")
except SimotelTimeoutError:
    print("درخواست با تایم‌اوت مواجه شد")
except SimotelError as e:
    print(f"خطای نامشخص سیموتل: {e}")

---

🧪 اجرای تست‌ها

pip install -e ".[dev]"
pytest simotel_connect/tests/ -v

---

📄 لایسنس

این پروژه تحت مجوز MIT منتشر شده است.