انتقل إلى المحتوى
MagizAI

للمطورين

ابنِ على MagizAI

أربع واجهات HTTP، لكل منها رمز وصول خاص بها. كل نقطة نهاية هنا مأخوذة من الشيفرة التي تخدمها، لذا أسماء الحقول في هذه الصفحة هي نفسها التي تصلك في الاستجابة.

العنوان الأساسيhttps://magiz.ai

البداية

كل الواجهات تتحدث JSON عبر HTTPS وتتوقع ترويسة Accept: application/json. أرسل رمزك في ترويسة Authorization، واقرأ رمز الحالة قبل المحتوى: الطلب المرفوض يحمل دائمًا حقل message يشرح السبب.

  • JSON فقط

    الطلبات والاستجابات بصيغة JSON. الاستثناء الوحيد هو نقطة البث في الأداة، التي تُرجع أحداث Server-Sent Events.

  • محصورة بمساحة العمل

    لا يصل الرمز إلا إلى مساحة العمل التي أُنشئ فيها. وطلب روبوت أو محادثة تخص حسابًا آخر يُرجع 404، ولا يُرجع بيانات مساحة عمل أخرى أبدًا.

  • بلا حالة

    لا كوكيز ولا رمز CSRF ولا جلسة. كل طلب يحمل بيانات اعتماده، لذا يعمل النداء نفسه من خادم أو تطبيق هاتف أو مهمة مجدولة.

curl https://magiz.ai/api/v1/me \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

المصادقة

الرموز هي رموز Bearer. كل رمز يحمل صلاحية تحدد الواجهة التي يفتحها، ويجري التحقق من هذه الصلاحية مع كل طلب.

Authorization: Bearer <token>
Accept: application/json

  • رمز REST API

    يُنشأ من لوحة التحكم في الإعدادات، ضمن لوحة Rest API tokens. سمِّه وانسخ قيمته مرة واحدة (تُعرض حينها فقط)، واستخدمه مع نقاط v1. يمكن للحساب الاحتفاظ بعشرين رمزًا كحد أقصى، وإلغاء أي رمز يسري فورًا.

    ability: api

  • رمز البوابة

    يُنشأ بإرسال بريد وكلمة مرور لوحة التحكم إلى نقطة دخول البوابة. لا يحصل عليه إلا مالك أو مسؤول مساحة عمل مفعّلة فيها البوابة بالعلامة البيضاء.

    ability: portal

  • رمز تطبيق الموظف

    يُنشأ بإرسال بريد وكلمة مرور إلى نقطة دخول تطبيق الموظف. يستطيع المالك والمسؤول والموظف تسجيل الدخول، أما مقعد المشاهدة للقراءة فقط فيُرفض. وتقوم التطبيقات بتجديد الرمز قبل انتهائه.

    ability: agent

  • نقاط الأداة

    بلا رمز إطلاقًا. المفتاح العام للروبوت موجود في الرابط، ويثبت الزائر ملكيته للمحادثة بإرسال معرّف الزائر نفسه الذي فتحها.

أنواع الرموز غير متبادلة. الرمز المُنشأ من شاشة الإعدادات يفتح نقاط v1 فقط: إن أرسلته إلى مسار portal أو agent فستحصل على 403، لأن تلك المسارات تتطلب صلاحيتي portal وagent وهما غير موجودتين في رمز الإعدادات. رموز البوابة وتطبيق الموظف تأتي من نقاط الدخول الخاصة بها.
كل رمز ينتهي بعد ثلاثين يومًا من إصداره. تطبيقات الموظفين تجدد رمزها عبر نقطة refresh، أما التكامل من الخادم فأنشئ له رمزًا بديلًا قبل انتهاء القديم.

الأخطاء

الطلب الفاشل يُرجع رمز الحالة المناسب مع محتوى JSON. وأخطاء التحقق تتبع شكل Laravel: رسالة مقروءة message مع كائن errors مفهرس بأسماء الحقول.

{
  "message": "The message field is required.",
  "errors": {
    "message": ["The message field is required."]
  }
}
الحالةسبب حدوثه
401الرمز مفقود أو تالف أو منتهٍ أو ملغى.
403الرمز صالح لكنه غير مسموح هنا: صلاحية خاطئة لهذه الواجهة، أو دور لا يملك الإذن، أو حساب أو مساحة عمل موقوفة.
404السجل غير موجود، أو يخص مساحة عمل أخرى. الحالتان غير متمايزتين عن قصد.
409الطلب يتعارض مع الحالة الراهنة، كدعوة زائر غادر الموقع بالفعل.
422فشل التحقق، أو رفضت قاعدة عمل الطلب. اقرأ كائن errors لتعرف الحقل والسبب.
429تم بلوغ حد المعدل أو قفل الحساب. انتظر عدد الثواني المذكور في ترويسة Retry-After.
500حدث خلل لدينا. لم يكتمل الإجراء.
502تعذر الوصول إلى مزود الذكاء الاصطناعي. تحقق من المفتاح المهيأ لمساحة العمل.
503إمكانية غير مهيأة على هذا الخادم، مثل الإشعارات الفورية بلا مفاتيح VAPID.

حدود المعدل

الحدود مضبوطة لكل مسار، وكل نقطة نهاية أدناه تذكر حدها. في المسارات المصادَقة يُحتسب لكل مستخدم مسجّل، وفي المسارات العامة لكل عنوان IP.

الاستجابة المحدودة تحمل الترويسات المعتادة، فيخبرك الرفض بالضبط كم عليك الانتظار.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
Retry-After: 41

نقاط النهاية الموسومة بـ«بلا حد على المسار» ليس لها حد خاص بها. لكنها تظل مقيدة بحصة الرسائل الشهرية في خطتك، فاستعلم عنها بفاصل زمني معقول لا في حلقة متلاحقة.

الأداة على موقعك

سطر واحد من كود التضمين يضع المساعد في كل صفحة. وكل ما يلي اختياري: الأداة تعمل بالمفتاح وحده.

<script src="https://magiz.ai/widget.js" data-key="cv_9f2a4c7e1b6d3a8f5c0e2b4d" defer></script>

خصائص وسم السكربت

المعاملالوصف
data-keyإلزامي. المفتاح العام لروبوتك، من قسم الروبوتات ثم التثبيت.
data-open="load"يفتح نافذة المحادثة فور تحميل الصفحة. استخدمه في صفحة غرضها كله هو المساعد، مثل صفحة الدردشة مع الذكاء الاصطناعي، واتركه في بقية الصفحات.
data-launcherيفرض شكل زر الفتح في هذه الصفحة متجاوزًا إعداد لوحة التحكم. القيم المقبولة: bubble أو teaser. مفيد حين يغطي الشكل الموسّع حقول نموذج.
data-identityرمز هوية موقَّع للشخص الذي يتصفح الصفحة. انظر أدناه.
data-cookie-domainنطاق الكوكي الذي يحفظ المحادثة عبر النطاقات الفرعية، مثل ‎.example.com. لا يلزم إلا حين يكون للنطاق لاحقة مركّبة مثل ‎.co.uk ويخطئ التخمين التلقائي.
data-langلغة نصوص نافذة الدردشة واتجاهها، لزوار يقرؤون لغة غير لغة الصفحة: en أو fr أو ar. ومن دونه تتبع النافذة لغة الصفحة ثم لغة المتصفح.
data-consent="wait"اضبطها على wait حين يتولى شريط ملفات تعريف الارتباط القرار. فإلى أن تستدعي صفحتك MagizAI.consent(true) لا يحفظ الودجت شيئًا في متصفح الزائر (لا كوكي لمعرّف الزائر، ولا شيء في localStorage أو sessionStorage) ولا يرسل أي بيانات عن الزيارة أو التصفح. ويظل بوسع الزائر فتح الدردشة قبل ذلك، فتعمل لتلك الصفحة فقط.

التحكم بالأداة من صفحتك

يضيف السكربت كائنًا صغيرًا إلى window بعد تحميله. وكل دالة آمنة للاستدعاء حتى قبل أن يفتح الزائر المحادثة.

// Open the panel, optionally with the question already asked.
MagizAI.open();
MagizAI.open('Which plan suits a site with 20,000 visits a month?');

// Close it again.
MagizAI.close();

// Call this when the visitor signs out: it ends this browser's conversation
// and forgets whose it was, so the next person starts anonymously.
MagizAI.logout();

// Record a sale the chat contributed to, for the revenue report.
MagizAI.trackConversion(149.00, 'USD');

// With your cookie banner (data-consent="wait" on the script tag):
// the visitor agreed, so the widget may store its visitor ID...
MagizAI.consent(true);
// ...or said no: what the widget stored leaves this browser.
MagizAI.consent(false);
استدعاء MagizAI.open() مع سؤال هو ما يجعل زر اسأل عن هذه الباقة يعمل: تُفتح النافذة والسؤال مُرسل بالفعل، فيرى الزائر إجابة بدل حقل فارغ. والمواقع التي رُكّبت قبل تغيير الاسم يمكنها الاستمرار في استدعاء window.ElyAgents، فهو الكائن نفسه.

يحفظ MagizAI.consent(true) معرّف الزائر ويبدأ عرض الزوار المباشرين وتتبّع التصفح، كلًّا حيث يكون مفعّلًا وما لم يرسل المتصفح إعداد عدم التتبع. ويوقفهما MagizAI.consent(false) في تلك الصفحة ويزيل ما حفظه الودجت في هذا المتصفح: معرّف الزائر ورابط المحادثة والبيانات التي قدّمها الزائر وتفضيلات الودجت نفسه، وتستمر الدردشة المفتوحة إلى أن تُغادر الصفحة. ولا يتذكر الودجت الإجابة، لذا استدعِها في كل صفحة ما إن يعرفها الشريط، والاستدعاء الذي يسبق تحميل الودجت يُحفظ له. ومن دون شريط، يؤجّل إعداد روبوت الدردشة «عدم حفظ معرّف الزائر إلا بعد أن يفتح الدردشة» كل ذلك بالطريقة نفسها إلى أن تُفتح الدردشة.

هوية الزائر الموقَّعة

بدونها يعامل المساعد الجميع كزوار مجهولين ولا يناقش أي حساب. ومعها يعرف من يسأل، فيجيب عن طلباته وفواتيره وخدماته وتذاكره هو وحده. يوقّع خادمك رمزًا مضغوطًا بخوارزمية HS256 باستخدام سر الهوية الخاص بالروبوت، والمتصفح ينقله فقط.

<?php
// Server-side, in the page your signed-in customer is served. Never in the browser:
// whoever holds the secret can impersonate any of your customers.
$secret = getenv('MAGIZAI_IDENTITY_SECRET');   // Chatbots → Install → Signed visitor identity

$b64 = fn (array $a) => rtrim(strtr(base64_encode(json_encode($a)), '+/', '-_'), '=');
$header  = $b64(['alg' => 'HS256', 'typ' => 'JWT']);
$payload = $b64([
    'sub'         => (string) $user->id,      // your id for this person
    'external_id' => (string) $user->id,
    'email'       => $user->email,
    'name'        => $user->name,
    'plan'        => $user->plan,             // optional, shown to your agents
    'company'     => $user->company_name,     // optional
    'locale'      => 'en',                    // optional
    'iat'         => time(),
    'exp'         => time() + 3600,           // 24 hours is the hard ceiling
]);
$sig = rtrim(strtr(base64_encode(hash_hmac('sha256', "$header.$payload", $secret, true)), '+/', '-_'), '=');
$token = "$header.$payload.$sig";
?>
<script>window.MagizAIIdentity = "<?= $token ?>";</script>
<script src="https://magiz.ai/widget.js" data-key="cv_9f2a4c7e1b6d3a8f5c0e2b4d" defer></script>
المعاملالوصف
subإلزامي. معرّفك أنت لهذا الشخص. ترتبط به المحادثة وذاكرتها. لا يكون "0" أبدًا: يُرفض كل رمز يسمّي "0".
external_idاسم بديل اختياري لـ sub، مقبول ليرسل خادمك الحقل الموجود لديه أصلًا. والقاعدة نفسها تنطبق: لا "0" أبدًا.
emailيُستخدم لربط الزائر بطلباته وتذاكره ومحادثاته السابقة، ويظهر لموظفيك.
nameيظهر لموظفيك ويستخدمه المساعد في تحية الزائر.
planاختياري. أي وصف تستخدمه للمستوى أو الشريحة. يراه موظفوك في بطاقة العميل.
companyاختياري. اسم الحساب أو المؤسسة.
localeاختياري. رمز لغة من حرفين، يُستخدم حين يتبع الروبوت لغة المستخدم المسجَّل بدل لغة المتصفح.
iat / expوقت الإصدار ووقت الانتهاء بالثواني. لا يُقبل أي رمز بعد 24 ساعة مهما كانت قيمة exp. أصدر رمزًا جديدًا مع كل تحميل للصفحة.
وقّع على الخادم ولا ترسل السر إلى المتصفح أبدًا: من يملكه يستطيع انتحال صفة أي عميل لديك. واستدعِ MagizAI.logout() عند تسجيل الخروج، حتى لا يسلّم جهاز مشترك المحادثة السابقة لمن يأتي بعده.

الويب هوك

هو الجزء الوحيد من المنصة الذي يتصل بك أنت. أضف عنوانًا من الأتمتة، في تبويب خطافات الويب، واختر الأحداث التي تهمك، فنرسل إلى عنوانك طلب POST بصيغة JSON موقَّعًا عند وقوعها.

الحدثسبب حدوثه
conversation.createdفتح زائر محادثة، قبل أن يُقال أي شيء.
message.receivedأرسل زائر رسالة.
ai.repliedأجاب المساعد. مفيد لتسجيل ما قيل للعميل.
keyword.matchedظهرت كلمة مفتاحية حددتها في رسالة زائر.
handoff.requestedطلبت المحادثة موظفًا بشريًا، سواء طلب الزائر ذلك أو صعّدها المساعد. وهذا هو الحدث الذي تربطه بتنبيهاتك.
handoff.followupترك زائر بيانات التواصل ليرد عليه فريقك لاحقًا. يُرسل بدلًا من handoff.requested عندما تكون المحادثة في انتظار موظف بالفعل، أو عندما لم يرد أحد على آخر طلب. اربطه بتنبيهاتك أيضًا.
conversation.resolvedأُغلقت محادثة، بيد موظف أو بيد المساعد. وهو المُشغّل المعتاد لإغلاق تذكرتك أنت.
tag.addedأُضيف وسم إلى محادثة.
lead.capturedجُمعت بيانات تواصل. وهو المُشغّل المعتاد لإنشاء سجل في نظام إدارة العملاء لديك.
lead.requestأكّد زائر في المحادثة طلبًا لفريقك، مثل معاودة الاتصال أو عرض سعر. تصل بيانات التواصل وما طلبه تحت data.lead.
conversion.recordedنُسب مبلغ مبيعات إلى محادثة.
action.executedنفّذ المساعد إجراءً من إجراءاتك، مثل مهارة أو أداة موصولة.
booking.createdتم حجز موعد لا يحتاج إلى موافقة. يصل الحجز تحت data.booking، دون أي رابط يتيح تغييره.
booking.requestedوصل طلب حجز وينتظر أن يؤكده فريقك أو يرفضه.
booking.confirmedتم تأكيد طلب حجز.
booking.declinedتم رفض طلب حجز.
booking.cancelledأُلغي حجز، من العميل أو من فريقك.
booking.rescheduledنُقل حجز إلى وقت آخر.
booking.completedعُلّم حجز بأنه تم.
booking.no_showلم يحضر عميل إلى موعده.

لكل إرسال الغلاف نفسه: اسم الحدث، ووقت وقوعه، وكائن data. ولا تُسلسَل سجلات قاعدة البيانات كما هي، فـ data تحمل حقولًا بسيطة فقط، والمحادثة تصل دائمًا داخل data.conversation ومعها المعرّف public_id.

POST https://your-app.example.com/hooks/magizai
Content-Type: application/json
User-Agent: MagizAI-Webhooks/1.0
X-Signature: sha256=6f1b0c2e…

{
  "event": "conversation.resolved",
  "timestamp": "2026-09-23T09:14:02+00:00",
  "data": {
    "conversation": {
      "public_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
      "status": "closed",
      "channel": "website",
      "visitor_name": "Nadia Karim",
      "visitor_email": "nadia@example.test",
      "visitor_page": "https://example.com/pricing"
    }
  }
}

التحقق من الإرسال

يحمل كل طلب ترويسة X-Signature: sha256= يتبعها HMAC للبايتات التي أرسلناها بالضبط، مفتاحها السر الخاص بعنوانك. تحقق منها قبل أن تثق بالمحتوى، وقارن بزمن ثابت.

// Node / Express. Verify against the RAW body, before any JSON parsing:
// re-serialising changes the bytes and the signature will never match.
app.post('/hooks/magizai', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.MAGIZAI_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  const a = Buffer.from(expected);
  const b = Buffer.from(req.get('X-Signature') || '');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(401);

  const { event, data } = JSON.parse(req.body.toString('utf8'));
  // Answer first, work afterwards: anything slower than 10 seconds counts as a failure.
  res.sendStatus(200);
  queue.push({ event, data });
});
القاعدةالوصف
HTTPS عام فقطيجب أن يشير العنوان إلى عنوان شبكي عام. أما العناوين الداخلية وعناوين الاسترجاع فمرفوضة، ويُثبَّت الاتصال على العنوان المتحقَّق منه، ولا تُتبع عمليات إعادة التوجيه.
مهلة 10 ثوانٍأجب برمز 2xx فور استلام المحتوى ثم نفّذ العمل بعد ذلك. وما يتجاوز ذلك يُحتسب إرسالًا فاشلًا.
ثلاث محاولاتيُعاد الإرسال بعد الفشل أو بعد رد خارج 2xx مرتين على الأكثر، بفاصل من بضع ثوانٍ إلى دقيقة، أي ثلاث محاولات في المجموع. وبعد الثالثة يبقى الإرسال معلَّمًا فاشلًا في السجل. والعنوان الذي يرفضه فحص العنوان العام لا يُعاد إليه الإرسال.
لا ضمان للترتيبالإرسالات تمر عبر طابور، فقد يصل حدثان بترتيب مختلف وقد تصل إعادة المحاولة مرتين. تعامل مع المحتوى كحقيقة تُطبَّق لا كخطوة تُعاد، واعتمد على public_id مفتاحًا.
كل إرسال مسجَّلتُحفظ الحالة ورمز الرد وأول 2000 حرف من ردك، وزر الاختبار يرسل محتوى نموذجيًا. راجع هذا السجل أولًا حين لا يصلك شيء.

REST API الإصدار v1

واجهة التكامل العامة. اقرأ روبوتاتك ومحادثاتك، وأضف معرفة، وأرسل رسالة زائر لتحصل على رد الذكاء الاصطناعي في استجابة JSON واحدة. تُصادق برمز تنشئه من شاشة الإعدادات.

المسار الأساسي/api/v19 نقطة نهاية

GET/api/v1/me

يُرجع المستخدم صاحب الرمز ومساحة عمله.

