API v2 (تجريبي)
التذكيرات
يرسل التذكير الرسالة نفسها إلى مستلم واحد مرة بعد مرة وفق جدول زمني: الإيجار كل شهر، أو حصة كل يوم اثنين، أو تقرير كل مساء. الجدول تعبير cron من 5 أجزاء بمنطقة زمنية تختارها. والتذكيرات التي تُنشأ عبر API هي نفسها التذكيرات الموجودة في صفحة التذكيرات في لوحة التحكم.
| العملية | نقطة النهاية | النطاق |
|---|---|---|
| إنشاء تذكير | POST /api/v2/reminders | reminders |
| عرض التذكيرات | GET /api/v2/reminders | reminders |
| جلب تذكير | GET /api/v2/reminders/{id} | reminders |
| التغيير أو الإيقاف المؤقت أو الاستئناف | PATCH /api/v2/reminders/{id} | reminders |
| حذف تذكير | DELETE /api/v2/reminders/{id} | reminders |
يحتاج إنشاء التذكيرات وتغييرها إلى باقة تتضمن التذكيرات؛ وإلا يُرجع 403 plan_required. أما العرض والقراءة والإيقاف المؤقت والحذف فتعمل مع أي باقة. ولرسالة تُرسَل مرة واحدة في وقت محدد، استخدم بدلًا من ذلك send_at في إرسال رسالة.
إنشاء تذكير#
https://wbiztool.com/api/v2/remindersالنص (Body): JSON (application/json)
curl -X POST https://wbiztool.com/api/v2/reminders \
-H "Authorization: Bearer $WBIZTOOL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: rent-flat-4b" \
-d '{
"name": "Weekly rent",
"from": 101,
"to": { "phone": "+919876543210" },
"text": "Hi, a reminder that the rent is due on Friday.",
"schedule": { "cron": "0 9 * * 1", "timezone": "Asia/Kolkata" }
}'import os
import requests
response = requests.post(
"https://wbiztool.com/api/v2/reminders",
headers={
"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}",
"Idempotency-Key": "rent-flat-4b",
},
json={
"name": "Weekly rent",
"from": 101,
"to": {"phone": "+919876543210"},
"text": "Hi, a reminder that the rent is due on Friday.",
"schedule": {"cron": "0 9 * * 1", "timezone": "Asia/Kolkata"},
},
timeout=30,
)
reminder = response.json()
print(response.status_code, reminder.get("id"), reminder.get("next_run_at"))// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/reminders", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "rent-flat-4b",
},
body: JSON.stringify({
name: "Weekly rent",
from: 101,
to: { phone: "+919876543210" },
text: "Hi, a reminder that the rent is due on Friday.",
schedule: { cron: "0 9 * * 1", timezone: "Asia/Kolkata" },
}),
});
const reminder = await response.json();
console.log(response.status, reminder.id, reminder.next_run_at);<?php
$ch = curl_init('https://wbiztool.com/api/v2/reminders');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: rent-flat-4b',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Weekly rent',
'from' => 101,
'to' => ['phone' => '+919876543210'],
'text' => 'Hi, a reminder that the rent is due on Friday.',
'schedule' => ['cron' => '0 9 * * 1', 'timezone' => 'Asia/Kolkata'],
]),
CURLOPT_RETURNTRANSFER => true,
]);
$reminder = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $reminder['id'] . ' next: ' . $reminder['next_run_at'];الاستجابة (201):
{
"id": 812,
"name": "Weekly rent",
"active": true,
"to": { "phone": "+919876543210" },
"from": 101,
"text": "Hi, a reminder that the rent is due on Friday.",
"media": null,
"schedule": { "cron": "0 9 * * 1", "timezone": "Asia/Kolkata" },
"next_run_at": "2026-10-19T09:00:00+05:30",
"created_at": "2026-10-18T10:20:11.004Z"
}
الجسم
namestringمطلوباسم للتذكير، بحد أقصى 100 حرف، كما يظهر في صفحة التذكيرات.
toobjectمطلوبواحد فقط من:
phone(بالصيغة الدولية مع+)، أوgroup(الاسم الدقيق لمجموعة WhatsApp)، أوcontact_id، أوusername(Telegram)، كما في الرسائل ← المستلمون.frominteger or nullمطلوب للمفتاح المقيد ببعض الأرقام
idالرقم الذي يرسله. يجب أن يكون متصلًا عند ضبطه. إذا حُذف أو كانnull: يرسله أي رقم متصل في مساحة العمل.textstringمطلوبالرسالة، بحد أقصى 3,000 حرف. وهي أيضًا التعليق عند إرسال
media.mediaobject or nullاختياريصورة أو ملف يُرسَل في كل مرة:
urlأوmedia_id، وtypeاختياريًا، كما في الرسائل ← الوسائط.scheduleobjectمطلوب
cron(مطلوب) وtimezone. راجع الجدول الزمني.activebooleanاختياري
true(افتراضي) يشغّله؛ وfalseينشئه موقوفًا مؤقتًا.
الجدول الزمني#
يتكوّن schedule.cron من خمسة أجزاء تفصل بينها مسافات: الدقيقة، والساعة، ويوم الشهر، والشهر، ويوم الأسبوع. وتعني * "كل". ويجب أن يكون جدولًا يعمل في وقت ما (وليس 31 فبراير).
cron | موعد التشغيل |
|---|---|
0 9 * * 1 | كل يوم اثنين الساعة 09:00 |
30 18 * * * | كل يوم الساعة 18:30 |
0 10 1 * * | اليوم الأول من كل شهر الساعة 10:00 |
0 9 * * 1-5 | أيام العمل (من الاثنين إلى الجمعة) الساعة 09:00 |
0 8,20 * * * | كل يوم الساعة 08:00 والساعة 20:00 |
0 9 15 1 * | 15 يناير الساعة 09:00، كل عام |
schedule.timezone اسم منطقة زمنية IANA، مثل Asia/Kolkata أو Europe/London أو America/New_York (الافتراضي UTC). أوقات cron بتلك المنطقة، ويُعطى next_run_at بها أيضًا مع فرق التوقيت. راجع مرجع المناطق الزمنية.
كل تشغيل يرسل رسالة مثل أي رسالة أخرى: يحتاج إلى رسائل متبقية في الباقة ويظهر في عرض الرسائل.
أخطاء الإنشاء#
| HTTP | الرمز | متى |
|---|---|---|
400 | validation_failed | حقل مطلوب مفقود أو فارغ، أو حقل غير معروف أو طويل جدًا (name وto.group)، أو media غير صالح |
400 | text_required | text فارغ |
400 | text_too_long | text أطول من 3,000 حرف |
400 | invalid_cron | schedule.cron ليس من 5 أجزاء، أو لا يعمل أبدًا |
400 | invalid_timezone | schedule.timezone ليس منطقة زمنية IANA |
403 | plan_required | الباقة لا تتضمن التذكيرات |
403 | number_not_allowed | المفتاح مقيد ببعض الأرقام وfrom ليس منها، أو مفقود |
422 | invalid_phone | to.phone ليس رقمًا صالحًا بالصيغة الدولية مع + |
422 | invalid_username | to.username ليس اسم مستخدم Telegram أو رابطًا أو معرّف tg: |
422 | username_needs_telegram | اسم مستخدم Telegram، لكن from ليس حساب Telegram (أو، بدون from، لا يوجد حساب Telegram متصل) |
422 | contact_not_found | لا توجد جهة اتصال بهذا to.contact_id |
422 | media_not_found | لا يوجد ملف بهذا media.media_id |
422 | invalid_media_url | media.url ليس رابط http(s) عامًا |
422 | number_not_connected | from ليس رقمًا متصلًا في مساحة العمل هذه |
عرض التذكيرات#
https://wbiztool.com/api/v2/remindersتذكيرات مساحة العمل، الأحدث أولًا، في صفحات (limit من 1 إلى 100، والافتراضي 25، وcursor). وتُضمَّن التذكيرات الموقوفة مؤقتًا مع "active": false. والمفتاح المقيد ببعض الأرقام لا يرى إلا التذكيرات التي تُرسَل منها.
curl "https://wbiztool.com/api/v2/reminders?limit=50" \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"
الاستجابة هي {"data": [Reminder, …], "next_cursor": "…" or null}.
جلب تذكير#
https://wbiztool.com/api/v2/reminders/{id}curl https://wbiztool.com/api/v2/reminders/812 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"
التذكير غير الموجود، أو المحذوف، أو الذي يُرسَل من رقم لا يُسمح للمفتاح باستخدامه، يُرجع 404 reminder_not_found.
تغيير تذكير أو إيقافه مؤقتا أو استئنافه#
https://wbiztool.com/api/v2/reminders/{id}النص (Body): JSON (application/json)
أرسل الحقول التي تتغيّر فقط؛ وتحتفظ الحقول الأخرى بقيمها. الحقول هي حقول إنشاء تذكير. والاستجابة 200 مع التذكير كما هو الآن.
- الإيقاف المؤقت:
{"active": false}. يتوقف عن العمل وتصبح قيمةnext_run_atهيnull. يعمل الإيقاف المؤقت مع أي باقة. - الاستئناف:
{"active": true}. يعمل مجددًا بدءًا من موعده التالي. يحتاج الاستئناف إلى باقة تتضمن التذكيرات. - يُستبدل
scheduleبالكامل: أرسلcronمعه. وبدونtimezone، يحتفظ التذكير بمنطقته الزمنية الحالية.
# Pause
curl -X PATCH https://wbiztool.com/api/v2/reminders/812 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"active": false}'
# Move it to Fridays at 10:00 and change the text
curl -X PATCH https://wbiztool.com/api/v2/reminders/812 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"schedule": {"cron": "0 10 * * 5"}, "text": "Hi, the rent is due today."}'import os
import requests
headers = {"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"}
url = "https://wbiztool.com/api/v2/reminders/812"
paused = requests.patch(url, headers=headers, json={"active": False}, timeout=30).json()
print(paused["active"], paused["next_run_at"]) # False None
resumed = requests.patch(url, headers=headers, json={"active": True}, timeout=30).json()
print(resumed["active"], resumed["next_run_at"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v2/reminders/812", {
method: "PATCH",
headers: { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ active: false }),
});
const reminder = await response.json();
console.log(reminder.active, reminder.next_run_at); // false null<?php
$ch = curl_init('https://wbiztool.com/api/v2/reminders/812');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['active' => false]),
CURLOPT_RETURNTRANSFER => true,
]);
$reminder = json_decode(curl_exec($ch), true);
curl_close($ch);
var_dump($reminder['active']);يُرجع التغيير الأخطاء نفسها التي يُرجعها الإنشاء، بالإضافة إلى 404 reminder_not_found. وإذا كان أحد الحقول خاطئًا، فلا يتغيّر شيء.
حذف تذكير#
https://wbiztool.com/api/v2/reminders/{id}يحذف التذكير: فلا يعمل مرة أخرى أبدًا. وتبقى الرسائل التي أرسلها في السجل. ولإيقافه لفترة بدلًا من ذلك، أوقفه مؤقتًا.
curl -X DELETE https://wbiztool.com/api/v2/reminders/812 \
-H "Authorization: Bearer $WBIZTOOL_API_KEY"
{ "id": 812, "deleted": true }
كائن Reminder#
| الحقل | النوع | الوصف |
|---|---|---|
id | integer | معرّف التذكير. |
name | string | اسمه. |
active | boolean | true ما دام يعمل، وfalse ما دام موقوفًا مؤقتًا. |
to | object | المستلم: phone (مع +) أو group أو username. والتذكير الذي أُنشئ باستخدام contact_id يعرض رقم جهة الاتصال أو مجموعتها. |
from | integer or null | id الرقم المرسِل، أو null لأي رقم متصل. |
text | string | الرسالة. |
media | object or null | type (image أو file) وurl وfile_name. |
schedule | object | cron وtimezone. |
next_run_at | string or null | موعد تشغيله التالي، بمنطقته الزمنية مع فرق التوقيت، مثل 2026-10-19T09:00:00+05:30. وتكون null ما دام موقوفًا مؤقتًا. |
created_at | string | وقت إنشائه (UTC). |
صفحات ذات صلة#
- التذكيرات في لوحة التحكم
- مرجع المناطق الزمنية
- الرسائل: رسالة واحدة في وقت محدد باستخدام
send_at - الأخطاء
