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

API v2 (تجريبي)

الرسائل

أرسل رسالة الآن أو في وقت محدد، إلى رقم هاتف أو مجموعة WhatsApp أو جهة اتصال محفوظة أو اسم مستخدم على Telegram. أرسل الرسالة نفسها إلى ما يصل إلى 1,000 مستلم في طلب واحد، واقرأ السجل، وتابع حالة الرسالة، وألغِها ما دامت تنتظر.

العمليةنقطة النهايةالنطاق
إرسال رسالةPOST /api/v2/messagesmessages:send
الإرسال إلى عدة مستلمينPOST /api/v2/messages/batchmessages:send
عرض الرسائلGET /api/v2/messagesmessages:read
جلب رسالةGET /api/v2/messages/{id}messages:read
إلغاء رسالةDELETE /api/v2/messages/{id}messages:send

تعمل المفاتيح والأخطاء وIdempotency-Key والحدود كما هو موضّح في نظرة عامة على API v2. ولتعرف متى أُرسلت الرسالة أو فشلت دون استعلام متكرر، أضف نقطة استقبال webhook.

إرسال رسالة#

POSThttps://wbiztool.com/api/v2/messages

النص (Body): JSON (application/json)

تدخل الرسالة قائمة الانتظار وتصل الاستجابة قبل إرسالها، برمز HTTP ‏202 ومعها Message بالحالة queued (أو scheduled إذا كان send_at في المستقبل). تابعها عبر جلب رسالة أو webhook.

curl -X POST https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-ready" \
  -d '{
    "from": 101,
    "to": { "phone": "+919876543210" },
    "text": "Hi Asha, your order #1042 is ready."
  }'

الاستجابة (202):

{
  "id": 9817263,
  "status": "queued",
  "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
  "to": { "phone": "+919876543210", "contact_id": 991 },
  "text": "Hi Asha, your order #1042 is ready.",
  "media": null,
  "send_at": null,
  "expires_at": null,
  "created_at": "2026-10-18T10:15:02.311Z",
  "sent_at": null,
  "error": null
}

الجسم

toobjectمطلوب

من يستلمها: حقل واحد بالضبط من phone أو group أو contact_id أو username. راجع المستلمون.

frominteger or nullمطلوب ما لم يكن لدى مساحة العمل رقم متصل واحد

قيمة id للرقم الذي يرسلها، من عرض الأرقام. إذا حذفته، فسيرسلها الرقم المتصل الوحيد: يُستخدم رقم WhatsApp المتصل الوحيد حتى لو كان حساب Telegram متصلًا أيضًا، ولا يُستخدم حساب Telegram إلا عندما لا يكون أي رقم WhatsApp متصلًا. ويُقبل الرقم الذي سُجّل خروجه: تنتظر رسائله حتى يعود اتصاله.

textstringمطلوب ما لم تُرسل وسائط

نص الرسالة، حتى 3,000 حرف. مع media يكون هو التعليق ويمكن حذفه. يعمل تنسيق WhatsApp: ‎*bold* و_italic_ و~strikethrough~. في JSON، اكتب الأسطر الجديدة بالشكل \n.

mediaobject or nullاختياري

صورة أو ملف للإرسال. راجع الوسائط.

send_atstring or nullاختياري

الإرسال في هذا الوقت بدلًا من الآن: بصيغة ISO 8601 مع فرق التوقيت، مثل 2026-10-20T09:30:00+05:30. يجب أن يكون في المستقبل. راجع الجدولة وانتهاء الصلاحية.

expires_atstring or nullاختياري

لا تُرسَل بعد هذا الوقت: تصبح الرسالة expired بدلًا من ذلك. بصيغة ISO 8601 مع فرق التوقيت، في المستقبل وبعد send_at.

الترويسات

Authorizationheaderمطلوب

‏Bearer wbz_live_…، مفتاح له النطاق messages:send.

Idempotency-Keyheaderاختياري

أي سلسلة فريدة، حتى لا تؤدي إعادة المحاولة أبدًا إلى إرسال رسالة ثانية. راجع Idempotency-Key.

أخطاء الإرسال#

