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

1. أنشئ مفتاح

   من لوحة التحكم، افتح الإعدادات ← مفاتيح الواجهة واختر إنشاء مفتاح.

   سمّه باسم النظام اللي بيستخدمه، عشان تعرف وش يتوقف لو ألغيته لاحقًا. بعدها اختر الصلاحيات اللي يحتاجها. لهذي البداية السريعة:

   • قراءة بيانات الحساب (account:read)
   • إرسال الرسائل (messages:send)

   أعطه أقل صلاحية يحتاجها. تقدر تضيف صلاحيات بعدين بدون ما تبدّل المفتاح.

   المفتاح يظهر مرة وحدة وما يظهر مرة ثانية. ما نحفظ المفتاح نفسه، نحفظ بصمته فقط، فانسخه الحين.

   تنبيه

   تعامل معه مثل كلمة المرور. أي أحد يملكه يقدر يرسل رسائل واتساب باسم منشأتك، وعملاؤك بيشوفونها منك. خلّه في متغيرات البيئة على سيرفرك، ولا تحطه في متصفح ولا تطبيق جوال ولا مستودع كود.

2. تأكد إن المفتاح شغّال

   قبل ما ترسل أي شيء، سوّ الطلب اللي ما يمكن يغلط.

   curl

   curl https://k-message.kerneltics.com/v1/me \
     -H "Authorization: Bearer km_live_YOUR_KEY"

   JavaScript

   const res = await fetch('https://k-message.kerneltics.com/v1/me', {
     headers: { Authorization: `Bearer ${process.env.KM_API_KEY}` },
   })
   console.log(await res.json())

   Python

   import os, requests
   
   res = requests.get(
       "https://k-message.kerneltics.com/v1/me",
       headers={"Authorization": f"Bearer {os.environ['KM_API_KEY']}"},
   )
   print(res.json())

   الرد

   {
     "organization": { "name": "زيتي لقطع الغيار", "slug": "zaiti" },
     "api_key": {
       "name": "خدمة الطلبات",
       "prefix": "km_live_a1b2c3d4",
       "scopes": ["account:read", "messages:send"],
       "rate_limit_per_min": 600
     },
     "whatsapp_accounts": [
       { "name": "Main", "display_phone_number": "+966 51 021 5213", "is_default_outgoing": true }
     ]
   }

   هذا الطلب يوصل قاعدة البيانات، فالرد 200 معناه إن المفتاح حقيقي وفعّال وصلاحياته صح. وما يقدر يرسل شيء ولا يغيّر شيء، عشان كذا هو الطلب الأول الصح: إذا كان فيه خطأ في الإعداد، هذا اللي يقوله لك قبل ما يلخبط الموضوع إرسال فاشل.

   إذا فشل، الرد يوضّح السبب. راجع الأخطاء.

3. أرسل رسالة

   إذا كان الشخص أرسل لك خلال آخر ٢٤ ساعة، الرسالة النصية تمر:

   curl https://k-message.kerneltics.com/v1/messages \
     -H "Authorization: Bearer km_live_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: order-1001-shipped" \
     -d '{
       "to": "+966500000000",
       "type": "text",
       "text": { "body": "طلبك في الطريق." }
     }'

   الرد 201

   {
     "id": "6f1c2d3e-...",
     "to": "+966500000000",
     "from": "Main",
     "type": "text",
     "status": "pending",
     "created_at": "2026-08-20T09:15:00Z"
   }

   ملاحظة

   pending معناها مقبولة، مو واصلة. الرسالة محفوظة وفي الطابور، وواتساب ما أكّد شيء بعد. الخطوة الرابعة تبيّن لك كيف تعرف.

   إذا الشخص ما أرسل لك خلال ٢٤ ساعة، هذا الطلب بيفشل وبتحتاج قالب معتمد. راجع إرسال رسالة قالب.

4. اعرف وش صار

   طريقتين، والثانية هي اللي تبيها في الإنتاج.

   اقرأ الرسالة مرة ثانية باستخدام الـ id من الرد:

   curl https://k-message.kerneltics.com/v1/messages/6f1c2d3e-... \
     -H "Authorization: Bearer km_live_YOUR_KEY"

   الحالة تتدرّج pending ← sent ← delivered ← read، أو تنتهي عند failed مع error_message يوضّح السبب.

   أو اشترك في الويب هوك، عشان توصلك النتيجة على سيرفرك بدون استعلام متكرر. أنشئه من الإعدادات ← الويب هوك، واختر message.delivered وmessage.read وmessage.failed.

وين تروح بعدها

• إرسال رسالة قالب — مطلوب خارج نافذة الـ ٢٤ ساعة، وهذا حال أغلب الإشعارات.
• الأخطاء — كل رمز خطأ وسببه وحله.
• التوثيق — الصلاحيات وحماية المفتاح.