> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# الوسائط في رؤوس قوالب WhatsApp: الصور ومقاطع الفيديو

> ما هي تنسيقات وأحجام الوسائط التي يقبلها WhatsApp في رؤوس القوالب، ولماذا لا تُضمَّن روابط YouTube، وكيفية تحميل الوسائط والإشارة إليها عبر Flowella.

يمكن أن يحمل قالب WhatsApp قطعة وسائط واحدة في رأسه: صورة أو فيديو أو مستند. عند استخدامها بشكل جيد، فإنها تضاعف معدلات الفتح والتفاعل لرسالة كانت لتكون نصية فقط. عند استخدامها بشكل سيء — تنسيق خاطئ، عنوان URL معطّل، نوع MIME غير متطابق — فإنها تتسبب في فشل الإرسال أو تجعل القالب يبدو غير احترافي.

هذه الصفحة هي المرجع العملي لما يعمل وما لا يعمل، وكيفية توصيل الوسائط عبر Flowella.

## التنسيقات والحدود المدعومة

هذه هي التنسيقات وحدود الأحجام التي تفرضها Meta على الوسائط في رؤوس القوالب (وفي أي مكان آخر في رسائل WhatsApp Business Platform).

### الصور

| التنسيق | الامتداد | نوع MIME | الحد الأقصى للحجم |
| - | - | - | - |
| JPEG | `.jpeg` / `.jpg` | `image/jpeg` | 5 ميغابايت |
| PNG | `.png` | `image/png` | 5 ميغابايت |

يجب أن تكون الصور **8 بت، RGB أو RGBA**. لا يُقبل WebP **في رؤوس القوالب** (فهو صالح فقط في رسائل الملصقات، وهي نوع رسالة منفصل).

**الأبعاد الموصى بها:** نسبة العرض إلى الارتفاع 1.91:1، بحد أدنى 800×418 بكسل. تُعرض الصور المربعة (1:1) بشكل مقبول أيضًا. نسب العرض الأخرى تُطبَّق عليها الأشرطة السوداء بواسطة عميل WhatsApp.

### مقاطع الفيديو

| التنسيق | الامتداد | نوع MIME | الحد الأقصى للحجم |
| - | - | - | - |
| 3GPP | `.3gp` | `video/3gpp` | 16 ميغابايت |
| MP4 | `.mp4` | `video/mp4` | 16 ميغابايت |

يجب أن تستخدم مقاطع الفيديو **برنامج ترميز الفيديو H.264** و **برنامج ترميز الصوت AAC**، مع **دفق صوت واحد أو بدون صوت**.

<Warning>
  مقاطع الفيديو المشفّرة بملف تعريف H.264 **"High" و B-frames** غير مدعومة من قبل عملاء WhatsApp لنظام Android. قم بالترميز (أو إعادة الترميز) باستخدام ملف تعريف H.264 **"Main" بدون B-frames**، أو ملف تعريف **"Baseline"**، وضع مربعات `moov` قبل مربعات `mdat` لتوافق أوسع.

  إذا كنت تستخدم ffmpeg، فإن العلامة `-movflags faststart` تتعامل مع ترتيب `moov`/`mdat`.
</Warning>

### المستندات

| التنسيق | الامتداد | نوع MIME | الحد الأقصى للحجم |
| - | - | - | - |
| PDF | `.pdf` | `application/pdf` | 100 ميغابايت |
| Microsoft Word | `.doc` / `.docx` | `application/msword` / `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | 100 ميغابايت |
| Microsoft Excel | `.xls` / `.xlsx` | `application/vnd.ms-excel` / `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | 100 ميغابايت |
| Microsoft PowerPoint | `.ppt` / `.pptx` | `application/vnd.ms-powerpoint` / `application/vnd.openxmlformats-officedocument.presentationml.presentation` | 100 ميغابايت |
| نص عادي | `.txt` | `text/plain` | 100 ميغابايت |

ملفات PDF هي الأكثر موثوقية في العرض عبر الأجهزة. تعمل مستندات Office ولكنها تتطلب من المستلم تثبيت تطبيق متوافق؛ على هاتف محمول غير تجاري، تُفتح عادةً كمعاينات.

## ما لا يعمل