HTTPالرمزمتى
400validation_failedحقل مفقود أو نوعه خاطئ أو غير معروف؛ أو لا يحتوي to على أي من حقوله أو يحتوي على عدة حقول منها؛ أو يحتوي media على url وmedia_id معًا أو على أي منهما؛ أو ليس expires_at بعد send_at
400text_requiredلا يوجد text ولا media
400text_too_longيزيد text على 3,000 حرف
400invalid_datetimeليس send_at أو expires_at بصيغة ISO 8601 مع فرق التوقيت
402no_creditsلم تتبقَّ لمساحة العمل رسائل في باقتها
403number_not_allowedالمفتاح مقيّد بأرقام أخرى
403account_disabledحساب مالك مساحة العمل معطّل
422invalid_phoneليس to.phone رقم هاتف بالصيغة الدولية مع +
422invalid_usernameليس to.username اسم مستخدم على Telegram أو رابطًا أو معرّف tg:
422username_needs_telegram‏to.username مع رقم WhatsApp في from
422contact_not_foundلا توجد جهة اتصال بقيمة to.contact_id هذه
422media_not_foundلا يوجد ملف بقيمة media.media_id هذه
422invalid_media_urlليس media.url رابط http(s) عامًا
422time_in_pastمضى وقت send_at أو expires_at
422number_not_foundليس from رقمًا في مساحة العمل هذه
422from_requiredلا يوجد from، وليس لدى مساحة العمل أي رقم متصل أو لديها عدة أرقام
422message_rejectedتعذّر إدخال الرسالة قائمة الانتظار؛ يوضّح message السبب
429number_daily_cap_reachedأرسل الرقم 1,000 رسالة في آخر 24 ساعة

الإرسال المرفوض لا يترك أثرًا: لا تُحفظ أي رسالة، فلا يوجد ما يُلغى. أما الأخطاء التي قد تحدث في أي طلب (المفاتيح، والنطاقات، وحدود المعدل، وIdempotency-Key) فهي في صفحة الأخطاء.

الإرسال إلى عدة مستلمين#

POSThttps://wbiztool.com/api/v2/messages/batch

النص (Body): JSON (application/json)

يرسل الرسالة نفسها إلى ما يصل إلى 1,000 مستلم. الجسم هو نفسه في إرسال رسالة، إلا أن to قائمة من المستلمين.

  • الكل أو لا شيء. يُفحص كل مستلم قبل إدخال أي شيء قائمة الانتظار، ويجب أن تتسع القائمة كلها للرسائل المتبقية في الباقة ولما يتسع له الرقم المرسِل خلال الساعات الـ24 القادمة. إذا كان أحد المستلمين خاطئًا، فلا يدخل شيء قائمة الانتظار، ويحدّده field، مثل to[3].phone.
  • المستلم المكرر يتلقى رسالة واحدة.
  • تكون الاستجابة 202 مع data: ‏Message واحد لكل مستلم، بترتيب to.
curl -X POST https://wbiztool.com/api/v2/messages/batch \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: opening-hours-2026-10-20" \
  -d '{
    "from": 101,
    "to": [
      { "phone": "+919876543210" },
      { "phone": "+447700900123" },
      { "group": "Bakery staff" }
    ],
    "text": "We open at 10 tomorrow."
  }'

الاستجابة (202)، كائن Message واحد لكل مستلم؛ ويشبه الثاني والثالث الأول، مع ضبط to على ‎{"phone": "+447700900123", …} و{"group": "Bakery staff", …}:

{
  "data": [
    {
      "id": 9817264,
      "status": "queued",
      "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
      "to": { "phone": "+919876543210", "contact_id": 991 },
      "text": "We open at 10 tomorrow.",
      "media": null,
      "send_at": null,
      "expires_at": null,
      "created_at": "2026-10-19T16:02:40.118Z",
      "sent_at": null,
      "error": null
    }
  ]
}

أخطاء الإرسال الجماعي#

هي نفسها أخطاء إرسال رسالة واحدة، مع موضع المستلم في field (to[0].phone)، بالإضافة إلى:

HTTPالرمزمتى
400too_many_recipientsيحتوي to على أكثر من 1,000 عنصر
400validation_failed‏to فارغ أو ليس قائمة
402no_creditsلا تتسع القائمة للرسائل المتبقية: يوضّح requested وremaining مقدار الفرق
429number_daily_cap_reachedلا تتسع القائمة لما يتسع له الرقم خلال الساعات الـ24 القادمة: يوضّح requested وroom العدد

عرض الرسائل#

GEThttps://wbiztool.com/api/v2/messages

رسائل مساحة العمل خلال آخر 90 يومًا، الأحدث أولًا، مقسّمة إلى صفحات. ويشمل ذلك الرسائل المرسلة من لوحة التحكم والحملات والتذكيرات والتكاملات وAPI v1، لا رسائل API v2 وحدها. والمفتاح المقيّد ببعض الأرقام لا يرى إلا رسائلها.

معاملات الاستعلام

numberintegerاختياري

الرسائل المرسلة من رقم id هذا فقط.

statusstringاختياري

الرسائل التي لها هذه الحالة فقط: queued أو scheduled أو sent أو delivered أو read أو failed أو cancelled أو expired.

sincestringاختياري

الرسائل المُنشأة في هذا الوقت أو بعده فقط (ISO 8601 مع فرق التوقيت).

untilstringاختياري

الرسائل المُنشأة قبل هذا الوقت فقط (ISO 8601 مع فرق التوقيت).

