> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# التعامل مع الوسائط

> تحميل وإرسال الوسائط، وفهم حدود الحجم والتحويلات، وتحميل الوسائط من الرسائل الواردة.

## الحدود

| نوع | الحد الأقصى الافتراضي |
| - | - |
| صورة | 20 ميغابايت |
| وثيقة (`/send/file`) | 50 ميغابايت |
| فيديو | 100 ميغابايت |
| الوسائط المحملة (الواردة) | 500 ميغابايت |

الحد الأقصى لجهاز طلب HTTP يساوي حد الفيديو (100 ميغابايت)، لذلك لا يمكن أن يتجاوز الرفع. استفسر عن القيم الحية باستخدام `GET /app/info` (`max_image_size`, `max_file_size`, `max_video_size`). هذه الحدود يتم تجميعها بشكل افتراضي؛ لا يوجد متغير بيئة لهم.

## طريقتان لتوفير وسائل الإعلام

تقبل كل نقطة نهاية للوسائط إما ملفًا ضمن طلب متعدد الأجزاء أو عنوان URL يجلب GOWA محتواه من جانب الخادم:

```bash theme={null}
# upload
curl -u admin:changeme -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 -F image=@photo.jpg

# URL
curl -u admin:changeme -X POST http://localhost:3000/send/image \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 -F image_url=https://example.com/photo.jpg
```

إرسال واحد أو الآخر، وليس كليهما. يجب أن تستخدم عناوين الوسائط البعيدة HTTP أو HTTPS وأن تعقد العزم على العناوين العامة. تقوم GOWA بحظر الحلقة الخلفية، الخاصة، والربط - المحلي، وغيرها من الوجهات المحجوزة، بما في ذلك إعادة توجيه الأهداف. تحميل الملفات المحلية كبيانات متعددة الأجزاء بدلاً من استخدام عنوان URL داخلي.

## معالجة

تحتاج GOWA إلى Fmpeg و libwebp على المضيف (كلاهما في صورة Docker).

| خيار | Endpoint | التأثيرات |
| - | - | - |
| `compress` | الصورة (الافتراضية `true`)، الفيديو (الافتراضي `false`) | إعادة الترميز قبل الإرسال. |
| `hd` | صورة، فيديو | أرسل بدقة HD دون تكبير الأبعاد: صور يصل طول ضلعها الأطول إلى 2560 بكسل؛ وفيديو بتنسيق H.264 وبحد أقصى 1280×1280. يتجاوز هذا الخيار `compress`. |
| `view_once` | صورة، فيديو | يمكن للمستلم فتحه مرة واحدة. |
| `gif_playback` | فيديو | العب كحلقة GIF. |
| `ptt` | صوت | إرسال كملاحظة صوتية (اضغط للتحدث). تم تحويلها باستخدام FFmpeg. |
| (تلقائي) | ملصق | JPG، PNG، WebP أو GIF تم تحويلها إلى ملصق WebP 512×512. يجب أن يستوفي WebP حدود ملصقات WhatsApp. |

`/send/file` يرسل المستندات دون تحويل.

