انتقل إلى المحتوى
OmniChannels.ai
القائمة

وسائط واتساب API: أنواع الملفات المدعومة وحدود الحجم

حدود حجم ملفات وسائط واتساب API وأنواع الملفات المدعومة للصور والفيديو والصوت والمستندات والملصقات، مع الرفع مقابل الرابط ومعرّفات الوسائط والتعليقات.

آخر تحديث 9 دقائق للقراءة

بقلم OmniChannels.ai Editorial Team · مراجعة BroadNet Messaging Solutions Team

واتساب

الإجابة المختصرة

تذكر وثائق Meta وقت كتابة هذا المقال الحدود القصوى التالية لوسائط واتساب Cloud API: الصور 5 ميغابايت (JPEG وPNG وWebP ثابت)، والفيديو 16 ميغابايت (MP4 أو 3GPP بترميز H.264 وAAC)، والصوت 16 ميغابايت، والمستندات 100 ميغابايت، والملصقات المتحركة 500 كيلوبايت والثابتة 100 كيلوبايت. ارفع الملف وأرسل معرّف الوسائط بدل الرابط، وتأكد من تطابق نوع MIME مع الملف.

في هذه الصفحة
  1. ما حدود حجم وسائط واتساب API؟
  2. ما صيغ الصور والملصقات المدعومة؟
  3. ما صيغ الفيديو والصوت المدعومة؟
  4. ما صيغ المستندات المدعومة؟
  5. هل أرفع الوسائط أم أرسل رابطًا؟
  6. كم تبقى صلاحية معرّفات الوسائط؟
  7. هل يمكنني إضافة تعليقات إلى رسائل الوسائط؟
  8. كيف تعمل الوسائط في قوالب الرسائل؟
  9. كيف أنزّل الوسائط التي يرسلها العميل؟
  10. مثال تطبيقي: عيادة أسنان ترسل التقارير
  11. ما الأخطاء الشائعة؟
  12. كيف تساعدك OmniChannels.ai

أهم النقاط

  • بحسب وثائق Meta وقت كتابة هذا المقال، الحدود هي 5 ميغابايت للصور، و16 ميغابايت للفيديو والصوت، و100 ميغابايت للمستندات، و500 كيلوبايت (متحرك) أو 100 كيلوبايت (ثابت) للملصقات.
  • يجب أن يكون الفيديو بترميز H.264 وصوته AAC، وأن تكون الصور بنظام ألوان RGB أو RGBA بعمق 8 بت؛ وقد يُرفض ملف ضمن حد الحجم بسبب الترميز أو نظام الألوان.
  • توصي Meta بإرسال الوسائط المرفوعة عبر المعرّف بدل الرابط لأداء أفضل.
  • تنتهي صلاحية معرّفات الوسائط الناتجة عن الرفع بعد 30 يومًا، وتلك المستلمة في webhooks الواردة بعد 7 أيام، فنزّل ملفات العملاء سريعًا.
  • تعليقات الصور والفيديو والمستندات محدودة بـ 1,024 حرفًا، وغالبًا يشير الخطأ 131053 إلى نوع MIME لا يطابق الملف.

هذا الدليل موجّه إلى المطورين والمسوّقين الذين يرسلون الصور والفيديو والصوت والمستندات والملصقات عبر واجهة واتساب للأعمال (WhatsApp Business API) ويريدون تجنب فشل الإرسال. يعرض أنواع الملفات وحدود الحجم التي توثّقها Meta، ويشرح الرفع مقابل الرابط، ومعرّفات الوسائط، والتعليقات، ورؤوس القوالب، ويبيّن كيفية التعامل مع الملفات التي يرسلها العملاء إليك.

جميع الأرقام أدناه هي القيم التي توثّقها Meta وقت كتابة المقال (7 نوفمبر 2026). قد تغيّرها Meta، لذا اعتمد مرجع الوسائط مصدرًا نهائيًا.

