پشتیبانی از تصویر و رسانه

کانال WhatsApp از طریق Baileys Web اجرا می‌شود. این سند قواعد فعلی مدیریت رسانه را برای ارسال، Gateway، و پاسخ‌های عامل ثبت می‌کند.

# اهداف

• ارسال رسانه با کپشن اختیاری از طریق openclaw message send --media.
• اجازه دادن به پاسخ‌های خودکار از صندوق ورودی وب برای شامل کردن رسانه در کنار متن.
• منطقی و قابل پیش‌بینی نگه داشتن محدودیت‌ها برای هر نوع.

# سطح CLI

• openclaw message send --media <path-or-url> [--message <caption>]
  • --media اختیاری است؛ کپشن می‌تواند برای ارسال‌های فقط رسانه خالی باشد.
  • --dry-run payload حل‌شده را چاپ می‌کند؛ --json مقدار { channel, to, messageId, mediaUrl, caption } را خروجی می‌دهد.

# رفتار کانال WhatsApp Web

• ورودی: مسیر فایل محلی یا URL با HTTP(S).
• جریان: بارگذاری در یک بافر، تشخیص نوع رسانه، و ساخت payload درست:
  • تصاویر: تغییر اندازه و فشرده‌سازی دوباره به JPEG (حداکثر ضلع 2048px) با هدف‌گیری channels.whatsapp.mediaMaxMb (پیش‌فرض: 50 MB).
  • صدا/صوت/ویدیو: عبور بدون تغییر تا 16 MB؛ صدا به‌صورت یادداشت صوتی (ptt: true) ارسال می‌شود.
  • اسناد: هر مورد دیگر، تا 100 MB، با حفظ نام فایل در صورت موجود بودن.
• پخش به سبک GIF در WhatsApp: یک MP4 با gifPlayback: true ارسال کنید (CLI: --gif-playback) تا کلاینت‌های موبایل آن را به‌صورت درون‌خطی تکرار کنند.
• تشخیص MIME ابتدا magic byteها، سپس هدرها، و بعد پسوند فایل را ترجیح می‌دهد.
• کپشن از --message یا reply.text می‌آید؛ کپشن خالی مجاز است.
• ثبت گزارش: حالت غیرمفصل ↩️/✅ را نشان می‌دهد؛ حالت مفصل شامل اندازه و مسیر/URL منبع است.

# خط لوله پاسخ خودکار

• getReplyFromConfig مقدار { text?, mediaUrl?, mediaUrls? } را برمی‌گرداند.
• وقتی رسانه وجود دارد، فرستنده وب مسیرهای محلی یا URLها را با همان خط لوله openclaw message send حل می‌کند.
• اگر چند ورودی رسانه ارائه شود، به‌ترتیب و پشت سر هم ارسال می‌شوند.

# رسانه ورودی به فرمان‌ها (Pi)

• وقتی پیام‌های وب ورودی شامل رسانه باشند، OpenClaw آن را در یک فایل موقت دانلود می‌کند و متغیرهای قالب‌بندی را در دسترس می‌گذارد:
  • {{MediaUrl}} شبه-URL برای رسانه ورودی.
  • {{MediaPath}} مسیر موقت محلی که پیش از اجرای فرمان نوشته می‌شود.
• وقتی sandbox داکر برای هر نشست فعال باشد، رسانه ورودی در فضای کاری sandbox کپی می‌شود و MediaPath/MediaUrl به یک مسیر نسبی مانند media/inbound/<filename> بازنویسی می‌شوند.
• درک رسانه (اگر از طریق tools.media.* یا tools.media.models مشترک پیکربندی شده باشد) پیش از قالب‌بندی اجرا می‌شود و می‌تواند بلوک‌های [Image]، [Audio]، و [Video] را در Body درج کند.
  • صدا {{Transcript}} را تنظیم می‌کند و از رونوشت برای تحلیل فرمان استفاده می‌کند تا فرمان‌های اسلش همچنان کار کنند.
  • توضیحات ویدیو و تصویر هر متن کپشن را برای تحلیل فرمان حفظ می‌کنند.
  • اگر مدل تصویر اصلی فعال از پیش به‌صورت بومی از بینایی پشتیبانی کند، OpenClaw بلوک خلاصه [Image] را رد می‌کند و به‌جای آن تصویر اصلی را به مدل می‌فرستد.
• به‌صورت پیش‌فرض فقط نخستین پیوست تصویر/صدا/ویدیوی مطابق پردازش می‌شود؛ برای پردازش چند پیوست، tools.media.<cap>.attachments را تنظیم کنید.

# محدودیت‌ها و خطاها

سقف‌های ارسال خروجی (ارسال وب WhatsApp)

• تصاویر: تا channels.whatsapp.mediaMaxMb (پیش‌فرض: 50 MB) پس از فشرده‌سازی دوباره.
• صدا/صوت/ویدیو: سقف 16 MB؛ اسناد: سقف 100 MB.
• رسانه بیش‌ازحد بزرگ یا ناخوانا → خطای شفاف در گزارش‌ها و پاسخ رد می‌شود.

سقف‌های درک رسانه (رونویسی/توضیح)

• پیش‌فرض تصویر: 10 MB (tools.media.image.maxBytes).
• پیش‌فرض صدا: 20 MB (tools.media.audio.maxBytes).
• پیش‌فرض ویدیو: 50 MB (tools.media.video.maxBytes).
• رسانه بیش‌ازحد بزرگ درک را رد می‌کند، اما پاسخ‌ها همچنان با بدنه اصلی عبور می‌کنند.

# نکات برای آزمون‌ها

• جریان‌های ارسال + پاسخ را برای موارد تصویر/صدا/سند پوشش دهید.
• فشرده‌سازی دوباره تصاویر (کران اندازه) و پرچم یادداشت صوتی برای صدا را اعتبارسنجی کنید.
• اطمینان حاصل کنید پاسخ‌های چندرسانه‌ای به‌صورت ارسال‌های ترتیبی منشعب می‌شوند.

# مرتبط

• ثبت تصویر با دوربین
• درک رسانه
• صدا و یادداشت‌های صوتی