الانتقال إلى المحتوى الرئيسي
وتقوم GOWA بخدمة بروتوكول السياق النموذجي نقطة نهاية من نفس العملية التي يقوم بها API REST. أي عميل MCP يدعم نقل HTTP يمكن إرسال الرسائل وقراءة المحادثة وإدارة المجموعات من خلالها.
  • URL: http://<host>:3000<APP_BASE_PATH>/mcp (الافتراضي http://localhost:3000/mcp)
  • تمكين بشكل افتراضي. تعطيل مع MCP_ENABLED=false أو --mcp-enabled=false.
  • عديم الجنسية: لا يوجد مصافحة جلسة للإبقاء على قيد الحياة بين المكالمات.
الترقية من الإصدار الأقدم؟ الأمر المستقل ./whatsapp mcp ونقطة النهاية الخاصة به SSE على المنفذ 8080 (/sse) قد ذهبت. قم بتشغيل ./whatsapp rest وتحديد العملاء عند /mcp. تم استبدال مجموعة الأدوات الوحيدة القديمة لكل عملية بالأدوات المدمجة أدناه.

قم بتوصيل عميل

تخضع نقطة النهاية /mcp للمصادقة الأساسية نفسها التي تخضع لها REST API. أرسل الترويسة Authorization، وأضف X-Device-Id إذا كنت تشغّل أكثر من جهاز:
القيمة YWRtaW46Y2hhbmdlbWU= هي ناتج base64("admin:changeme")؛ أنشئ قيمتك باستخدام echo -n 'user:pass' | base64. احذف Authorization إذا كانت المصادقة الأساسية معطّلة، واحذف X-Device-Id إذا كان هناك جهاز واحد فقط. يعتمد تنسيق التكوين بالضبط على العميل. إذا استطاع العميل تشغيل خوادم stdio فقط، استخدم جسر مثل mcp-remote.

أدوات

يتيح GOWA سبع أدوات. تقبل كل أداة وسيطًا باسم type (للإرسال) أو action (لجميع الأدوات الأخرى) لتحديد العملية. ملاحظات بشأن الحججج:
  • تتطلب whatsapp_send دائمًا type وphone. تُرسل الوسائط عبر عنوان URL فقط (image_url، video_url، audio_url، file_url، sticker_url)؛ ولا يستطيع MCP رفع ملفات محلية. يتطلب link كلًا من link وcaption؛ ويتطلب forward الحقل message_id.
  • تقبل whatsapp_send حقول الجدولة (scheduled_at، timezone، recurrence، weekdays، day_of_month، end_at، occurrence_limit). أدِر الجدولة الناتجة باستخدام whatsapp_schedule (تتطلب get وpause وresume وcancel الحقل schedule_id).
  • whatsapp_message يحتاج إلى phone (المحادثة) وmessage_id؛ edit يحتاج أيضاً إلى message.
  • في فرع main من GOWA بعد v9.9.0، تقبل whatsapp_message مع action: "edit" القيمة media_type: "image" أو media_type: "document" لاستبدال التعليق التوضيحي. طابِق نوع الوسائط الأصلي واحذف link. راجع تعديل تعليق توضيحي.
  • whatsapp_chat: يحتاج get_messages إلى chat_jid; archive needs chat_jid and archived.
  • whatsapp_app: يتطلب login_code الحقل phone.
الأزرار التجريبية، وموقع الطلب، وإرسال العربات متاحة من خلال REST فقط. انظر الرسائل التفاعلية. أدوات النشرة الإخبارية تدعم اكتشاف القناة، وعدادات التاريخ، واشتراكات التحديث المباشر المجددة تلقائيا. انظر newsletters. تطبيق تنزيلات URL للوسائط نفس فحوصات العنوان العام التي ترسل وتتصل مباشرة بدون HTTP_PROXY أو HTTPS_PROXY. التحميلات من الملفات المحلية تتطلب API REST. يعرض عميل MCP الخاص بك مخطط الإدخال الكامل لكل أداة. نقطة النهاية HTTP تقبل POST و DLETE. يتم تعطيل تدفق SSE.

تحديد الجهاز

