البداية السريعة

خمس خطوات

1. 1

   أنشئ حسابا وفعّل بريدك

   أنشئ حسابا ثم افتح الرابط في رسالة التفعيل. تسجيل الدخول مرفوض حتى يُفعّل البريد، وتُنشأ لك مساحة عمل مع الحساب.

2. 2

   أنشئ API key للاختبار

   من لوحة التحكم، افتح المطوّرون ← API keys وأنشئ مفتاحا بوضع test. يُعرض السر مرة واحدة عند الإنشاء ولا يمكن استرجاعه بعدها. ضعه في بيئة التشغيل لا في ملف:

   shellنسخ

   export WA_API_KEY="wa_test_..."

   كل طلب يصادق بـ Authorization: Bearer وهذا المفتاح. لا يوجد header اسمه x-api-key — راجع المصادقة للصورة كاملة.

3. 3

   احجز رقم اختبار من الـ Sandbox

   الـ Sandbox مجموعة أرقام اختبار مشتركة تملكها المنصة. حجز رقم ينشئ لك قناة ويعيد رمز تحقق. ولا يمكنك اختيار الرقم الذي يقع لك.

   curlنسخ

   curl -X POST https://whats.azzamkh.sa/api/v1/sandbox/sessions \
     -H "Authorization: Bearer $WA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "recipient": "+9665XXXXXXXX" }'
   
   # 201 Created
   # {
   #   "id": "sbx_...",
   #   "status": "waiting_for_verification",
   #   "sandbox_number": "+999...",
   #   "channel_id": "ch_...",
   #   "recipient": "+9665XXXXXXXX",
   #   "verification": {
   #     "code": "482910",
   #     "send_from": "+9665XXXXXXXX",
   #     "send_to": "+999...",
   #     "attempts_remaining": 5,
   #     "expires_at": "2026-08-13T10:10:00.000Z"
   #   }
   # }

4. 4

   أثبت ملكيتك لرقم المستلم

   أرسل الرمز رسالة واتساب عادية من جهاز المستلم إلى الرقم المذكور في send_to، ثم استدعِ verify. الملكية تُثبت بعنوان المرسل، فالرمز وحده لا يكفي. الرمز صالح 10 دقائق ولديك 5 محاولات.

   curlنسخ

   curl -X POST https://whats.azzamkh.sa/api/v1/sandbox/sessions/sbx_.../verify \
     -H "Authorization: Bearer $WA_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "code": "482910" }'
   
   # 200 OK
   # { "id": "sbx_...", "status": "verified", "channel_id": "ch_...", ... }

5. 5

   أرسل أول رسالة

   القناة متصلة والمستلم موثّق. أرسل.

   curlJavaScriptPython

   نسخ

   curl -X POST https://whats.azzamkh.sa/api/v1/messages \
     -H "Authorization: Bearer $WA_API_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{
       "channel_id": "ch_...",
       "to": "+9665XXXXXXXX",
       "type": "text",
       "text": { "body": "Your code is 481902" }
     }'
   
   # 201 Created
   # {
   #   "id": "msg_...",
   #   "status": "queued",
   #   "channel_id": "ch_...",
   #   "to": "+9665XXXXXXXX",
   #   "type": "text",
   #   "category": "utility",
   #   "created_at": "2026-08-13T10:00:00.000Z"
   # }

   رد 201 يعني القبول لا التسليم: قيمة status هي queued والتسليم غير متزامن. تابعها عبر نقاط الرسائل أو عبر webhook.

ما يفعله الـ Sandbox وما لا يفعله

الـ Sandbox موجود لتتكامل قبل أن تملك رقما. وهو ضيّق عمدا: مفتاح test مطلوب، ولا يمكن مراسلة إلا مستلم موثّق، والحجز مؤقت.

بعد ذلك

استقبل الردود وتحديثات التسليم عبر الـ webhooks. انتقل من الـ Sandbox عبر القنوات. واعرف ماذا تفعل الـ API حين يخفق شيء في الأخطاء والحدود.