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 ولا معاملات سلسلة الاستعلام.
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"
}
}
| الحقل | النوع | الوصف |
|---|---|---|
status | integer | 1 إذا رُفع الملف، و0 إذا فشل الطلب. |
message | string | File uploaded successfully، وإلا نص الخطأ. |
data.id | integer | معرّف ملف الوسائط. استخدمه مع جلب ملف وسائط. |
data.file_name | string | الاسم الذي خُزّن به الملف، ويولّده Wbiztool. |
data.original_file_name | string | اسم الملف الذي رفعته. |
data.file_url | string | عنوان URL مباشر للتنزيل. استخدمه كقيمة img_url أو file_url عند الإرسال. |
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: … | استخدم أحد الامتدادات المدعومة. |
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، تصل ملفات .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عند الإرسال. - اعثر على الملفات المرفوعة سابقًا باستخدام عرض الوسائط.
