الإرسال

إرسال رسالة نصية

POST /messages
Idempotency-Key: order-123-v1

{
  "instance_id": "ins_…",
  "type": "text",
  "to": "9665xxxxxxxx",
  "text": "Hello",
  "client_reference": "order-123",
  "options": { "delay_profile": "normal" }
}

text: مطلوب، حتى 8192 حرفاً (تُحسب الحروف وليس البايتات؛ العربي والإنجليزي سواء). أطول من ذلك يرجع 422 INVALID_TEXT.

المفتاح في Authorization و instance_id في الجسم — مطلوبان ويجب أن يكونا للجلسة نفسها.

حقل to: أرقام فقط مع رمز الدولة بدون + أو أصفار بادئة (مثل 9665xxxxxxxx).

options.delay_profile (اختياري): تأخير عشوائي قبل الإرسال يقلل خطر الحظر — none بدون تأخير، normal من 2 إلى 12 ثانية (الافتراضي)، cautious من 25 إلى 60 ثانية، high_protection من 61 إلى 180 ثانية. استخدم none للرسائل العاجلة فقط مثل رموز التحقق؛ الإرسال الفوري الكثيف يرفع خطر الحظر.

client_reference: مرجع من نظامك حتى 128 حرفاً (اختياري) — يعود معك في GET وفي حدث message.unknown.

رد الإرسال — قبول الطلب (ليس وصوله لواتساب)

HTTP 202
{
  "success": true,
  "message_id": "msg_…",
  "status": "queued",
  "request_id": "…"
}

الطلب يدخل الطابور ويُرد عليك فوراً بـ 202 دون انتظار واتساب. تابع النتيجة باستعلام GET أو عبر Webhook.

HTTP 200 عند تكرار نفس Idempotency-Key مع نفس جسم الطلب — آمن ولا يُنشئ رسالة مكررة.

وسائط — صورة، فيديو، صوت، مستند

// A) upload, then send by media_id
POST /media   (multipart/form-data, field: file, max 50 MB)
→ 201 { "media_id": "med_…", "mime_type": "application/pdf", "file_name": "…", "size_bytes": 1024, "url": "https://…/m/…", "expires_at": "…" }

POST /messages
{
  "instance_id": "ins_…",
  "type": "media",
  "to": "9665xxxxxxxx",
  "media": { "media_id": "med_…", "caption": "Invoice" }
}

// B) send from your public URL
{
  "instance_id": "ins_…",
  "type": "media",
  "to": "9665xxxxxxxx",
  "media": { "url": "https://example.com/file.pdf", "filename": "file.pdf", "caption": "…" }
}

استخدم media_id من الرفع أو url عام (واحد منهما فقط). caption اختياري حتى 2048 حرفاً. الملفات المرفوعة والمستقبلة تُحذف تلقائياً بعد مدة الاحتفاظ، والروابط مؤقتة حتى expires_at.

لإرسال نفس الملف لأرقام كثيرة: ارفعه مرة واحدة واستخدم نفس media_id لكل الأرقام (أو في إرسال دفعة). رفع نفس الملف بنفس الاسم مرة أخرى يعيد نفس media_id، والرفع محدود بـ 30 ملفاً في الدقيقة لكل جلسة.

إرسال دفعة

POST /messages/batch

{
  "instance_id": "ins_…",
  "messages": [
    { "type": "text", "to": "9665xxxxxxxx", "text": "Hello" },
    { "type": "media", "to": "9665xxxxxxxx", "media": { "media_id": "med_…" } }
  ]
}

حتى 50 رسالة في الطلب؛ تعود نتيجة لكل عنصر في results[] (ok و message_id أو error). Idempotency-Key و delay_profile لا يُطبقان على الدفعة.