> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# روبوت WeCom

> Platform API guide - Ace Data Cloud

انشر مثيل حساب WeCom خاص بك، وسجّل الدخول عبر مسح رمز QR باستخدام WeCom على الهاتف، واقرأ الحساب وجهات الاتصال والمحادثات والرسائل المتزامنة محليًا عبر REST API أو MCP. يمثّل المثيل حساب WeCom عاديًا، ولا يتطلب خادمًا خاصًا أو إعداد نطاق بريد إلكتروني للشركة.

الحالة الحالية Alpha. اكتملت مصادقة حقيقية لقراءة الحساب والمحادثات؛ واكتمل قبول حقيقي لإرسال النصوص من صاحب الحساب وقراءة الأحداث المرتجعة؛ ولا تزال عمليات جهات الاتصال الأخرى والمجموعات واستعادة المثيلات الجديدة تتطلب قبولًا في بيئة النشر. إرسال الوسائط والرد بالاقتباس و@ الفعلية وإدارة أعضاء المجموعة وإيصالات التسليم غير متاحة بعد. يُرجى الاعتماد على القيمة المرجعة من `/api/capabilities` الخاصة بالمثيل.

## النشر وتسجيل الدخول

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

يتم احتساب رسوم كل مثيل بشكل مستقل، ويعمل وفق المدة المشتراة. لا تُفرض رسوم منفصلة لكل رسالة على استدعاءات REST / MCP، ويُرجى الرجوع إلى صفحة الباقة لمعرفة السعر الفعلي. تعتمد المرجعية الافتراضية الحالية على باقة مدة روبوت WeChat، ويجب تأكيد التسعير بالاقتران مع موارد التشغيل قبل الإتاحة النهائية.

## API وMCP

استخدم عنوان API للمثيل في صفحة الإدارة، وتحمل جميع واجهات الحساب `Authorization: Bearer <رمز API للمثيل>`. هذه المسارات تخص مثيلًا مخصصًا وليست بوابة API مشتركة. عنوان MCP هو عنوان المثيل مضافًا إليه `/mcp/`، ويستخدم رمز Bearer نفسه.

| الواجهة | الوظيفة |
| - | - |
| `GET /api/status`،`GET /api/auth/status` | ما إذا كان الحساب جاهزًا وقائمة القدرات |
| `GET /api/auth/qr` | PNG Base64 لرمز QR الحالي لتسجيل الدخول |
| `GET /api/account` | الحساب الحالي |
| `GET /api/contacts?kind=all` | الزملاء الداخليون وجهات الاتصال الخارجية، ويمكن تحديد internal / external |
| `GET /api/conversations` | المحادثات المحلية، مع الاحتفاظ بمعرّف المحادثة الأصلي |
| `GET /api/messages` | الرسائل المتزامنة محليًا؛ معاملات conversation\_id وafter\_rowid وlimit |
| `POST /api/search` | البحث في جهات الاتصال والمحادثات والنصوص المحلية |
| `POST /api/messages` | مهمة إرسال نصية غير متزامنة، ويجب توفير Idempotency-Key |
| `POST /api/messages/send` | نقطة إدخال الإرسال نفسها، تدعم هدفًا واحدًا أو أهدافًا متعددة |
| `GET /api/groups/{conversation_id}` | معلومات المجموعة وأعضاؤها المتزامنون محليًا |
| `GET /api/tasks` | المهام الأخيرة ونتائج كل هدف |
| `GET /api/tasks/{id}` | الاستعلام عن نتيجة الإرسال |
| `POST /api/tasks/{id}/cancel` | إلغاء مهمة لم تبدأ بعد |
| `POST /api/runtime/pause`،`POST /api/runtime/resume` | إيقاف الأتمتة مؤقتًا؛ والاستئناف بعد تحقق صاحب الحساب |
| `GET /api/diagnostics`،`GET /api/diagnostics/screenshot` | حالة المثيل والشاشة الحالية، وكلاهما يتطلب مصادقة |
| `GET /api/events?after=0` | أحداث الرسائل ذات المؤشر القابل للاستئناف |
| `WS /ws` | تدفق أحداث الرسائل، مصادقة Bearer |

