> ## 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.

# دليل استخدام وكيل حساب WhatsApp

> Platform API guide - Ace Data Cloud

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

> تستخدم هذه الخدمة قدرة الأجهزة المرتبطة في WhatsApp، وليست WhatsApp Business API الرسمية؛ لذلك فإن طريقة ربط الحساب غير مدعومة من WhatsApp رسميًا. قد تؤدي تغييرات البروتوكول أو إلغاء ربط الجهاز أو قيود الحساب إلى انقطاع الخدمة. قم بربط الحسابات التي تملكها فقط، والتزم بشروط WhatsApp، ولا تستخدمها للرسائل المزعجة أو الإرسال الجماعي دون موافقة.

## النشر والتفويض الشخصي

1. أنشئ تطبيق «وكيل حساب WhatsApp» في لوحة التحكم، وبعد تفعيل الاشتراك اضغط على النشر. سيتم تكوين موارد المثيل تلقائيًا بواسطة المنصة.
2. بعد جاهزية المثيل، اعرض رمز QR في صفحة الإدارة. افتح WhatsApp على هاتفك الشخصي وانتقل إلى **الإعدادات → الأجهزة المرتبطة → ربط جهاز** ثم امسح الرمز. يمكنك أيضًا إدخال رقم هاتفك لطلب رمز اقتران، ثم تأكيده من الهاتف.
3. بعد أن تتحول حالة صفحة الإدارة إلى «متصل»، انسخ عنوان MCP المخصص ورمز وصول Bearer.
4. عند تسجيل الخروج، سيحاول النظام إلغاء ربط الجهاز وحذف الجلسة المحلية والسجل. إذا كانت نتيجة تسجيل الخروج غير مؤكدة، قم أولًا بإلغاء ربط الجهاز من قسم «الأجهزة المرتبطة» في الهاتف؛ يؤدي تدمير المثيل إلى إزالة وحدة التخزين الدائمة الخاصة به.

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

## المصادقة والقدرات

باستثناء `/health` و `/readyz`، تتطلب واجهات REST وMCP والمسح الضوئي والاقتران جميعها `Authorization: Bearer <رمز الوصول>`. يجب وضع الرمز في ترويسة الطلب فقط، وليس في عنوان URL أو السجلات. يعرض `GET /api/capabilities` العمليات المدعومة فعليًا في المثيل الحالي وحدود الاحتفاظ.

الدعم الحالي يشمل: حالة الحساب والاتصال، والجلسات وجهات الاتصال التي تتم مزامنتها مع الأجهزة المرتبطة، وأحداث الرسائل في الوقت الحقيقي، وقراءة الرسائل المحفوظة محليًا، وإرسال واستقبال النصوص والوسائط التي لا تتجاوز 10 MiB، والردود المقتبسة، والتفاعلات التعبيرية، ووضع علامة مقروء، بالإضافة إلى تعديل/سحب الرسائل الشخصية التي تسمح بها صلاحيات الحساب والقواعد الحالية لـ WhatsApp، ومعلومات المجموعات وعمليات الأعضاء الفردية. تظل تعديلات المجموعات خاضعة لتحقق WhatsApp من صلاحيات الأعضاء والمديرين.

**نطاق السجل التاريخي**: يمكن فقط قراءة الرسائل التي تمت مزامنتها فعليًا من الهاتف إلى الجهاز المرتبط، بالإضافة إلى الرسائل التي تم استلامها أثناء اتصال الوكيل. لا يمكن ضمان الحصول على جميع الرسائل القديمة؛ يحتفظ التخزين المحلي بحد أقصى بأحدث 5,000 رسالة و2,000 حدث. عند وجود بيانات وصفية للوسائط، قد لا يمكن تنزيل الوسائط الأصلية بعد ذلك.

## MCP

توفر صفحة إدارة النشر العنوان `https://whatsapp-bot-<معرّف المثيل>.app.acedata.cloud/mcp`. قم بتكوين هذا العنوان في عميل MCP الذي يدعم Streamable HTTP وترويسات الطلبات المخصصة، وأضف نفس رمز Bearer. تتضمن أدوات MCP: `whatsapp_capabilities` و`whatsapp_whoami` و`whatsapp_chats` و`whatsapp_contacts` و`whatsapp_messages` و`whatsapp_events` و`whatsapp_send` و`whatsapp_send_status` و`whatsapp_media` و`whatsapp_mark_read` و`whatsapp_group` و`whatsapp_group_update`.

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

## أمثلة REST