limitintegerاختياري

عدد الرسائل في الصفحة، من 1 إلى 100 (الافتراضي 25).

cursorstringاختياري

قيمة next_cursor من الصفحة السابقة، مع عوامل التصفية نفسها.

يمكن الجمع بين عوامل التصفية. في سلسلة الاستعلام، اكتب + في فرق التوقيت بالشكل %2B (تصل + العادية كمسافة، وتُقرأ هي أيضًا كـ+)، أو استخدم Z.

curl -G https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  --data-urlencode "status=failed" \
  --data-urlencode "since=2026-10-01T00:00:00+05:30" \
  --data-urlencode "limit=100"

تكون الاستجابة ‎{"data": [Message, …], "next_cursor": "…" or null}.

أخطاء العرض#

HTTPالرمزمتى
400validation_failedليس number معرّف رقم، أو ليس status إحدى الحالات، أو ليس limit بين 1 و100
400invalid_datetimeليس since أو until بصيغة ISO 8601 مع فرق التوقيت
400invalid_cursorالمؤشر تالف أو أُنشئ بعوامل تصفية أخرى

جلب رسالة#

GEThttps://wbiztool.com/api/v2/messages/{id}

رسالة واحدة وحالتها الآن.

curl https://wbiztool.com/api/v2/messages/9817263 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

الاستجابة (200)، لرسالة تم تسليمها:

{
  "id": 9817263,
  "status": "delivered",
  "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
  "to": { "phone": "+919876543210", "contact_id": 991 },
  "text": "Hi Asha, your order #1042 is ready.",
  "media": null,
  "send_at": null,
  "expires_at": null,
  "created_at": "2026-10-18T10:15:02.311Z",
  "sent_at": "2026-10-18T10:15:09.870Z",
  "error": null
}

الرسالة غير الموجودة، أو التابعة لمساحة عمل أخرى، أو (بالنسبة إلى مفتاح مقيّد ببعض الأرقام) المرسلة من رقم آخر، تُرجع 404 message_not_found.

إلغاء رسالة#

DELETEhttps://wbiztool.com/api/v2/messages/{id}

يلغي رسالة لا تزال تنتظر (queued أو scheduled)، أيًّا كان منشئها. تكون الاستجابة 200 مع Message، وحالتها الآن cancelled. وتتلقى نقطة استقبال webhook الحدث message.cancelled.

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

curl -X DELETE https://wbiztool.com/api/v2/messages/9817263 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

أخطاء الإلغاء#

HTTPالرمزمتى
404message_not_foundلا توجد رسالة كهذه لهذا المفتاح
409not_cancellableلم تعد تنتظر؛ يوضّح status في الخطأ حالتها الآن، مثل sent

كائن Message#

تُرجع كل عملية في هذه الصفحة كائنات Message، وتحمل أحداث webhook واحدًا منها في data.message.

الحقلالنوعالوصف
idintegerمعرّف الرسالة. استخدمه لجلب الرسالة أو إلغائها.
statusstringموضعها الآن. راجع الحالات.
fromobjectالرقم المرسِل: id، وphone (خاناته مع رمز الدولة، بدون +)، وplatform (whatsapp أو telegram).
toobjectالمستلم: phone (مع +) أو group أو username، وcontact_id، أي جهة الاتصال المحفوظة التي أُرسلت إليها. يُحفظ رقم الهاتف أو المجموعة التي يُرسَل إليها لأول مرة كجهة اتصال. (لا تكون قيمة contact_id هي null إلا في رسالة اختبار إلى رقم غير محفوظ.)
textstringالنص أو التعليق؛ ‏"" عندما لا يوجد.
mediaobject or null‏type (image أو file)، وurl، وfile_name (null للصور). قد يكون url رابطًا يعمل لمدة محدودة؛ لا تخزّنه.
send_atstring or nullالوقت المجدول للإرسال، أو null لـ"الآن".
expires_atstring or nullالوقت الذي لا تُرسَل بعده، أو null.
created_atstringوقت إنشائها.
sent_atstring or nullوقت إرسالها، بعد أن تُرسَل (sent أو delivered أو read).
errorobject or nullللرسالة failed أو expired، يوضّح message السبب، مثل File exceeds WhatsApp size limit (16MB max). وإلا فهو null.

الحالات#

الحالةالمعنى
queuedتنتظر الإرسال.
scheduledتنتظر وقت send_at.
sentأُرسلت من رقمك (علامة صح واحدة في WhatsApp).
deliveredسُلّمت إلى هاتف المستلم (علامتا صح).
readقرأها المستلم (علامتا صح زرقاوان).
failedتعذّر إرسالها؛ يوضّح error.message السبب.
cancelledأُلغيت قبل إرسالها: عبر إلغاء رسالة، أو من لوحة التحكم، أو لأن رقمها أو حملتها أُزيلت.
expiredلم تُرسَل قبل expires_at.

