انتقل إلى المحتوى
WbizTool

API الوسائط

API رفع الوسائط

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

POSThttps://wbiztool.com/api/v1/media/upload/

النص (Body): multipart/form-data

يُخزَّن الملف فورًا، وتتضمن الاستجابة file_url الخاص به. تظهر الملفات المرفوعة أيضًا في صفحة مكتبة الوسائط في لوحة التحكم.

مثال سريع#

curl -X POST https://wbiztool.com/api/v1/media/upload/ \
  -F client_id=12345 \
  -F api_key=YOUR_API_KEY \
  -F media_file=@./invoice-4821.pdf

استبدل 12345 وYOUR_API_KEY بقيمك الخاصة. راجع المصادقة لمعرفة مكان العثور عليها.

معاملات الطلب#

أرسل الطلب بصيغة multipart/form-data. لا تقرأ نقطة النهاية هذه أجسام JSON ولا معاملات سلسلة الاستعلام.

Authorizationheaderموصى به

‏Bearer YOUR_API_KEY: مفتاح API الخاص بك من Settings → API keys (الإعدادات ← مفاتيح API). مع الترويسة، يمكن حذف client_id وapi_key من الجسم؛ وإذا أُرسل المفتاح في الترويسة والجسم معًا، يُستخدم مفتاح الترويسة إذا كان صالحًا. راجع إرسال المفتاح في ترويسة.

client_idintegerبدون ترويسة Authorization

معرّف العميل في API ‏(API Client ID) من Settings → API keys. اختياري مع الترويسة؛ وإذا أرسلته، فيجب أن يكون لمساحة عمل المفتاح.

api_keystringبدون ترويسة Authorization

مفتاح API الخاص بك من الصفحة نفسها، عندما لا ترسله في الترويسة.

media_filefileمطلوب

الملف المراد رفعه، حتى 64 MB، ويجب أن يتسع في تخزين الوسائط لمساحة العمل. يُحدَّد نوعه من امتداد اسم الملف، لذا يجب أن ينتهي الاسم بأحد الامتدادات المدعومة.

أنواع الملفات المدعومة#

الفئةالامتدادات
الصور‎.jpg، ‎.jpeg، ‎.png، ‎.gif، ‎.webp، ‎.bmp
المستندات‎.pdf، ‎.doc، ‎.docx، ‎.xls، ‎.xlsx، ‎.ppt، ‎.pptx، ‎.txt، ‎.csv
الصوت‎.mp3، ‎.m4a، ‎.wav، ‎.ogg، ‎.aac
الفيديو‎.mp4، ‎.mov، ‎.avi
الأرشيفات‎.zip، ‎.rar

تُخزَّن الصور مع file_type بقيمة image؛ وكل ما عداها يكون file.

مساحة التخزين لكل مساحة عمل#

تشترك كل الملفات في مكتبة الوسائط لمساحة العمل في حد تخزين واحد تحدده باقة مساحة العمل. تُحتسب الملفات المرفوعة عبر هذا API والملفات المرفوعة في صفحة مكتبة الوسائط على حد سواء، وحذف ملف يحرّر مساحته.

الباقةتخزين الوسائط
الفترة التجريبية المجانية250 MB
Lite1 GB
Standard2 GB
Advanced5 GB
Enterprise10 GB
AppSumo Plan 1 وPlan 21 GB
AppSumo Plan 32 GB
AppSumo Plan 43 GB
AppSumo Plan 55 GB

لدى الباقات الأقدم، ولمساحة العمل التي ليس لها باقة نشطة، 1 GB. يُرفض الرفع الذي لا يتسع مع Storage full: … (راجع الأخطاء). ومساحة العمل التي تجاوزت حدها بالفعل تحتفظ بملفاتها، لكن لا يمكنها إضافة ملفات جديدة حتى تتوفر مساحة لها.

الاستجابة#

يُرجع الطلب الناجح HTTP 200:

{
  "status": 1,
  "message": "File uploaded successfully",
  "data": {
    "id": 5122,
    "file_name": "media_12345_17895804001234_3f9a1c7e.pdf",
    "original_file_name": "invoice-4821.pdf",
    "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895804001234_3f9a1c7e.pdf",
    "file_type": "file",
    "file_size": 248312,
    "file_size_display": "242.5 KB",
    "mime_type": "application/pdf",
    "is_image": false,
    "file_extension": "pdf",
    "created_at": "2026-09-16T10:20:31.512934+00:00"
  }
}
الحقلالنوعالوصف
statusinteger‏1 إذا رُفع الملف، و0 إذا فشل الطلب.
messagestring‏File uploaded successfully، وإلا نص الخطأ.
data.idintegerمعرّف ملف الوسائط. استخدمه مع جلب ملف وسائط.
data.file_namestringالاسم الذي خُزّن به الملف، ويولّده WbizTool: media_ ثم معرّف مساحة العمل ووقت الرفع وجزء عشوائي، مع امتداد الملف.
data.original_file_namestringاسم الملف الذي رفعته.
data.file_urlstringعنوان URL مباشر للتنزيل. استخدمه كقيمة img_url أو file_url عند الإرسال. وهو عام ولا تنتهي صلاحيته، لكنه يتوقف عن العمل عند حذف الملف. قد يكون على media.wbiztool.com (شبكة CDN الخاصة بنا) أو على wbiztool-static.s3.ap-southeast-1.amazonaws.com؛ وكلاهما يقدّم الملف نفسه، لذا خزّنه كما هو ولا تُنشئ هذه العناوين بنفسك.
data.file_typestring‏image أو file.
data.file_sizeintegerالحجم بالبايت.
data.file_size_displaystringحجم مقروء بمنزلة عشرية واحدة، مثل 242.5 KB.
data.mime_typestringنوع MIME مستنتج من الامتداد، مثل application/pdf.
data.is_imageboolean‏true عندما تكون قيمة file_type هي image.
data.file_extensionstringامتداد original_file_name بأحرف صغيرة، بدون النقطة.
data.created_atstringوقت الرفع، بصيغة ISO 8601 بتوقيت UTC مع الفرق +00:00.

