إرسال الرسائل

يرسل POST /v1/messages نصاً أو وسائط إلى شخص أو مجموعة أو قناة.

{
  "sessionId": "8d4c1f0e-3b9a-4f57-9a3e-2c1d0b7a6e55",
  "to": "963912345678",
  "text": "Your order #1042 has shipped."
}

متزامن أم غير متزامن

المتزامن (الافتراضي). يعود الطلب بعد أن يقبل واتساب الرسالة.

{ "id": "5b0c…", "status": "sent", "waMessageId": "3EB0C4…", "tookMs": 4210, "mode": "sync", … }

يستغرق ذلك عادةً 3–10 ثوانٍ، لأن YASend يباعد بين رسائل كل رقم كما يفعل الإنسان، وهذا ما يحمي رقمك من الحظر.

غير المتزامن (?async=true). تحصل على 202 Accepted فوراً:

curl -X POST "https://api.yasend.dev/v1/messages?async=true" \
  -H "Authorization: Bearer $YASEND_KEY" -H "Content-Type: application/json" \
  -d '{"sessionId": "'$SESSION_ID'", "to": "963912345678", "text": "Hi!"}'
# 202 → {"id": "5b0c…", "status": "queued", "expiresAt": "…", …}

ثم يرسل YASend الرسالة نيابةً عنك ويُبلغك بالنتيجة:

• عبر الويب هوك message.sent أو message.failed (الويب هوك)؛
• أو عبر GET /v1/messages/{id} إن كنت تفضّل الاستعلام الدوري.

الإرسال غير المتزامن:

• يحفظ الترتيب. رسالة واحدة في كل مرة لكل جلسة، الأقدم أولاً.
• ينتظر انتهاء المشكلات المؤقتة. إذا كانت الجلسة تعيد الاتصال، أو بلغت حصة يومية أو حد إحماء، تبقى الرسالة queued وتُعاد محاولتها بتباعد متزايد. يبيّن error آخر سبب، ويبيّن nextAttemptAt موعد المحاولة التالية.
• تنتهي صلاحيته. إذا تعذّر الإرسال حتى expiresAt تفشل الرسالة بالرمز EXPIRED.
• لا يُكرّر أبداً. إذا كان ممكناً أن يكون واتساب قد استلم الرسالة دون أن نتأكد من ذلك، تفشل بالرمز DELIVERY_UNKNOWN بدلاً من إعادة المحاولة، لأن تكرار رمز التحقق أسوأ من فشل واضح.
• يمكن إلغاؤه وهو في الانتظار عبر POST /v1/messages/{id}/cancel.

استخدم الإرسال غير المتزامن لكل ما فيه كمية، ولكل طلب ينتظره مستخدموك.

حالة الرسالة

تعني sent أن واتساب قَبِل الرسالة. أما إشعارات التسليم والقراءة فتصل لاحقاً عبر الويب هوك message.status، مرتبطة بـ waMessageId.

يعرض GET /v1/messages رسائلك المرسلة مؤخراً (الأحدث أولاً). يمكنك التصفية بـ sessionId وstatus، والتنقل بين الصفحات بـ before=<nextBefore>.

لا نحتفظ برسائلك. بمجرد إرسال الرسالة (أو فشلها أو إلغائها) نمسح نصها وروابط وسائطها والمستلم. يعيد GET /v1/messages وGET /v1/messages/{id} سجل التسليم فقط: المعرّف والحالة والخطأ والأوقات، مع حقل to فارغ، ويُحذف السجل نفسه بعد نحو 3 أيام. احتفظ بنسختك الخاصة إن احتجت إليها.

منع التكرار (Idempotency)

أخطاء الشبكة واردة. لإعادة محاولة الإرسال بأمان، أضف الترويسة Idempotency-Key: من 1 إلى 255 محرفاً قابلاً للطباعة، فريدة لكل رسالة. معرّف الطلب أو رمز التحقق في نظامك خيار جيد.

curl -X POST https://api.yasend.dev/v1/messages -H "Idempotency-Key: otp-req-7f3a91" ...

المجموعات والقنوات

أرسل إلى مجموعة بمعرّفها، مثل [email protected]:

• GET /v1/sessions/{id}/groups يعرض مجموعاتك؛
• POST /v1/sessions/{id}/groups ينشئ مجموعة.

وأرسل إلى قناة تديرها بمعرّفها …@newsletter.

بعد الإرسال

تعمل نقاط النهاية التالية على رسالة بمعرّفها في واتساب (waMessageId):