المصادقة رمز Bearer بصلاحية apiحد المعدل بلا حد على المسار

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/v1/me \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "user": {
    "id": 12,
    "name": "Amelia Fox",
    "email": "amelia@acme.test",
    "role": "owner"
  },
  "company": {
    "id": 3,
    "name": "Acme Ltd",
    "slug": "acme-ltd",
    "plan": "pro"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

GET/api/v1/chatbots

يسرد كل روبوت في مساحة العمل.

المصادقة رمز Bearer بصلاحية apiحد المعدل بلا حد على المسار

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/v1/chatbots \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": [
    {
      "id": 7,
      "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
      "name": "Support bot",
      "provider": "claude",
      "model": "claude-haiku-4-5",
      "is_active": true
    }
  ]
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

GET/api/v1/chatbots/{key}

يُرجع روبوتًا واحدًا مع هوية الأداة البصرية وعدد مصادر المعرفة لديه.

المصادقة رمز Bearer بصلاحية apiحد المعدل بلا حد على المسار

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.

الطلب

curl https://magiz.ai/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": {
    "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
    "name": "Support bot",
    "provider": "claude",
    "model": "claude-haiku-4-5",
    "is_active": true,
    "knowledge_sources": 14,
    "branding": {
      "primary_color": "#4f46e5",
      "launcher_text": "Chat with us",
      "position": "right",
      "theme": "minimal",
      "logo_url": null,
      "avatar_url": null,
      "title": "Support bot",
      "subtitle": "We typically reply in a few seconds",
      "layout": "classic",
      "launcher": "bubble",
      "quick_replies": [],
      "agent_avatars": [],
      "composer_style": "full",
      "sound": true,
      "screen_share": false,
      "copilot": false,
      "auto_actions": true,
      "copilot_use_profile": false,
      "copilot_autostart": true,
      "live_visitors": true,
      "behavior_tracking": false,
      "recommend_mode": "reactive",
      "proactive": {
        "enabled": false,
        "message": "Hi! Anything I can help you find?",
        "delay": 20,
        "scroll": 0,
        "exit_intent": false,
        "url_contains": "",
        "frequency": "session"
      }
    }
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

GET/api/v1/chatbots/{key}/conversations

يسرد محادثات روبوت، الأحدث نشاطًا أولًا، بنتيجة مقسمة إلى صفحات.

المصادقة رمز Bearer بصلاحية apiحد المعدل بلا حد على المسار

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
per_pageintegerاختياريفي الاستعلام. عدد الصفوف في الصفحة. القيمة الافتراضية 20 والحد الأعلى 100.

الطلب

curl "https://magiz.ai/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations?per_page=2" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "current_page": 1,
  "data": [
    {
      "id": 4821,
      "public_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
      "status": "bot",
      "visitor_id": "v_2c9a71b4e5",
      "last_message_at": "2026-08-08T09:41:12.000000Z"
    },
    {
      "id": 4820,
      "public_id": "1d3f92ac-77b1-4a0d-8c6e-2f5a9b4c1d70",
      "status": "closed",
      "visitor_id": "v_71ad03f9c2",
      "last_message_at": "2026-08-08T08:02:55.000000Z"
    }
  ],
  "first_page_url": "https://magiz.ai/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations?page=1",
  "from": 1,
  "last_page": 34,
  "last_page_url": "https://magiz.ai/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations?page=34",
  "next_page_url": "https://magiz.ai/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations?page=2",
  "path": "https://magiz.ai/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations",
  "per_page": 2,
  "prev_page_url": null,
  "to": 2,
  "total": 67
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

GET/api/v1/chatbots/{key}/knowledge

يسرد المستندات التي يحملها الروبوت، الأحدث أولًا، في نتيجة مقسّمة على صفحات.

المصادقة رمز Bearer بصلاحية apiحد المعدل بلا حد على المسار

تُستثنى الصفحات التي نتجت عن زحف رابط، فيطابق العدد ما يراه المشرف في شاشة المعرفة. واستخدم source_url_prefix لتسأل فقط عن المستندات التي أرسلها تكاملك أنت، وبهذا توازن المزامنة بين ما أرسلته وما هو موجود فعلًا.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
typestringاختيارييعيد هذا النوع فقط: text أو qa أو url أو file.
source_url_prefixstringاختيارييعيد فقط المستندات التي يبدأ عنوانها بهذا.
per_pageintegerاختياريفي الاستعلام. عدد الصفوف في الصفحة. القيمة الافتراضية 20 والحد الأعلى 100.

الطلب

curl "https://magiz.ai/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/knowledge?source_url_prefix=https://example.com/help/&per_page=50" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": [
    {
      "id": 918,
      "type": "text",
      "title": "Refund policy",
      "source_url": "https://example.com/help/refund-policy",
      "status": "ready",
      "chunk_count": 3,
      "created_at": "2026-09-14T08:21:55+00:00"
    }
  ],
  "current_page": 1,
  "per_page": 50,
  "total": 1,
  "last_page": 1
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.

POST/api/v1/chatbots/{key}/knowledge

يضيف مستندًا نصيًا أو سؤالًا وجوابًا إلى روبوت ويدرّبه فورًا.

المصادقة رمز Bearer بصلاحية apiصلاحية الدور manage-contentحد المعدل بلا حد على المسار

يجري التدريب داخل الطلب لا في طابور، لذا يتوقف النداء حتى تُفهرس الوثيقة. توقع عدة ثوانٍ لمستند طويل.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
titlestringمطلوباسم للمستند. حتى 200 محرف.
contentstringمطلوبنص المستند.
typestringاختياريالقيمة text أو qa. الافتراضية text.
source_urlstringاختياريمطلوب حين يكون type مساويًا لـ url. الصفحة المراد زحفها، حتى 2048 محرفًا.
visibilitystringاختياريpublic أو customer. لا يُستخدم مستند customer إلا حين يكون الزائر معرَّفًا برمز موقَّع.

الطلب

curl -X POST https://magiz.ai/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/knowledge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "title": "Refund policy",
        "type": "text",
        "source_url": "https://example.com/help/refund-policy",
        "content": "We refund any order within 30 days of delivery. Ship it back with the original packing slip and we credit the original payment method within five working days."
      }'

الاستجابة

