تستخدم هذه الخدمة قدرة الأجهزة المرتبطة في WhatsApp، وليست WhatsApp Business API الرسمية؛ لذلك فإن طريقة ربط الحساب غير مدعومة من WhatsApp رسميًا. قد تؤدي تغييرات البروتوكول أو إلغاء ربط الجهاز أو قيود الحساب إلى انقطاع الخدمة. قم بربط الحسابات التي تملكها فقط، والتزم بشروط WhatsApp، ولا تستخدمها للرسائل المزعجة أو الإرسال الجماعي دون موافقة.
النشر والتفويض الشخصي
- أنشئ تطبيق «وكيل حساب WhatsApp» في لوحة التحكم، وبعد تفعيل الاشتراك اضغط على النشر. سيتم تكوين موارد المثيل تلقائيًا بواسطة المنصة.
- بعد جاهزية المثيل، اعرض رمز QR في صفحة الإدارة. افتح WhatsApp على هاتفك الشخصي وانتقل إلى الإعدادات → الأجهزة المرتبطة → ربط جهاز ثم امسح الرمز. يمكنك أيضًا إدخال رقم هاتفك لطلب رمز اقتران، ثم تأكيده من الهاتف.
- بعد أن تتحول حالة صفحة الإدارة إلى «متصل»، انسخ عنوان MCP المخصص ورمز وصول Bearer.
- عند تسجيل الخروج، سيحاول النظام إلغاء ربط الجهاز وحذف الجلسة المحلية والسجل. إذا كانت نتيجة تسجيل الخروج غير مؤكدة، قم أولًا بإلغاء ربط الجهاز من قسم «الأجهزة المرتبطة» في الهاتف؛ يؤدي تدمير المثيل إلى إزالة وحدة التخزين الدائمة الخاصة به.
المصادقة والقدرات
باستثناء/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
target قيمة JID التي يتم إرجاعها من /api/chats أو /api/contacts؛ لا يجوز استخدام أي رقم هاتف عشوائي للإرسال البارد. يجب أن يؤكد صاحب الحساب المستلم والمحتوى أولًا.
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=<المؤشر التالي السابق>&wait_ms=25000 الاستطلاع الطويل لمدة تصل إلى 25 ثانية؛ ويوفر GET /api/events/stream?after=<المؤشر> خدمة SSE. تحتوي الأحداث على seq متزايد بشكل رتيب. يجب حفظ next_cursor الموجود في الاستجابة ضمن الحالة الدائمة لـ Agent؛ إذا كانت gap=true، فهذا يعني أن الأحداث القديمة قد تم تنظيفها، ويجب إعادة جلب حالة الجلسة الحالية والمتابعة من oldest_cursor. يتم الإبلاغ بشكل مستقل عن أحداث الرسائل وحالات الإرسال وحالة الاتصال.
الحالات الشائعة
لا يوجد ضمان للحصول على سجل تاريخي غير محدود، أو توفر جميع الوسائط لفترة طويلة، أو قبول WhatsApp لجميع عمليات المجموعة دائمًا. عند الحاجة إلى التحقق من مثيل محدد، راجع أولًا
/api/auth/status و/api/capabilities.