<AccordionGroup>
  <Accordion title="تضمين YouTube و Vimeo">
    لا يمكنك تضمين فيديو YouTube أو Vimeo في رأس القالب. يجب أن يكون الرأس ملف MP4 أو 3GPP يمكن لـ Meta جلبه واستضافته.

    إذا كنت تريد إرسال فيديو YouTube، هناك خياران:

    1. **ضع رابط YouTube في النص أو زر URL.** النقر عليه يفتح تطبيق YouTube أو المتصفح. ستكون معاينة الفيديو المعروضة في WhatsApp صورة مصغّرة ثابتة.
    2. **قم بتنزيل الفيديو وأعد تحميله كـ MP4.** يخضع ذلك لحقوقك في إعادة توزيع المحتوى، وهو ما يعني عادةً أنه يجب أن يكون فيديو خاصًا بك.

    الخيار الأخير هو الطريقة للحصول على معاينة فيديو فعلية داخل المحادثة.
  </Accordion>

  <Accordion title="GIF">
    الرسوم المتحركة GIF (`.gif`) ليست في القائمة المدعومة. يحوّلها WhatsApp من جانب الخادم عند مشاركتها من نظير إلى نظير في تطبيق المستهلك، لكن Business Platform لا يفعل ذلك. أعد ترميز GIF كـ MP4 (والذي يشغّله عملاء WhatsApp للهاتف المحمول مع التشغيل التلقائي بدون صوت، بنفس الطريقة التي يعرضون بها GIF).
  </Accordion>

  <Accordion title="صور WebP">
    صور WebP صالحة فقط لرسائل الملصقات، وليس رؤوس القوالب. حوّلها إلى JPEG أو PNG قبل استخدامها كصورة رأس.
  </Accordion>

  <Accordion title="صور HEIC مباشرة من iPhone">
    تحفظ أجهزة iPhone الصور افتراضيًا بتنسيق HEIC، وهو ليس في القائمة المدعومة. إما تغيير إعداد iPhone للالتقاط بتنسيق JPEG، أو تحويل HEIC إلى JPEG قبل التحميل.
  </Accordion>

  <Accordion title="الملفات التي تتجاوز حد الحجم">
    ستُرفض صورة بحجم 6 ميغابايت، أو فيديو بحجم 18 ميغابايت، أو PDF بحجم 110 ميغابايت. اضغط قبل التحميل. بالنسبة للصور، يعيد عميل WhatsApp أيضًا الضغط عند العرض، لذا فإن صورة 4 ميغابايت لن تبدو أفضل بشكل ملحوظ من صورة 1 ميغابايت على شاشة الهاتف.
  </Accordion>
</AccordionGroup>

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

تدعم Meta نمطين للحصول على الوسائط في القالب:

### النمط 1: مقبض الوسائط (موصى به)

قم بتحميل الملف عبر Media API من Meta، واحصل على **مقبض وسائط**، وأشر إلى المقبض عند إرسال القالب. يستخدمه Flowella افتراضيًا.

الفوائد:

* تستضيف Meta الملف، لذا لا توجد إخفاقات في عناوين URL معطلة في وقت الإرسال.
* تسليم أسرع لأن Meta لا تحتاج إلى الجلب من عنوان URL خارجي.
* يعمل مع حدود الأحجام الكاملة أعلاه.

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

### النمط 2: عنوان URL عام HTTPS

قدّم عنوان URL لملف يمكن الوصول إليه بشكل عام. تجلبه Meta في وقت الإرسال.

هذا مفيد عندما:

* تتغير الوسائط لكل مستلم (PDF مخصص، أو ملصق شحن لكل طلب).
* يتم إنشاء الوسائط أثناء الطلب ولا تريد التحميل لكل إرسال.

التحذيرات:

* يجب أن يكون عنوان URL **قابلاً للوصول بشكل عام** (بدون مصادقة) ويستخدم **HTTPS مع شهادة صالحة**.
* إذا أعاد عنوان URL خطأ أو كان بطيئًا، فسيفشل الإرسال.
* تخزّن Meta الملف المُجلَب مؤقتًا لفترة؛ تحديث الملف في عنوان URL لا يُحدّث بالضرورة ما يتم إرساله.

## كيف يتعامل Flowella مع تحميل الوسائط