```bash theme={null}
BASE='https://whatsapp-bot-<معرّف المثيل>.app.acedata.cloud'
TOKEN='<رمز الوصول المعروض في صفحة الإدارة>'

curl "$BASE/api/auth/status" -H "Authorization: Bearer $TOKEN"
curl "$BASE/api/chats?limit=20" -H "Authorization: Bearer $TOKEN"
curl "$BASE/api/chats/123%40s.whatsapp.net/messages?limit=20" -H "Authorization: Bearer $TOKEN"
```

أرسل فقط إلى **جلساتك أو جهات اتصالك الموجودة مسبقًا**. يجب أن يستخدم `target` قيمة JID التي يتم إرجاعها من `/api/chats` أو `/api/contacts`؛ لا يجوز استخدام أي رقم هاتف عشوائي للإرسال البارد. يجب أن يؤكد صاحب الحساب المستلم والمحتوى أولًا.

```bash theme={null}
curl -X POST "$BASE/api/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: my-confirmed-message-20261004-1" \
  -H 'Content-Type: application/json' \
  -d '{"target":"123@s.whatsapp.net","action":"text","text":"你好"}'
```

يمكن أن تكون قيمة `action` هي `text` أو `media` أو `edit` أو `revoke` أو `reaction`. لإرسال الوسائط يتم تمرير `media_base64` و`mime_type`؛ وللرد يتم تمرير `reply_to`؛ وللتعديل والسحب يتم تمرير `message_id` الخاص بالمستخدم الذي يمكن العثور عليه محليًا؛ وللتفاعل يتم تمرير `message_id` و`emoji`. يمكن تنزيل الوسائط عبر `GET /api/chats/{target}/messages/{id}/media`، ويمكن وضع علامة مقروء عبر `POST /api/chats/{target}/read`.

يجب أن يحتوي الإرسال على `Idempotency-Key` بطول 8–128 حرفًا. يكون `message_id` المُعاد ثابتًا، وتكون الحالة `pending` أو `accepted` أو `unknown` أو `delivered` أو `read`. تعني `accepted` فقط أن الاتصال المحلي قبل عملية الإرسال، **ولا تعني أن الطرف الآخر استلمها**. عند حدوث `unknown`، استعلم عن `GET /api/sends/{Idempotency-Key}` وأحداث الرسائل؛ لا تستخدم مفتاحًا جديدًا لإرسال نفس الرسالة لتجنب التكرار. لا يقوم الوكيل بإعادة إرسال العمليات غير المؤكدة تلقائيًا.

لا يتم حذف سجلات الإرسال تلقائيًا؛ بعد الوصول إلى 100,000 سجل، يرفض المثيل عمليات الإرسال الجديدة (HTTP 507)، لتجنب حدوث إرسال مكرر بعد تنظيف مفاتيح عدم التكرار القديمة.

## الأحداث في الوقت الحقيقي

يدعم `GET /api/events?after=&lt;المؤشر التالي السابق>&wait_ms=25000` الاستطلاع الطويل لمدة تصل إلى 25 ثانية؛ ويوفر `GET /api/events/stream?after=&lt;المؤشر>` خدمة SSE. تحتوي الأحداث على `seq` متزايد بشكل رتيب. يجب حفظ `next_cursor` الموجود في الاستجابة ضمن الحالة الدائمة لـ Agent؛ إذا كانت `gap=true`، فهذا يعني أن الأحداث القديمة قد تم تنظيفها، ويجب إعادة جلب حالة الجلسة الحالية والمتابعة من `oldest_cursor`. يتم الإبلاغ بشكل مستقل عن أحداث الرسائل وحالات الإرسال وحالة الاتصال.

## الحالات الشائعة

| HTTP / الحالة | طريقة المعالجة |
| - | - |
| 401 | تحقق من رمز Bearer وترويسة الطلب. |
| 404 | الجلسة أو جهة الاتصال أو الرسالة المستهدفة غير موجودة في السجل المحلي لهذا المثيل. |
| 409 | الحساب غير متصل، أو أن مفتاح عدم التكرار نفسه مرتبط بمحتوى مختلف. |
| 413 | الوسائط تتجاوز 10 MiB. |
| 403 / 429 | تم رفض العملية أو تم تفعيل حد التكرار؛ إذا حدث ذلك أثناء الإرسال، يجب أولًا التحقق من نتيجة مفتاح عدم التكرار. |
| 502 / 503 | فشل الاتصال أو العملية البعيدة؛ إذا كانت نتيجة الإرسال غير مؤكدة، تحقق أولًا من حالة العملية والأحداث. |

لا يوجد ضمان للحصول على سجل تاريخي غير محدود، أو توفر جميع الوسائط لفترة طويلة، أو قبول WhatsApp لجميع عمليات المجموعة دائمًا. عند الحاجة إلى التحقق من مثيل محدد، راجع أولًا `/api/auth/status` و`/api/capabilities`.


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