ما حدود حجم وسائط واتساب API؟

لكل نوع وسائط سقف خاص، والحد الأعلى لأي وسائط في Cloud API هو 100 ميغابايت. تحظى المستندات بأكبر مساحة، والملصقات بأقلها.

نوع الوسائط الحد الأقصى للحجم ملاحظات
صورة 5 MB RGB أو RGBA بعمق 8 بت فقط
فيديو 16 MB فيديو H.264 وصوت AAC
صوت 16 MB عدة صيغ، انظر أدناه
مستند 100 MB ملفات Office وPDF والنصوص
ملصق (متحرك) 500 KB WebP فقط
ملصق (ثابت) 100 KB WebP فقط

قد يلتزم الملف بحد الحجم ويفشل مع ذلك بسبب الصيغة. تسرد الأقسام التالية الصيغ المقبولة لكل نوع.

ما صيغ الصور والملصقات المدعومة؟

يمكن أن تكون الصور JPEG أو PNG أو WebP ثابتة، بحجم يصل إلى 5 ميغابايت، وبنظام ألوان RGB أو RGBA بعمق 8 بت. أما الملصقات فيجب أن تكون WebP.

النوع الامتداد نوع MIME
JPEG .jpeg image/jpeg
PNG .png image/png
WebP ثابت .webp image/webp

توثّق Meta ثلاث قواعد إضافية للصور. يُحوَّل WebP الثابت المرسل في رسالة صورة إلى JPEG. وتُرفض ملفات WebP المتحركة، وملفات WebP التي لا يمكن فك ترميزها، والصور التي يتجاوز أحد أضلاعها 4,096 بكسل. أما الملصقات فاستخدم WebP بنوع image/webp: حتى 500 كيلوبايت إن كان متحركًا و100 كيلوبايت إن كان ثابتًا.

إذا كانت أصول علامتك التجارية ملفات PNG كبيرة من أداة تصميم، فصدّر صورة JPEG بحجم مناسب للويب بدل إرسال الأصل.

ما صيغ الفيديو والصوت المدعومة؟

الفيديو بصيغة MP4 أو 3GPP حتى 16 ميغابايت. ويمكن أن يكون الصوت AAC أو AMR أو MP3 أو M4A أو OGG بترميز Opus، وبحد أقصى 16 ميغابايت أيضًا.

النوع الامتداد نوع MIME
فيديو MP4 .mp4 video/mp4
فيديو 3GPP .3gp video/3gpp
صوت AAC .aac audio/aac
صوت AMR .amr audio/amr
صوت MP3 .mp3 audio/mpeg
صوت MP4 .m4a audio/mp4
صوت OGG .ogg audio/ogg

بالنسبة للفيديو، تشترط Meta ترميز H.264 وصوت AAC، بمسار صوتي واحد أو دون صوت. وتنصح Meta كذلك بتجنب ملف H.264 "High" مع B-frames لأن تطبيقات واتساب على أندرويد لا تدعمه؛ استخدم "Main" دون B-frames، أو "Baseline". ضع صناديق moov قبل صناديق mdat، وهذا يعني في ffmpeg الخيار -movflags faststart.

أما OGG فيُدعم فيه ترميز Opus فقط، ولا يُدعم النوع الأساسي audio/ogg، ويجب أن يكون المدخل أحادي القناة (mono).

ما صيغ المستندات المدعومة؟

يمكن أن تكون المستندات PDF أو Word أو Excel أو PowerPoint أو نصًا عاديًا، حتى 100 ميغابايت.

النوع الامتداد نوع MIME
PDF .pdf application/pdf
Word .doc, .docx application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document
Excel .xls, .xlsx application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
PowerPoint .ppt, .pptx application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation
نص .txt text/plain