كل مكالمة تحل جهازها بهذا الترتيب:
  1. حجة device_id على مكالمة الأداة.
  2. ترويسة X-Device-Id على اتصال MCP .
  3. الجهاز الوحيد المسجل، عندما يكون واحد منه بالضبط.
وإلا فشلت المكالمة مع device identification required: set the X-Device-Id header or pass device_id. انظر Multi-device.

العملاء البعيدين مع OAuth

العملاء المضيفون مثل موصلات كلود المخصصة لا يمكن إرفاق رأس المصادقة الأساسي. بالنسبة لهم، يمكن لGOWA تشغيل خادم إذن OAuth 2.1 ل /mcp. يتم إيقافه بشكل افتراضي.
المتطلبات والسلوك:
  • يجب تعيين APP_BASIC_AUTH: صفحة التفويض توقع على المستخدمين بنفس هذه الحسابات. فشل الإعداد بدونه.
  • يجب أن يكون المصدر والمورد HTTPS العملاء الرابط، لا عناوين داخلية مثل http://gowa:3000.
  • مع تشغيل OAuth ، يقبل /mcp الرمز المميز لحامله أو المصادقة الأساسية. لا تقبل الرموز المميزة على مسارات REST أو واجهة المستخدم.
  • ويقوم العملاء بتسجيل أنفسهم (تسجيل العملاء الديناميكيين 7591 (RFC 7591) وتقتصر هيئات التسجيل على 16 كيلوبايت ويعاد توجيه كل جهاز من أجهزة URI إلى 2 كيلوبايت. وتقتصر التسجيلات على 40 في الساعة و 000 1 من الزبائن المخزونين؛ أما الزبائن غير المستعملين فيجري تقسيمهم بعد 24 ساعة.
  • PKCE S256 إلزامي. تنتهي صلاحية الرموز بعد 5 دقائق، والوصول إلى الرموز بعد ساعة واحدة؛ تحديث الرموز المدوّرة، وإعادة استخدام الرمز القديم يلغي العائلة الرمزية بأكملها. يتم تخزين فقط تجزئة SHA-256 من الرموز المميزة، في MCP_OAUTH_DB_URI (file:storages/oauth.db).
إعادة توجيه URIs يجب أن تتطابق مع القيم المسجلة بالضبط. يمكن للعملاء الأصليين استخدام نسخ IP التراجع HTTP مع منفذ ديناميكي. تتطلب ردود المكالمات localhost منفذا صريحا ومطابقة دقيقة. تتطلب عمليات إعادة توجيه أخرى HTTPS. و OAuth resource مرتبط بـ MCP URL; يمكن لطلبات الرموز أن تحذف ذلك، ولكن يجب أن تتطابق القيمة الموردة. وتشمل ردود التفويض الناجحة iss. الرموز والرموز المميزة المنتهية الصلاحية يتم تقسيمها أثناء كتابة OAuth. مازالت التجزئة الرمزية المتجددة مطلوبة في الوقت نفسه للكشف عن إعادة اللعب ضد العائلة الحية، لمدة 30 يوما على الأكثر من العمر الرمزي التحديثي. حذف أو استبدال قاعدة بيانات OAuth يبطل العملاء الحاليين والمنح. نقاط النهاية، نسبةً إلى عنوان الجهة المُصدِرة: /oauth/authorize، /oauth/token، /oauth/register. تستخدم بيانات الاكتشاف الوصفية عناوين URL المعروفة well-known في جذر النطاق مع إدراج المسار، لذا عند ضبط APP_BASE_PATH=/gowa يجب أن يوجّه الوكيل الطلبات إلى:
تحقق من الاكتشاف من الخارج:
ثم أضف https://gowa.example.com/mcp كموصل مخصص وقم بتسجيل الدخول باستخدام حساب APP_BASIC_AUTH.
تأكد من أن الوصول إلى Cloudflare أو تحديات البوت أو وكلاء المصادقة أمام GOWA لا يعترضون المسارات المعروفة جيداً أو /oauth/* أو /mcp. حد معدل تسجيل الدخول الفاشلة على /oauth/authorize في وكيلك.