# البدء السريع

> أرسل أول رسالة واتساب عبر الواجهة البرمجية العامة لمجيب في 5 دقائق — احصل على مفتاح API، أرسل قالباً بـcurl، وتحقّق من التسليم.

أرسل أول رسالة واتساب في 5 دقائق. هذا الدليل يفترض أن لديك حساب مجيب على باقة Starter أو Professional ورقم واتساب واحد متّصل على الأقل.

## الخطوة 1 — كيف أحصل على مفتاح API؟

1. سجّل دخولك إلى [لوحة تحكم مجيب](https://app.mojeeb.app)
2. افتح صفحة **مفاتيح API** من الشريط الجانبي
3. اضغط **إنشاء مفتاح**، اعطه اسماً، وأكّد
4. انسخ المفتاح — يبدو هكذا: `mk_live_8aB3cDe4FgH5iJ6kLm7nOp_a1b2c3d4e5`

السر يُعرض **مرة واحدة**. إذا فقدته يجب إلغاؤه وإنشاء واحد جديد. احفظه في مدير الأسرار، وليس في الكود المصدري.

## الخطوة 2 — كيف أجد agent_id ورقم الإرسال (from)؟

نفس صفحة **مفاتيح API** تُدرج كل وكلاء مؤسستك تحت قسم **"معرّفات الوكلاء"** — اضغط على أي معرّف لنسخه إلى الحافظة. الـ`agent_id` هو UUID مثل `12345678-1234-1234-1234-123456789012`. ويستطيع مفتاحك أن يخبرك أيضاً: `GET /v1/me` يؤكد أن المفتاح يعمل، و`GET /v1/agents` يعرض الوكلاء الذين يستطيع العمل عليهم (راجع [مفتاحك ووكلاؤه](./agents/key-and-agents)).

لرقم `from`، اذهب إلى **الاتصالات** على الوكيل وانسخ أي رقم واتساب نشط — يبدو مثل `+15557654321`. إذا قدّمت رقم `from` لا يطابق أي اتصال نشط، تُخبرك الواجهة بالضبط بالأرقام التي ستعمل في رسالة الخطأ — لا حاجة للتخمين.

## الخطوة 3 — كيف أُرسل أول قالب؟

القوالب معتمدة مسبقاً من ميتا ويمكن إرسالها في أي وقت، حتى خارج نافذة الـ24 ساعة لخدمة العملاء. النص الحر مقيّد بداخل النافذة وموثَّق بشكل منفصل في [إرسال رسالة](./whatsapp/send-message).

لست متأكداً من الاسم الدقيق للقالب أو لغته؟ اعرض قوالب الرقم أولاً: يأتي كل قالب بحالته وبما يلزم تعبئته، ولا تُسلَّم إلا القوالب `approved`. راجع [عرض قوالب واتساب](./whatsapp/list-templates).

```bash
curl -X POST https://api.mojeeb.app/v1/whatsapp/templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "12345678-1234-1234-1234-123456789012",
    "from":     "+15557654321",
    "to":       "+15551234567",
    "template": {
      "name":     "arabic_signup_message",
      "language": "ar"
    }
  }'
```

الاستجابة الناجحة هي HTTP 202 Accepted مع كائن الرسالة، بحالة `status: queued` في البداية. كل الحقول في [مرجع إرسال قالب واتساب](./api-reference/send-whats-app-template).

`id` هو معرّفك للاستعلام عن الحالة. الـ202 يعني أن الرسالة **في طابور الإرسال** — التسليم الفعلي يحدث بشكل غير متزامن عبر واجهة WhatsApp Business Cloud من ميتا.

## الخطوة 4 — كيف أتحقّق من حالة التسليم؟

```bash
curl https://api.mojeeb.app/v1/whatsapp/messages/01c45011-d803-4eb0-a762-3228a4c392f3 \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

تتحرّك الحالة عبر `queued` → `sent` → `delivered` → `read` (أو تنتقل إلى `failed`). بمجرد قبول ميتا للرسالة، يُعبّأ `platform_message_id` بـ`wamid` من ميتا للمرجعية في سجلاتهم. تصنيف الحالة الكامل في [الاستعلام عن حالة الرسالة](./whatsapp/message-status).

## ما التالي؟

- [التوثيق](./authentication) — صيغة المفتاح الكاملة، النطاقات، التقييد لكل وكيل
- [الإعادة الآمنة](./idempotency) — اجعل إعادات المحاولة آمنة بـ`Idempotency-Key`
- [الأخطاء](./errors) — كل رمز خطأ مع حالة HTTP والمعنى
- [حدود المعدّل](./rate-limits) — الافتراضي 60 طلب/دقيقة/مفتاح وكيف تتعامل مع 429
- [مفتاحك ووكلاؤه](./agents/key-and-agents) — أول أدلّة الوكيل: الإعدادات، وجهات الاتصال والعملاء المحتملون، والمعرفة، والقنوات، والفريق، والتحليلات، والاستخدام
- [مرجع الواجهة](./api-reference/mojeeb-public-api) — العقد الكامل القابل للقراءة آلياً

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

### ماذا لو رقم `from` لا يطابق أي اتصال؟

ستحصل على `422 from_phone_not_found_for_agent` مع `available_phones` تُدرج كل رقم واتساب نشط على الوكيل. صحّح وأعد المحاولة — لا حاجة لاستعلام آخر لاكتشاف ما هو صالح.

### لماذا لم تصل رسالتي؟

الـ202 يعني أن مجيب وضع الإرسال في الطابور. التسليم قد يفشل في جانب ميتا لأسباب لا يمكننا توقّعها (المستلم حظر رقم العمل، أو كان خارج نافذة الـ24 ساعة لإرسال نص حر، أو القالب غير معتمد في منطقة المستلم). استعلم عن `GET /v1/whatsapp/messages/{id}` — `status: "failed"` مع `failed_at` معبّأ يُخبرك أن الإرسال رُفض في المصب.

### هل يمنعني مجيب من إرسال قالب غير معتمد؟

لا. قبل وضع الإرسال في الطابور، يتحقق مجيب من وجود اسم القالب ولغته على الرقم، أياً كانت حالتهما. فالقالب الذي لا يزال قيد المراجعة أو رُفض يُقبَل بـ`202` ثم يفشل لدى ميتا. اعرض قوالب الرقم أولاً وأرسل فقط ما حالته `status: approved`؛ راجع [عرض قوالب واتساب](./whatsapp/list-templates).

### هل يمكنني إرسال نفس الرسالة مرّتين بأمان؟

نعم — أضف رأس `Idempotency-Key`. أول إرسال يُعيد 202؛ إعادة محاولة مطابقة بنفس المفتاح تُعيد الاستجابة الأصلية. راجع [الإعادة الآمنة](./idempotency).