تقبل رسائل المستندات اسم ملف اختياريًا مع امتداده، ويختار تطبيق واتساب أيقونة الملف بحسب هذا الامتداد. اختر اسمًا مقروءًا مثل invoice-2026-1042.pdf لأن العميل يراه.

هل أرفع الوسائط أم أرسل رابطًا؟

توصي Meta برفع الملف وإرسال معرّف الوسائط. ويمكنك بدلًا من ذلك إرسال رابط إلى ملف على خادم عام، لكن مراجع Meta للصور والفيديو والمستندات تقول إن المعرّف المرفوع أفضل أداءً، وتقول إرشادات الإنتاجية لديها الشيء نفسه للأحجام الكبيرة.

معرّف الوسائط الرابط
طريقة العمل ارفع أولًا ثم أشر إلى المعرّف الناتج أشر إلى عنوان عام؛ يُجلب الملف عند الإرسال
توجيه Meta موصى به مدعوم وغير موصى به
الصلاحية 30 يومًا من الرفع ما دام خادمك يقدّم الملف
سبب الفشل معرّف منتهٍ أو غير صالح عنوان لا يمكن الوصول إليه أو بطيء أو بنوع خاطئ

مع نقطة النهاية الخاصة بـ Meta، يكون الرفع طلب POST إلى /<PHONE_NUMBER_ID>/media مع الملف ونوع MIME الخاص به وmessaging_product=whatsapp، وتكون الاستجابة {"id": "<MEDIA_ID>"}. تُشفَّر الملفات المرفوعة وتُحفظ 30 يومًا ما لم تحذفها قبل ذلك.

على نقطة نهاية واتساب في OmniChannels.ai، تأخذ رسالة الوسائط إما mediaUrl (رابط HTTPS عام) أو mediaFile (ملف ترفعه مع الطلب)، ويوضع التعليق في content. راجع وثائق واتساب API. واسأل فريقنا عن كيفية تعامل حسابك مع تخزين الوسائط وإعادة استخدامها في الإرسال الكبير.

كم تبقى صلاحية معرّفات الوسائط؟

تذكر Meta 30 يومًا للمعرّف الناتج عن الرفع، و7 أيام للمعرّف المستلم في webhook وارد. أما رابط التنزيل الناتج عن المعرّف فتنتهي صلاحيته بعد 5 دقائق.

النتائج العملية:

  • لا تخزّن معرّف الوسائط مؤقتًا لأشهر. احتفظ بملفك الأصلي وأعد الرفع عند رفض المعرّف.
  • نزّل الملفات الواردة فور وصول الحدث واحتفظ بنسختك الخاصة.
  • لا تخزّن رابط تنزيل تم الحصول عليه؛ اطلب رابطًا جديدًا عند الحاجة.

هل يمكنني إضافة تعليقات إلى رسائل الوسائط؟

نعم. تقبل رسائل الصور والفيديو والمستندات تعليقًا اختياريًا حتى 1,024 حرفًا بحسب مراجع الرسائل لدى Meta. التعليقات نص عادي بجانب الملف.

لا تحتوي رسائل الصوت والملصقات على تعليق في هذا النموذج. وإن أردت كلمات مع رسالة صوتية فأرسل رسالة نصية قصيرة بجانبها. التعليقات داخل نافذة خدمة العملاء حرة الصياغة؛ أما خارجها فيجب أن تُرسل الوسائط داخل قالب معتمد.

كيف تعمل الوسائط في قوالب الرسائل؟

يمكن أن يتضمن القالب صورة أو فيديو أو مستندًا في رأسه، ويُثبَّت هذا الرأس عند إنشاء القالب. وعند تقديم القالب للاعتماد توفّر ملفًا نموذجيًا، ويمكنك تقديم الملف الفعلي عند الإرسال.

