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

API الرسائل

API حالة الرسالة

تحقّق مما إذا كانت الرسالة التي أرسلتها عبر API لا تزال في قائمة الانتظار، أو أُرسلت، أو فشلت. استخدمه للتأكد من أن الرسائل المهمة قد أُرسلت، ولمعرفة سبب عدم إرسال إحداها.

POSThttps://wbiztool.com/api/v1/message/status/{msg_id}/

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

ضع معرّف الرسالة في عنوان URL، مستبدلًا {msg_id} بقيمة msg_id التي أرجعها إرسال رسالة أو الإرسال إلى مجموعة أو الإرسال إلى عدة أرقام أو جدولة رسالة. مثال: https://wbiztool.com/api/v1/message/status/9817263/.

مثال سريع#

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

استبدل 12345 وYOUR_API_KEY بقيمك الخاصة. راجع المصادقة لمعرفة مكان العثور عليها.

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

URL

msg_idintegerمطلوب

معرّف الرسالة، كجزء من مسار عنوان URL. يجب أن يكون عددًا صحيحًا وأن ينتمي إلى مساحة العمل الخاصة بمفتاح API.

الجسم

client_idintegerمطلوب

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

api_keystringمطلوب

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

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

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

Python
from wbiztool_client import WbizToolClient

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

result = client.get_message_status(msg_id=9817263)
print(result.get("status_text"), result.get("error"))

تُرجع المكتبة الحقول نفسها التي يُرجعها API، لذا فإن result["status"] هي حالة الرسالة، وليست مؤشرًا على نجاح الطلب. تُطلق أخطاء المصادقة الاستثناء requests.HTTPError؛ اقرأ السبب باستخدام e.response.json()["message"].

الاستجابة#

تُرجع نقطة النهاية HTTP 200 مع الحالة الحالية للرسالة:

{
  "message": "Sent",
  "status": 1,
  "status_text": "Sent",
  "error": ""
}

رسالة فاشلة:

{
  "message": "Failed",
  "status": 2,
  "status_text": "Failed",
  "error": "Phone number invalid"
}
الحقلالنوعالوصف
statusintegerرمز حالة الرسالة. راجع الجدول أدناه.
status_textstringاسم الحالة: Created أو Sent أو Failed أو Cancelled أو Expired.
messagestringالقيمة نفسها الموجودة في status_text.
errorstring or nullسبب فشل الرسالة. موجود دائمًا؛ ويكون فارغًا ("" أو null) عند عدم وجود خطأ.

قيم الحالة#

statusstatus_textالمعنى
0Createdفي قائمة الانتظار أو مجدولة، بانتظار الإرسال.
1Sentأُرسلت من رقم WhatsApp الخاص بك.
2Failedتعذّر إرسالها، أو انقطع الإرسال. يوضّح error السبب. إذا كانت قيمة error هي Sending was interrupted and may have been delivered. Check WhatsApp before resending.، فقد تكون الرسالة قد وصلت إلى المستلم بالفعل، لذا لا تُعِد إرسالها تلقائيًا.
3Cancelledأُلغيت قبل إرسالها، مثلًا باستخدام إلغاء رسالة.
4Expiredلم تُرسَل قبل المهلة المحددة في expire_after_seconds.

‏Sent هي حالة النجاح النهائية. لا تُبلغ نقطة النهاية هذه عمّا إذا كانت الرسالة قد سُلّمت إلى الهاتف أو قُرئت.

أمثلة على قيم error للرسائل الفاشلة: Phone number invalid، Group not found، Image Url Error، File Url Error، Blocked Contact، File exceeds WhatsApp size limit (…)، File type not supported، Sending was interrupted and may have been delivered. Check WhatsApp before resending.

الأخطاء#

{
  "message": "Unknown message id",
  "status": 0,
  "status_text": "pending",
  "error": "Invalid message id"
}
الرسالةطريقة الإصلاح
Unknown message idلا توجد رسالة بهذا المعرّف في مساحة العمل الخاصة بمفتاح API. تحقّق من المعرّف ومن أنك تستخدم مفتاحًا من مساحة العمل نفسها.
Auth Errorأرسل client_id وapi_key كليهما. جسم JSON غير الصالح (مثلًا بسبب فاصلة زائدة في النهاية) يُرجع أيضًا Auth Error.
Invalid Client Idأرسل client_id كرقم. يُرجَع مع HTTP 403.
Auth Error: invalid api keyتأكد من أن المفتاح موجود، ولم يُحذف، وينتمي إلى client_id هذا. يُرجَع مع HTTP 400.

نصائح#

  • فضّل webhooks للتحديثات الفورية: مرّر webhook عند إرسال الرسالة، وسيُعلمك Wbiztool عند إرسالها أو فشلها، فلا تحتاج إلى الاستعلام المتكرر. الرسائل الملغاة والمنتهية الصلاحية لا تستدعي webhook، لذا تحقّق منها هنا.
  • الاستعلام المتكرر: إذا كنت تستعلم بشكل متكرر، فتوقف بمجرد أن تصبح قيمة status غير 0. اترك بضع ثوانٍ بين كل فحص وآخر.
  • رسائل كثيرة دفعة واحدة: للتحقق من رسائل يوم كامل، استخدم سجل الرسائل بدلًا من استدعاء نقطة النهاية هذه لكل معرّف.
  • تُحذف الرسائل القديمة: الرسائل المرسلة والفاشلة والملغاة والمنتهية الصلاحية التي لم يطرأ عليها تغيير لمدة 90 يومًا تقريبًا تُرجع Unknown message id. وكذلك الرسائل التي لا تزال في قائمة الانتظار بعد 90 يومًا من إنشائها أو جدولتها، على رقم غير متصل أو محذوف.
  • التكاملات القديمة: الطلب POST /api/v1/msg_status/ مع msg_id في الجسم مهمل (deprecated). وهو يُرجع الحقول نفسها. ويقبل أيضًا GET مع client_id وapi_key وmsg_id في سلسلة الاستعلام (query string)، ما يكشف مفتاح API في عناوين URL والسجلات. انتقل إلى نقطة النهاية هذه.