تتضمن حمولة الإرسال `target` و`type: "text"` و`text`. يقبل `target` معرّف المحادثة أو معرّف جهة الاتصال أو معرّف مستخدم المؤسسة أو الاسم الكامل الفريد؛ وتُفضّل المعرّفات؛ وإذا ظل اسم العرض غير قادر على تحديد موقع فريد، فسيرفض المثيل العملية ولن يخمّن الكائن. ستُفتح محادثة جهة الاتصال التي لا توجد لها محادثة محلية عبر العميل أولًا، ثم يُتحقق من معرّف المحادثة الفعلي قبل الإرسال. رأس الطلب `Idempotency-Key` يتكون من 8–128 حرفًا أو رقمًا أو `_.:-`. يجب أن تعيد الطلبات المتكررة للعملية نفسها استخدام المفتاح نفسه وجسم الطلب نفسه.

استبدل `target` بمصفوفة `targets` للإرسال تسلسليًا إلى 1–50 هدفًا محددًا بوضوح. لا يمكن توفير كليهما في الوقت نفسه. يجب أن تكمل جميع الأهداف تحليل الهوية أولًا، وسيتم رفض الأسماء المستعارة المختلفة التي تشير إلى الكائن نفسه. بعد فشل أحد الأهداف، يتوقف الإرسال اللاحق، وتُسجّل نتيجة المهمة لكل عنصر على أنها `succeeded` أو `failed` أو `unknown` أو `not_attempted`؛ لا تعامل النجاح الجزئي على أنه نجاح كامل. لا تزال هذه العملية تتطلب قبولًا حقيقيًا لجهات اتصال محددة في بيئة النشر.

قد تكون المهام في حالات queued أو running أو submitting أو succeeded أو failed أو unknown أو cancelled. تعني `succeeded` أنه بعد الإرسال تم العثور على النص المطابق ومعرّف رسالة الخادم في سجل المحادثة المقابل، وتظل `delivered` بقيمة null، ولا يعني ذلك أن الطرف الآخر قد استلمها. تعني unknown أن النتيجة غير واضحة، لذا تحقّق من السجلات التاريخية ولا تكرر الإرسال باستخدام مفتاح جديد. لا يعيد المثيل إرسال المهام المتقطعة تلقائيًا.

لا يتضمن السجل إلا المحتوى الذي قام العميل بمزامنته بالفعل، ولا يمكن ضمان اكتمال السجل كله. قد تُرجع الرسائل غير النصية نوع unknown، ولم يُتح تنزيل المرفقات بعد. تحتفظ الأحداث بأحدث 10,000 سجل، وتشير `gap` إلى أن المؤشر قد تجاوز نافذة الاحتفاظ. لا يعيد الاتصال الأول تشغيل السجل القديم باعتباره رسائل جديدة.

يمكن استخدام `server_accepted` و`server_id` في سجل الرسائل للتحقق مما إذا كان الخادم قد قبل الرسالة المحلية؛ وعند وجود سجل محلي فقط دون معرّف خادم، لا يمكن اعتبار الإرسال ناجحًا. لا تمثل هذه الحقول ما إذا كان المستلم قد استلم أو قرأ الرسالة. يحتفظ سجل الأحداث بالحالة عند إنشائها، ويجب استخدام واجهة سجل الرسائل للاستعلام عن حالة التأكيد الحالية.

## الحساب وبيانات الاعتماد

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

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

عند اكتشاف مطالبة تحقق أمني أو تسجيل خروج الحساب أو تغييره، ستتوقف قائمة انتظار الأتمتة مؤقتًا بشكل دائم. بعد إكمال تحقق الهاتف، يمكنك متابعة المهام التي لم تُنفذ بعد عبر «الاستئناف بعد التحقق» في وحدة تحكم المثيل؛ ولن تُعاد المهام التي تم إرسالها بالفعل لكن نتيجتها غير مؤكدة. قد يؤدي العمل العادي عن بُعد أيضًا إلى تشغيل التحقق الأمني في WeCom. إن نافذة الـ24 ساعة بعد التحقق التي توضحها التعليمات الرسمية لعدم القفل مجددًا لا تعني أنه تم إلغاء الكشف، ولا تعني أن المثيل يستطيع ضمان التشغيل طويل الأمد دون مراقبة.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.