انتقل إلى المحتوى
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 ولا معاملات سلسلة الاستعلام.

client_idintegerمطلوب

معرّف العميل في API ‏(API Client ID) من Settings → API keys (الإعدادات ← مفاتيح API).

api_keystringمطلوب

مفتاح API الخاص بك من الصفحة نفسها.

media_filefileمطلوب

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

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

الفئةالامتدادات
الصور.jpg، .jpeg، .png، .gif
المستندات.pdf، .doc، .xls، .ppt، .txt، .csv
الصوت.mp3، .wav
الفيديو.mp4، .mov
الأرشيفات.zip

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

الاستجابة#

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

{
  "status": 1,
  "message": "File uploaded successfully",
  "data": {
    "id": 5122,
    "file_name": "media_12345_17895804001234.pdf",
    "original_file_name": "invoice-4821.pdf",
    "file_url": "https://wbiztool-static.s3.ap-southeast-1.amazonaws.com/media/org_12345/media_12345_17895804001234.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.
data.original_file_namestringاسم الملف الذي رفعته.
data.file_urlstringعنوان URL مباشر للتنزيل. استخدمه كقيمة img_url أو file_url عند الإرسال.
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: …استخدم أحد الامتدادات المدعومة.
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، تصل ملفات .doc و.ppt و.csv و.zip و.wav و.mov المُرسَلة مع msg_type 2 بعد إضافة .pdf إلى اسمها (مثل brochure.doc.pdf). حوّل المستندات إلى PDF قبل إرسالها. راجع إرسال الصور والملفات. كما يُرسَل الاسم بأحرف صغيرة (يصل 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 عند الإرسال.
  • اعثر على الملفات المرفوعة سابقًا باستخدام عرض الوسائط.