دعم الصور والوسائط

تعمل قناة WhatsApp على Baileys Web. تتناول هذه الصفحة قواعد التعامل مع الوسائط في عمليات الإرسال وGateway وردود الوكيل.

الأهداف

• إرسال وسائط مع تسمية توضيحية اختيارية عبر openclaw message send --media.
• السماح للردود التلقائية من صندوق الوارد على الويب بتضمين وسائط إلى جانب النص.
• إبقاء الحدود الخاصة بكل نوع معقولة وقابلة للتوقع.

واجهة CLI

openclaw message send --target <dest> --media <path-or-url> [--message <caption>]

• --media <path-or-url> — إرفاق وسائط (صورة/صوت/فيديو/مستند)؛ يقبل المسارات المحلية أو عناوين URL. اختياري؛ يمكن أن تكون التسمية التوضيحية فارغة عند إرسال الوسائط فقط.
• --gif-playback — معاملة وسائط الفيديو كصورة GIF متحركة (WhatsApp فقط).
• --force-document — إرسال الوسائط كمستند لتجنب ضغط القناة (Telegram وWhatsApp)؛ ينطبق على الصور وملفات GIF ومقاطع الفيديو.
• --reply-to <id> و--thread-id <id> و--pin و--silent — خيارات التسليم والمحادثات المتسلسلة المشتركة مع عمليات إرسال النصوص فقط.
• --dry-run — طباعة الحمولة بعد حلّها وتخطي الإرسال.
• --json — طباعة النتيجة بتنسيق JSON: ‏{ action, channel, dryRun, handledBy, messageId?, payload } (يتضمن payload نتيجة الإرسال الخاصة بالقناة، بما في ذلك أي مرجع للوسائط).

سلوك قناة WhatsApp Web

• الإدخال: مسار ملف محلي أو عنوان URL يستخدم HTTP(S).
• التدفق: التحميل في مخزن مؤقت، واكتشاف نوع الوسائط، ثم إنشاء حمولة الإرسال وفقًا للنوع:
  • الصور: تُحسَّن لتلائم الحد channels.whatsapp.mediaMaxMb (الافتراضي 50 ميغابايت). يُعاد ضغط الصور غير الشفافة بتنسيق JPEG (يبدأ تسلسل الأبعاد الجانبية الافتراضي عند 2048 بكسل، ثم يتناقص عند تكرار تجاوز الحجم)؛ وتُحفظ الصور ذات الشفافية بتنسيق PNG. إذا كان المصدر أصلًا ملف JPEG أو PNG أو WebP مقبولًا ضمن ميزانية الحجم وطول الجانب، تُحفظ البايتات الأصلية دون تغيير بدلًا من إعادة ضغطها. لا يُعاد ترميز ملفات GIF المتحركة مطلقًا، بل يُتحقق من حجمها فقط.
  • الصوت/الرسائل الصوتية: ما لم يكن الصوت أصلًا بتنسيق صوتي أصلي للرسائل الصوتية (.ogg/.opus أو audio/ogg/audio/opus)، يُحوَّل الصوت الصادر عبر ffmpeg إلى Opus/OGG (أحادي القناة بتردد 48 كيلوهرتز ومعدل 64 كيلوبت في الثانية، وبحد أقصى 20 دقيقة) قبل إرساله كملاحظة صوتية (ptt: true).
  • الفيديو: يُمرَّر دون تعديل حتى 16 ميغابايت.
  • المستندات: أي محتوى آخر، حتى 100 ميغابايت، مع الحفاظ على اسم الملف عند توفره.
• التشغيل بأسلوب GIF في WhatsApp: إرسال ملف MP4 مع gifPlayback: true ‏(CLI: ‏--gif-playback) كي تعرضه تطبيقات الأجهزة المحمولة مكررًا ضمن المحادثة.
• يفضّل اكتشاف نوع MIME البايتات السحرية المستشعرة، ثم امتداد الملف، ثم ترويسات الاستجابة؛ ولا تتجاوز الحاوية العامة المستشعرة (application/octet-stream أو zip) مطلقًا تعيينًا أكثر تحديدًا للامتداد (مثل XLSX مقابل ZIP).
• تأتي التسمية التوضيحية من --message أو reply.text؛ ويُسمح بأن تكون فارغة.
• التسجيل: يعرض الوضع غير المفصل ↩️/✅؛ ويتضمن الوضع المفصل الحجم ومسار المصدر/عنوان URL.

