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

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

اهداف

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

سطح CLI

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

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

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

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

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

رسانه ورودی به فرمان‌ها

• وقتی پیام‌های وب ورودی شامل رسانه باشند، OpenClaw آن را در یک فایل موقت دانلود می‌کند و متغیرهای قالب‌سازی را در دسترس می‌گذارد:
  • {{MediaUrl}} شبه‌نشانی برای رسانه ورودی.
  • {{MediaPath}} مسیر موقت محلی که پیش از اجرای فرمان نوشته می‌شود.
• وقتی sandbox Docker برای هر نشست فعال باشد، رسانه ورودی به فضای کاری 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).
• رسانه بیش‌ازحد بزرگ از درک رد می‌شود، اما پاسخ‌ها همچنان با بدنه اصلی عبور می‌کنند.

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

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

مرتبط

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