{
  "data": {
    "id": 918,
    "title": "Refund policy",
    "type": "text",
    "status": "ready",
    "chunk_count": 3,
    "source_url": "https://example.com/help/refund-policy"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
422حُفظ المستند لكن تعذّر تدريبه. وتحمل الاستجابة معرّفه وحالته لتعيد التدريب بدل رفعه من جديد.

DELETE/api/v1/chatbots/{key}/knowledge

يحذف المستندات المرسَلة: المستند الموجود عند source_url، أو كل ما تحت url_prefix عدا العناوين المذكورة في keep.

المصادقة رمز Bearer بصلاحية apiصلاحية الدور manage-contentحد المعدل بلا حد على المسار

بهذه الطريقة تحذف المزامنة المقالات التي حُذفت من المصدر: أرسل في keep العناوين التي ما زالت لديك، ويذهب كل ما عداها مما سبق أن أرسلته تحت ذلك البادئة. ولا يمس ذلك الصفحات المزحوفة ولا الملفات المرفوعة ولا المستندات المضافة يدويًا.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
source_urlstringاختيارييحذف المستند الوحيد المرسَل بهذا العنوان. إلزامي ما لم يُرسل url_prefix.
url_prefixstringاختيارييحذف كل مستند مرسَل يبدأ عنوانه بهذا. ويجب أن يتضمن مسارًا لا نطاقًا فقط.
keeparrayاختياريالعناوين المستثناة عند استخدام url_prefix. حتى 5000 عنوان.

الطلب

curl -X DELETE https://magiz.ai/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/knowledge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "url_prefix": "https://example.com/help/",
        "keep": [
          "https://example.com/help/refund-policy",
          "https://example.com/help/delivery-times"
        ]
      }'

الاستجابة

{
  "data": {
    "removed": 14
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
422لا يتضمن url_prefix مسارًا. ونطاق مجرد كان سيمحو كل مستندات الروبوت، لذا يُرفض الطلب.

POST/api/v1/chatbots/{key}/messages

يرسل رسالة زائر ويُرجع رد الذكاء الاصطناعي في استجابة واحدة بلا بث.

المصادقة رمز Bearer بصلاحية apiصلاحية الدور handle-conversationsحد المعدل بلا حد على المسار

يُولَّد الرد كاملًا قبل إرسال الاستجابة. وإن أردت الكلمات فور وصولها فاستخدم نقطة البث في الأداة. وحين يستلم موظف بشري المحادثة يكون reply مساويًا لـ null ويشرح الحقل note السبب.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
messagestringمطلوبرسالة الزائر. حتى 4000 محرف، ولا يجوز أن تكون مسافات فقط.
visitor_idstringمطلوبالمعرّف الذي تسنده أداتك للزائر وتحتفظ به طوال الجلسة. حتى 100 محرف.
conversation_iduuidاختياريمحادثة قائمة تريد متابعتها. اتركه ليبدأ محادثة جديدة.
metaobjectاختياريسياق حر يُحفظ على المحادثة.

الطلب

curl -X POST https://magiz.ai/api/v1/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "message": "How long does delivery to Dubai take?"
      }'

الاستجابة

{
  "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
  "status": "bot",
  "reply": {
    "id": 33127,
    "content": "Orders to Dubai arrive in two to four working days with DHL Express. You get a tracking link by email as soon as the parcel leaves our warehouse.",
    "model": "claude-haiku-4-5",
    "tokens_in": 812,
    "tokens_out": 41
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429بلغت مساحة العمل حد الرسائل الشهري.
502تعذر الوصول إلى مزود الذكاء الاصطناعي. تحقق من المفتاح المهيأ لمساحة العمل.

GET/api/v1/conversations/{conversation}

يُرجع محادثة واحدة مع نصها الكامل.

المصادقة رمز Bearer بصلاحية apiحد المعدل بلا حد على المسار

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl https://magiz.ai/api/v1/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": {
    "id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
    "status": "bot",
    "visitor_id": "v_2c9a71b4e5",
    "messages": [
      {
        "id": 33126,
        "role": "visitor",
        "content": "How long does delivery to Dubai take?",
        "created_at": "2026-08-08T09:41:04.000000Z"
      },
      {
        "id": 33127,
        "role": "assistant",
        "content": "Orders to Dubai arrive in two to four working days with DHL Express.",
        "created_at": "2026-08-08T09:41:07.000000Z"
      }
    ]
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

واجهة برمجة الذكاء الاصطناعي

ذكاء MagizAI الاصطناعي لبرامجك الخاصة دون روبوت دردشة: الكتابة وإعادة الصياغة والتلخيص والاستخراج والتصنيف والترجمة، والإجابة عن الأسئلة مما درّبت عليه نشاطك التجاري. ويمكنها أيضًا بدء تشغيل أحد وكلاء الذكاء الاصطناعي في مساحة العمل وقراءة ما جرى فيه. يفعّل مدير مساحة العمل تطبيق واجهة برمجة الذكاء الاصطناعي، ثم ينشئ رمزًا مع تحديد «يمكنه استخدام واجهة برمجة الذكاء الاصطناعي» في الإعدادات، رموز API. يُحتسب كل طلب رسالة ذكاء اصطناعي واحدة من الباقة مثل رد الدردشة، وطلبًا واحدًا من طلبات واجهة برمجة الذكاء الاصطناعي الشهرية في الباقة. يحمل كل خطأ رمزًا ثابتًا: app_off أو no_ability أو invalid أو health_off أو cap أو rate_limited أو no_ai أو failed أو not_found أو agents_off أو agents_stopped أو agent_unavailable. لا ترسل سجلات صحية إلا إذا فعّلت مساحة العمل الذكاء الاصطناعي للبيانات الصحية، وعندها ضع contains_health_data على الطلب.

المسار الأساسي/api/v1/ai5 نقطة نهاية

POST/api/v1/ai/complete

ينفّذ مهمة ذكاء اصطناعي واحدة على النص الذي ترسله. يعيد نصًا، أو حقولًا في extract وclassify.

المصادقة رمز Bearer بصلاحية apiصلاحية الدور aiحد المعدل 60 طلب كل 1 دقيقة، لكل رمز

النتيجة اقتراح: راجعها قبل أن تصل إلى عميل أو تغيّر سجلًا. في extract تكون قيمة الحقل الذي لا يذكره النص null. وفي classify يحمل كل حقل أحد خياراته، أو null.

المعاملات

المعاملالنوعمطلوبالوصف
purposestringمطلوبإحدى القيم: write أو rewrite أو summarise أو extract أو classify أو translate أو answer.
inputstringمطلوبالنص المطلوب العمل عليه: الوصف في write، والنص مع سؤاله في answer. حتى 10000 حرف.
languagestringاختياريالكتابة بهذه اللغة، برمز مثل fr أو باسم مثل French. مطلوب في translate. الافتراضي: لغة النص.
tonestringاختياريإحدى القيم: neutral أو friendly أو formal أو warm.
fieldsarrayاختياريفي extract وclassify: حتى 25 اسم حقل، أو كائنات تحتوي name وdescription وoptions. يتطلب classify خيارات لكل حقل.
contains_health_databooleanاختياريtrue عندما يحمل النص بيانات صحية. يُرفض ما لم تفعّل مساحة العمل الذكاء الاصطناعي للبيانات الصحية.

الطلب

curl -X POST https://magiz.ai/api/v1/ai/complete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "purpose": "extract",
        "input": "Hi, this is Sara Bell. My order A-1055 has not arrived in Dubai yet.",
        "fields": ["name", "order_number", "city"]
      }'

الاستجابة

{
  "purpose": "extract",
  "fields": {
    "name": "Sara Bell",
    "order_number": "A-1055",
    "city": "Dubai"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403app_off: تطبيق واجهة برمجة الذكاء الاصطناعي متوقف في مساحة العمل.
403no_ability: أُنشئ الرمز دون صلاحية ai، أو لم يعد صاحبه قادرًا على إدارة مساحة العمل.
403health_off: الطلب يحمل contains_health_data والذكاء الاصطناعي للبيانات الصحية متوقف.
422invalid: فشل حقل في التحقق. يسمّيه الكائن errors.
429cap: نفدت طلبات واجهة برمجة الذكاء الاصطناعي لهذا الشهر، أو رسائل الذكاء الاصطناعي في الباقة.
429rate_limited: طلبات كثيرة جدًا بهذا الرمز خلال دقيقة. يبيّن Retry-After متى تحاول مجددًا.
502failed: لم يقدّم الذكاء الاصطناعي إجابة صالحة. حاول مرة أخرى.
503no_ai: لا يوجد في مساحة العمل ذكاء اصطناعي يمكنه الإجابة الآن (لا يوجد مفتاح صالح، أو مساحة العمل غير نشطة).

POST/api/v1/ai/answer

يجيب عن سؤال من المعرفة المدرَّبة في مساحة العمل ويذكر المصادر التي استخدمها.

المصادقة رمز Bearer بصلاحية apiصلاحية الدور aiحد المعدل 30 طلب كل 1 دقيقة، لكل رمز

لا يقرأ إلا المقاطع العامة ما لم تكن audience بالقيمة staff. يبيّن knowledge ما وجده البحث: used أو none_found أو no_knowledge أو unavailable. وعندما لا يطابق شيء، يُطلب من النموذج أن يقول ذلك بدل التخمين.

المعاملات

المعاملالنوعمطلوبالوصف
questionstringمطلوبالسؤال. حتى 2000 حرف.
languagestringاختياريالكتابة بهذه اللغة، برمز مثل fr أو باسم مثل French. مطلوب في translate. الافتراضي: لغة النص.
audiencestringاختياريpublic (الافتراضي) يقرأ المقاطع العامة فقط. وstaff يقرأ أيضًا مقاطع العملاء المسجلين والملاحظات الداخلية.
contains_health_databooleanاختياريtrue عندما يحمل النص بيانات صحية. يُرفض ما لم تفعّل مساحة العمل الذكاء الاصطناعي للبيانات الصحية.

الطلب

curl -X POST https://magiz.ai/api/v1/ai/answer \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "question": "Do you deliver to Dubai, and how long does it take?"
      }'

الاستجابة

{
  "answer": "Yes. Orders to Dubai arrive in two to four working days with DHL Express.",
  "knowledge": "used",
  "sources": [
    {
      "title": "Shipping and delivery",
      "url": "https://acme.test/shipping"
    }
  ]
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403app_off: تطبيق واجهة برمجة الذكاء الاصطناعي متوقف في مساحة العمل.
403no_ability: أُنشئ الرمز دون صلاحية ai، أو لم يعد صاحبه قادرًا على إدارة مساحة العمل.
403health_off: الطلب يحمل contains_health_data والذكاء الاصطناعي للبيانات الصحية متوقف.
422invalid: فشل حقل في التحقق. يسمّيه الكائن errors.
429cap: نفدت طلبات واجهة برمجة الذكاء الاصطناعي لهذا الشهر، أو رسائل الذكاء الاصطناعي في الباقة.
429rate_limited: طلبات كثيرة جدًا بهذا الرمز خلال دقيقة. يبيّن Retry-After متى تحاول مجددًا.
502failed: لم يقدّم الذكاء الاصطناعي إجابة صالحة. حاول مرة أخرى.
503no_ai: لا يوجد في مساحة العمل ذكاء اصطناعي يمكنه الإجابة الآن (لا يوجد مفتاح صالح، أو مساحة العمل غير نشطة).

GET/api/v1/ai/agents

يعرض وكلاء مساحة العمل النشطين الذين يمكن للرمز تشغيلهم.

المصادقة رمز Bearer بصلاحية apiصلاحية الدور aiحد المعدل 60 طلب كل 1 دقيقة، لكل رمز

لا يظهر الوكيل الذي يعمل ببيانات صحية: لا يعمل أبدًا عبر الواجهة. تكون can_act صحيحة عندما يمكن للوكيل طلب إجراءات، وهي تنتظر مديرًا في لوحة التحكم. يتطلب تفعيل تطبيق الوكلاء.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/v1/ai/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": [
    {
      "id": 12,
      "name": "Billing desk",
      "version": 3,
      "tools": [
        "customer_lookup",
        "customer_balance",
        "message_draft"
      ],
      "can_act": false
    },
    {
      "id": 14,
      "name": "Customer care",
      "version": 1,
      "tools": [
        "customer_lookup",
        "customer_tag",
        "customer_note"
      ],
      "can_act": true
    }
  ]
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403app_off: تطبيق واجهة برمجة الذكاء الاصطناعي متوقف في مساحة العمل.
403agents_off: تطبيق الوكلاء متوقف في مساحة العمل.
403no_ability: أُنشئ الرمز دون صلاحية ai، أو لم يعد صاحبه قادرًا على إدارة مساحة العمل.
429rate_limited: طلبات كثيرة جدًا بهذا الرمز خلال دقيقة. يبيّن Retry-After متى تحاول مجددًا.

POST/api/v1/ai/agents/{id}/runs

يبدأ تشغيلًا لوكيل واحد بمهمة. يرد فورًا بالتشغيل، أو عند انتهائه خلال ثواني wait.

المصادقة رمز Bearer بصلاحية apiصلاحية الدور aiحد المعدل 10 طلب كل 1 دقيقة، لكل رمز

يلتزم التشغيل بكل قواعد تطبيق الوكلاء: حدود الوكيل وسقوف التكلفة وزر الإيقاف. يُحتسب كل استدعاء للنموذج طلبًا واحدًا من واجهة برمجة الذكاء الاصطناعي ورسالة ذكاء اصطناعي واحدة. تعني الحالة 202 أن التشغيل مستمر: اقرأه عبر GET /api/v1/ai/runs/{id}. تنتظر الإجراءات والمسودات مديرًا في صفحة التشغيل في لوحة التحكم (dashboard_url)، ولا يمكن للواجهة الموافقة عليها. يتطلب تفعيل تطبيق الوكلاء.

المعاملات

المعاملالنوعمطلوبالوصف
idintegerمطلوبفي المسار. معرّف الوكيل من GET /api/v1/ai/agents.
taskstringمطلوبما يُطلب من الوكيل. حتى 4000 حرف.
inputsobjectاختياريحتى 20 قيمة مسمّاة، مثل {"invoice": "INV-0107"}. تستخدم الأسماء الأحرف والأرقام و _. يقرؤها الوكيل بيانات، لا تعليمات أبدًا.
waitintegerاختياريعدد الثواني التي ينتظر فيها الطلب انتهاء التشغيل، من 0 إلى 25. الافتراضي 0: رد فوري بالحالة 202.

الطلب

curl -X POST https://magiz.ai/api/v1/ai/agents/12/runs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
        "task": "Check what Ananya Rao owes and draft a polite reminder.",
        "inputs": {"customer": "Ananya Rao"},
        "wait": 20
      }'

الاستجابة

{
  "run": {
    "id": 845,
    "agent": {
      "id": 12,
      "name": "Billing desk",
      "version": 3
    },
    "status": "done",
    "ended": "done",
    "output": "Ananya Rao owes INR 4,500 on invoice INV-0107, due on 20 October. I saved a reminder email as a draft for you to check.",
    "approval": "pending",
    "actions": [],
    "drafts": 1,
    "dashboard_url": "https://magiz.ai/agents/runs/845",
    "usage": {
      "model_calls": 3,
      "tool_calls": 2,
      "tokens_in": 4120,
      "tokens_out": 310,
      "cost_usd": "0.004380"
    },
    "started_at": "2026-10-16T09:12:03.120Z",
    "finished_at": "2026-10-16T09:12:09.874Z"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403app_off: تطبيق واجهة برمجة الذكاء الاصطناعي متوقف في مساحة العمل.
403agents_off: تطبيق الوكلاء متوقف في مساحة العمل.
403no_ability: أُنشئ الرمز دون صلاحية ai، أو لم يعد صاحبه قادرًا على إدارة مساحة العمل.
404not_found: لا يوجد وكيل بهذا المعرّف في مساحة العمل.
409agent_unavailable: الوكيل مؤرشف، أو يعمل ببيانات صحية.
409agents_stopped: أوقف مدير مساحة العمل جميع الوكلاء.
422invalid: فشل حقل في التحقق. يسمّيه الكائن errors.
429cap: نفدت طلبات واجهة برمجة الذكاء الاصطناعي لهذا الشهر أو رسائل الذكاء الاصطناعي في الباقة، أو بلغ سقف تكلفة الوكلاء لهذا اليوم.
429rate_limited: طلبات كثيرة جدًا بهذا الرمز خلال دقيقة. يبيّن Retry-After متى تحاول مجددًا.

GET/api/v1/ai/runs/{id}

يقرأ تشغيلًا بدأ عبر واجهة برمجة الذكاء الاصطناعي: حالته وإجابته وما ينتظر مديرًا وما استهلكه.

المصادقة رمز Bearer بصلاحية apiصلاحية الدور aiحد المعدل 120 طلب كل 1 دقيقة، لكل رمز

قيمة status هي running أو waiting أو done أو stopped أو failed. وتبيّن ended كيف انتهى، مثل done أو waiting أو step_limit أو time_limit أو cap أو rejected. تكون approval بقيمة pending ما دام على مدير أن يقرر. لا يمكن هنا قراءة التشغيلات التي بدأت من لوحة التحكم أو مسار عمل أو محادثة.

المعاملات

المعاملالنوعمطلوبالوصف
idintegerمطلوبفي المسار. معرّف التشغيل من الطلب الذي بدأه.

الطلب

curl https://magiz.ai/api/v1/ai/runs/846 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "run": {
    "id": 846,
    "agent": {
      "id": 14,
      "name": "Customer care",
      "version": 1
    },
    "status": "waiting",
    "ended": "waiting",
    "output": "I asked to tag Ananya Rao as a late payer.",
    "approval": "pending",
    "actions": [
      {
        "id": 77,
        "tool": "customer_tag",
        "status": "pending"
      }
    ],
    "drafts": 0,
    "dashboard_url": "https://magiz.ai/agents/runs/846",
    "usage": {
      "model_calls": 2,
      "tool_calls": 2,
      "tokens_in": 2890,
      "tokens_out": 120,
      "cost_usd": "0.002710"
    },
    "started_at": "2026-10-16T09:20:41.502Z",
    "finished_at": "2026-10-16T09:20:45.019Z"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403app_off: تطبيق واجهة برمجة الذكاء الاصطناعي متوقف في مساحة العمل.
403agents_off: تطبيق الوكلاء متوقف في مساحة العمل.
403no_ability: أُنشئ الرمز دون صلاحية ai، أو لم يعد صاحبه قادرًا على إدارة مساحة العمل.
404not_found: لا يوجد تشغيل بهذا المعرّف بدأ عبر واجهة برمجة الذكاء الاصطناعي في مساحة العمل.
429rate_limited: طلبات كثيرة جدًا بهذا الرمز خلال دقيقة. يبيّن Retry-After متى تحاول مجددًا.

واجهة البوابة

واجهة المستأجر خلف البوابة بالعلامة البيضاء التي يمكن للعميل استضافتها على نطاقه. تدير الروبوتات والمعرفة ومفاتيح المزودين والاستهلاك وشيفرة التضمين. تبقى البيانات والذكاء الاصطناعي على المنصة، ولا يُعاد أبدًا مفتاح مزود مخزّن إلى المتصفح.

المسار الأساسي/api/portal20 نقطة نهاية

POST/api/portal/login

يبدّل بريد وكلمة مرور لوحة التحكم برمز Bearer للبوابة.

المصادقة بدون مصادقة، عامةحد المعدل 10 طلب كل 1 دقيقة لكل عنوان IP

الرسائل عند الفشل مبهمة عن قصد: كلمة مرور خاطئة، أو عنوان غير معروف، أو بوابة مطفأة، أو دور غير كافٍ، كلها تُرجع النص نفسه، فلا تصلح النقطة لاكتشاف الحسابات الموجودة. وتتشارك المحاولات عدّاد القفل نفسه مع نموذج الدخول على الويب.

المعاملات

المعاملالنوعمطلوبالوصف
emailstringمطلوبالبريد الإلكتروني لمستخدم في لوحة التحكم. حتى 255 محرفًا.
passwordstringمطلوبكلمة مرور ذلك المستخدم في لوحة التحكم.

الطلب

curl -X POST https://magiz.ai/api/portal/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "email": "amelia@acme.test",
        "password": "correct-horse-battery-staple"
      }'

الاستجابة

{
  "token": "17|Ck2Ft9pQvYb3xLmR8sJd0aWnZeH6uT4gPqK1oI5c",
  "user": {
    "name": "Amelia Fox",
    "email": "amelia@acme.test",
    "role": "owner"
  },
  "company": {
    "name": "Acme Ltd",
    "plan": "pro"
  },
  "brand": {
    "name": "Acme Support",
    "powered_by": "MagizAI",
    "logo_url": "https://cdn.acme.test/logo.svg"
  }
}

الأخطاء

الحالةسبب حدوثه
401البريد أو كلمة المرور خاطئة. والنص نفسه سواء كان العنوان موجودًا أم لا.
403البوابة مطفأة لهذه المساحة، أو المساحة موقوفة، أو المستخدم ليس مالكًا ولا مسؤولًا. وصياغته كصياغة كلمة المرور الخاطئة عن قصد.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429محاولات كثيرة، من حد المسار أو من قفل الحساب المشترك. وترويسة Retry-After تحدد مدة الانتظار.

POST/api/portal/logout

يلغي رمز البوابة المستخدم في النداء.

المصادقة رمز Bearer بصلاحية portalحد المعدل بلا حد على المسار

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl -X POST https://magiz.ai/api/portal/logout \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "message": "Signed out."
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

GET/api/portal/me

يُرجع المستخدم المسجّل ومساحة العمل وعلامتها البيضاء وحدود الخطة واستهلاك الشهر الحالي.

المصادقة رمز Bearer بصلاحية portalحد المعدل بلا حد على المسار

يكون monthly_message_limit مساويًا لـ null في الخطة غير المحدودة، ومعه usage_percent كذلك.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/portal/me \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "user": {
    "name": "Amelia Fox",
    "email": "amelia@acme.test",
    "role": "owner"
  },
  "company": {
    "name": "Acme Ltd",
    "plan": "pro"
  },
  "brand": {
    "name": "Acme Support",
    "powered_by": "MagizAI",
    "logo_url": "https://cdn.acme.test/logo.svg"
  },
  "limits": {
    "plan": "Pro",
    "monthly_message_limit": 10000,
    "chatbot_limit": 5,
    "agent_seats": 10
  },
  "usage": {
    "messages_used": 3142,
    "message_limit": 10000,
    "usage_percent": 31,
    "chatbots": 2
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

GET/api/portal/chatbots

يسرد كل روبوت في مساحة العمل مع عدد مصادر المعرفة والمحادثات.

المصادقة رمز Bearer بصلاحية portalحد المعدل بلا حد على المسار

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/portal/chatbots \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": [
    {
      "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
      "name": "Support bot",
      "role": "support",
      "provider": "claude",
      "model": "claude-haiku-4-5",
      "is_active": true,
      "knowledge_sources": 14,
      "conversations": 67
    }
  ]
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

GET/api/portal/chatbots/{key}

يُرجع روبوتًا واحدًا مع شخصيته وتعليماته ورسالة الترحيب وهويته البصرية.

المصادقة رمز Bearer بصلاحية portalحد المعدل بلا حد على المسار

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.

الطلب

curl https://magiz.ai/api/portal/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": {
    "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
    "name": "Support bot",
    "role": "support",
    "provider": "claude",
    "model": "claude-haiku-4-5",
    "is_active": true,
    "knowledge_sources": 14,
    "conversations": 67,
    "persona": "Warm, direct, never oversells.",
    "instructions": "Always quote delivery times from the shipping table.",
    "welcome_message": "Hi! How can I help you today?",
    "branding": {
      "primary_color": "#4f46e5",
      "launcher_text": "Chat with us",
      "position": "right",
      "theme": "minimal",
      "logo_url": null,
      "avatar_url": null,
      "title": "Support bot",
      "subtitle": "We typically reply in a few seconds",
      "layout": "classic",
      "launcher": "bubble",
      "quick_replies": [],
      "agent_avatars": [],
      "composer_style": "full",
      "sound": true,
      "screen_share": false,
      "copilot": false,
      "auto_actions": true,
      "copilot_use_profile": false,
      "copilot_autostart": true,
      "live_visitors": true,
      "behavior_tracking": false,
      "recommend_mode": "reactive",
      "proactive": {
        "enabled": false,
        "message": "Hi! Anything I can help you find?",
        "delay": 20,
        "scroll": 0,
        "exit_intent": false,
        "url_contains": "",
        "frequency": "session"
      }
    }
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

GET/api/portal/chatbots/{key}/options

يعيد كل القيم التي يقبلها التحديث: مزودو ونماذج الذكاء الاصطناعي التي تسمح بها الباقة، ومستويات الجودة، والسمات، والتخطيطات، وأزرار الفتح، وأنماط الرد، وأنماط حقل الكتابة.

المصادقة رمز Bearer بصلاحية portalحد المعدل بلا حد على المسار

اقرأه قبل بناء نموذج تحرير بدل تثبيت القوائم في الكود. فالخيارات تتبع الباقة وما إذا كانت مساحة العمل تستخدم مفتاح مزود خاصًا بها، وهي تتغير بتغير الباقات. أما المفاتيح نفسها فلا تُعاد أبدًا، بل يُعاد فقط وجودها من عدمه.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.

الطلب

curl https://magiz.ai/api/portal/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/options \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": {
    "key_mode": "platform",
    "providers": [
      {
        "key": "openai",
        "label": "OpenAI",
        "models": ["gpt-4o-mini", "gpt-4o"],
        "has_key": false
      }
    ],
    "tiers": [
      { "key": "fastest",  "label": "Fastest",  "help": "Quickest replies at the lowest cost." },
      { "key": "standard", "label": "Standard", "help": "The balanced default." },
      { "key": "advanced", "label": "Advanced", "help": "Deepest reasoning for hard questions." }
    ],
    "themes": ["minimal", "ocean", "emerald", "midnight", "sunset", "crisp", "violet", "rose", "slate", "forest"],
    "layouts": ["classic", "hub", "compact"],
    "launchers": ["bubble", "teaser"],
    "reply_styles": ["bubbles", "flat", "cards", "compact", "spacious", "speech", "outline", "document", "terminal", "pill", "square", "notes"],
    "composer_styles": ["full", "minimal"],
    "current": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "ai_tier": "standard"
    }
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

PUT/api/portal/chatbots/{key}

يحدّث محتوى الروبوت ومظهر الأداة.

المصادقة رمز Bearer بصلاحية portalصلاحية الدور manage-chatbotsحد المعدل بلا حد على المسار

الحقل name مطلوب في كل نداء. وتُدمج حقول الهوية البصرية فوق المحفوظ، فإرسال primary_color وحده يترك البقية كما هي، وإرسال welcome_message فارغًا يعيده إلى رسالة الترحيب الافتراضية. ولا يمكن تغيير المزود أو النموذج من هنا.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
namestringمطلوباسم الروبوت. حتى 120 محرفًا.
personastringاختياريالأسلوب الذي ينبغي أن يتحدث به المساعد. حتى 2000 محرف.
instructionsstringاختياريتعليمات دائمة للمساعد. حتى 4000 محرف.
welcome_messagestringاختياريرسالة الترحيب عند فتح الدردشة. حتى 300 محرف، وإرسالها فارغة يعيدها إلى الافتراضية.
is_activebooleanاختياريهل يجيب الروبوت. اتركه ليبقى الإعداد الحالي.
primary_colorstringاختياريلون تمييز الأداة بصيغة hex. حتى 9 محارف.
launcher_textstringاختيارينص زر فتح الدردشة. حتى 40 محرفًا.
positionstringاختياريجهة ظهور الأداة: left أو right.
themestringاختياريسمة الأداة: minimal أو ocean أو emerald أو midnight أو sunset أو crisp أو violet أو rose أو slate أو forest.

الطلب

curl -X PUT https://magiz.ai/api/portal/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "Support bot",
        "welcome_message": "Hi! Ask me anything about your order.",
        "primary_color": "#0a7d5f",
        "position": "right",
        "theme": "emerald",
        "is_active": true
      }'

الاستجابة

{
  "data": {
    "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
    "name": "Support bot",
    "role": "support",
    "provider": "claude",
    "model": "claude-haiku-4-5",
    "is_active": true,
    "knowledge_sources": 14,
    "conversations": 67,
    "persona": "Warm, direct, never oversells.",
    "instructions": "Always quote delivery times from the shipping table.",
    "welcome_message": "Hi! Ask me anything about your order.",
    "branding": {
      "primary_color": "#0a7d5f",
      "launcher_text": "Chat with us",
      "position": "right",
      "theme": "emerald"
    }
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.

GET/api/portal/chatbots/{key}/knowledge

يسرد مصادر معرفة الروبوت وحالة تدريب كل منها.

المصادقة رمز Bearer بصلاحية portalحد المعدل بلا حد على المسار

تُسرد المصادر الرئيسية فقط. أما الصفحات المكتشفة أثناء زحف رابط فهي أبناء لذلك المصدر ولا تظهر منفصلة.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.

الطلب

curl https://magiz.ai/api/portal/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/knowledge \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": [
    {
      "id": 918,
      "type": "text",
      "title": "Refund policy",
      "source_url": null,
      "status": "ready",
      "chunk_count": 3,
      "created_at": "2026-08-08T09:12:44+00:00"
    },
    {
      "id": 902,
      "type": "url",
      "title": "acme.test",
      "source_url": "https://acme.test/shipping",
      "status": "processing",
      "chunk_count": 0,
      "created_at": "2026-08-07T16:30:02+00:00"
    }
  ]
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

POST/api/portal/chatbots/{key}/knowledge

يضيف ملاحظة نصية أو زوج سؤال وجواب أو رابطًا لزحفه.

المصادقة رمز Bearer بصلاحية portalصلاحية الدور manage-contentحد المعدل بلا حد على المسار

الحقول المطلوبة تعتمد على type: الحقل content مع text، والحقلان question وanswer مع qa، والحقل source_url مع url. يُنشأ المصدر فورًا بحالة pending ويُفهرس في الخلفية، فاستعلم من نقطة السرد لترى حالته تتحول إلى ready.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
typestringمطلوبالقيمة text أو qa أو url. وهي التي تحدد أي الحقول أدناه مطلوب.
titlestringاختيارياسم للمصدر. وإن تُرك فارغًا يعود إلى اسم افتراضي مناسب لنوعه.
contentstringاختياريمطلوب حين يكون type مساويًا لـ text. متن الملاحظة، حتى 1,000,000 محرف.
questionstringاختياريمطلوب حين يكون type مساويًا لـ qa. حتى 2000 محرف.
answerstringاختياريمطلوب حين يكون type مساويًا لـ qa. حتى 50,000 محرف.
source_urlurlاختياريمطلوب حين يكون type مساويًا لـ url. الصفحة المراد زحفها، حتى 2048 محرفًا.

الطلب

curl -X POST https://magiz.ai/api/portal/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/knowledge \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "type": "qa",
        "title": "Weekend delivery",
        "question": "Do you deliver on Saturdays?",
        "answer": "Yes. Saturday delivery is available in Dubai and Abu Dhabi at no extra cost."
      }'

الاستجابة

{
  "data": {
    "id": 919,
    "type": "qa",
    "title": "Weekend delivery",
    "source_url": null,
    "status": "pending",
    "chunk_count": 0,
    "created_at": "2026-08-08T10:04:18+00:00"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.

DELETE/api/portal/chatbots/{key}/knowledge/{source}

يحذف مصدر معرفة وملفه المخزّن وكل ما فُهرس منه.

المصادقة رمز Bearer بصلاحية portalصلاحية الدور manage-contentحد المعدل بلا حد على المسار

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
sourceintegerمطلوبفي المسار. معرّف مصدر المعرفة.

الطلب

curl -X DELETE https://magiz.ai/api/portal/chatbots/cv_9f2a4c7e1b6d3a8f5c0e2b4d/knowledge/919 \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "message": "Knowledge source removed."
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

GET/api/portal/keys

يسرد كل مزودي الذكاء الاصطناعي وما إذا كان لمساحة العمل مفتاح خاص لدى كل منهم.

المصادقة رمز Bearer بصلاحية portalحد المعدل بلا حد على المسار

لا يُعاد المفتاح المخزّن أبدًا، بل آخر أربعة محارف منه وما إذا كان موجودًا.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/portal/keys \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": [
    { "provider": "claude",     "label": "Anthropic Claude", "last_four": "9f2c", "configured": true },
    { "provider": "openai",     "label": "OpenAI",           "last_four": null,   "configured": false },
    { "provider": "gemini",     "label": "Google Gemini",    "last_four": null,   "configured": false },
    { "provider": "deepseek",   "label": "DeepSeek",         "last_four": null,   "configured": false },
    { "provider": "kimi",       "label": "Moonshot Kimi",    "last_four": null,   "configured": false },
    { "provider": "groq",       "label": "Groq (Llama)",     "last_four": null,   "configured": false },
    { "provider": "mistral",    "label": "Mistral",          "last_four": null,   "configured": false },
    { "provider": "openrouter", "label": "OpenRouter",       "last_four": null,   "configured": false }
  ]
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

PUT/api/portal/keys/{provider}

يحفظ أو يستبدل مفتاح مساحة العمل لمزود واحد.

المصادقة رمز Bearer بصلاحية portalصلاحية الدور manage-workspaceحد المعدل بلا حد على المسار

المعاملات

المعاملالنوعمطلوبالوصف
providerstringمطلوبفي المسار. رمز المزود: claude أو openai أو gemini أو deepseek أو kimi أو groq أو mistral أو openrouter.
api_keystringمطلوبمفتاح المزود. يُخزَّن مشفرًا ولا يُعاد أبدًا. حتى 300 محرف.

الطلب

curl -X PUT https://magiz.ai/api/portal/keys/openai \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "api_key": "sk-proj-0f4c8b2e6a1d7f3c9b5e0a2d" }'

الاستجابة

{
  "data": {
    "provider": "openai",
    "last_four": "a2d0",
    "configured": true
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
422رمز المزود غير معروف.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.

DELETE/api/portal/keys/{provider}

يحذف مفتاح مساحة العمل لمزود واحد.

المصادقة رمز Bearer بصلاحية portalصلاحية الدور manage-workspaceحد المعدل بلا حد على المسار

النداء متكرر الأثر. حذف مزود بلا مفتاح يُرجع 200 أيضًا مع رسالة تفيد بأن لا مفتاح كان محفوظًا.

المعاملات

المعاملالنوعمطلوبالوصف
providerstringمطلوبفي المسار. رمز المزود: claude أو openai أو gemini أو deepseek أو kimi أو groq أو mistral أو openrouter.

الطلب

curl -X DELETE https://magiz.ai/api/portal/keys/openai \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "message": "API key removed."
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
422رمز المزود غير معروف.

GET/api/portal/conversations

قائمة المحادثات مع عدد غير المقروء ومجاميع الأقسام.

المصادقة رمز Bearer بصلاحية portalصلاحية الدور view-inboxحد المعدل بلا حد على المسار

هو التدفق نفسه الذي يقرؤه صندوق الوارد في لوحة التحكم وتطبيقات الموظفين، حتى لا يختلف الاثنان أبدًا. استخدم filter للتضييق: all أو waiting أو mine أو team أو ai أو resolved. وتعود حتى 60 محادثة، الأكثر إلحاحًا أولًا.

المعاملات

المعاملالنوعمطلوبالوصف
filterstringاختياريفي الاستعلام. تضييق القائمة: all أو waiting أو mine أو team أو ai أو human أو resolved. القيمة الافتراضية all.
conversationuuidاختياريفي الاستعلام. افتح هذه المحادثة وأعدها في active وعلّمها مقروءة.

الطلب

curl "https://magiz.ai/api/portal/conversations?filter=waiting" \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "conversations": [
    {
      "id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
      "chatbot": "Support bot",
      "visitor": "Nadia Karim",
      "email": "nadia@example.test",
      "status": "agent",
      "channel": "website",
      "last_at": "2 minutes ago",
      "preview": "I still have not received the replacement…",
      "escalated": true,
      "unread": 2,
      "tags": [],
      "group": "waiting",
      "handoff_state": "handoff_pending",
      "assigned_to": null,
      "online": true,
      "waiting_seconds": 143
    }
  ],
  "counts": { "all": 412, "ai": 301, "human": 74, "resolved": 37, "unread": 6 },
  "groups": { "waiting": 3, "mine": 5, "team": 12, "ai": 355, "resolved": 37 },
  "listed": 1,
  "list_limit": 60,
  "active": null
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
403الحساب أو مساحة العمل موقوفة.

GET/api/portal/conversations/{conversation}

محادثة واحدة بنصها الكامل، ويضعها في حالة مقروء.

المصادقة رمز Bearer بصلاحية portalصلاحية الدور view-inboxحد المعدل بلا حد على المسار

القراءة تتطلب صلاحية view-inbox فقط، فيستطيع العميل منح زميل له رؤية محادثاته دون القدرة على الرد على العملاء.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl https://magiz.ai/api/portal/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91 \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "active": {
    "id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
    "visitor": "Nadia Karim",
    "email": "nadia@example.test",
    "status": "agent",
    "channel": "website",
    "handoff_state": "human_connected",
    "messages": [
      { "id": 33128, "role": "visitor", "content": "Where is my replacement?", "at": "10:14 AM" },
      { "id": 33129, "role": "assistant", "content": "Let me check that order for you.", "at": "10:14 AM" },
      { "id": 33131, "role": "agent", "content": "It ships tomorrow, tracking to follow.", "at": "10:16 AM", "agent": "Sara" }
    ]
  },
  "conversations": [],
  "counts": { "all": 412, "ai": 301, "human": 74, "resolved": 37, "unread": 5 }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

POST/api/portal/conversations/{conversation}/reply

يرد على الزائر بصفة موظف بشري، ويأخذ المحادثة من الذكاء الاصطناعي.

المصادقة رمز Bearer بصلاحية portalصلاحية الدور handle-conversationsحد المعدل 60 طلب كل 1 دقيقة لكل مستخدم مسجّل

إرسال رد يوقف إجابات الذكاء الاصطناعي في تلك المحادثة ويلغي أي مؤقّت تحويل معلّق. أرسل client_id عند إعادة المحاولة: فإن كانت المحاولة الأولى قد وصلتنا فعلًا، يُعاد الرد المحفوظ بدل أن يصل العميل مرتين.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.
bodystringمطلوبالرد المراد إرساله. حتى 4000 محرف، ولا يجوز أن يكون مسافات فقط.
client_idstringاختياريمعرّفك الخاص لهذا الرد. إعادة إرساله تُرجع الرسالة المُنشأة سلفًا بدل رسالة ثانية. حتى 64 محرفًا.

الطلب

curl -X POST https://magiz.ai/api/portal/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/reply \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "body": "It ships tomorrow, tracking to follow.",
        "client_id": "outbox-8821"
      }'

الاستجابة

{
  "message": {
    "id": 33131,
    "role": "agent",
    "content": "It ships tomorrow, tracking to follow.",
    "at": "10:16 AM"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422كان الرد مسافات فقط.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لهذا المستخدم.

POST/api/portal/conversations/{conversation}/resolve

يغلق المحادثة ويطلق حدث conversation.resolved عبر الويب هوك.

المصادقة رمز Bearer بصلاحية portalصلاحية الدور handle-conversationsحد المعدل بلا حد على المسار

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl -X POST https://magiz.ai/api/portal/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/resolve \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "status": "closed",
  "resolution": "resolved"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

POST/api/portal/conversations/{conversation}/reopen

يعيد فتح محادثة مغلقة ويعيدها إلى الذكاء الاصطناعي.

المصادقة رمز Bearer بصلاحية portalصلاحية الدور handle-conversationsحد المعدل بلا حد على المسار

يحتفظ الزائر بسجله: فإعادة الفتح تكمل الخيط نفسه بدل أن تبدأ خيطًا جديدًا.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl -X POST https://magiz.ai/api/portal/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/reopen \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "status": "bot"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

GET/api/portal/analytics

يُرجع إجماليات المحادثات والرسائل والوحدات والتكلفة لهذا الشهر في مساحة العمل.

المصادقة رمز Bearer بصلاحية portalحد المعدل بلا حد على المسار

الحقل cost بوحدات العملة الكاملة، محوّلًا عن إجماليات الميكروسنت المحفوظة داخليًا. وتبدأ الفترة دائمًا من أول يوم في الشهر الحالي.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/portal/analytics \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": {
    "period": "month",
    "since": "2026-08-01T00:00:00+00:00",
    "conversations": 412,
    "messages": {
      "ai_replies": 1904,
      "human_replies": 233,
      "visitor_messages": 2088,
      "total": 4225
    },
    "tokens": 1874320,
    "cost": 4.216874,
    "messages_used": 3142
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

GET/api/portal/widget-snippet

يُرجع وسم شيفرة التضمين الجاهز للصق لروبوت مساحة العمل.

المصادقة رمز Bearer بصلاحية portalحد المعدل بلا حد على المسار

يختار أول روبوت نشط، وإن لم يوجد فأحدث روبوت أُنشئ.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/portal/widget-snippet \
  -H "Authorization: Bearer $PORTAL_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "data": {
    "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
    "snippet": "<script src=\"https://magiz.ai/widget.js\" data-key=\"cv_9f2a4c7e1b6d3a8f5c0e2b4d\" defer></script>"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
404لا روبوت في مساحة العمل بعد، فلا شيفرة تضمين لإرجاعها.

واجهة تطبيق الموظف

الواجهة خلف تطبيقات الموظفين للهاتف وسطح المكتب. تعمل على صندوق الوارد: قراءة المحادثات والرد والاستلام والإغلاق والوسم واستخدام مساعد الذكاء الاصطناعي ومتابعة الزوار المتصلين وتسجيل جهاز للإشعارات. وحين تكون تطبيقات الطابور أو الحجوزات أو العملاء مفعّلة في مساحة العمل، تدير أيضًا مكتب الاستقبال: طابور اليوم وجدول اليوم وسجل الأشخاص. كل إجراء ينفّذ منطق المستأجر نفسه المستخدم في لوحة التحكم، فيتطابق السلوك تمامًا.

المسار الأساسي/api/agent44 نقطة نهاية

POST/api/agent/login

يبدّل بريدًا وكلمة مرور برمز Bearer لتطبيق الموظف.

المصادقة بدون مصادقة، عامةحد المعدل 10 طلب كل 1 دقيقة لكل عنوان IP

لا يسجّل الدخول هنا إلا المالك والمسؤول والموظف. ويُرفض مقعد المشاهدة، ويُرفض أي حساب مساحة عمله موقوفة. وتتشارك المحاولات عدّاد القفل نفسه مع نموذج الدخول على الويب وواجهة البوابة. عند تفعيل تسجيل الدخول بخطوتين يُرسل الرمز مع البريد وكلمة المرور، ولا تمنح مساحة عمل تشترطه رمزًا لشخص لم يفعّله.

المعاملات

المعاملالنوعمطلوبالوصف
emailstringمطلوبالبريد الإلكتروني لمستخدم في لوحة التحكم. حتى 255 محرفًا.
passwordstringمطلوبكلمة مرور ذلك المستخدم في لوحة التحكم.
device_namestringاختياريتسمية لهذا الجهاز تظهر بجانب الرمز. حتى 120 محرفًا.
codestringاختياريفقط إذا كان تسجيل الدخول بخطوتين مفعّلًا لهذا الحساب: الرمز المكوّن من 6 أرقام من تطبيق المصادقة، أو رمز استرداد، يُرسل مع البريد وكلمة المرور نفسيهما.

الطلب

curl -X POST https://magiz.ai/api/agent/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "email": "sara@acme.test",
        "password": "correct-horse-battery-staple",
        "device_name": "Sara iPhone 15"
      }'

الاستجابة

{
  "token": "42|Yb7Kd1sQvNc3xLmR8sJd0aWnZeH6uT4gPqK1oI5c",
  "expires_at": "2026-09-07T10:14:02+00:00",
  "device_name": "Sara iPhone 15",
  "user": {
    "id": 58,
    "name": "Sara Bell",
    "email": "sara@acme.test",
    "role": "Agent",
    "avatar": "https://cdn.acme.test/avatars/58.png"
  },
  "company": {
    "id": 3,
    "name": "Acme Ltd",
    "plan": "pro"
  }
}

الأخطاء

الحالةسبب حدوثه
401البريد أو كلمة المرور خاطئة. والنص نفسه سواء كان العنوان موجودًا أم لا.
401تسجيل الدخول بخطوتين مفعّل لهذا الحساب: قيمة two_factor هي code_required إن لم يُرسل رمز، وwrong_code إن لم يطابق. ومحاولات الرمز محدودة بست محاولات كل 5 دقائق لكل حساب وعنوان.
403هذا الحساب لا يستطيع إدارة المحادثات، أو مساحة عمله غير متاحة.
403الحقل two_factor قيمته setup_required: تشترط مساحة العمل تسجيل الدخول بخطوتين لهذا الشخص وهو غير مفعّل. يفعّله من ملفه الشخصي على الويب ثم يسجّل الدخول من جديد.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429محاولات كثيرة، من حد المسار أو من قفل الحساب المشترك. وترويسة Retry-After تحدد مدة الانتظار.

POST/api/agent/refresh

يبدّل رمز موظف ما زال صالحًا برمز جديد.

المصادقة رمز Bearer بصلاحية agentحد المعدل 6 طلب كل 60 دقيقة لكل مستخدم مسجّل

جدّد الرمز بعد تجاوزه نصف عمره. ويُترك الرمز القديم لينتهي وحده بدل إلغائه، فلا تُخرج استجابة ضائعة في الطريق جهازًا من حسابه.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl -X POST https://magiz.ai/api/agent/refresh \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "token": "43|Qw9Lm2tRvNc3xLmR8sJd0aWnZeH6uT4gPqK1oI5c",
  "expires_at": "2026-09-07T11:02:31+00:00",
  "device_name": "Sara iPhone 15",
  "user": {
    "id": 58,
    "name": "Sara Bell",
    "email": "sara@acme.test",
    "role": "Agent",
    "avatar": "https://cdn.acme.test/avatars/58.png"
  },
  "company": {
    "id": 3,
    "name": "Acme Ltd",
    "plan": "pro"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
403الحقل two_factor قيمته setup_required: أصبحت مساحة العمل تشترط تسجيل الدخول بخطوتين لهذا الشخص وهو غير مفعّل. يُحذف الرمز، فسجّل الدخول من جديد بعد تفعيله.
429تم بلوغ حد المسار لهذا المستخدم.

GET/api/agent/me

يُرجع الموظف المسجّل ومساحة عمله وموعد انتهاء الرمز الحالي.

المصادقة رمز Bearer بصلاحية agentحد المعدل بلا حد على المسار

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/agent/me \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "user": {
    "id": 58,
    "name": "Sara Bell",
    "email": "sara@acme.test",
    "role": "Agent",
    "avatar": "https://cdn.acme.test/avatars/58.png"
  },
  "company": {
    "id": 3,
    "name": "Acme Ltd",
    "plan": "pro"
  },
  "expires_at": "2026-09-07T10:14:02+00:00",
  "device_name": "Sara iPhone 15"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

POST/api/agent/logout

يلغي رمز الموظف المستخدم في النداء.

المصادقة رمز Bearer بصلاحية agentحد المعدل بلا حد على المسار

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl -X POST https://magiz.ai/api/agent/logout \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "message": "Signed out."
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

POST/api/agent/broadcasting/auth

يصرّح باشتراك قناة لحظية لتطبيق يحمل رمزًا بدل كوكي الجلسة.

المصادقة رمز Bearer بصلاحية agentحد المعدل بلا حد على المسار

نقطة البث في Laravel تتوقع كوكي جلسة لا تملكه التطبيقات. وهذه هي منطق التصريح نفسه لكن عبر رمز Bearer.

المعاملات

المعاملالنوعمطلوبالوصف
socket_idstringمطلوبمعرّف الاتصال الذي يمنحه الاتصال اللحظي.
channel_namestringمطلوباسم القناة المراد الاشتراك فيها.

الطلب

curl -X POST https://magiz.ai/api/agent/broadcasting/auth \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "socket_id": "812734.1904221",
        "channel_name": "private-company.3"
      }'

الاستجابة

{
  "auth": "reverbappkey:6f1c0a9b8e7d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
403حامل الرمز غير مسموح له بتلك القناة.

GET/api/agent/inbox

يُرجع تغذية صندوق الوارد: قائمة المحادثات وعدّادات غير المقروء وإجماليات الأقسام.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور view-inboxحد المعدل بلا حد على المسار

تحمل الاستجابة الواحدة ستين صفًا كحد أقصى، بينما يعدّ الحقل groups صندوق الوارد كله، فاستخدم filter للوصول إلى بقية القسم. وتمرير conversation يُرجع تلك المحادثة في active ويعلّمها مقروءة.

المعاملات

المعاملالنوعمطلوبالوصف
filterstringاختياريفي الاستعلام. تضييق القائمة: all أو waiting أو mine أو team أو ai أو human أو resolved. القيمة الافتراضية all.
conversationuuidاختياريفي الاستعلام. افتح هذه المحادثة وأعدها في active وعلّمها مقروءة.

الطلب

curl "https://magiz.ai/api/agent/inbox?filter=waiting" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "conversations": [
    {
      "id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
      "chatbot": "Support bot",
      "visitor": "Nadia Karim",
      "email": "nadia@example.test",
      "status": "agent",
      "channel": "website",
      "last_at": "2 minutes ago",
      "preview": "I still have not received the replacement…",
      "escalated": true,
      "unread": 2,
      "resolution": null,
      "tags": [
        { "id": 4, "name": "Delivery", "color": "#0a7d5f" }
      ],
      "group": "waiting",
      "handoff_state": "handoff_pending",
      "assigned_to": null,
      "mine": false,
      "online": true,
      "waiting_seconds": 143
    }
  ],
  "counts": {
    "all": 412,
    "ai": 301,
    "human": 74,
    "resolved": 37,
    "unread": 6
  },
  "groups": {
    "waiting": 3,
    "mine": 5,
    "team": 12,
    "ai": 355,
    "resolved": 37
  },
  "listed": 1,
  "list_limit": 60,
  "active": null
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

GET/api/agent/conversations/{conversation}

يُرجع محادثة واحدة كاملة مع نصها وملف الزائر والوسوم والملاحظات والأحداث.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور view-inboxحد المعدل بلا حد على المسار

هذه نقطة صندوق الوارد نفسها مع اختيار المحادثة مسبقًا، فالمحتوى بالشكل ذاته وتصلك المحادثة المطلوبة في active. ومعرّف غير موجود في مساحة العمل ليس خطأ: تحصل على 200 مع active مساويًا لـ null. وفتح المحادثة يعلّمها مقروءة.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "conversations": [],
  "counts": { "all": 412, "ai": 301, "human": 74, "resolved": 37, "unread": 6 },
  "groups": { "waiting": 3, "mine": 5, "team": 12, "ai": 355, "resolved": 37 },
  "listed": 0,
  "list_limit": 60,
  "active": {
    "id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
    "status": "agent",
    "resolution": null,
    "resolved_at": null,
    "handoff_requested_at": "Aug 8, 2026 · 10:41 AM",
    "escalated": true,
    "resolved_by_ai": false,
    "events": [
      { "type": "human_connected", "source": "agent", "at": "Aug 8 · 10:42 AM" }
    ],
    "tags": [
      { "id": 4, "name": "Delivery", "color": "#0a7d5f", "source": "manual" }
    ],
    "tag_suggestions": [
      { "id": 71, "name": "Refund", "confidence": 0.82, "reason": "Visitor asked for money back." }
    ],
    "visitor": "Nadia Karim",
    "chatbot": "Support bot",
    "channel": "website",
    "email": "nadia@example.test",
    "phone": null,
    "page": "https://acme.test/orders/8812",
    "locale": "en",
    "joined": "Aug 8, 2026",
    "msg_count": 9,
    "group": "mine",
    "handoff_state": "human_connected",
    "assigned_to": "Sara Bell",
    "mine": true,
    "online": true,
    "last_seen": "12 seconds ago",
    "waiting_seconds": null,
    "referrer": "https://www.google.com/",
    "entry_page": "https://acme.test/",
    "device": "mobile",
    "browser": "Safari",
    "os": "iOS",
    "country": "AE",
    "timezone": "Asia/Dubai",
    "page_views": 6,
    "prechat": [
      { "field": "name", "value": "Nadia Karim" },
      { "field": "email", "value": "nadia@example.test" }
    ],
    "prechat_greeting": "Before we start, please introduce yourself.",
    "journey": [
      { "url": "https://acme.test/orders/8812", "at": "Aug 8 · 10:38 AM" },
      { "url": "https://acme.test/", "at": null }
    ],
    "revenue_cents": 24900,
    "revenue_amount": 249.0,
    "revenue_currency": "AED",
    "revenue_label": "AED 249.00",
    "summary": "Replacement for order 8812 never arrived; courier shows delivered.",
    "summary_at": "3 minutes ago",
    "intent": "support",
    "lead_id": 233,
    "lead_status": "new",
    "messages": [
      { "id": 33126, "role": "visitor", "content": "I still have not received the replacement.", "at": "10:41 AM" },
      { "id": 33127, "role": "agent", "content": "Let me pull up the courier record now.", "at": "10:42 AM" }
    ],
    "notes": [
      { "id": 12, "body": "Courier claims delivered — opening a claim.", "author": "Sara Bell", "at": "Aug 8 · 10:44 AM" }
    ],
    "watchers": [],
    "watching": false,
    "detected_language": "en",
    "routed_by": "VIP customers",
    "blocked": false,
    "abuse_strikes": 0
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

POST/api/agent/conversations/{conversation}/reply

يرسل رد الموظف ويوصله عبر القناة التي تجري عليها المحادثة.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل بلا حد على المسار

إرسال رد يستلم المحادثة تلقائيًا. ومرّر client_id من صندوق صادر يعمل دون اتصال لتصبح إعادة المحاولة آمنة: تكرار المعرّف نفسه يُرجع الرسالة المُنشأة سلفًا ويضبط duplicate على true بدل إرسال رسالة ثانية.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.
bodystringمطلوبالرد المراد إرساله. حتى 4000 محرف، ولا يجوز أن يكون مسافات فقط.
client_idstringاختياريمعرّفك الخاص لهذا الرد. إعادة إرساله تُرجع الرسالة المُنشأة سلفًا بدل رسالة ثانية. حتى 64 محرفًا.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/reply \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "body": "I have opened a claim with the courier and posted a replacement today.",
        "client_id": "outbox-2026-08-08-0007"
      }'

الاستجابة

{
  "message": {
    "id": 33131,
    "role": "agent",
    "content": "I have opened a claim with the courier and posted a replacement today.",
    "at": "10:47 AM"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422كان الرد مسافات فقط.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.

GET/api/agent/attachments/options

ما يستطيع هذا الموظف إرفاقه: الأنواع المقبولة، وحد الحجم، وعدد الملفات في الإرسالة الواحدة.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور view-inboxحد المعدل بلا حد على المسار

اقرأه عند تشغيل التطبيق بدل تثبيت الحدود في الكود، ليصل أي تغيير في المنصة إلى تطبيق مثبَّت دون انتظار إصدار جديد في المتجر.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/agent/attachments/options \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "accept": "image/jpeg,.jpg,image/png,.png,image/gif,.gif,image/webp,.webp,application/pdf,.pdf,text/plain,.txt,text/csv,.csv,…",
  "max_bytes": 2097152,
  "max_label": "2 MB",
  "max_files": 5,
  "types_label": "JPG, PNG, GIF, WEBP, PDF, TXT, CSV, DOCX, XLSX or PPTX"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

POST/api/agent/conversations/{conversation}/attachments

يرسل من ملف إلى خمسة ملفات إلى الزائر، مع تعليق اختياري.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 30 طلب كل 1 دقيقة لكل مستخدم مسجّل

إرسال ملف هو رد: يأخذ المحادثة تمامًا كما يفعل الرد النصي، ويصل الملف عبر القناة التي يستخدمها الزائر. وترجع الدفعة الجزئية برمز 207 مع الرسائل التي أُرسلت والملفات التي رُفضت، لأن إهدار عمل نجح بالفعل أسوأ من نتيجة مختلطة.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.
files[]fileمطلوبمن ملف إلى خمسة ملفات، تُرسل بصيغة multipart. وأي نوع غير مقبول أو يتجاوز حد الحجم يُرفض ملفًا ملفًا.
captionstringاختيارينص يُرسل مع الملف الأول. أما البقية فتحمل أسماء ملفاتها.
client_idstringاختياريمعرّفك الخاص لهذا الرد. إعادة إرساله تُرجع الرسالة المُنشأة سلفًا بدل رسالة ثانية. حتى 64 محرفًا.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/attachments \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json" \
  -F "files[]=@/path/to/replacement-label.pdf" \
  -F "caption=Here is the return label." \
  -F "client_id=outbox-2026-08-08-0008"

الاستجابة

{
  "messages": [
    {
      "id": 33140,
      "role": "agent",
      "content": "Here is the return label.",
      "at": "10:52 AM",
      "attachment": {
        "id": "at_5b1c9d3e7a2f",
        "url": "https://example.com/inbox/attachments/at_5b1c9d3e7a2f",
        "thumb_url": null,
        "is_image": false,
        "name": "replacement-label.pdf",
        "mime": "application/pdf",
        "kind": "document",
        "size": 84213,
        "size_label": "82 KB"
      }
    }
  ],
  "errors": []
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
207أُرسل بعض الملفات ورُفض بعضها. وتحمل الاستجابة القائمتين معًا.
422لم يُرسل أي ملف. رُفضت كل ملفات الدفعة، ويبين errors سبب رفض كل ملف.
429تم بلوغ حد المسار لهذا المستخدم.

POST/api/agent/conversations/{conversation}/takeover

ينتزع المحادثة من الذكاء الاصطناعي ويسندها إلى الموظف المنادي.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل بلا حد على المسار

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/takeover \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "status": "agent"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

POST/api/agent/conversations/{conversation}/release

يعيد المحادثة إلى الذكاء الاصطناعي.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل بلا حد على المسار

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/release \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "status": "bot"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

POST/api/agent/conversations/{conversation}/resolve

يغلق المحادثة بوصفها محلولة.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل بلا حد على المسار

المحادثة المحلولة تُفتح من تلقاء نفسها إن عاد الزائر برسالة جديدة.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/resolve \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "status": "closed",
  "resolution": "resolved"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

POST/api/agent/conversations/{conversation}/reopen

يعيد فتح محادثة مغلقة ويسلّمها إلى الذكاء الاصطناعي.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل بلا حد على المسار

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/reopen \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "status": "bot"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

GET/api/agent/tags

يسرد فهرس وسوم مساحة العمل.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور view-inboxحد المعدل بلا حد على المسار

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/agent/tags \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "tags": [
    { "id": 4, "name": "Delivery", "color": "#0a7d5f" },
    { "id": 5, "name": "Refund", "color": "#b4531f" }
  ]
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

POST/api/agent/conversations/{conversation}/tags

يربط وسمًا من الفهرس بمحادثة.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور view-inboxحد المعدل بلا حد على المسار

يجب أن يكون الوسم موجودًا في فهرس مساحة العمل؛ أنشئ الوسوم من لوحة التحكم.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.
tag_idintegerمطلوبمعرّف وسم موجود سلفًا في فهرس مساحة العمل.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/tags \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "tag_id": 4 }'

الاستجابة

{
  "attached": 4
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.

DELETE/api/agent/conversations/{conversation}/tags/{tag}

يزيل وسمًا من محادثة.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور view-inboxحد المعدل بلا حد على المسار

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.
tagintegerمطلوبفي المسار. معرّف الوسم.

الطلب

curl -X DELETE https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/tags/4 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "detached": 4
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

GET/api/agent/canned

يسرد الردود الجاهزة المتاحة لهذا الموظف، الأكثر استخدامًا أولًا.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور view-inboxحد المعدل بلا حد على المسار

الردود المشتركة مع ردود هذا الموظف، مرتبة حسب تكرار الاستخدام.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/agent/canned \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "canned": [
    {
      "id": 19,
      "title": "Courier claim opened",
      "shortcut": "/claim",
      "body": "I have opened a claim with the courier. You will hear from us within one working day."
    }
  ]
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

POST/api/agent/canned/{canned}/used

يسجّل أن ردًا جاهزًا أُدرج، ليستمر الترتيب في التعلم.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل بلا حد على المسار

لا يعلّم الموظف ردًا مستخدمًا إلا إن كان مشتركًا أو خاصًا به.

المعاملات

المعاملالنوعمطلوبالوصف
cannedintegerمطلوبفي المسار. معرّف الرد الجاهز.

الطلب

curl -X POST https://magiz.ai/api/agent/canned/19/used \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "ok": true
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
403الرد الجاهز يخص موظفًا آخر وليس مشتركًا.
404لا رد جاهز بهذا المعرّف في مساحة العمل هذه.

GET/api/agent/conversations/{conversation}/customer-context

يُرجع طلبات Shopify واشتراك Stripe للزائر من أجل لوحة العميل.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور view-inboxحد المعدل بلا حد على المسار

يتراجع التكاملان بلطف بدل الفشل. يكون connected مساويًا لـ false حين لا تكون مساحة العمل قد ربطت تلك الخدمة؛ فيأتي shopify.orders مصفوفة فارغة وstripe.data مساويًا لـ null. ويأتي stripe.data أيضًا بالشكل {"found": false} حين يكون Stripe مربوطًا لكن لا عميل يطابق بريد الزائر.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/customer-context \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "email": "nadia@example.test",
  "shopify": {
    "connected": true,
    "orders": [
      {
        "name": "#8812",
        "total": "249.00 AED",
        "financial_status": "paid",
        "fulfillment_status": "fulfilled",
        "created_at": "Aug 1, 2026",
        "url": "https://acme.test/account/orders/5541882"
      }
    ]
  },
  "stripe": {
    "connected": true,
    "data": {
      "found": true,
      "customer": {
        "name": "Nadia Karim",
        "email": "nadia@example.test"
      },
      "subscriptions": [
        {
          "status": "active",
          "plan": "Care Plus",
          "amount": "29.00 AED",
          "renews": "Sep 1, 2026"
        }
      ]
    }
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
404لا سجل بهذا المعرّف في مساحة العمل هذه.

POST/api/agent/conversations/{conversation}/revenue

يضبط أو يمسح قيمة الصفقة المنسوبة إلى محادثة.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل بلا حد على المسار

أرسل amount مساويًا لـ null لمسح القيمة. وتعود العملة إلى المحفوظ في المحادثة، ثم إلى USD.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.
amountnumberاختياريقيمة الصفقة بوحدات العملة الكاملة، حتى 100,000,000. أرسل null لمسحها.
currencystringاختياريرمز العملة من ثلاثة أحرف. ويعود إلى القيمة المحفوظة في المحادثة، ثم إلى USD.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/revenue \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "amount": 249, "currency": "AED" }'

الاستجابة

{
  "revenue_cents": 24900,
  "revenue_amount": 249.0,
  "revenue_currency": "AED",
  "revenue_label": "AED 249.00"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.

POST/api/agent/conversations/{conversation}/lead

يحفظ بيانات التواصل الملتقطة في المحادثة بوصفها عميلًا محتملًا.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل بلا حد على المسار

يحتاج إلى اسم أو بريد أو هاتف ملتقط سلفًا في المحادثة، وإلا فلا شيء ليُحفظ.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/lead \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "lead": {
    "id": 233,
    "status": "new",
    "source": "manual"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422لم يُلتقط اسم ولا بريد ولا هاتف في هذه المحادثة بعد.

POST/api/agent/conversations/{conversation}/suggest

يصوغ ردًا مقترحًا للموظف مستندًا إلى معرفة الروبوت.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 30 طلب كل 1 دقيقة لكل مستخدم مسجّل

يكلف نداء ذكاء اصطناعي واحدًا. وحين لا يوجد ما يُجاب عنه بعد، أو لا مفتاح مزود مهيأ، يُرجع النداء 200 مع suggestion مساوٍ لـ null. واحتفظ بالحقل id المُعاد لتبلغ عن النتيجة لاحقًا.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.
draftstringاختياريما كتبه الموظف حتى الآن ليبني عليه الاقتراح. حتى 4000 محرف.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/suggest \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "draft": "tell her the claim is open" }'

الاستجابة

{
  "id": 1204,
  "suggestion": "I have opened a claim with the courier for order #8812 and posted a replacement today. You will get a new tracking link by email within the hour."
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لهذا المستخدم.

POST/api/agent/conversations/{conversation}/enhance

يعيد صياغة مسودة الموظف نحويًا أو أسلوبيًا.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 30 طلب كل 1 دقيقة لكل مستخدم مسجّل

يكلف نداء ذكاء اصطناعي واحدًا. وإن تعذر على النموذج تحسين النص عاد الأصل مع enhanced مساوٍ لـ false.

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.
bodystringمطلوبالمسودة المراد إعادة صياغتها. حتى 4000 محرف، ولا يجوز أن تكون مسافات فقط.
modestringاختياريالقيمة fix أو professional أو friendly أو concise أو expand. الافتراضية fix.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/enhance \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "body": "claim is open, replacement sent today",
        "mode": "professional"
      }'

الاستجابة

{
  "text": "The claim is open and a replacement was posted today.",
  "enhanced": true
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422كانت المسودة مسافات فقط.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لهذا المستخدم.

POST/api/agent/conversations/{conversation}/summary

يولّد ملخصًا داخليًا قصيرًا للمحادثة.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 30 طلب كل 1 دقيقة لكل مستخدم مسجّل

المعاملات

المعاملالنوعمطلوبالوصف
conversationuuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.

الطلب

curl -X POST https://magiz.ai/api/agent/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/summary \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "summary": "Replacement for order 8812 never arrived; courier shows delivered. Claim opened, replacement posted.",
  "summary_at": "a few seconds ago"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا سجل بهذا المعرّف في مساحة العمل هذه.
422تعذّر توليد ملخص الآن.
429تم بلوغ حد المسار لهذا المستخدم.

POST/api/agent/suggestion/{suggestion}/outcome

يسجّل ما فعله الموظف باقتراح الذكاء الاصطناعي.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 60 طلب كل 1 دقيقة لكل مستخدم مسجّل

أبلغ بـ generated أو inserted أو edited أو dismissed لتبقى جودة المساعد قابلة للقياس.

المعاملات

المعاملالنوعمطلوبالوصف
suggestionintegerمطلوبفي المسار. المعرّف الذي أعادته نقطة suggest.
outcomestringمطلوبالقيمة generated أو inserted أو edited أو dismissed.

الطلب

curl -X POST https://magiz.ai/api/agent/suggestion/1204/outcome \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "outcome": "edited" }'

الاستجابة

{
  "ok": true
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا اقتراح بهذا المعرّف في مساحة العمل هذه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لهذا المستخدم.

GET/api/agent/visitors

يسرد كل من يتصفح مواقع مساحة العمل الآن، بمن فيهم من لم يفتح الدردشة.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور view-inboxحد المعدل بلا حد على المسار

يخبرك enabled إن كان أي روبوت نشط قد فُعّلت فيه ميزة الزوار المتصلين. والحقل poll_seconds هو الفاصل الذي يريده الخادم، فاقرأه بدل تثبيت رقم في الشيفرة.

المعاملات

المعاملالنوعمطلوبالوصف
limitintegerاختياريفي الاستعلام. عدد الزوار المطلوب إرجاعه. يُحصر بين 1 و200، والافتراضي 100.

الطلب

curl "https://magiz.ai/api/agent/visitors?limit=50" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "visitors": [
    {
      "id": "90211",
      "visitor_id": "v_2c9a71b4e5",
      "session_token": "ps_5f1c0a9b8e7d5c4b3a2f1e0d",
      "label": "Nadia Karim",
      "short": "2C9A",
      "name": "Nadia Karim",
      "email": "nadia@example.test",
      "current_url": "https://acme.test/orders/8812",
      "current_title": "Order 8812",
      "entry_url": "https://acme.test/",
      "referrer": "https://www.google.com/",
      "country": "AE",
      "device": "mobile",
      "browser": "Safari",
      "os": "iOS",
      "page_views": 6,
      "seconds_on_site": 412,
      "last_seen_at": "2026-08-08T10:46:51+00:00",
      "started_at": "2026-08-08T10:39:59+00:00",
      "state": "chatting",
      "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
      "unread": 2,
      "chatbot": "Support bot"
    }
  ],
  "counts": {
    "total": 1,
    "browsing": 0,
    "chatting": 1,
    "waiting": 0
  },
  "poll_seconds": 25,
  "enabled": true
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

POST/api/agent/visitors/{visitor}/invite

يبدأ محادثة مع زائر يتصفح بإرسال أول رسالة إليه.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور view-inboxحد المعدل 30 طلب كل 1 دقيقة لكل مستخدم مسجّل

ينشئ محادثة إن لم تكن للزائر واحدة، ويعلّمها بأن يديرها بشر كي لا يتحدث الذكاء الاصطناعي فوقك، ويُرجع 201 في هذه الحالة؛ أما الزائر الذي لديه محادثة مفتوحة فيُرجع 200. وإن لم تكن نافذة الدردشة مفتوحة وصلته الرسالة مع نبضته التالية.

المعاملات

المعاملالنوعمطلوبالوصف
visitorstringمطلوبفي المسار. معرّف الزائر من قائمة الزوار المتصلين. يُقتطع إلى 100 محرف.
messagestringمطلوبالجملة الافتتاحية المراد إرسالها. حتى 2000 محرف، ولا يجوز أن تكون مسافات فقط.
chatbot_idintegerاختياريأرسل من هذا الروبوت. وإن تُرك فارغًا يُفضَّل روبوت الزائر نفسه، ثم أي روبوت نشط.

الطلب

curl -X POST https://magiz.ai/api/agent/visitors/v_2c9a71b4e5/invite \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "message": "Hi Nadia — I can see order 8812 on your screen. Want me to check it?" }'

الاستجابة

{
  "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
  "created": true,
  "delivery_within_seconds": 25,
  "message": {
    "id": 33140,
    "role": "agent",
    "content": "Hi Nadia — I can see order 8812 on your screen. Want me to check it?",
    "at": "10:52 AM"
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
404معرّف الزائر أصبح فارغًا بعد الاقتطاع.
409لم يعد ذلك الزائر على الموقع.
422لا روبوت نشط في مساحة العمل للإرسال منه.
429تم بلوغ حد المسار لهذا المستخدم.
500تعذّر بدء الدردشة. ولم يُحفظ شيء، فالمحاولة من جديد آمنة.

GET/api/agent/push/vapid

يُرجع المفتاح العام الذي يحتاجه الجهاز قبل الاشتراك في الإشعارات.

المصادقة رمز Bearer بصلاحية agentحد المعدل بلا حد على المسار

يكون configured مساويًا لـ false على خادم لم تُهيَّأ فيه الإشعارات قط، ما يتيح للتطبيق شرح الوضع بدل الفشل عند خطوة الاشتراك.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/agent/push/vapid \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "configured": true,
  "public_key": "BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

POST/api/agent/push/subscribe

يسجّل جهازًا لاستقبال الإشعارات الفورية.

المصادقة رمز Bearer بصلاحية agentحد المعدل 20 طلب كل 1 دقيقة لكل مستخدم مسجّل

يحدّث السجل أو ينشئه اعتمادًا على endpoint، لأن المتصفحات تعيد إصدار الاشتراك كلما دوّرته خدمة الإشعارات. وإعادة إرسال endpoint موجود تحدّث السجل بدل إنشاء ثانٍ.

المعاملات

المعاملالنوعمطلوبالوصف
endpointurlمطلوبعنوان الإشعارات الذي يصدره المتصفح. يجب أن يكون رابط https، حتى 2048 محرفًا.
keysobjectمطلوبزوج مفاتيح الاشتراك من المتصفح.
keys.p256dhstringمطلوبمفتاح p256dh من اشتراك المتصفح. حتى 255 محرفًا.
keys.authstringمطلوبسر auth من اشتراك المتصفح. حتى 255 محرفًا.
device_namestringاختياريتسمية لهذا الجهاز تظهر بجانب الرمز. حتى 120 محرفًا.
platformstringاختياريالقيمة ios أو android أو desktop.

الطلب

curl -X POST https://magiz.ai/api/agent/push/subscribe \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "endpoint": "https://web.push.apple.com/QK9x2m4Lp0",
        "keys": {
          "p256dh": "BJx7Qm2f0aLd9k3sVn1cRt8yUu5oWq4eZa6hGi2jKl0",
          "auth": "9fK2sQ7vN1cX3mLp"
        },
        "device_name": "Sara iPhone 15",
        "platform": "ios"
      }'

الاستجابة

{
  "ok": true,
  "id": 77,
  "devices": 2
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
422العنوان ليس رابط https، فلا يمكن أن يكون خدمة إشعارات حقيقية.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لهذا المستخدم.
500تعذّر تسجيل الجهاز للتنبيهات.

DELETE/api/agent/push/subscribe

يزيل اشتراك الإشعارات لهذا الجهاز.

المصادقة رمز Bearer بصلاحية agentحد المعدل بلا حد على المسار

محصور بالمنادي، فلا يُستعمل endpoint مسرَّب لقطع تنبيهات موظف آخر.

المعاملات

المعاملالنوعمطلوبالوصف
endpointstringمطلوبعنوان الإشعارات المراد حذفه. حتى 2048 محرفًا.

الطلب

curl -X DELETE https://magiz.ai/api/agent/push/subscribe \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "endpoint": "https://web.push.apple.com/QK9x2m4Lp0" }'

الاستجابة

{
  "ok": true,
  "removed": 1
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.

POST/api/agent/push/test

يرسل تنبيهًا تجريبيًا حقيقيًا إلى أجهزة الموظف المنادي.

المصادقة رمز Bearer بصلاحية agentحد المعدل 6 طلب كل 1 دقيقة لكل مستخدم مسجّل

يتجاهل ساعات الهدوء ووضع عدم الإزعاج عن قصد: من يطلب اختبار التسليم يريد أن يعرف هل يعمل.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl -X POST https://magiz.ai/api/agent/push/test \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "ok": true,
  "result": {
    "sent": 2,
    "failed": 0,
    "pruned": 0
  }
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
422لم يستلم أي جهاز الاختبار. اسمح بالإشعارات على الجهاز ثم أعد المحاولة.
429تم بلوغ حد المسار لهذا المستخدم.
503الإشعارات الفورية غير مهيأة على هذا الخادم.

GET/api/agent/settings/notifications

يُرجع تفضيلات تنبيهات هذا الموظف وحالة توفره وأجهزته المسجلة.

المصادقة رمز Bearer بصلاحية agentحد المعدل بلا حد على المسار

تُطبَّق هذه التفضيلات على الخادم قبل إرسال أي تنبيه، فهذه هي النقطة الوحيدة التي يقرر فيها الموظف هل يرن هاتفه.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl https://magiz.ai/api/agent/settings/notifications \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "settings": {
    "push_enabled": true,
    "sound_enabled": true,
    "vibrate_enabled": true,
    "email_enabled": false,
    "events": {
      "visitor_arrived":   { "push": false, "sound": null,     "label": "Visitor arrived",   "critical": false },
      "chat_started":      { "push": true,  "sound": "chime",  "label": "Chat started",      "critical": false },
      "visitor_message":   { "push": true,  "sound": "chime",  "label": "Visitor message",   "critical": false },
      "handoff_requested": { "push": true,  "sound": "urgent", "label": "Handoff requested", "critical": true  },
      "sla_breach":        { "push": true,  "sound": "urgent", "label": "SLA breach",        "critical": true  }
    },
    "sound_pack": "default",
    "volume": 70,
    "quiet_hours_start": "22:00",
    "quiet_hours_end": "07:00",
    "quiet_hours_tz": "Asia/Dubai",
    "dnd_until": null,
    "quiet_now": false,
    "dnd_now": false,
    "chatbot_filter": null,
    "only_my_conversations": false
  },
  "availability": "online",
  "push": {
    "configured": true,
    "public_key": "BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U",
    "devices": 2
  },
  "chatbots": [
    { "id": 7, "name": "Support bot" }
  ]
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.

PUT/api/agent/settings/notifications

يحدّث تفضيلات تنبيهات هذا الموظف وحالة توفره.

المصادقة رمز Bearer بصلاحية agentحد المعدل بلا حد على المسار

تحديث جزئي: تتغير الحقول المرسلة فقط، وتُدمج خريطة events بدل استبدالها، فلا تستطيع نسخة تطبيق قديمة محو إعداد لا تعرفه. وتُتجاهل مفاتيح الأحداث غير المعروفة.

المعاملات

المعاملالنوعمطلوبالوصف
push_enabledbooleanاختياريالمفتاح الرئيسي للإشعارات الفورية في هذا الحساب.
sound_enabledbooleanاختياريهل تصدر التنبيهات صوتًا.
vibrate_enabledbooleanاختياريهل تهتز التنبيهات على الجهاز.
email_enabledbooleanاختياريهل تُرسل التنبيهات بالبريد أيضًا.
eventsobjectاختياريإعدادات لكل حدث، مفهرسة بالحدث: visitor_arrived وchat_started وvisitor_message وhandoff_requested وsla_breach. تُدمج مع المحفوظ.
events.*.pushbooleanاختياريهل يرسل هذا الحدث إشعارًا. مطلوب لكل حدث تضمّنه.
events.*.soundstringاختيارياسم الصوت لهذا الحدث، أو null للافتراضي. حتى 24 محرفًا.
sound_packstringاختيارياسم حزمة الأصوات. حتى 24 محرفًا.
volumeintegerاختياريمستوى صوت التنبيه من 0 إلى 100.
quiet_hours_startstringاختياريبداية ساعات الهدوء بصيغة HH:MM بتوقيت الموظف نفسه.
quiet_hours_endstringاختيارينهاية ساعات الهدوء بصيغة HH:MM. ويجب إرسالها مع البداية.
quiet_hours_tzstringاختياريالمنطقة الزمنية التي تُقرأ بها ساعات الهدوء، مثل Asia/Dubai. حتى 64 محرفًا.
dnd_minutesintegerاختياريإسكات التنبيهات هذا العدد من الدقائق، من 0 إلى 1440. أرسل 0 للإلغاء.
chatbot_filterarrayاختيارينبّه على هذه الروبوتات فقط. وتُسقط المعرّفات خارج مساحة العمل، والنتيجة الفارغة تلغي المرشّح.
only_my_conversationsbooleanاختيارينبّه على المحادثات المسندة إلى هذا الموظف فقط.
availabilitystringاختياريالقيمة online أو away أو offline.

الطلب

curl -X PUT https://magiz.ai/api/agent/settings/notifications \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "push_enabled": true,
        "volume": 70,
        "quiet_hours_start": "22:00",
        "quiet_hours_end": "07:00",
        "quiet_hours_tz": "Asia/Dubai",
        "events": {
          "visitor_arrived": { "push": false, "sound": null }
        },
        "availability": "online"
      }'

الاستجابة

{
  "settings": {
    "push_enabled": true,
    "sound_enabled": true,
    "vibrate_enabled": true,
    "email_enabled": false,
    "events": {
      "visitor_arrived":   { "push": false, "sound": null,     "label": "Visitor arrived",   "critical": false },
      "chat_started":      { "push": true,  "sound": "chime",  "label": "Chat started",      "critical": false },
      "visitor_message":   { "push": true,  "sound": "chime",  "label": "Visitor message",   "critical": false },
      "handoff_requested": { "push": true,  "sound": "urgent", "label": "Handoff requested", "critical": true  },
      "sla_breach":        { "push": true,  "sound": "urgent", "label": "SLA breach",        "critical": true  }
    },
    "sound_pack": "default",
    "volume": 70,
    "quiet_hours_start": "22:00",
    "quiet_hours_end": "07:00",
    "quiet_hours_tz": "Asia/Dubai",
    "dnd_until": null,
    "quiet_now": false,
    "dnd_now": false,
    "chatbot_filter": null,
    "only_my_conversations": false
  },
  "availability": "online"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
422تحتاج ساعات الهدوء إلى بداية ونهاية معًا؛ نصف النافذة لا يفعل شيئًا.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
500تعذّر حفظ الإعدادات.

GET/api/agent/apps

يسرد تبويبات التطبيقات التي يمكن لهذا الشخص فتحها في تطبيقات الموظفين: الطابور والحجوزات والعملاء، كل منها ما دام مفعّلًا لمساحة العمل. لا تُدرج تطبيقات البيانات الصحية أبدًا.

المصادقة رمز Bearer بصلاحية agentحد المعدل 60 طلب كل 1 دقيقة لكل مستخدم مسجّل

يُدرج التطبيق حين يكون مفعّلًا في صفحة التطبيقات ويملك الشخص الصلاحية التي تطلبها شاشاته في لوحة التحكم. اطلب القائمة من جديد كلما عاد التطبيق إلى الواجهة. الخادم الذي لا يعرف هذا المسار يجيب 404: اعرض صندوق الوارد وحده.

المعاملات

لا تأخذ نقطة النهاية هذه أي معاملات.

الطلب

curl "https://magiz.ai/api/agent/apps" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "apps": [
    {
      "id": "queue",
      "title": "Queue",
      "actions": [
        "next",
        "ticket",
        "walk_in",
        "sitting"
      ],
      "poll_seconds": 8
    },
    {
      "id": "bookings",
      "title": "Bookings",
      "actions": [
        "confirm",
        "decline",
        "cancel",
        "completed",
        "no_show"
      ],
      "poll_seconds": 30
    },
    {
      "id": "customers",
      "title": "Patients",
      "label": "patients",
      "actions": [
        "search",
        "profile"
      ],
      "poll_seconds": null
    }
  ]
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
429تم بلوغ حد المسار لهذا المستخدم.

GET/api/agent/queue

طوابير مساحة العمل ومكتب الاستقبال لطابور واحد اليوم: الرقم الحالي، ومن ينتظر بترتيب النداء، ومن فاته دوره، وآخر من خرجوا، وأرقام الجلسة.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 120 طلب كل 1 دقيقة لكل مستخدم مسجّل

الأسماء وأرقام الهواتف للموظفين فقط. ومن حُصر في بعض الفروع لا يرى إلا طوابير تلك الفروع. اطلب من جديد كل poll_seconds ما دامت الشاشة مفتوحة.

المعاملات

المعاملالنوعمطلوبالوصف
lineintegerاختياريفي الاستعلام. الطابور المطلوب عرضه. الافتراضي أول طابور مفعّل.
sittingintegerاختياريفي الاستعلام. الجلسة المطلوب عرضها. الافتراضي الجلسة الجارية، وإلا التالية.

الطلب

curl "https://magiz.ai/api/agent/queue?line=7" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "lines": [
    {
      "id": 7,
      "name": "Dr Sana Wani, room 1",
      "status": "live"
    }
  ],
  "desk": {
    "line": {
      "id": 7,
      "name": "Dr Sana Wani, room 1",
      "status": "live",
      "timezone": "Asia/Kolkata"
    },
    "sittings": [
      {
        "id": 311,
        "slot": 0,
        "starts_at": "2026-10-12T04:30:00.000Z",
        "ends_at": "2026-10-12T07:30:00.000Z",
        "status": "running"
      },
      {
        "id": 312,
        "slot": 1,
        "starts_at": "2026-10-12T11:30:00.000Z",
        "ends_at": "2026-10-12T14:30:00.000Z",
        "status": "idle"
      }
    ],
    "sitting": {
      "id": 311,
      "day": "2026-10-12",
      "slot": 0,
      "status": "running",
      "taking": true,
      "starts_at": "2026-10-12T04:30:00.000Z",
      "ends_at": "2026-10-12T07:30:00.000Z",
      "current_number": 4,
      "in_consult": true,
      "waiting": 2,
      "late_until": null,
      "note": null,
      "avg_seconds": 540,
      "version": 18
    },
    "called": {
      "id": 9014,
      "number": 4,
      "name": "Asma Test",
      "phone": "+919906010001",
      "status": "called",
      "source": "page",
      "arrived": true,
      "emergency": false,
      "misses": 0,
      "taken_at": "2026-10-12T04:41:09.000Z",
      "called_at": "2026-10-12T05:02:40.000Z"
    },
    "waiting": [
      {
        "id": 9015,
        "number": 5,
        "name": "Walk In Test",
        "phone": null,
        "status": "waiting",
        "source": "desk",
        "arrived": true,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      },
      {
        "id": 9016,
        "number": 6,
        "name": null,
        "phone": "+919906010003",
        "status": "waiting",
        "source": "whatsapp",
        "arrived": false,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      }
    ],
    "skipped": [],
    "recent": [
      {
        "id": 9013,
        "number": 3,
        "name": "Imran Test",
        "phone": "+919906010002",
        "status": "done",
        "source": "page",
        "arrived": true,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      }
    ],
    "summary": {
      "taken": 6,
      "seen": 3,
      "unseen": 0,
      "cancelled": 0,
      "open": 3,
      "wait_median": 14
    },
    "at": "2026-10-12T05:06:12.000Z"
  },
  "poll_seconds": 8
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
403app_off: التطبيق معطّل لمساحة العمل. يمكن لمدير مساحة العمل تفعيله من صفحة التطبيقات.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا طابور ولا رقم ولا جلسة بهذا المعرّف في مساحة العمل وفروع هذا الشخص.
429تم بلوغ حد المسار لهذا المستخدم.

POST/api/agent/queue/lines/{line}/next

التالي: يُسجَّل المريض الموجود عند الطبيب على أنه تمت رؤيته، أو غائبًا مع skip، ويُنادى التالي. ومع ticket يُنادى هذا الرقم بدلًا منه.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 240 طلب كل 1 دقيقة لكل مستخدم مسجّل

أرسل رقم إصدار الجلسة من آخر قراءة. الضغطة المبنية على صورة أقدم لا تغيّر شيئًا وتجيب 409 بالرمز stale، فلا تحرّك ضغطتان الطابور مرتين.

المعاملات

المعاملالنوعمطلوبالوصف
lineintegerمطلوبفي المسار. معرّف الطابور.
sittingintegerمطلوبمعرّف الجلسة، من desk.sitting.id.
versionintegerمطلوبقيمة desk.sitting.version من آخر قراءة.
skipbooleanاختياريtrue حين لا يكون المريض الذي نودي موجودًا.
ticketintegerاختياريرقم منتظر أو فائت يُنادى بدل التالي في الدور.

الطلب

curl -X POST https://magiz.ai/api/agent/queue/lines/7/next \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "sitting": 311, "version": 17 }'

الاستجابة

{
  "ok": true,
  "lines": [
    {
      "id": 7,
      "name": "Dr Sana Wani, room 1",
      "status": "live"
    }
  ],
  "desk": {
    "line": {
      "id": 7,
      "name": "Dr Sana Wani, room 1",
      "status": "live",
      "timezone": "Asia/Kolkata"
    },
    "sittings": [
      {
        "id": 311,
        "slot": 0,
        "starts_at": "2026-10-12T04:30:00.000Z",
        "ends_at": "2026-10-12T07:30:00.000Z",
        "status": "running"
      },
      {
        "id": 312,
        "slot": 1,
        "starts_at": "2026-10-12T11:30:00.000Z",
        "ends_at": "2026-10-12T14:30:00.000Z",
        "status": "idle"
      }
    ],
    "sitting": {
      "id": 311,
      "day": "2026-10-12",
      "slot": 0,
      "status": "running",
      "taking": true,
      "starts_at": "2026-10-12T04:30:00.000Z",
      "ends_at": "2026-10-12T07:30:00.000Z",
      "current_number": 4,
      "in_consult": true,
      "waiting": 2,
      "late_until": null,
      "note": null,
      "avg_seconds": 540,
      "version": 18
    },
    "called": {
      "id": 9014,
      "number": 4,
      "name": "Asma Test",
      "phone": "+919906010001",
      "status": "called",
      "source": "page",
      "arrived": true,
      "emergency": false,
      "misses": 0,
      "taken_at": "2026-10-12T04:41:09.000Z",
      "called_at": "2026-10-12T05:02:40.000Z"
    },
    "waiting": [
      {
        "id": 9015,
        "number": 5,
        "name": "Walk In Test",
        "phone": null,
        "status": "waiting",
        "source": "desk",
        "arrived": true,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      },
      {
        "id": 9016,
        "number": 6,
        "name": null,
        "phone": "+919906010003",
        "status": "waiting",
        "source": "whatsapp",
        "arrived": false,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      }
    ],
    "skipped": [],
    "recent": [
      {
        "id": 9013,
        "number": 3,
        "name": "Imran Test",
        "phone": "+919906010002",
        "status": "done",
        "source": "page",
        "arrived": true,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      }
    ],
    "summary": {
      "taken": 6,
      "seen": 3,
      "unseen": 0,
      "cancelled": 0,
      "open": 3,
      "wait_median": 14
    },
    "at": "2026-10-12T05:06:12.000Z"
  },
  "poll_seconds": 8
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
403app_off: التطبيق معطّل لمساحة العمل. يمكن لمدير مساحة العمل تفعيله من صفحة التطبيقات.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا طابور ولا رقم ولا جلسة بهذا المعرّف في مساحة العمل وفروع هذا الشخص.
409stale: تحرّك الطابور من شاشة أخرى. اقرأه من جديد واضغط مرة أخرى.
409لا يمكن للرقم أو الجلسة القيام بهذه الحركة الآن: الرمز ended أو not_live أو not_called أو closed أو full أو stopped.
429تم بلوغ حد المسار لهذا المستخدم.

POST/api/agent/queue/lines/{line}/tickets/{ticket}

رقم واحد: here (في العيادة، أو عاد إلى الدور بعد أن فاته)، وemergency (التالي في الدور)، وcancel، وdone (تمت رؤيته، لا تنادِ أحدًا الآن)، وskip (غير موجود، لا تنادِ أحدًا الآن).

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 240 طلب كل 1 دقيقة لكل مستخدم مسجّل

تُسجَّل كل حركة في سجل الطابور مع اسم من ضغط، كما في مكتب الاستقبال في لوحة التحكم. والرد هو حال الطابور بعد الحركة، بالشكل الذي يعيده GET /api/agent/queue، مع ok ورسالة.

المعاملات

المعاملالنوعمطلوبالوصف
lineintegerمطلوبفي المسار. معرّف الطابور.
ticketintegerمطلوبفي المسار. معرّف الرقم.
opstringمطلوبhere أو emergency أو cancel أو done أو skip.

الطلب

curl -X POST https://magiz.ai/api/agent/queue/lines/7/tickets/9016 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "op": "cancel" }'

الاستجابة

{
  "ok": true,
  "message": "Token 6 is cancelled.",
  "lines": [
    {
      "id": 7,
      "name": "Dr Sana Wani, room 1",
      "status": "live"
    }
  ],
  "desk": {
    "line": {
      "id": 7,
      "name": "Dr Sana Wani, room 1",
      "status": "live",
      "timezone": "Asia/Kolkata"
    },
    "sittings": [
      {
        "id": 311,
        "slot": 0,
        "starts_at": "2026-10-12T04:30:00.000Z",
        "ends_at": "2026-10-12T07:30:00.000Z",
        "status": "running"
      },
      {
        "id": 312,
        "slot": 1,
        "starts_at": "2026-10-12T11:30:00.000Z",
        "ends_at": "2026-10-12T14:30:00.000Z",
        "status": "idle"
      }
    ],
    "sitting": {
      "id": 311,
      "day": "2026-10-12",
      "slot": 0,
      "status": "running",
      "taking": true,
      "starts_at": "2026-10-12T04:30:00.000Z",
      "ends_at": "2026-10-12T07:30:00.000Z",
      "current_number": 4,
      "in_consult": true,
      "waiting": 2,
      "late_until": null,
      "note": null,
      "avg_seconds": 540,
      "version": 18
    },
    "called": {
      "id": 9014,
      "number": 4,
      "name": "Asma Test",
      "phone": "+919906010001",
      "status": "called",
      "source": "page",
      "arrived": true,
      "emergency": false,
      "misses": 0,
      "taken_at": "2026-10-12T04:41:09.000Z",
      "called_at": "2026-10-12T05:02:40.000Z"
    },
    "waiting": [
      {
        "id": 9015,
        "number": 5,
        "name": "Walk In Test",
        "phone": null,
        "status": "waiting",
        "source": "desk",
        "arrived": true,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      },
      {
        "id": 9016,
        "number": 6,
        "name": null,
        "phone": "+919906010003",
        "status": "waiting",
        "source": "whatsapp",
        "arrived": false,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      }
    ],
    "skipped": [],
    "recent": [
      {
        "id": 9013,
        "number": 3,
        "name": "Imran Test",
        "phone": "+919906010002",
        "status": "done",
        "source": "page",
        "arrived": true,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      }
    ],
    "summary": {
      "taken": 6,
      "seen": 3,
      "unseen": 0,
      "cancelled": 0,
      "open": 3,
      "wait_median": 14
    },
    "at": "2026-10-12T05:06:12.000Z"
  },
  "poll_seconds": 8
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
403app_off: التطبيق معطّل لمساحة العمل. يمكن لمدير مساحة العمل تفعيله من صفحة التطبيقات.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا طابور ولا رقم ولا جلسة بهذا المعرّف في مساحة العمل وفروع هذا الشخص.
409لا يمكن للرقم أو الجلسة القيام بهذه الحركة الآن: الرمز ended أو not_live أو not_called أو closed أو full أو stopped.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لهذا المستخدم.

POST/api/agent/queue/lines/{line}/walk-in

يعطي رقمًا من مكتب الاستقبال على الجلسة المعروضة، حتى لو امتلأت أو أوقفت إعطاء الأرقام. الاسم والهاتف اختياريان.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 60 طلب كل 1 دقيقة لكل مستخدم مسجّل

تُسجَّل كل حركة في سجل الطابور مع اسم من ضغط، كما في مكتب الاستقبال في لوحة التحكم. والرد هو حال الطابور بعد الحركة، بالشكل الذي يعيده GET /api/agent/queue، مع ok ورسالة.

المعاملات

المعاملالنوعمطلوبالوصف
lineintegerمطلوبفي المسار. معرّف الطابور.
sittingintegerمطلوبمعرّف الجلسة، من desk.sitting.id.
namestringاختيارياختياري. حتى 80 حرفًا.
phonestringاختيارياختياري. حتى 20 حرفًا مع رمز الدولة.

الطلب

curl -X POST https://magiz.ai/api/agent/queue/lines/7/walk-in \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "sitting": 311, "name": "Walk In Test" }'

الاستجابة

{
  "ok": true,
  "message": "Token 5 added.",
  "ticket": {
    "id": 9015,
    "number": 5
  },
  "lines": [
    {
      "id": 7,
      "name": "Dr Sana Wani, room 1",
      "status": "live"
    }
  ],
  "desk": {
    "line": {
      "id": 7,
      "name": "Dr Sana Wani, room 1",
      "status": "live",
      "timezone": "Asia/Kolkata"
    },
    "sittings": [
      {
        "id": 311,
        "slot": 0,
        "starts_at": "2026-10-12T04:30:00.000Z",
        "ends_at": "2026-10-12T07:30:00.000Z",
        "status": "running"
      },
      {
        "id": 312,
        "slot": 1,
        "starts_at": "2026-10-12T11:30:00.000Z",
        "ends_at": "2026-10-12T14:30:00.000Z",
        "status": "idle"
      }
    ],
    "sitting": {
      "id": 311,
      "day": "2026-10-12",
      "slot": 0,
      "status": "running",
      "taking": true,
      "starts_at": "2026-10-12T04:30:00.000Z",
      "ends_at": "2026-10-12T07:30:00.000Z",
      "current_number": 4,
      "in_consult": true,
      "waiting": 2,
      "late_until": null,
      "note": null,
      "avg_seconds": 540,
      "version": 18
    },
    "called": {
      "id": 9014,
      "number": 4,
      "name": "Asma Test",
      "phone": "+919906010001",
      "status": "called",
      "source": "page",
      "arrived": true,
      "emergency": false,
      "misses": 0,
      "taken_at": "2026-10-12T04:41:09.000Z",
      "called_at": "2026-10-12T05:02:40.000Z"
    },
    "waiting": [
      {
        "id": 9015,
        "number": 5,
        "name": "Walk In Test",
        "phone": null,
        "status": "waiting",
        "source": "desk",
        "arrived": true,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      },
      {
        "id": 9016,
        "number": 6,
        "name": null,
        "phone": "+919906010003",
        "status": "waiting",
        "source": "whatsapp",
        "arrived": false,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      }
    ],
    "skipped": [],
    "recent": [
      {
        "id": 9013,
        "number": 3,
        "name": "Imran Test",
        "phone": "+919906010002",
        "status": "done",
        "source": "page",
        "arrived": true,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      }
    ],
    "summary": {
      "taken": 6,
      "seen": 3,
      "unseen": 0,
      "cancelled": 0,
      "open": 3,
      "wait_median": 14
    },
    "at": "2026-10-12T05:06:12.000Z"
  },
  "poll_seconds": 8
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
403app_off: التطبيق معطّل لمساحة العمل. يمكن لمدير مساحة العمل تفعيله من صفحة التطبيقات.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا طابور ولا رقم ولا جلسة بهذا المعرّف في مساحة العمل وفروع هذا الشخص.
409لا يمكن للرقم أو الجلسة القيام بهذه الحركة الآن: الرمز ended أو not_live أو not_called أو closed أو full أو stopped.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لهذا المستخدم.

POST/api/agent/queue/lines/{line}/sittings/{sitting}

الجلسة: إيقاف مؤقت، استئناف، إيقاف الأرقام الجديدة، استئناف إعطائها، أو إنهاؤها.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 60 طلب كل 1 دقيقة لكل مستخدم مسجّل

تُسجَّل كل حركة في سجل الطابور مع اسم من ضغط، كما في مكتب الاستقبال في لوحة التحكم. والرد هو حال الطابور بعد الحركة، بالشكل الذي يعيده GET /api/agent/queue، مع ok ورسالة.

المعاملات

المعاملالنوعمطلوبالوصف
lineintegerمطلوبفي المسار. معرّف الطابور.
sittingintegerمطلوبفي المسار. معرّف الجلسة.
opstringمطلوبpause أو resume أو stop أو open أو end. الإنهاء يحتسب المريض الموجود في الغرفة على أنه تمت رؤيته ويُلغي كل رقم ما زال ينتظر.

الطلب

curl -X POST https://magiz.ai/api/agent/queue/lines/7/sittings/311 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "op": "pause" }'

الاستجابة

{
  "ok": true,
  "message": "The sitting is paused.",
  "lines": [
    {
      "id": 7,
      "name": "Dr Sana Wani, room 1",
      "status": "live"
    }
  ],
  "desk": {
    "line": {
      "id": 7,
      "name": "Dr Sana Wani, room 1",
      "status": "live",
      "timezone": "Asia/Kolkata"
    },
    "sittings": [
      {
        "id": 311,
        "slot": 0,
        "starts_at": "2026-10-12T04:30:00.000Z",
        "ends_at": "2026-10-12T07:30:00.000Z",
        "status": "running"
      },
      {
        "id": 312,
        "slot": 1,
        "starts_at": "2026-10-12T11:30:00.000Z",
        "ends_at": "2026-10-12T14:30:00.000Z",
        "status": "idle"
      }
    ],
    "sitting": {
      "id": 311,
      "day": "2026-10-12",
      "slot": 0,
      "status": "running",
      "taking": true,
      "starts_at": "2026-10-12T04:30:00.000Z",
      "ends_at": "2026-10-12T07:30:00.000Z",
      "current_number": 4,
      "in_consult": true,
      "waiting": 2,
      "late_until": null,
      "note": null,
      "avg_seconds": 540,
      "version": 18
    },
    "called": {
      "id": 9014,
      "number": 4,
      "name": "Asma Test",
      "phone": "+919906010001",
      "status": "called",
      "source": "page",
      "arrived": true,
      "emergency": false,
      "misses": 0,
      "taken_at": "2026-10-12T04:41:09.000Z",
      "called_at": "2026-10-12T05:02:40.000Z"
    },
    "waiting": [
      {
        "id": 9015,
        "number": 5,
        "name": "Walk In Test",
        "phone": null,
        "status": "waiting",
        "source": "desk",
        "arrived": true,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      },
      {
        "id": 9016,
        "number": 6,
        "name": null,
        "phone": "+919906010003",
        "status": "waiting",
        "source": "whatsapp",
        "arrived": false,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      }
    ],
    "skipped": [],
    "recent": [
      {
        "id": 9013,
        "number": 3,
        "name": "Imran Test",
        "phone": "+919906010002",
        "status": "done",
        "source": "page",
        "arrived": true,
        "emergency": false,
        "misses": 0,
        "taken_at": "2026-10-12T04:41:09.000Z",
        "called_at": null
      }
    ],
    "summary": {
      "taken": 6,
      "seen": 3,
      "unseen": 0,
      "cancelled": 0,
      "open": 3,
      "wait_median": 14
    },
    "at": "2026-10-12T05:06:12.000Z"
  },
  "poll_seconds": 8
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
403app_off: التطبيق معطّل لمساحة العمل. يمكن لمدير مساحة العمل تفعيله من صفحة التطبيقات.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا طابور ولا رقم ولا جلسة بهذا المعرّف في مساحة العمل وفروع هذا الشخص.
409لا يمكن للرقم أو الجلسة القيام بهذه الحركة الآن: الرمز ended أو not_live أو not_called أو closed أو full أو stopped.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لهذا المستخدم.

GET/api/agent/bookings

جدول يوم واحد بتوقيت مساحة العمل: الحجوزات التي تشغل وقتًا في ذلك اليوم، مع بيانات التواصل والتغييرات التي يسمح بها كل حجز الآن.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 120 طلب كل 1 دقيقة لكل مستخدم مسجّل

الحجوزات الملغاة والمرفوضة تحرّر وقتها فلا تظهر. لا تُعاد أبدًا إجابات الحجز ولا الملاحظات الداخلية. ومن حُصر في بعض الفروع لا يرى إلا حجوزات تلك الفروع.

المعاملات

المعاملالنوعمطلوبالوصف
datestringاختياريفي الاستعلام. YYYY-MM-DD بتوقيت مساحة العمل. الافتراضي اليوم.

الطلب

curl "https://magiz.ai/api/agent/bookings?date=2026-10-12" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "date": "2026-10-12",
  "today": "2026-10-12",
  "timezone": "Asia/Kolkata",
  "bookings": [
    {
      "id": 5521,
      "status": "confirmed",
      "kind": "appointment",
      "starts_at": "2026-10-12T04:30:00.000Z",
      "ends_at": "2026-10-12T05:00:00.000Z",
      "timezone": "Asia/Kolkata",
      "name": "Rafiq Test",
      "phone": "+919906040001",
      "email": null,
      "service": "Consultation",
      "staff": "Dr Sana Wani",
      "form": "Chinar Lane Clinic",
      "series": false,
      "actions": [
        "completed",
        "no_show",
        "cancel"
      ]
    },
    {
      "id": 5524,
      "status": "pending",
      "kind": "appointment",
      "starts_at": "2026-10-12T09:00:00.000Z",
      "ends_at": "2026-10-12T09:30:00.000Z",
      "timezone": "Asia/Kolkata",
      "name": "Mehak Test",
      "phone": "+919906040002",
      "email": null,
      "service": "Cleaning",
      "staff": "Dr Sana Wani",
      "form": "Chinar Lane Clinic",
      "series": false,
      "actions": [
        "confirm",
        "decline"
      ]
    },
    {
      "id": 5530,
      "status": "confirmed",
      "kind": "appointment",
      "starts_at": "2026-10-12T11:00:00.000Z",
      "ends_at": "2026-10-12T11:30:00.000Z",
      "timezone": "Asia/Kolkata",
      "name": "Owais Test",
      "phone": null,
      "email": null,
      "service": "Follow-up",
      "staff": "Dr Sana Wani",
      "form": "Chinar Lane Clinic",
      "series": true,
      "actions": [
        "cancel"
      ]
    }
  ],
  "poll_seconds": 30
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
403app_off: التطبيق معطّل لمساحة العمل. يمكن لمدير مساحة العمل تفعيله من صفحة التطبيقات.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
429تم بلوغ حد المسار لهذا المستخدم.

POST/api/agent/bookings/{booking}/status

يغيّر الحجز كما يفعل الموظفون في لوحة التحكم: تأكيد حجز منتظر أو رفضه، وإلغاء حجز مؤكد، ووضع علامة تم أو لم يحضر على حجز بدأ.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 60 طلب كل 1 دقيقة لكل مستخدم مسجّل

يُسجَّل التغيير في سجل النشاط، ويتلقى العميل الرسالة نفسها التي ترسلها لوحة التحكم، وتتلقى سير العمل والـ webhooks حدث الحجز.

المعاملات

المعاملالنوعمطلوبالوصف
bookingintegerمطلوبفي المسار. معرّف الحجز.
actionstringمطلوبconfirm أو decline أو cancel أو completed أو no_show. وتبيّن قائمة actions في كل حجز ما ينطبق الآن.
reasonstringاختيارياختياري مع decline أو cancel. حتى 250 حرفًا.
scopestringاختياريlater مع cancel: هذا الحجز والحجوزات اللاحقة من سلسلته.

الطلب

curl -X POST https://magiz.ai/api/agent/bookings/5521/status \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "action": "completed" }'

الاستجابة

{
  "ok": true,
  "message": "Marked as done",
  "bookings": [
    {
      "id": 5521,
      "status": "completed",
      "actions": []
    }
  ]
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
403app_off: التطبيق معطّل لمساحة العمل. يمكن لمدير مساحة العمل تفعيله من صفحة التطبيقات.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا حجز بهذا المعرّف في مساحة العمل وفروع هذا الشخص.
409لا يمكن للحجز قبول هذا التغيير الآن: الرمز booking_not_pending أو booking_not_active أو booking_not_started أو booking_too_late.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لهذا المستخدم.
501not_available: هذا الخادم لا يستطيع تغيير الحجوزات من تطبيقات الموظفين.

GET/api/agent/customers

يبحث عن الأشخاص بالاسم أو الهاتف أو البريد، الأحدث تعديلًا أولًا. وبلا q يعيد أحدث الأشخاص.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 60 طلب كل 1 دقيقة لكل مستخدم مسجّل

المعاملات

المعاملالنوعمطلوبالوصف
qstringاختياريفي الاستعلام. اسم أو هاتف أو بريد. البحث بالهاتف يتجاهل المسافات ورمز الدولة.

الطلب

curl "https://magiz.ai/api/agent/customers?q=asha" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "q": "asha",
  "people": [
    {
      "id": 812,
      "name": "Asha Test",
      "phone": "+919906011111",
      "email": "asha@example.test"
    }
  ],
  "total": 1,
  "label": "patients",
  "title": "Patients"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
403app_off: التطبيق معطّل لمساحة العمل. يمكن لمدير مساحة العمل تفعيله من صفحة التطبيقات.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
429تم بلوغ حد المسار لهذا المستخدم.

GET/api/agent/customers/{person}

ملف مختصر: بيانات التواصل، والحجوزات القادمة والأخيرة، وعدد الفواتير المفتوحة ما دام تطبيق الفواتير مفعّلًا.

المصادقة رمز Bearer بصلاحية agentصلاحية الدور handle-conversationsحد المعدل 60 طلب كل 1 دقيقة لكل مستخدم مسجّل

لا تُعاد ملاحظة الشخص أبدًا. والسجل المدمج في غيره يجيب بالسجل الذي صار إليه. وتكون قيمة open_invoices هي null ما دام تطبيق الفواتير معطّلًا.

المعاملات

المعاملالنوعمطلوبالوصف
personintegerمطلوبفي المسار. معرّف الشخص.

الطلب

curl "https://magiz.ai/api/agent/customers/812" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Accept: application/json"

الاستجابة

{
  "person": {
    "id": 812,
    "name": "Asha Test",
    "phone": "+919906011111",
    "email": "asha@example.test",
    "guardian": null,
    "tags": [
      "regular"
    ]
  },
  "bookings": {
    "upcoming": [
      {
        "id": 5590,
        "at": "2026-10-20T05:30:00.000Z",
        "service": "Cleaning",
        "status": "confirmed"
      }
    ],
    "recent": [
      {
        "id": 5402,
        "at": "2026-09-28T06:00:00.000Z",
        "service": "Check-up",
        "status": "completed"
      }
    ]
  },
  "open_invoices": 1,
  "label": "patients",
  "title": "Patients"
}

الأخطاء

الحالةسبب حدوثه
401لم يُرسل رمز صالح.
403الحساب أو مساحة العمل موقوفة.
403app_off: التطبيق معطّل لمساحة العمل. يمكن لمدير مساحة العمل تفعيله من صفحة التطبيقات.
403الرمز صالح، لكن دور المستخدم لا يمنح هذا الإجراء.
404لا شخص بهذا المعرّف في مساحة العمل هذه.
429تم بلوغ حد المسار لهذا المستخدم.

نقاط الأداة

النقاط العامة التي تناديها شيفرة التضمين من متصفحات زوارك. وُثِّقت لتتمكن من تصحيح تركيب أو بناء واجهة دردشة خاصة بك. وهي ليست واجهة تكامل، ولا تقبل أي منها رمز وصول.

المسار الأساسي/widget/{key}7 نقطة نهاية

GET/widget/{key}/config

يُرجع الإعدادات العامة للروبوت: الهوية البصرية والترحيب ونموذج ما قبل الدردشة وبيانات الاتصال اللحظي.

المصادقة بدون مصادقة، عامةحد المعدل 60 طلب كل 1 دقيقة لكل عنوان IP

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.

الطلب

curl https://magiz.ai/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/config \
  -H "Accept: application/json"

الاستجابة

{
  "public_key": "cv_9f2a4c7e1b6d3a8f5c0e2b4d",
  "name": "Support bot",
  "welcome_message": "Hi! How can I help you today?",
  "human_handoff_enabled": true,
  "branding": {
    "primary_color": "#4f46e5",
    "launcher_text": "Chat with us",
    "position": "right",
    "theme": "minimal",
    "logo_url": null,
    "avatar_url": null,
    "title": "Support bot",
    "subtitle": "We typically reply in a few seconds",
    "layout": "classic",
    "launcher": "bubble",
    "quick_replies": [],
    "agent_avatars": [],
    "composer_style": "full",
    "sound": true,
    "screen_share": false,
    "copilot": false,
    "auto_actions": true,
    "copilot_use_profile": false,
    "copilot_autostart": true,
    "live_visitors": true,
    "behavior_tracking": false,
    "recommend_mode": "reactive",
    "proactive": {
      "enabled": false,
      "message": "Hi! Anything I can help you find?",
      "delay": 20,
      "scroll": 0,
      "exit_intent": false,
      "url_contains": "",
      "frequency": "session"
    }
  },
  "powered_by": "MagizAI",
  "powered_by_url": "https://magiz.ai",
  "pre_chat_form": {
    "enabled": true,
    "greeting": "Before we start, please introduce yourself.",
    "fields": {
      "name":  { "enabled": true,  "required": false },
      "email": { "enabled": true,  "required": true  },
      "phone": { "enabled": false, "required": false }
    }
  },
  "realtime": {
    "key": "reverbappkey",
    "host": "realtime.acme.test",
    "port": 443,
    "scheme": "https"
  }
}

الأخطاء

الحالةسبب حدوثه
404لا روبوت نشط بهذا المفتاح العام. والروبوت المعطّل يعطي الرد نفسه.
429تم بلوغ حد المسار لعنوان IP هذا.

POST/widget/{key}/boot

يفتح محادثة زائر أو يستأنفها ويُرجع النص حتى اللحظة.

المصادقة بدون مصادقة، عامةحد المعدل 30 طلب كل 1 دقيقة لكل عنوان IP

مرّر conversation_id للاستئناف. وإن لم يطابق معرّف الزائر الذي ترسله، أو كانت تلك المحادثة مغلقة، فتُفتح محادثة جديدة بدل أن يفشل النداء. ويوضح الحقل identity ما أثبته هذا الطلب عن هوية السائل. وقيمة state واحدة من verified أو staff_view أو expired أو refused أو client_area_no_client أو staff_session أو no_account أو account_closed أو module_error أو not_configured أو sign_in_page أو signed_out أو absent. ولا يتضمن first_name إلا عندما يتم التحقق من رمز الهوية المرسل مع هذا الطلب نفسه لعميل، ولا يتضمنه أبدًا في عرض الموظفين.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
visitor_idstringمطلوبالمعرّف الذي تسنده أداتك للزائر وتحتفظ به طوال الجلسة. حتى 100 محرف.
conversation_iduuidاختياريمحادثة قائمة تريد متابعتها. اتركه ليبدأ محادثة جديدة.
metaobjectاختياريسياق عن الزائر والصفحة. وقد يحمل meta.visitor الاسم والبريد والهاتف من نموذج ما قبل الدردشة لديك.
identitystringاختياريرمز هوية موقّع من خادمك أنت. يُتحقق منه قبل الوثوق بأي شيء فيه. حتى 4000 محرف. ويُرفض الرمز إذا كانت قيمة sub أو external_id هي "0". تستمر المحادثة المسجّل دخولها دون رمز لمدة 15 دقيقة بعد آخر رمز تم التحقق منه. بعد ذلك تُوضع جانبًا وتبدأ محادثة جديدة، ويعيدها الرمز الصالح التالي للشخص نفسه خلال 24 ساعة.
signed_outbooleanاختياريأرسل true عندما تعرف صفحتك أن أحدًا لم يسجّل الدخول. إذا كانت المحادثة تخص شخصًا سجّل الدخول سابقًا، فإنها تُغلق وتبدأ محادثة جديدة، فلا يراها الشخص التالي على جهاز مشترك.
identity_stateobjectاختياريسبب عدم وجود رمز هوية في الصفحة، برموز فقط: {"v":1,"status":"client|staff|none","reason":"..."}. السبب واحد من signed_out أو staff أو staff_view أو no_account أو account_closed أو module_error أو not_configured. يُستخدم لصياغة الردود ولا يمنح أي وصول أبدًا. وكل ما يخرج عن هذا الشكل يُتجاهل.

الطلب

curl -X POST https://magiz.ai/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/boot \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "meta": {
          "page": "https://acme.test/orders/8812",
          "visitor": { "name": "Nadia Karim", "email": "nadia@example.test" }
        }
      }'

الاستجابة

{
  "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
  "status": "bot",
  "handoff_state": "bot_active",
  "wait_remaining": null,
  "identity": { "state": "absent" },
  "messages": [
    {
      "id": 33126,
      "role": "visitor",
      "content": "I still have not received the replacement.",
      "at": "2026-08-08T10:41:04+00:00"
    },
    {
      "id": 33127,
      "role": "assistant",
      "content": "Let me check that order for you.",
      "at": "2026-08-08T10:41:07+00:00"
    }
  ]
}

الأخطاء

الحالةسبب حدوثه
404لا روبوت نشط بهذا المفتاح العام. والروبوت المعطّل يعطي الرد نفسه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لعنوان IP هذا.

POST/widget/{key}/stream

يرسل رسالة زائر ويبث رد الذكاء الاصطناعي عبر Server-Sent Events.

المصادقة بدون مصادقة، عامةحد المعدل 20 طلب كل 1 دقيقة لكل عنوان IP

الاستجابة بصيغة text/event-stream لا JSON. وتصل الأحداث بالترتيب: meta أولًا، ثم أي عدد من أحداث delta، وربما recommendations، وأخيرًا done أو error. أما الرفض قبل بدء البث فهو استجابة خطأ JSON عادية. ويحمل حدث meta أيضًا الحقل identity، وهو الكائن نفسه الذي يُرجعه boot.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
visitor_idstringمطلوبالمعرّف الذي تسنده أداتك للزائر وتحتفظ به طوال الجلسة. حتى 100 محرف.
messagestringمطلوبرسالة الزائر. حتى 4000 محرف، ولا يجوز أن تكون مسافات فقط.
conversation_iduuidاختياريمحادثة قائمة تريد متابعتها. اتركه ليبدأ محادثة جديدة.
metaobjectاختياريسياق عن الزائر والصفحة. وقد يحمل meta.visitor الاسم والبريد والهاتف من نموذج ما قبل الدردشة لديك.
identitystringاختياريرمز هوية موقّع من خادمك أنت. يُتحقق منه قبل الوثوق بأي شيء فيه. حتى 4000 محرف. ويُرفض الرمز إذا كانت قيمة sub أو external_id هي "0". تستمر المحادثة المسجّل دخولها دون رمز لمدة 15 دقيقة بعد آخر رمز تم التحقق منه. بعد ذلك تُوضع جانبًا وتبدأ محادثة جديدة، ويعيدها الرمز الصالح التالي للشخص نفسه خلال 24 ساعة.
signed_outbooleanاختياريأرسل true عندما تعرف صفحتك أن أحدًا لم يسجّل الدخول. إذا كانت المحادثة تخص شخصًا سجّل الدخول سابقًا، فإنها تُغلق وتبدأ محادثة جديدة، فلا يراها الشخص التالي على جهاز مشترك.
identity_stateobjectاختياريسبب عدم وجود رمز هوية في الصفحة، برموز فقط: {"v":1,"status":"client|staff|none","reason":"..."}. السبب واحد من signed_out أو staff أو staff_view أو no_account أو account_closed أو module_error أو not_configured. يُستخدم لصياغة الردود ولا يمنح أي وصول أبدًا. وكل ما يخرج عن هذا الشكل يُتجاهل.

الطلب

curl -N -X POST https://magiz.ai/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/stream \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91",
        "message": "Where is my replacement?"
      }'

الاستجابة

event: meta
data: {"conversation_id":"6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91","visitor_message_id":33128,"status":"bot","identity":{"state":"absent"}}

event: delta
data: {"delta":"Your replacement "}

event: delta
data: {"delta":"was posted this morning."}

event: recommendations
data: {"products":[{"id":41,"name":"Express delivery","price":"AED 25.00","currency":"AED","url":"https://acme.test/express","buy_url":"https://acme.test/express","image_url":null,"description":"Next-working-day delivery across the UAE.","in_stock":true}]}

event: done
data: {"message_id":33129,"source":"ai","sources":[{"title":"Shipping policy","url":"https://acme.test/shipping"}]}

الأخطاء

الحالةسبب حدوثه
404لا روبوت نشط بهذا المفتاح العام. والروبوت المعطّل يعطي الرد نفسه.
422كانت الرسالة مسافات فقط.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لعنوان IP هذا.

POST/widget/{key}/chat/reset

يغلق محادثة الزائر الحالية ليبدأ الأداة محادثة نظيفة.

المصادقة بدون مصادقة، عامةحد المعدل 30 طلب كل 1 دقيقة لكل عنوان IP

متكرر الأثر ومحقَّق الملكية. يغلق المحادثة على الخادم، ثم تفتح الأداة محادثة جديدة، وهذا ما يمسح السياق.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
visitor_idstringمطلوبالمعرّف الذي تسنده أداتك للزائر وتحتفظ به طوال الجلسة. حتى 100 محرف.
conversation_iduuidمطلوبالمحادثة المراد إغلاقها. ويجب أن تعود لمعرّف الزائر الذي ترسله.

الطلب

curl -X POST https://magiz.ai/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/chat/reset \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "conversation_id": "6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91"
      }'

الاستجابة

{
  "ok": true
}

الأخطاء

الحالةسبب حدوثه
404لا روبوت نشط بهذا المفتاح العام. والروبوت المعطّل يعطي الرد نفسه.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لعنوان IP هذا.

GET/widget/{key}/conversations/{conversationId}/history

يستعلم عن الرسائل الجديدة في محادثة، بما فيها ردود الموظف البشري.

المصادقة بدون مصادقة، عامةحد المعدل 60 طلب كل 1 دقيقة لكل عنوان IP

مرّر after بأعلى معرّف رسالة لديك لتجلب الجديد فقط. تُرجع المحادثة المسجّل دخولها {"reauth": true, "messages": []} عندما يمضي أكثر من 15 دقيقة على آخر رمز تم التحقق منه. استدعِ boot مجددًا برمز الهوية الموجود في الصفحة للمتابعة.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
conversationIduuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.
visitor_idstringمطلوبالمعرّف الذي تسنده أداتك للزائر وتحتفظ به طوال الجلسة. حتى 100 محرف.
afterintegerاختياريفي الاستعلام. أعد الرسائل التي معرّفها أكبر من هذه القيمة فقط.

الطلب

curl "https://magiz.ai/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/history?visitor_id=v_2c9a71b4e5&after=33127" \
  -H "Accept: application/json"

الاستجابة

{
  "status": "agent",
  "handoff_state": "human_connected",
  "wait_remaining": null,
  "messages": [
    {
      "id": 33131,
      "role": "agent",
      "content": "I have opened a claim with the courier and posted a replacement today.",
      "at": "2026-08-08T10:47:20+00:00"
    }
  ]
}

الأخطاء

الحالةسبب حدوثه
404لا محادثة بهذا المعرّف لهذا الروبوت ومعرّف الزائر هذا.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لعنوان IP هذا.

POST/widget/{key}/conversations/{conversationId}/rate

يسجّل إعجابًا أو عدم إعجاب برد واحد من الذكاء الاصطناعي.

المصادقة بدون مصادقة، عامةحد المعدل 60 طلب كل 1 دقيقة لكل عنوان IP

أرسل rating مساويًا لـ 0 للتراجع عن تقييم سابق. وعدم الإعجاب يُسجَّل أيضًا فجوة معرفة لتصلحها مساحة العمل.

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
conversationIduuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.
visitor_idstringمطلوبالمعرّف الذي تسنده أداتك للزائر وتحتفظ به طوال الجلسة. حتى 100 محرف.
message_idintegerمطلوبرسالة المساعد التي يجري تقييمها.
ratingintegerمطلوبالقيمة 1 للإعجاب، و-1 لعدم الإعجاب، و0 للتراجع عن تقييم سابق.

الطلب

curl -X POST https://magiz.ai/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/rate \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "message_id": 33129,
        "rating": -1
      }'

الاستجابة

{
  "ok": true,
  "rating": -1
}

الأخطاء

الحالةسبب حدوثه
404لم تُوجد المحادثة، أو أن معرّف الرسالة ليس رسالة مساعد فيها.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لعنوان IP هذا.

POST/widget/{key}/conversations/{conversationId}/csat

يسجّل درجة رضا عن المحادثة كاملة.

المصادقة بدون مصادقة، عامةحد المعدل 10 طلب كل 1 دقيقة لكل عنوان IP

المعاملات

المعاملالنوعمطلوبالوصف
keystringمطلوبفي المسار. المفتاح العام للروبوت، وهو القيمة نفسها المستخدمة في شيفرة التضمين.
conversationIduuidمطلوبفي المسار. المعرّف العام للمحادثة، وهو UUID.
visitor_idstringمطلوبالمعرّف الذي تسنده أداتك للزائر وتحتفظ به طوال الجلسة. حتى 100 محرف.
scoreintegerمطلوبدرجة الرضا من 1 إلى 5.
commentstringاختياريتعليق نصي حر. حتى 2000 محرف.

الطلب

curl -X POST https://magiz.ai/widget/cv_9f2a4c7e1b6d3a8f5c0e2b4d/conversations/6f0f1d84-2b6a-4a51-9f0e-5c2b3a7d8e91/csat \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "visitor_id": "v_2c9a71b4e5",
        "score": 5,
        "comment": "Sorted in two minutes."
      }'

الاستجابة

{
  "ok": true
}

الأخطاء

الحالةسبب حدوثه
404لا محادثة بهذا المعرّف لهذا الروبوت ومعرّف الزائر هذا.
422فشل التحقق من أحد الحقول. وكائن errors يسميه.
429تم بلوغ حد المسار لعنوان IP هذا.

نقاط الأداة غير الموثقة هنا

هذه النقاط موجودة وتستخدمها شيفرة التضمين، لكنها داخلية للأداة وليست شيئًا تناديه بنفسك. أدرجناها لتعرف أن استبعادها كان مقصودًا.

الطريقةنقطة النهايةالسبب
POST/widget/{key}/uploadرفع ملف بصيغة multipart، مرتبط بتدفق المرفقات في الأداة وقواعد تخزينها.
POST/widget/{key}/request-humanاستقبال طلب التحويل خارج أوقات العمل. يرسل تنبيهات بالبريد وواتساب إلى مساحة العمل، لذا يبقى ضمن تدفق الأداة نفسها.
POST/widget/{key}/conversionsإشارة تحويل لخط التقارير، ولا معنى لها إلا مع شيفرة التتبع في الأداة.
POST/widget/{key}/trackإشارة سلوك لأحداث الصفحة والمنتج والسلة. تُفعَّل اختياريًا لكل روبوت وتتشكل بالكامل من الأداة.
POST/widget/{key}/presenceنبضة الزوار المتصلين. توقيتها مرتبط بفاصل الإشارة في الأداة.
POST/widget/{key}/assistإرشاد المساعد على الصفحة. المحتوى المرسل لقطة من صفحة الزائر تنتجها الأداة.
GET/widget/{key}/attachments/{attachment}يمرر مرفقًا إلى الزائر صاحب المحادثة. والعنوان تصدره الأداة ويُتحقق منه مقابل ذلك الزائر.
POST/widget/{key}/chat/reveal/{token}يستبدل رمزًا لمرة واحدة بمعلومة طلبها الزائر ولا يجوز الاحتفاظ بها، مثل كلمة مرور الاستضافة الخاصة به. لا يستدعيه إلا زر الأداة نفسها. يعمل الرمز مرة واحدة فقط، لمدة 3 دقائق، داخل المحادثة المسجّل دخولها التي أُنشئ لها، وللزائر صاحب تلك المحادثة وحده. ولا تُعرض بيانات الدخول إلا لتثبيت WHMCS يعمل بوحدة إصدارها 1.6.0 أو أحدث. ويُرفض أي طلب آخر (404 أو 410 أو 422) ولا يحصل على شيء.
POST/widget/{key}/chat/verificationيبيّن ما إذا كان رمز تأكيد أُرسل بالبريد الإلكتروني ينتظر في محادثة الزائر، والعنوان المخفي الذي أُرسل إليه، وعدد المحاولات المتبقية. لا يستدعيه إلا مربع الرمز في الأداة، وللزائر صاحب المحادثة وحده. ولا يعيد الرمز أبدًا.
POST/widget/{key}/chat/verification/{ref}/codeيتحقق من رمز واحد أُدخل في مربع الرمز في الأداة مقابل الرمز المرسل بالبريد لتغيير ما. خمس محاولات لكل طلب، ثم يُغلق الطلب. لا يُحفظ الرمز الصحيح ولا يُمرَّر: ترسل الأداة بعده رسالة عادية تطلق التغيير عبر دورة المحادثة المعتادة.
POST/widget/{key}/chat/verification/{ref}/resendيرسل رمزًا جديدًا عبر قناة البريد نفسها ليحل محل السابق. ثلاث مرات على الأكثر لكل طلب، بفاصل ثلاثين ثانية، وضمن الحد الساعي للتاجر. ولا يعيد إلا العنوان المخفي.
POST/widget/{key}/chat/pay/{token}زر الدفع أسفل أول طلب لعميل جديد (وحدة WHMCS 1.8.0). يستبدل رمزًا بتسجيل الدخول الفردي الخاص بـ WHMCS إلى الحساب الذي فتحته تلك المحادثة، على فاتورته، ويُنشأ في تلك اللحظة. لا يستدعيه إلا زر الأداة نفسها، من المحادثة التي أُنشئ لها الرمز وللزائر صاحبها، لمدة ساعتين. ويُرفض أي طلب آخر (404 أو 410 أو 422) ولا يحصل على شيء.

تحتاج شيئًا غير موجود هنا؟

أخبرنا بما تبنيه وسنرشدك إلى نقطة النهاية المناسبة، أو نضيف واحدة.

تحدث إليناتصفح مركز المساعدة