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

API الرسائل

API إلغاء رسالة

ألغِ رسالة WhatsApp لم تُرسَل بعد. استخدمه لإيقاف تذكير مجدول بعد إلغاء موعد، أو لسحب رسالة في قائمة الانتظار أُرسلت عن طريق الخطأ.

POSThttps://wbiztool.com/api/v1/cancel_msg/

النص (Body): JSON أو حقول نموذج

يمكنك إلغاء أي رسالة لا تزال بانتظار الإرسال (الحالة 0، Created): الرسائل المجدولة، والرسائل التي دخلت قائمة الانتظار عبر إرسال رسالة أو الإرسال إلى مجموعة أو الإرسال إلى عدة أرقام. لا يمكن استرجاع رسالة أُرسلت بالفعل. وإذا كان أحد البوتات يرسل الرسالة في تلك اللحظة، فقد تُرسَل رغم ذلك، لذا تأكّد في حالات الإلغاء المهمة باستخدام حالة الرسالة.

مثال سريع#

curl -X POST https://wbiztool.com/api/v1/cancel_msg/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "msg_id": 9817263
  }'

استبدل 12345 وYOUR_API_KEY بقيمك الخاصة، و9817263 بقيمة msg_id التي حصلت عليها عند إرسال الرسالة أو جدولتها.

معاملات الطلب#

client_idintegerمطلوب

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

api_keystringمطلوب

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

msg_idintegerمطلوب

قيمة msg_id التي أرجعها طلب الإرسال أو الجدولة. يجب أن تنتمي الرسالة إلى مساحة العمل الخاصة بمفتاح API.

لا تحتاج نقطة النهاية هذه إلى whatsapp_client.

استخدام مكتبات العملاء الرسمية#

تستدعي مكتبتا Python وNode.js نقطة النهاية هذه نيابةً عنك.

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.cancel_message(msg_id=9817263)
print(result)

تُطلق المكتبتان خطأً عند أخطاء المصادقة (HTTP 400/403): تُطلق Python الاستثناء requests.HTTPError، وتُطلق Node.js الخطأ API error: 400 - {…}. أما الرد Msg has been … فيعود كنتيجة عادية مع status: 0.

الاستجابة#

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

{
  "message": "Cancelled",
  "status": 1
}
الحقلالنوعالوصف
statusinteger‏1 إذا أُلغيت الرسالة، و0 إذا لم تُلغَ.
messagestring‏Cancelled عند النجاح، وإلا السبب.

بعد الإلغاء، تُظهر حالة الرسالة الرسالة بالحالة 3 (Cancelled). الرسالة الملغاة لا تُرسَل، ولا تستدعي الـ webhook الخاص بها، ولا تُحتسب بعد ذلك من رصيدك المتبقي.

الأخطاء#

تُرجع معظم الأخطاء HTTP 200 مع status بقيمة 0، لذا تحقّق دائمًا من status في الجسم:

{ "message": "Msg has been Sent", "status": 0 }
الرسالةطريقة الإصلاح
Msg has been Sentأُرسلت الرسالة بالفعل، ولا يمكن إلغاؤها.
Msg has been Failedفشلت الرسالة بالفعل، فلا يوجد ما يُلغى.
Msg has been Cancelledأُلغيت الرسالة في وقت سابق.
Msg has been Expiredانتهت صلاحية الرسالة قبل إرسالها، فلا يوجد ما يُلغى.
No msg found for given msg_idتحقّق من msg_id. يجب أن يكون رقمًا وأن ينتمي إلى مساحة العمل نفسها التي ينتمي إليها مفتاح API.
Msg_id cant be nullأضف msg_id.
Auth Errorأرسل client_id وapi_key كليهما.
Invalid Client Idأرسل client_id كرقم. يُرجَع مع HTTP 403.
Auth Error: invalid api keyتأكد من أن المفتاح موجود، ولم يُحذف، وينتمي إلى client_id هذا. يُرجَع مع HTTP 400.
Invalid JSON format: …جسم JSON غير صالح، وغالبًا بسبب فاصلة زائدة في النهاية، أو أنك أرسلت حقول نموذج بدون client_id.
كائن فارغ {}أُرسل جسم JSON بطريقة غير POST.

نصائح#

  • احفظ كل msg_id: تحتاج إليه للإلغاء. في الإرسال إلى عدة أرقام، ألغِ كل msg_id في الاستجابة على حدة.
  • ألغِ مبكرًا: بعد إرسال الرسالة لا يمكن التراجع عن ذلك، لذا ألغِ الرسائل المجدولة بمجرد أن تعرف أنك لم تعد بحاجة إليها.
  • إعادة الجدولة: لا توجد نقطة نهاية لتغيير وقت مجدول. ألغِ الرسالة ثم جدوِل رسالة جديدة.
  • اعتبر الرسائل ذات الحالة النهائية منتهية: الرد Msg has been … يعني أن الرسالة لم تعد في قائمة الانتظار، فلا حاجة إلى إعادة المحاولة.