# إرسال رسالة واتساب

> إرسال رسالة واتساب نصية حرة عبر POST /v1/whatsapp/messages — شكل الطلب، قواعد التحقق، وقيد نافذة خدمة العملاء (24 ساعة).

يُرسل رسالة نصية حرة إلى مستلم واتساب. النص الحر مقيّد بـ**نافذة خدمة العملاء (24 ساعة) من ميتا** — يجب أن يكون العميل قد راسل الوكيل خلال آخر 24 ساعة. للإرسال خارج النافذة، استخدم [إرسال قالب](./send-template) بدلاً من ذلك.

## أي نقطة أستدعي؟

`POST` إلى `/v1/whatsapp/messages` عبر HTTPS. النقطة تتطلّب نطاق `whatsapp:send` على مفتاح API الخاص بك — راجع [التوثيق](../authentication) لمعرفة كيف تعمل النطاقات.

```
POST /v1/whatsapp/messages
```

## كيف يبدو الطلب؟

```bash
curl -X POST https://api.mojeeb.app/v1/whatsapp/messages \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-to-ticket-9001" \
  -d '{
    "agent_id": "12345678-1234-1234-1234-123456789012",
    "from":     "+15557654321",
    "to":       "+15551234567",
    "text":     { "body": "Thanks for reaching out! How can I help?" }
  }'
```

## ماذا يُوضع في جسم الطلب؟

أربعة حقول مطلوبة. الوكيل و`from` معاً يُحدّدان رقم واتساب الذي ترسل منه؛ `to` و`text.body` يحملان الوجهة والرسالة نفسها.

| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
| `agent_id` | UUID | نعم | الوكيل المُرسِل. يجب أن يكون مُصرَّحاً لمفتاح API. |
| `from` | نص E.164 | نعم | رقم عمل واتساب المُرسِل. يجب مطابقة اتصال واتساب نشط على الوكيل. |
| `to` | نص E.164 | نعم | هاتف المستلم، مثل `+15551234567`. |
| `text.body` | نص | نعم | نص الرسالة. حد طوله في [المرجع](../api-reference/send-whats-app-message). |

## ما الرؤوس الاختيارية التي يمكنني إرسالها؟

اثنان يستحقّان المعرفة — كلاهما يُحسّن الموثوقية وقابلية التتبّع دون تغيير ما يُرسَل.

| الرأس | الغرض |
|---|---|
| `Idempotency-Key` | اجعل الإعادات آمنة. راجع [الإعادة الآمنة](../idempotency). |
| `X-Correlation-ID` | معرّف تتبّع مخصّص نحترمه إن كان صالحاً ونُعيده في الاستجابة؛ راجع [الأخطاء](../errors) للقواعد. |

## كيف تبدو استجابة النجاح؟

`HTTP 202 Accepted` مع كائن الرسالة: `id`، و`status: "queued"`، و`agent_id` و`to` كما أرسلتهما، و`type: "text"`، و`created_at`. كل الحقول مع مثال موجودة في [مرجع هذه النقطة](../api-reference/send-whats-app-message)، المعروض من عقد الواجهة نفسه فلا يتقادم أبداً.

الـ202 يعني أن الرسالة **في طابور** التسليم. استخدم `id` المُعاد مع [استعلام حالة الرسالة](./message-status) لتتبّع التسليم.

## ماذا قد يفشل؟

يُعاد ظرف الخطأ القياسي. الرموز الشائعة أدناه؛ تفرّع على `code` (ثابت) — لا تفرّع أبداً على `message` (قد يُعاد صياغته). الكتالوج الكامل في صفحة [الأخطاء](../errors).

| `code` | HTTP | متى |
|---|---|---|
| `invalid_request_body` | 422 | حقل مطلوب مفقود — `param` يُسمي أيهما |
| `invalid_phone_number` | 422 | `to` ليس E.164 صالحاً |
| `invalid_from_phone` | 422 | `from` ليس E.164 صالحاً |
| `from_phone_not_found_for_agent` | 422 | `from` لا يطابق أي اتصال واتساب نشط — `available_phones` يُدرج ما يعمل |
| `agent_not_authorized` | 403 | مفتاح API غير مسموح له باستخدام هذا الوكيل |
| `insufficient_scope` | 403 | مفتاح API يفتقر `whatsapp:send` |
| `rate_limit_exceeded` | 429 | ميزانية المفتاح تم بلوغها — راجع [حدود المعدّل](../rate-limits) |

## ماذا عن نافذة الـ24 ساعة؟

قواعد WhatsApp Business تتطلّب إرسال النص الحر **داخل نافذة خدمة العملاء (24 ساعة)** — يجب أن يكون العميل قد راسل الوكيل خلال آخر 24 ساعة. خارج هذه النافذة، ميتا ترفض التسليم حتى لو قبل مجيب الطلب وأعاد `202`.

إن أرسلت نصاً حراً خارج النافذة، الاستجابة الفورية لا تزال `202` (نقبل ونضع في الطابور)، لكن الرسالة ستنتقل إلى `status: "failed"` مع `failed_at` معبّأ بمجرد رفض ميتا للتسليم. استعلم عن [حالة الرسالة](./message-status) لرؤية ذلك يحدث. يُعاد الإرسال الفاشل بضع مرات، فانتظر دقيقتين تقريباً قبل أن تعتبر `failed` نهائية؛ راجع [هل `failed` نهائية؟](./message-status#هل-failed-نهائية)

للإرسال خارج النافذة، استخدم [قالباً معتمداً مسبقاً](./send-template) بدلاً من ذلك — القوالب يمكن إرسالها في أي وقت.

## أسئلة شائعة

### هل يمكنني إرسال وسائط (صور، صوت، مستندات)؟

ليس في v1 من الواجهة العامة. دعم الوسائط محجوز كتغيير إضافي. استخدم لوحة التحكم لإرسال الوسائط في الوقت الحالي.

### ما الحد الأقصى لطول الجسم؟

الحد الدقيق في [مرجع هذه النقطة](../api-reference/send-whats-app-message)؛ وهو يُطابق حد واتساب نفسه. الأجسام الأطول تُرفَض بـ`invalid_request_body`.

### هل تتحقّق الواجهة مما إذا كان المستلم داخل نافذة الـ24 ساعة؟

لا — ميتا تُطبّق النافذة، وليس نحن. الواجهة تقبل طلبك وتضع الإرسال في الطابور؛ إن رفضت ميتا التسليم، سترى `status: "failed"` على استعلام حالة الرسالة.

### هل يمكن لنفس الرقم الإرسال إلى نفسه؟

لا يمكنك الإرسال إلى رقم عملك الخاص — ميتا ترفض هذا على مستوى المنصة. الإرسال يُعيد 202 منّا لكن `failed` على استعلام الحالة.