بالنسبة لمعظم حالات الاستخدام، يدير Flowella مقبض الوسائط نيابةً عنك:

<Steps>
  <Step title="أضف ملف وسائط رأس عند بناء القالب">
    في **القوالب → إنشاء**، اختر **صورة** أو **فيديو** أو **مستند** كنوع الرأس، ثم **اسحب الملف على منطقة التحميل المتقطعة** أو انقر عليها للتصفح. يعمل السحب والإفلات لأنواع الرؤوس الثلاثة ويستخدم نفس مسار التحميل مثل النقر. بالنسبة لرؤوس **المستندات**، يعرض المحرر أيضًا حقل **اسم ملف المستند** الذي يُعبّأ افتراضيًا من الملف المُحمَّل — قم بتحريره للتحكم في الاسم الذي يراه المستلمون على فقاعة مستند WhatsApp.
  </Step>

  <Step title="يتحقق Flowella من الملف">
    يتم فحص التنسيق والحجم ونوع MIME قبل الإرسال. إذا أفلت أو اخترت ملفًا غير مدعوم، يخبرك إشعار على الفور بما هو خطأ (نوع خاطئ أو تجاوز حد الحجم) بدلاً من انتظار Meta لرفض القالب.
  </Step>

  <Step title="يقوم Flowella بالتحميل إلى Meta وتخزين المقبض">
    يتم تحميل الملف عبر Media API من Meta. يتم حفظ المقبض المُرجَع مقابل القالب.
  </Step>

  <Step title="يتضمن إرسال القالب المقبض">
    عند إرسال القالب للموافقة، ترى Meta الوسائط الفعلية (وليس عنوان URL)، لذا يمكن لعملية المراجعة تقييم المرئيات كجزء من الموافقة.
  </Step>

  <Step title="تعيد الإرسالات استخدام نفس المقبض">
    حتى تتغير وسائط رأس القالب، يستخدم كل إرسال نفس المقبض. يتم تحديث المقابض تلقائيًا قبل انتهاء الصلاحية. بالنسبة لرؤوس المستندات، يتم الاحتفاظ بـ **اسم ملف المستند** الذي عيّنته في المحرر مع المسودة، ويتم نقله عبر موافقة Meta والنشر، ويُستخدم في كل إرسال — إرسالات سير عمل HubSpot، والإرسالات التجريبية، والإرسالات المجمّعة، وإرسالات صندوق الوارد تعرض جميعها اسم ملفك بدلاً من الاسم الداخلي للقالب.
  </Step>

  <Step title="حفظ قالب معتمد يعيد تحميل العينة">
    تخزّن Meta عينة الوسائط لقالب معتمد كرابط معاينة، وترفض ذلك الرابط عند تحديث القالب. عند حفظ قالب معتمد برأس وسائط، أو قالب عرض دوار معتمد، ينزّل Flowella كل عينة من Meta ويحمّلها مرة أخرى. يشمل ذلك رؤوس الصور والفيديو والمستندات، وكل بطاقة في العرض الدوار. إذا انتهت صلاحية رابط المعاينة من Meta، يفشل الحفظ مع رسالة تطلب منك تحميل ذلك الملف مرة أخرى. أعد تحميل الملف في المحرر، ثم احفظ مرة أخرى.
  </Step>

  <Step title="يقوم التكرار بنسخ الوسائط عبر">
    عند استخدام **القوالب → تكرار**، ينسخ Flowella ملف الرأس و **اسم ملف المستند** إلى المسودة الجديدة. إذا فشل النسخ، يعرض المحرر تحذيرًا ويمنع النشر حتى تعيد تحميل الملف.
  </Step>
</Steps>

بالنسبة للوسائط لكل مستلم (ملفات PDF مخصصة، وملصقات الشحن)، استخدم خيار **عنوان URL عام** في منشئ القوالب ومرّر عنوان URL كمتغير عند تشغيل الإرسال من سير عمل أو API. راجع [إجراءات سير العمل](/ar/hubspot/workflow-actions).

## التصميم لمنفذ عرض WhatsApp

بعض ملاحظات التصميم التي لا تظهر في مواصفات Meta ولكنها مهمة في الممارسة العملية:

