POST/api/v2/templates/media

رفع وسائط هيدر القالب

ارفع صورة أو فيديو أو مستنداً لهيدر واتساب. أرجع assetId إلى headerAssetId. لواتساب الرسمي يمكن إرسال mediaUrl بدل الملف. لواتساب ويب ضع targetProvider=user_session.

متى تستخدمه. اختياري: للرفع المنفصل قبل الإنشاء. يمكن أيضاً إرفاق الملف مباشرة في POST /api/v2/templates.

مثال الطلب

مثال صحيح: رفع صورة هيدر

curl --location 'https://raselsms.com/api/v2/templates/media' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"mediaType":"image","file":"<multipart binary>","note":"Content-Type: multipart/form-data"}'

مثال الاستجابة

201 — رفع صورة هيدر

{  "success": true,  "data": {    "media": {      "assetId": "6800asset123def4567890aaaa",      "mimeType": "image/png",      "size": 18432    }  }}

401 — مفتاح API مفقود أو غير صالح.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "UNAUTHORIZED",  "error": "Missing or invalid API key"}

403 — الهاتف غير موثّق أو الصلاحية غير كافية (غالباً messages:create أو api_keys:read).

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "FORBIDDEN",  "error": "Phone not verified or missing permission"}

429 — تم تجاوز حد الطلبات. انتظر Retry-After إن وُجد.

{  "success": false,  "requestId": "msgreq_1739012345678_abc123",  "code": "RATE_LIMITED",  "error": "Rate limit exceeded",  "retryAfterSeconds": 30}

طلب HTTP

POST /api/v2/templates/media

ترويسات الطلب

الترويسة	النوع	الوصف
X-API-Key	string	مفتاح Rasel API. أرسله في كل طلب موثّق ما عدا الويب هوك الوارد. *

جسم الطلب

الحقل	النوع	الوصف
mediaType	image \| video \| document	نوع وسائط الهيدر: image أو video أو document. *
file	string (binary)	الملف المرفوع. مرادف headerMedia في إنشاء أو إرسال multipart.
mediaUrl	string	رابط HTTP(S) عام لهيدر الوسائط عند عدم إرفاق ملف. واتساب الرسمي فقط في مسار الرفع.
targetProvider	user_session \| eshaar \| meta	هدف الرفع: user_session أو eshaar أو meta.

حقول الاستجابة

الحقل	النوع	الوصف
success	boolean	صحيح عندما ينجح الإجراء، أو عندما ينجح مستلم واحد على الأقل في الدفعة.
data	object	البيانات الأساسية في مسارات القوائم وملخص الحساب.
data.media	object	وسائط الترويسة المحفوظة لهذا القالب.
data.media.assetId	string	معرّف الملف المحفوظ. أعده كـ headerAssetId عند إنشاء قالب.
data.media.mediaHandle	string	مقبض الوسائط عند المزوّد عندما يعيده الرفع.
data.media.previewUrl	string	رابط لمعاينة الملف المحفوظ.
data.media.mimeType	string	نوع MIME للملف المحفوظ.
data.media.size	integer	حجم الملف بالبايت.
data.media.source	string	مصدر حركة المحفظة مثل usage أو admin_topup أو topup_request. في رفع الوسائط هو أصل الأصل المخزّن.
message	string	رسالة نتيجة مقروءة بعد الإنشاء أو الرفع.

رموز الحالة

الحالة	الوصف
201	تم الإنشاء.
400	طلب غير صالح، أو خطأ تحقق، أو المورد لا يمكن استخدامه في هذه الحالة.
401	مفتاح API مفقود أو غير صالح.
403	الهاتف غير موثّق، أو الصلاحية ناقصة، أو الحساب لا يستطيع تنفيذ هذا الإجراء.
429	تم تجاوز حد المعدل، أو وصل عدد محاولات التحقق إلى الحد الأقصى.

حالات يجب أن تعرفها

هذا المسار multipart وليس JSON.

جرّب الطلب

هذا المسار يقبل رفع ملف (multipart/form-data). أرسله من خادمك أو من أداة تدعم الملفات — جرّب الطلب ينفّذ طلبات JSON فقط.