في واجهتنا، يمكن أن يكون headerFormat هو IMAGE أو VIDEO أو DOCUMENT عند الإنشاء، ويحمل headerFile الملف النموذجي، ويستبدل mediaUrl وقت الإرسال وسائط الرأس. راجع وثائق القوالب لدى Meta لمعرفة متطلبات الملف النموذجي. اطلع على فئات القوالب والاعتماد وأمثلة القوالب.

كيف أنزّل الوسائط التي يرسلها العميل؟

تصل الوسائط الواردة في webhook مع معرّف وسائط؛ تحوّله إلى رابط ثم تنزّل الملف بتفويض.

  1. اقرأ معرّف الوسائط من حدث الرسالة الواردة.
  2. اطلب رابط الوسائط لهذا المعرّف. تتضمن استجابة Meta الحقول url وmime_type وsha256 وfile_size.
  3. أرسل طلب GET إلى ذلك الرابط مع ترويسة Authorization: Bearer <token>. بدون الرمز يفشل الطلب.
  4. تحقق من ترويسة Content-Type وقيمة sha256، ثم خزّن الملف.
  5. عند 404 اطلب رابطًا جديدًا وأعد المحاولة؛ وإن استمر الفشل فجدّد رمز الوصول.

الحد الأقصى للوسائط الواردة في Cloud API لدى Meta هو 100 ميغابايت. ويؤدي ملف أكبر إلى webhook برمز الخطأ 131052؛ اطلب من العميل إرسال ملف أصغر أو مشاركته بطريقة أخرى. افحص كل ملف قبل فتحه داخليًا. راجع دليل webhooks، وتأكد مع مهندس الإعداد لديك من كيفية تسليم الوسائط الواردة في حسابك.

مثال تطبيقي: عيادة أسنان ترسل التقارير

"عيادة ابتسامة النيل" (مثال افتراضي) في القاهرة ترسل بطاقات المواعيد وتقارير الأشعة.

  1. بطاقات المواعيد صور PNG بحجم 300 كيلوبايت مع تعليق من سطرين. أقل بكثير من 5 ميغابايت.
  2. تقارير العلاج ملفات PDF بين 2 و8 ميغابايت، باسم report-2026-0381.pdf، وتُرسل مستندات.
  3. فيديو جولة العيادة بحجم 25 ميغابايت أكبر من حد الفيديو. يعيد الفريق ترميزه بصيغة MP4 (H.264/AAC) بأقل من 16 ميغابايت مع faststart.
  4. يرسل المرضى صور الوصفات الطبية. يُنزّل صندوق الوارد كل ملف فورًا، لأن المعرّف الوارد تنتهي صلاحيته بعد 7 أيام.
  5. صُدِّرت التحية الصوتية بصيغة OGG أحادية القناة بترميز Opus، لأن صيغ OGG الأخرى تُرفض.

ما الأخطاء الشائعة؟

  • الحكم بالحجم وحده. صورة بحجم 3 ميغابايت بنظام ألوان خاطئ أو فيديو بترميز خاطئ يفشلان أيضًا.
  • عدم تطابق MIME. ملف .jpg يُقدَّم بنوع application/octet-stream سبب كلاسيكي للخطأ 131053.
  • الإشارة إلى رابط بطيء أو خاص، مثل رابط موقّع انتهت صلاحيته أو صفحة خلف تسجيل دخول.
  • الاعتماد على معرّف وسائط قديم. تنتهي صلاحية المعرّفات بعد 30 يومًا.
  • تجاهل انتهاء صلاحية الوارد. يجب حفظ ملفات العملاء خلال 7 أيام.
  • WebP متحرك كصورة. يُرفض؛ استخدم ملصقًا أو فيديو.
  • الحدود تتغير. أعد مراجعة مرجع Meta قبل أن تثبّت قواعد التحقق في الشيفرة.

كيف تساعدك OmniChannels.ai