* **النص على الصور.** احتفظ به كبيرًا وعالي التباين. يعرض WhatsApp الصورة تقريبًا بعرض شاشة الهاتف المحمول، لذا فإن أي شيء أصغر من حوالي 14 بكسل يُعرض غير قابل للقراءة.
* **المنطقة الآمنة.** قد يقصّ WhatsApp أو يطبّق أشرطة سوداء؛ احتفظ بالمحتوى المهم في وسط 80% من الصورة.
* **اتساق العلامة التجارية.** تجلس صورة الرأس واسم عرض WhatsApp وصورة الملف الشخصي جميعها متقاربة — احتفظ بها متسقة بصريًا.
* **الإطار الأول من الفيديو.** يستخدم WhatsApp الإطار الأول كمعاينة ثابتة قبل تشغيل الفيديو. لا تبدأ بإطار أسود أو شاشة بداية لشعار الشركة؛ ابدأ بصورة ذات معنى.
* **اسم ملف المستند.** عند إرسال PDF أو مستند آخر، فإن **اسم الملف** مرئي للمستلم على فقاعة مستند WhatsApp. يعرض محرر القوالب حقل **اسم ملف المستند** ضمن تحميل رأس المستند؛ يُعبَّأ افتراضيًا من اسم الملف المُحمَّل وهو ما يراه المستلمون فعليًا عند إرسال القالب. استخدم اسمًا واضحًا ووصفيًا مثل `Acme-Order-12345-Receipt.pdf`، وليس `attachment.pdf` أو اسم كائن Meta CDN.

## الأخطاء الشائعة والحلول

<AccordionGroup>
  <Accordion title="131053 — نوع MIME غير متطابق">
    نوع MIME الفعلي للملف لا يتطابق مع ما تم الإعلان عنه. يحدث غالبًا عندما يكون "JPEG" مُصدَّر من iPhone هو في الواقع HEIC، أو عندما تُعيد أداة تسمية `.docx` إلى `.pdf` بدون تحويل.

    الحل: افحص الملف (على macOS/Linux: `file -I yourfile.png`) وإما أعد التصدير بالتنسيق الصحيح أو غيّر الامتداد ليطابق.
  </Accordion>

  <Accordion title="يتم تشغيل الفيديو بدون صوت">
    برنامج ترميز الصوت شيء آخر غير AAC، أو هناك عدة تدفقات صوتية.

    الحل: أعد الترميز باستخدام `ffmpeg -i input.mp4 -c:v libx264 -profile:v main -c:a aac -movflags faststart output.mp4`.
  </Accordion>

  <Accordion title="الفيديو لا يعمل على Android">
    مُرمَّز بملف تعريف H.264 High و B-frames. أعد الترميز باستخدام ملف تعريف Main أو Baseline.
  </Accordion>

  <Accordion title="فشل جلب عنوان URL العام">
    لا تستطيع Meta الوصول إلى عنوان URL. الأسباب الشائعة: يتطلب عنوان URL مصادقة، الشهادة غير صالحة، الخادم بطيء في الاستجابة (انتهاء المهلة)، أو يُرجع عنوان URL إعادة توجيه بدلاً من الملف.

    الحل: اختبر عنوان URL باستخدام `curl -I` للتأكد من أنه يُرجع 200 مع نوع المحتوى الصحيح، وأن الشهادة تتحقق. ثم أعد المحاولة.
  </Accordion>

  <Accordion title="الصورة تبدو مبكسلة">
    المصدر منخفض الدقة، أو تم تكبيره. لا يعيد WhatsApp المعالجة من أجل الحدة؛ ما تحمّله هو ما يُعرَض.

    الحل: قم بالتحميل بحد أدنى 800 بكسل على الحافة الطويلة لصورة 1.91:1، ولا تكبّر مصدرًا صغيرًا.
  </Accordion>
</AccordionGroup>

## أدلة ذات صلة

* [مرجع القوالب](/ar/app/template-reference) — البنية الكاملة للقالب التي تندرج فيها هذه الوسائط
* [القوالب](/ar/app/templates) — إنشاء القوالب خطوة بخطوة في Flowella
* [إجراءات سير العمل](/ar/hubspot/workflow-actions) — تمرير عناوين URL للوسائط لكل مستلم عبر سير عمل HubSpot


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