معالجة الصور تفحص أبعاد الترويسة قبل فك الترميز. أطول حافة مقبولة هي 768 32 بكسل. الصور غير JPEG لديها ميزانية 40 مليون بكسل. ولدى JPEGs سقف قدره 80 مليون بكسل بالإضافة إلى ميزانية تفكيك الذاكرة 320 ميغابايت، وبالتالي يرفض عدد كبير من JPEG تقدمي أو MYK دون سقف البكسل. يمكن لإرسال الصورة الأصلية حذف الصور المصغرة عندما يتجاوز فك الترميز الميزانية. الصور المتحركة التفاعلية لها حدود منفصلة أصغر في [الرسائل التفاعلية](https://gowa-docs.mintlify.site/ar/examples/interactive-messages.md).

## الوسائط الواردة

عند ضبط `WHATSAPP_AUTO_DOWNLOAD_MEDIA=true` (الإعداد الافتراضي)، ينزّل GOWA الوسائط من الرسائل الواردة إلى `statics/media/` ويضع المسار النسبي في حمولة خطاف الويب:

```json theme={null}
{
  "image": "statics/media/1752404751-ad9e37ac-c658-4fe5-8d25-ba4a3f4d58fd.jpeg"
}
```

إحضاره على `http://<host>:3000/statics/media/<file>`. تعيين `WHATSAPP_IGNORE_STATUS_MEDIA=true` لتخطي الوسائط من تحديثات الحالة.

مع إيقاف التحميل التلقائي، تحمل الحمولة عنوان WatsApp CDN بدلاً من ذلك. قم بالتحميل من خلال GOWA، الذي يقوم بفك تشفير الملف:

```bash theme={null}
curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/message/3EB0C127D7BACC83D6A3/download?phone=628987654321@s.whatsapp.net"
```

WhatsApp يحتفظ بالوسائط على خوادمه لفترة محدودة. قم بتنزيل ما تحتاجه على الفور.

على نظام GOWA `main` بعد v9.9.0، يمكن للتنزيلات الصريحة وأجهزة إعادة التوجيه أن تطلب من الهاتف إعادة تحميل الوسائط التي انتهت صلاحيتها. يجب أن يكون الهاتف على الإنترنت ولا يزال لديه الملف. وتنتظر GOWA ما يصل إلى 30 ثانية للحصول على رد. وينطبق هذا أيضا على إجراءات MCP `download_media` و `forward` و [Chatwoot Histimports](https://gowa-docs.mintlify.site/ar/integrations/chatwoot.md#%D8%B3%D8%AC%D9%84-%D8%A7%D9%84%D8%A7%D8%B3%D8%AA%D9%8A%D8%B1%D8%A7%D8%AF).

## التخزين والتنظيف

المسارات نسبية إلى دليل العملية، وعادةً ما يكون `src/` عند التشغيل من المصدر أو `/app` في Docker. يربط Compose دليلي `storages/` و`statics/` في المستودع داخل `/app`.

| المسار | المحتويات |
| - | - |
| `statics/media/` | تم تنزيل ملفات ويب هوك والتنزيلات الصريحة، بما في ذلك دلائل الدردشة/التاريخ الفرعية. |
| `storages/<timestamp>-<uuid>[.<extension>]` | نسخ إضافية تم حفظها بواسطة معالج الصور الواردة عند تمكين التنزيلات التلقائية. |
| `storages/scheduled/` | المرفقات المحتفظ بها عن طريق الإرسالات المجدولة. دع المجدول يدير هذه المرفقات. |
| `storages/history-*.json` | دفن التاريخ بمعزل عن التنزيلات الإعلامية. |

لا يوجد إعداد للاحتفاظ بالوسائط بناءً على عمرها أو نقطة نهاية لتنظيفها. قد توجد نسخ من الصورة في كلٍّ من `storages/` و`statics/media/`. لا تحذف دليل `storages/` بالكامل مطلقًا لاستعادة مساحة الوسائط.

أوقف GOWA وأي عمليات أخرى تكتب البيانات مؤقتًا، وأنشئ نسخة احتياطية من الملفات المطلوبة، ثم عاين الملفات المراد حذفها. تُنفَّذ أمثلة GNU find هذه من دليل النشر وتختار الملفات التي مضى عليها 31 يومًا كاملًا على الأقل.

```bash theme={null}
find ./statics/media -type f -mtime +30 -print
find ./storages -maxdepth 1 -type f -mtime +30 \
  -name '[0-9]*-????????-????-????-????-????????????*' -print
```

بعد مراجعة كل مسار، استبدل `-print` بـ `-delete` في الأوامر نفسها. احتفظ بملفات قاعدة البيانات، وملفات SQLite المصاحبة `-wal` و`-shm`، والمرفقات المجدولة، والملفات المخصصة. أعد تشغيل GOWA بعد ذلك. تتوقف المسارات المحذوفة وعناوين URL الثابتة عن العمل، ولا تؤدي إزالة الوسائط إلى حذف سجل المحادثات.

`WHATSAPP_AUTO_DOWNLOAD_MEDIA=false` توقف التنزيلات التلقائية والنسخ الإضافية للصور في المستقبل. لا يزيل الملفات القديمة أو يمنع تنزيلات REST أو MCP الصريحة. راجع دليل تخزين وتنظيف الوسائط الكامل]\([https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/media-storage.md](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/media-storage.md)).

`/statics` لا يزال عاماً. ويتم استخدام HTML وSVG والنصوص النصية والمستندات الأخرى كمرفقات مع `application/octet-stream` و`nosniff`. وحدات البايت للصور المدعومة تحت مسارات معاينة الصورة يمكن أن تكون داخل الخط. حماية المحتوى هذه لا تقيد من يمكنه تنزيل ملف. حماية الوسائط الحساسة عند الوكيل العكسي.

## استكشاف الأخطاء

| مشكلة | إصلاح |
| - | - |
| خطأ `413` أو حد الجسم | الملف يتجاوز 100 ميغابايت؛ ارسل رابط بدلاً من ذلك. |
| فشل الملاحظة الصوتية أو تشغيل الملف | تثبيت FFmpeg; تعيين `ptt=true`. |
| فشل تحويل الملصق | ثبّت أدوات libwebp (`cwebp`، `dwebp`، `webpmux`). |
| أخفق رابط الوسائط | يجب أن يكون عنوان URL عامًا ، وإرجاع الملف مباشرة (لا توجد صفحة HTML) وتلائم الحد الأقصى للحجم. |


## Related topics

- [إرسال الرسائل](https://gowa-docs.mintlify.site/ar/examples/sending-messages.md)
- [تلقي الرسائل](https://gowa-docs.mintlify.site/ar/examples/receiving-messages.md)
- [رسائل تفاعلية تجريبية](https://gowa-docs.mintlify.site/ar/examples/interactive-messages.md)
- [خطأ في التعامل](https://gowa-docs.mintlify.site/ar/advanced/error-handling.md)
- [تحميل الوسائط من الرسالة](https://gowa-docs.mintlify.site/ar/api-reference/message/تحميل-الوسائط-من-الرسالة.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.