مسار الرد التلقائي

• تُرجع getReplyFromConfig حمولة رد (أو مصفوفة من الحمولات) تتضمن text? وmediaUrl? وmediaUrls? إلى جانب حقول أخرى.
• عند وجود وسائط، يحل مرسل الويب المسارات المحلية أو عناوين URL باستخدام المسار نفسه الذي يستخدمه openclaw message send.
• تُرسل إدخالات الوسائط المتعددة بالتتابع عند توفيرها.

الوسائط الواردة إلى الأوامر

• عندما تتضمن رسائل الويب الواردة وسائط، ينزّلها OpenClaw إلى ملف مؤقت ويتيح متغيرات القوالب:
  • {{MediaUrl}} — عنوان URL زائف للوسائط الواردة.
  • {{MediaPath}} — مسار مؤقت محلي يُكتب قبل تشغيل الأمر.
• عند تمكين بيئة Docker معزولة لكل جلسة، تُنسخ الوسائط الواردة إلى مساحة عمل البيئة المعزولة، وتُعاد كتابة MediaPath/MediaUrl إلى مسار نسبي داخل البيئة المعزولة مثل media/inbound/<filename>.
• يعمل فهم الوسائط (المُعد عبر tools.media.* أو tools.media.models المشتركة) قبل تطبيق القوالب، ويمكنه إدراج كتل [Image] و[Audio] و[Video] في Body.
  • يضبط الصوت {{Transcript}} ويستخدم النص المنسوخ لتحليل الأوامر، بحيث تظل أوامر الشرطة المائلة تعمل.
  • تحافظ أوصاف الفيديو والصور على أي نص للتسمية التوضيحية لاستخدامه في تحليل الأوامر.
  • إذا كان النموذج الأساسي النشط يدعم الرؤية أصلًا، يتخطى OpenClaw كتلة ملخص [Image] ويمرر الصورة الأصلية إلى النموذج بدلًا منها.
• افتراضيًا، لا تتم معالجة سوى أول مرفق صورة/صوت/فيديو مطابق؛ اضبط tools.media.<capability>.attachments لمعالجة عدة مرفقات.

الحدود والأخطاء

حدود الإرسال الصادر (إرسال WhatsApp عبر الويب)

• الصور: حتى channels.whatsapp.mediaMaxMb (الافتراضي 50 ميغابايت) بعد التحسين.
• الصوت/الفيديو: حد 16 ميغابايت (الافتراضي المشترك؛ يتجاوزه mediaMaxMb عند الإرسال عبر WhatsApp).
• المستندات: حد 100 ميغابايت (الافتراضي المشترك؛ يتجاوزه mediaMaxMb عند الإرسال عبر WhatsApp).
• تؤدي الوسائط المتجاوزة للحجم أو غير القابلة للقراءة إلى ظهور خطأ واضح في السجلات، ويُتخطى الرد.

حدود فهم الوسائط (النسخ/الوصف)

• القيمة الافتراضية للصور: 10 ميغابايت (tools.media.image.maxBytes).
• القيمة الافتراضية للصوت: 20 ميغابايت (tools.media.audio.maxBytes).
• القيمة الافتراضية للفيديو: 50 ميغابايت (tools.media.video.maxBytes).
• تتخطى الوسائط المتجاوزة للحجم عملية الفهم، لكن الرد يستمر باستخدام النص الأصلي.

ملاحظات للاختبارات

• تغطية مسارات الإرسال والرد لحالات الصور والصوت والمستندات.
• التحقق من حدود الحجم بعد تحسين الصور ومن علامة الملاحظة الصوتية للصوت.
• ضمان توزيع الردود متعددة الوسائط إلى عمليات إرسال متتابعة.

ذو صلة

• التقاط الصور بالكاميرا
• فهم الوسائط
• الصوت والملاحظات الصوتية