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

API v2 (تجريبي)

التذكيرات

يرسل التذكير الرسالة نفسها إلى مستلم واحد مرة بعد مرة وفق جدول زمني: الإيجار كل شهر، أو حصة كل يوم اثنين، أو تقرير كل مساء. الجدول تعبير cron من 5 أجزاء بمنطقة زمنية تختارها. والتذكيرات التي تُنشأ عبر API هي نفسها التذكيرات الموجودة في صفحة التذكيرات في لوحة التحكم.

العمليةنقطة النهايةالنطاق
إنشاء تذكيرPOST /api/v2/remindersreminders
عرض التذكيراتGET /api/v2/remindersreminders
جلب تذكيرGET /api/v2/reminders/{id}reminders
التغيير أو الإيقاف المؤقت أو الاستئنافPATCH /api/v2/reminders/{id}reminders
حذف تذكيرDELETE /api/v2/reminders/{id}reminders

يحتاج إنشاء التذكيرات وتغييرها إلى باقة تتضمن التذكيرات؛ وإلا يُرجع 403 plan_required. أما العرض والقراءة والإيقاف المؤقت والحذف فتعمل مع أي باقة. ولرسالة تُرسَل مرة واحدة في وقت محدد، استخدم بدلًا من ذلك send_at في إرسال رسالة.

إنشاء تذكير#

POSThttps://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" }
  }'

الاستجابة (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الرمزمتى
400validation_failedحقل مطلوب مفقود أو فارغ، أو حقل غير معروف أو طويل جدًا (name وto.group)، أو media غير صالح
400text_required‏text فارغ
400text_too_long‏text أطول من 3,000 حرف
400invalid_cron‏schedule.cron ليس من 5 أجزاء، أو لا يعمل أبدًا
400invalid_timezone‏schedule.timezone ليس منطقة زمنية IANA
403plan_requiredالباقة لا تتضمن التذكيرات
403number_not_allowedالمفتاح مقيد ببعض الأرقام وfrom ليس منها، أو مفقود
422invalid_phone‏to.phone ليس رقمًا صالحًا بالصيغة الدولية مع +
422invalid_username‏to.username ليس اسم مستخدم Telegram أو رابطًا أو معرّف tg:
422username_needs_telegramاسم مستخدم Telegram، لكن from ليس حساب Telegram (أو، بدون from، لا يوجد حساب Telegram متصل)
422contact_not_foundلا توجد جهة اتصال بهذا to.contact_id
422media_not_foundلا يوجد ملف بهذا media.media_id
422invalid_media_url‏media.url ليس رابط http(s) عامًا
422number_not_connected‏from ليس رقمًا متصلًا في مساحة العمل هذه

عرض التذكيرات#

GEThttps://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}.

جلب تذكير#

GEThttps://wbiztool.com/api/v2/reminders/{id}
curl https://wbiztool.com/api/v2/reminders/812 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

التذكير غير الموجود، أو المحذوف، أو الذي يُرسَل من رقم لا يُسمح للمفتاح باستخدامه، يُرجع 404 reminder_not_found.

تغيير تذكير أو إيقافه مؤقتا أو استئنافه#

PATCHhttps://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."}'

يُرجع التغيير الأخطاء نفسها التي يُرجعها الإنشاء، بالإضافة إلى 404 reminder_not_found. وإذا كان أحد الحقول خاطئًا، فلا يتغيّر شيء.

حذف تذكير#

DELETEhttps://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#

الحقلالنوعالوصف
idintegerمعرّف التذكير.
namestringاسمه.
activeboolean‏true ما دام يعمل، وfalse ما دام موقوفًا مؤقتًا.
toobjectالمستلم: phone (مع +) أو group أو username. والتذكير الذي أُنشئ باستخدام contact_id يعرض رقم جهة الاتصال أو مجموعتها.
frominteger or null‏id الرقم المرسِل، أو null لأي رقم متصل.
textstringالرسالة.
mediaobject or null‏type (image أو file) وurl وfile_name.
scheduleobject‏cron وtimezone.
next_run_atstring or nullموعد تشغيله التالي، بمنطقته الزمنية مع فرق التوقيت، مثل 2026-10-19T09:00:00+05:30. وتكون null ما دام موقوفًا مؤقتًا.
created_atstringوقت إنشائه (UTC).

صفحات ذات صلة#