يمكن إلغاء queued وscheduled. ويمكن أن تصبح sent لاحقًا delivered ثم read. أما failed وcancelled وexpired وread فهي نهائية. تُبلغ webhooks عن sent وfailed وcancelled وexpired؛ ولمعرفة delivered وread، اجلب الرسالة.

المستلمون#

يقبل to حقلًا واحدًا بالضبط من هذه الحقول:

الحقلمثالمن يستلمها
phone‎{"phone": "+919876543210"}رقم هاتف بالصيغة الدولية مع + ‏(E.164). يُسمح بالمسافات والشرطات.
group‎{"group": "Bakery staff"}مجموعة WhatsApp يكون الرقم المرسِل عضوًا فيها، باسمها الدقيق (حتى 200 حرف).
contact_id‎{"contact_id": 991}جهة اتصال محفوظة في مساحة العمل، بمعرّفها (قيمة contact_id لرسالة سابقة مثلًا). تُرسَل إلى رقم جهة الاتصال تلك أو مجموعتها.
username‎{"username": "@asha_bakes"}مستخدم Telegram: ‎@name، أو رابط t.me/name، أو tg: ومعرّف مستخدم. فقط من حساب Telegram، لذا حدّد واحدًا في from (أو اجعل حسابًا واحدًا فقط متصلًا).

يتطلب الإرسال إلى المجموعات وعلى Telegram أن يكون الرقم المرسِل عضوًا في تلك المجموعة أو قادرًا على الوصول إلى ذلك المستخدم؛ وتظهر المشكلات هنا كرسالة failed، لا كخطأ عند الإرسال.

الوسائط#

يرسل media صورة أو ملفًا، ويكون text تعليقًا عليه. حدّد واحدًا بالضبط من url أو media_id:

media.urlstringإما url أو media_id

رابط http أو https عام للملف، حتى 1,000 حرف. تُرفض الروابط إلى عناوين خاصة أو محلية بالخطأ invalid_media_url.

media.media_idintegerإما url أو media_id

ملف في مكتبة الوسائط الخاصة بمساحة العمل، من رفع ملف. ارفع الملف مرة واحدة وأرسله كلما شئت.

media.typestringاختياري

‏image أو file. إذا حذفته، فيُرسَل الرابط المنتهي بـ‎.jpg أو ‎.jpeg أو ‎.png أو ‎.gif أو ‎.webp كصورة وأي رابط آخر كملف؛ أما media_id فيستخدم النوع الذي رُفع به الملف.

media.file_namestringاختياري

لـfile: الاسم الذي يراه المستلم، مثل invoice-1042.pdf (حتى 100 حرف). إذا حذفته، فيُؤخذ الاسم من الرابط أو من الملف المرفوع. امتداده يحدّد طريقة إرسال الملف، لذا أضف امتدادًا. يُتجاهل للصور.

{
  "to": { "phone": "+919876543210" },
  "text": "Your invoice for order #1042",
  "media": { "url": "https://example.com/invoices/1042.pdf", "type": "file", "file_name": "invoice-1042.pdf" }
}

يُجلب الملف عند إرسال الرسالة، لا عند استدعاء API، لذا يظهر الرابط المعطّل أو الملف الكبير جدًا كرسالة failed مع السبب في error.message. وقواعد الحجم والنوع هي قواعد v1 نفسها: راجع إرسال الصور والملفات.

الجدولة وانتهاء الصلاحية#

  • send_at يجدول الرسالة. تبقى scheduled حتى ذلك الوقت، ويمكن إلغاؤها إلى أن تُرسَل. اكتب الوقت مع فرق التوقيت، فـ2026-10-20T09:30:00+05:30 تعني 09:30 بتوقيت الهند. وللرسائل المتكررة، استخدم التذكيرات.
  • expires_at موعد نهائي: إذا لم تُرسَل الرسالة بحلوله (لأن الرقم سُجّل خروجه مثلًا)، فتصبح expired بدلًا من أن تُرسَل متأخرة. استخدمه لرموز الاستخدام لمرة واحدة، ومواعيد التوصيل، والعروض. تضع مهمة في الخلفية علامة انتهاء الصلاحية بعد 30 ثانية على الأقل من الموعد النهائي، لذا لا تعتمد على مواعيد نهائية أقصر من دقيقة.
  • يجب أن يكون كلاهما في المستقبل، وأن يكون expires_at بعد send_at.

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

  • Webhooks: استقبل message.sent وmessage.failed بدلًا من الاستعلام المتكرر.
  • الوسائط: ارفع ملفات لإرسالها بواسطة media_id.
  • الأرقام: قيمة id التي تستخدمها في from.
  • الأخطاء