SparkTG

توثيق تحديث وكيل (v2)

تحديث وكيل (v2)

v2

تحديث وكيل (v2)

تسجيل الدخول والخروج والاستراحات وتعديلات الملف الشخصي

API v2v2نقطة نهاية 1

نظرة عامة

سجّل دخول وكيل أو خروجه، أو ضعه في استراحة، أو غيّر رقم هاتفه أو رمز الدولة أو اسم العرض. يحل هذا محل PATCH /api/v1/agents. حدّد الوكيل بواحد فقط من agent_number أو agent_sip، ثم أرسل حقلًا واحدًا على الأقل لتغييره؛ لا تُمَس الحقول التي تتركها. النص (body) بصيغة JSON، وأي حقل غير مدرج أدناه يُرفض برمز 400. تُرفض القيمة null والسلاسل الفارغة؛ فهذه النقطة لا تمسح أي شيء. تُحتسب كل مكالمة ناجحة مرة واحدة.

نقاط النهاية المتاحة

PUT/api/v2/agents

المعاملات الرئيسية

agent_number(String)

رقم هاتف الوكيل الحالي. أرسل هذا الحقل أو agent_sip، وليس كليهما.

agent_sip(String)

امتداد SIP الخاص بالوكيل. أرسل هذا الحقل أو agent_number، وليس كليهما.

status(Integer)

القيمة 0 تسجّل دخول الوكيل (متاح). والقيمة 2 تسجّل خروجه (غير متصل) أو، مع break_id، تضعه في تلك الاستراحة. لا تُقبل قيم أخرى.

break_id(Integer)

الاستراحة التي يوضع فيها الوكيل. يجب أن تكون استراحة مفعّلة لخدمتك. إرسال break_id يعني ضمنًا الحالة 2، ولا يمكن الجمع بينه وبين الحالة 0. مع الحالة 2 ودون break_id تُستخدم الاستراحة الافتراضية 7 (غير متصل) التي تسجّل خروج الوكيل.

number(String)

رقم الهاتف الجديد: من 4 إلى 15 رقمًا، دون + أو مسافات أو شرطات. يجب ألا يخص وكيلًا آخر في الخدمة. لا يمكن تغييره أثناء مكالمة الوكيل.

country_code(String)

من 1 إلى 4 أرقام دون +، ولا تبدأ بالرقم 0، مثل 91 أو 971.

سيناريوهات الاستخدام

تسجيل دخول وكيل

اضبط status على 0. يصبح الوكيل متاحًا ويبدأ باستلام المكالمات من قوائم الانتظار الخاصة به. وهذا يعيد الوكيل أيضًا من أي استراحة.

0 معاملمتاح في الأمثلة

تسجيل خروج وكيل

اضبط status على 2 دون break_id. يصبح الوكيل غير متصل (الاستراحة 7) ويتوقف عن استلام المكالمات. إرسال الحالة 2 مع break_id بقيمة 7 يؤدي إلى النتيجة نفسها.

0 معاملمتاح في الأمثلة

وضع وكيل في استراحة

أرسل break_id؛ والحالة 2 مفهومة ضمنًا. يتوقف الوكيل عن استلام المكالمات حتى يُسجَّل دخوله مجددًا. هنا يُحدَّد الوكيل برقم الهاتف بدلًا من امتداد SIP.

0 معاملمتاح في الأمثلة

الانتقال من استراحة إلى أخرى

لا يمكن للوكيل الانتقال مباشرة من استراحة إلى أخرى؛ هذه المكالمة تُرجع 409. سجّل دخوله أولًا (الحالة 0)، ثم أرسل break_id الجديد. يمكن إعادة محاولة المكالمتين بأمان.

0 معاملمتاح في الأمثلة

تحديث بيانات الملف الشخصي

غيّر الاسم ورقم الهاتف ورمز الدولة معًا. يمكن إرسال حقول الملف الشخصي في المكالمة نفسها مع status أو break_id، لكن لا يمكن تغيير الرقم أثناء مكالمة الوكيل.

0 معاملمتاح في الأمثلة

مثال سريع

جرّب هذه الواجهة بأمر cURL بسيط

استدعاء API أساسي
curl -X PUT 'https://telephonycloud.co.in/api/v2/agents' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"agent_sip": "10114", "status": 0}'
💡 استبدل <YOUR_TOKEN> برمز API الخاص بك

معاينة الاستجابة

استجابة نموذجية من هذه الواجهة

استجابة نموذجية
{"status":"success","changed":["status","break_id"],"agent":{"id":735,"name":"Priya Sharma","number":"9876500000","country_code":"91","sip":"10114","status":2,"break_id":3}}
عرض صيغة الاستجابة الكاملة في قسم الاستجابة