ترسل OmniChannels.ai رسائل واتساب من صور وفيديو وصوت ومستندات وملصقات عبر واجهة واحدة، برابط عام أو بملف مرفوع مع تعليق، وتعرض الوسائط والمرفقات في صندوق الوارد المشترك. وBroadNet مزوّد حلول أعمال رسمي لدى Meta (Business Solution Provider)، لذا يمكن إنشاء القوالب ذات رؤوس الصور أو الفيديو أو المستندات وتتبعها مع حالة الاعتماد. اقرأ وثائق واتساب API والأخطاء والحدود، أو اطلع على قناة واتساب.

الأسئلة الشائعة

ما حد حجم الملفات في واتساب API؟

يختلف بحسب النوع. تذكر وثائق Meta 5 ميغابايت للصور، و16 ميغابايت للفيديو والصوت، و100 ميغابايت للمستندات، و500 كيلوبايت للملصقات المتحركة أو 100 كيلوبايت للثابتة. والحد الأعلى للوسائط في Cloud API هو 100 ميغابايت. قد تتغير الحدود، فتأكد منها في مرجع الوسائط الحالي لدى Meta قبل بناء قواعد التحقق.

ما أنواع الملفات التي يدعمها واتساب Business API؟

الصور: JPEG وPNG وWebP ثابت. الفيديو: MP4 و3GPP بترميز فيديو H.264 وصوت AAC. الصوت: AAC وAMR وMP3 وM4A وOGG بترميز Opus. المستندات: TXT وXLS وXLSX وDOC وDOCX وPPT وPPTX وPDF. الملصقات: WebP فقط. يُرفض أي نوع خارج هذه القوائم، لذا حوّل الملف قبل الإرسال.

هل أرسل الوسائط عبر رابط أم عبر معرّف الوسائط؟

توصي وثائق Meta بمعرّف وسائط مرفوع لأداء أفضل. يجب أن يشير الرابط إلى ملف على خادم عام، فتضطر المنصة إلى جلبه وقت الإرسال، بينما يشير المعرّف إلى ملف مخزَّن لدى Meta أصلًا. صلاحية المعرّفات الناتجة عن الرفع 30 يومًا، وبعدها يلزم الرفع من جديد.

كم تبقى صلاحية معرّف وسائط واتساب؟

تذكر Meta مدة 30 يومًا للمعرّفات الناتجة عن رفع الوسائط، و7 أيام لمعرّفات الوسائط المستلمة في webhooks الواردة. وتبقى الملفات المرفوعة 30 يومًا ما لم تحذفها قبل ذلك. أما رابط التنزيل الناتج عن المعرّف فتنتهي صلاحيته بعد 5 دقائق، فاطلب رابطًا جديدًا كلما احتجت إلى الملف.

هل يمكنني إضافة تعليق إلى صورة أو فيديو في واتساب؟

نعم. يذكر مرجع الرسائل لدى Meta تعليقًا اختياريًا حتى 1,024 حرفًا لرسائل الصور والفيديو والمستندات. ولا تحتمل رسائل الصوت والملصقات تعليقًا. وإن أردت نصًا مع ملصق أو رسالة صوتية فأرسل رسالة نصية منفصلة بعدها.

ماذا يعني خطأ واتساب 131053؟

تصفه Meta بأنه تعذّر رفع الوسائط المستخدمة في الرسالة. والسبب المعتاد نوع MIME لا يطابق امتداد الملف، أو نوع غير مدعوم. راجع تفاصيل الخطأ في الـ webhook المرتبط، وتحقق من الصيغة في أنواع الوسائط المدعومة لدى Meta، وأعد ترميز الملف عند الحاجة.

المصادر

  1. Media — WhatsApp Business Platform, Meta for Developers
  2. Image messages — WhatsApp Business Platform, Meta for Developers
  3. Video messages — WhatsApp Business Platform, Meta for Developers
  4. Document messages — WhatsApp Business Platform, Meta for Developers
  5. Error codes — WhatsApp Business Platform, Meta for Developers

تابع القراءة

مزيد من الأدلة