الأخطاء#

تُرجع الأخطاء أيضًا HTTP 200، مع status بقيمة 0:

{ "status": 0, "message": "File is too large. Maximum size is 64MB. Your file: 71.3MB" }
الرسالةطريقة الإصلاح
Only POST method is supportedأرسل طلب POST.
client_id is requiredأضف client_id كحقل نموذج. تأكد من أن الجسم بصيغة multipart/form-data، وليس JSON.
api_key is requiredأضف api_key كحقل نموذج.
media_file is requiredأرسل الملف في حقل باسم media_file.
client_id must be a valid integerأرسل client_id كرقم.
Invalid API keyتأكد من أن المفتاح موجود ولم يُحذف أو يُعطَّل.
Invalid client_id for this API keyالمفتاح ينتمي إلى client_id مختلف.
File is too large. Maximum size is 64MB. Your file: …MBارفع ملفًا حجمه 64 MB أو أقل.
File type not supported. Type detected: …استخدم أحد الامتدادات المدعومة.
Storage full: this workspace uses … of its … of media storage, and this file is …. Delete files you no longer need in the Media directory, or contact us if you need more space.لا يتسع الملف في تخزين الوسائط لمساحة العمل. احذف الملفات التي لم تعد تحتاج إليها في صفحة مكتبة الوسائط، أو تواصل معنا للحصول على مساحة أكبر.
Error uploading file: …تعذّر إكمال الرفع. حاول مرة أخرى. تحصل على هذا الخطأ أيضًا إذا لم يكن مفتاح API مرتبطًا بمساحة عمل؛ أنشئ مفتاحًا جديدًا في مساحة العمل التي تريد استخدامها.

الرفع والإرسال#

ارفع الملف، ثم مرّر file_url إلى إرسال رسالة: كقيمة img_url مع msg_type 1 للصور، أو كقيمة file_url مع msg_type 2 للملفات الأخرى.

رفع ملف PDF وإرساله
import requests

BASE = "https://wbiztool.com/api/v1"
AUTH = {"client_id": 12345, "api_key": "YOUR_API_KEY"}

with open("invoice-4821.pdf", "rb") as f:
    upload = requests.post(f"{BASE}/media/upload/", data=AUTH, files={"media_file": f}, timeout=120).json()
if upload["status"] != 1:
    raise SystemExit("Upload failed: " + upload["message"])

media = upload["data"]
message = {
    **AUTH,
    "whatsapp_client": 678,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Your invoice for order #4821 is attached.",
}
if media["is_image"]:
    message.update(msg_type=1, img_url=media["file_url"])
else:
    message.update(msg_type=2, file_url=media["file_url"], file_name=media["original_file_name"])

sent = requests.post(f"{BASE}/send_msg/", json=message, timeout=60).json()
print(sent)

كل نوع ملف يقبله هذا API يحتفظ بامتداده عند إرساله مع msg_type 2، مثل brochure.doc أو catalogue.zip. تصل ملفات الصوت بصيغتي WAV وOGG كمستندات بدلًا من صوت قابل للتشغيل، وتفشل مع File type not supported عند إرسالها كصورة (msg_type 1). أما MP3 وM4A وAAC فتصل كصوت يُشغَّل في الدردشة، مع النص كرسالة منفصلة. راجع إرسال الصور والملفات. ويُرسَل الاسم بأحرف صغيرة (يصل Invoice-4821.PDF باسم invoice-4821.pdf).

يجب ألا يزيد حجم الصور المُرسَلة مع msg_type 1 على 16 MB. الصور الأكبر تُرفع هنا بنجاح، لكنها تفشل عند الإرسال مع File exceeds WhatsApp size limit (16MB max). اضغطها أولًا، أو أرسلها كملف مع msg_type 2.

نصائح#

  • أعد استخدام الملفات المرفوعة. خزّن id أو file_url وأرسل الملف نفسه مرات عديدة بدلًا من رفعه مجددًا.
  • اجعل الاسم الأصلي ذا معنى. ‏original_file_name هو ما تراه في لوحة التحكم، وهو قيمة مناسبة لـ file_name عند الإرسال.
  • اعثر على الملفات المرفوعة سابقًا باستخدام عرض الوسائط.