وضعیت اپراتورها

وضعیت و تاریخچهٔ اپراتورها

وب‌سرویس وضعیت و تاریخچهٔ اپراتورها، وضعیت فعلی اپراتورها و یک Timeline یکپارچه از تغییر وضعیت‌ها و رویدادهای تماس را در اختیار سامانهٔ شما قرار می‌دهد. با این API می‌توانید حضور اپراتورها، مشغول‌بودن آن‌ها و رخدادهای تماس را در CRM یا داشبورد اختصاصی نمایش دهید.

اطلاعات پایه

نشانی Production:

https://panel.telefonchy.com

هدر الزامی همهٔ درخواست‌ها:

webservice-token: YOUR_WEBSERVICE_TOKEN

نکته مهم: پارامتر service_id در همهٔ مسیرها الزامی است و باید متعلق به صاحب همان توکن باشد.

دریافت وضعیت همهٔ اپراتورها

GET /webservice/v1/operators/status?service_id=SERVICE_ID

curl \
  --header "webservice-token: YOUR_WEBSERVICE_TOKEN" \
  "https://panel.telefonchy.com/webservice/v1/operators/status?service_id=SERVICE_ID"

فقط اپراتورهای فعال سرویس در data.items برگردانده می‌شوند.

دریافت وضعیت یک اپراتور

برای محدودکردن پاسخ به یک داخلی مشخص، پارامتر exten را ارسال کنید:

GET /webservice/v1/operators/status?service_id=SERVICE_ID&exten=201

curl \
  --header "webservice-token: YOUR_WEBSERVICE_TOKEN" \
  "https://panel.telefonchy.com/webservice/v1/operators/status?service_id=SERVICE_ID&exten=201"

اگر exten به سرویس انتخاب‌شده تعلق نداشته باشد، پاسخ 404 برگردانده می‌شود.

ساختار پاسخ وضعیت

{
  "status": "Ok",
  "code": 200,
  "message": null,
  "data": {
    "service_id": "SERVICE_ID",
    "items": [
      {
        "exten": "201",
        "name": "اپراتور فروش",
        "state": "Idle",
        "state_label": "آنلاین",
        "is_online": true,
        "stated_at": "2026-09-07T10:20:00+00:00",
        "jalali_stated_at": "1405-06-16 13:50:00"
      }
    ]
  }
}

وضعیت‌های اپراتور

فقط وضعیت Unavailable آفلاین است. اگر وضعیت ذخیره‌شده ناشناخته باشد، API مقدار Unknown و is_online=false را برمی‌گرداند.

فیلد stated_at زمان استاندارد ISO-8601 آخرین تغییر وضعیت و jalali_stated_at معادل جلالی آن است.

دریافت Timeline اپراتورها

GET /webservice/v1/operators/events?service_id=SERVICE_ID

این مسیر دو نوع داده را با ترتیب زمانی نزولی ترکیب می‌کند:

• source=presence: تغییر وضعیت اپراتور

• source=call: رویدادهای تماس ذخیره‌شده در CDR

پارامترهای Timeline

حداکثر بازهٔ زمانی قابل درخواست ۹۰ روز است.

نمونهٔ دریافت Timeline

curl --get \
  --header "webservice-token: YOUR_WEBSERVICE_TOKEN" \
  --data-urlencode "service_id=SERVICE_ID" \
  --data-urlencode "exten=201" \
  --data-urlencode "source=all" \
  --data-urlencode "state=Idle,InUse,Unavailable" \
  --data-urlencode "from=2026-09-01T00:00:00+03:30" \
  --data-urlencode "to=2026-09-07T23:59:59+03:30" \
  --data-urlencode "limit=50" \
  "https://panel.telefonchy.com/webservice/v1/operators/events"

صفحه‌بندی با Cursor

اگر مقدار has_more برابر true بود، فیلترهای درخواست قبلی را بدون تغییر و همراه next_cursor ارسال کنید.

curl --get \
  --header "webservice-token: YOUR_WEBSERVICE_TOKEN" \
  --data-urlencode "service_id=SERVICE_ID" \
  --data-urlencode "exten=201" \
  --data-urlencode "source=all" \
  --data-urlencode "limit=50" \
  --data-urlencode "cursor=OPAQUE_CURSOR" \
  "https://panel.telefonchy.com/webservice/v1/operators/events"

cursor را Decode یا تغییر ندهید. برای جلوگیری از تکرار یا حذف نتیجه، همهٔ فیلترهای صفحهٔ قبل را ثابت نگه دارید.

پاسخ ناقص هنگام قطعی CDR

اگر CDR موقتاً در دسترس نباشد، تاریخچهٔ presence پنهان نمی‌شود؛ اما پاسخ به‌شکل ناقص علامت‌گذاری می‌شود:

{
  "partial": true,
  "has_more": false,
  "next_cursor": null,
  "warnings": [
    "call_events_unavailable"
  ]
}

در این وضعیت فقط داده‌های موجود قابل اتکا هستند. پس از بازیابی CDR، همان صفحه را دوباره درخواست کنید.

نگه‌داری تاریخچه

• وضعیت فعلی و رکورد تغییر وضعیت در یک تراکنش ثبت می‌شوند.

• اگر وضعیت جدید با وضعیت قبلی یکسان باشد، تاریخچهٔ جدید ساخته نمی‌شود.

• تاریخچهٔ presence فقط از زمان فعال‌سازی قابلیت موجود است و دادهٔ گذشته به‌صورت تخمینی تکمیل نمی‌شود.

• رکوردهای بیش از ۹۰ روز به‌صورت روزانه حذف می‌شوند.

محدودیت درخواست

دو مسیر GET وضعیت و Timeline از remains کم نمی‌کنند. برای هر توکن و هر مسیر، حداکثر ۶۰ درخواست در دقیقه مجاز است.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42

در صورت عبور از سقف درخواست:

HTTP/1.1 429 Too Many Requests
Retry-After: 24

خطاهای رایج

بهترین روش استفاده

• توکن وب‌سرویس را فقط در Backend نگه‌داری کنید.

• برای نمایش زنده، وضعیت فعلی را با فاصلهٔ زمانی منطقی دریافت کنید.

• برای Timeline از cursor استفاده کرده و فیلترها را بین صفحه‌ها ثابت نگه دارید.

• زمان رخداد را با occurred_at پردازش و jalali_datetime را برای نمایش فارسی استفاده کنید.

• در پاسخ partial، وضعیت CDR را بررسی کرده و درخواست را بعداً تکرار کنید.