API الوسائط
API رفع الوسائط
ارفع ملف صورة أو مستند أو صوت أو فيديو إلى مكتبة الوسائط في مساحة العمل الخاصة بك، واحصل على عنوان URL للتنزيل. مرّر هذا العنوان إلى إرسال رسالة، أو إلى إنشاء تذكير كقيمة img_url، عندما لا تكون لديك استضافة ملفات خاصة بك.
https://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.pdfimport requests
with open("invoice-4821.pdf", "rb") as f:
response = requests.post(
"https://wbiztool.com/api/v1/media/upload/",
data={"client_id": 12345, "api_key": "YOUR_API_KEY"},
files={"media_file": f},
timeout=120,
)
try:
result = response.json()
except ValueError:
# A proxy can reject a very large upload with an HTML page before it reaches WbizTool.
raise SystemExit(f"HTTP {response.status_code}: not JSON. Check the file size.")
if result["status"] == 1:
print("Uploaded:", result["data"]["file_url"])
else:
print("Failed:", result["message"])// Node.js 20+ (built-in fetch, FormData and fs.openAsBlob). Save as .mjs to use top-level await.
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("client_id", "12345");
form.append("api_key", "YOUR_API_KEY");
form.append("media_file", await openAsBlob("./invoice-4821.pdf"), "invoice-4821.pdf");
// Don't set Content-Type yourself; fetch adds the multipart boundary.
const response = await fetch("https://wbiztool.com/api/v1/media/upload/", { method: "POST", body: form });
const result = await response.json();
if (result.status === 1) {
console.log("Uploaded:", result.data.file_url);
} else {
console.error("Failed:", result.message);
}<?php
$ch = curl_init('https://wbiztool.com/api/v1/media/upload/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
// An array body (not json_encode) makes cURL send multipart/form-data.
CURLOPT_POSTFIELDS => [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'media_file' => new CURLFile('/path/to/invoice-4821.pdf', 'application/pdf', 'invoice-4821.pdf'),
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 120,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
echo 'Uploaded: ' . $result['data']['file_url'];
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}استبدل 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 |
| Lite | 1 GB |
| Standard | 2 GB |
| Advanced | 5 GB |
| Enterprise | 10 GB |
| AppSumo Plan 1 وPlan 2 | 1 GB |
| AppSumo Plan 3 | 2 GB |
| AppSumo Plan 4 | 3 GB |
| AppSumo Plan 5 | 5 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"
}
}
| الحقل | النوع | الوصف |
|---|---|---|
status | integer | 1 إذا رُفع الملف، و0 إذا فشل الطلب. |
message | string | File uploaded successfully، وإلا نص الخطأ. |
data.id | integer | معرّف ملف الوسائط. استخدمه مع جلب ملف وسائط. |
data.file_name | string | الاسم الذي خُزّن به الملف، ويولّده WbizTool: media_ ثم معرّف مساحة العمل ووقت الرفع وجزء عشوائي، مع امتداد الملف. |
data.original_file_name | string | اسم الملف الذي رفعته. |
data.file_url | string | عنوان URL مباشر للتنزيل. استخدمه كقيمة img_url أو file_url عند الإرسال. وهو عام ولا تنتهي صلاحيته، لكنه يتوقف عن العمل عند حذف الملف. قد يكون على media.wbiztool.com (شبكة CDN الخاصة بنا) أو على wbiztool-static.s3.ap-southeast-1.amazonaws.com؛ وكلاهما يقدّم الملف نفسه، لذا خزّنه كما هو ولا تُنشئ هذه العناوين بنفسك. |
data.file_type | string | image أو file. |
data.file_size | integer | الحجم بالبايت. |
data.file_size_display | string | حجم مقروء بمنزلة عشرية واحدة، مثل 242.5 KB. |
data.mime_type | string | نوع MIME مستنتج من الامتداد، مثل application/pdf. |
data.is_image | boolean | true عندما تكون قيمة file_type هي image. |
data.file_extension | string | امتداد original_file_name بأحرف صغيرة، بدون النقطة. |
data.created_at | string | وقت الرفع، بصيغة 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 للملفات الأخرى.
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)// Node.js 20+ (built-in fetch, FormData and fs.openAsBlob). Save as .mjs to use top-level await.
import { openAsBlob } from "node:fs";
const BASE = "https://wbiztool.com/api/v1";
const form = new FormData();
form.append("client_id", "12345");
form.append("api_key", "YOUR_API_KEY");
form.append("media_file", await openAsBlob("./invoice-4821.pdf"), "invoice-4821.pdf");
const upload = await (await fetch(`${BASE}/media/upload/`, { method: "POST", body: form })).json();
if (upload.status !== 1) throw new Error(`Upload failed: ${upload.message}`);
const media = upload.data;
const message = {
client_id: 12345,
api_key: "YOUR_API_KEY",
whatsapp_client: 678,
country_code: "91",
phone: "9876543210",
msg: "Your invoice for order #4821 is attached.",
...(media.is_image
? { msg_type: 1, img_url: media.file_url }
: { msg_type: 2, file_url: media.file_url, file_name: media.original_file_name }),
};
const sent = await fetch(`${BASE}/send_msg/`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(message),
});
console.log(await sent.json());كل نوع ملف يقبله هذا 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عند الإرسال. - اعثر على الملفات المرفوعة سابقًا باستخدام عرض الوسائط.

