مرجع API

مرجع نيرون - دعم العملاء المدعوم بالذكاء الاصطناعي API

يوفر نيرون - دعم العملاء المدعوم بالذكاء الاصطناعي واجهة برمجة تطبيقات RESTful تسمح لك بدمج إرسال رسائل واتساب في تطبيقاتك الخاصة. استخدم App Keys للمصادقة وإرسال الرسائل القالبية برمجياً.

المحتويات

→Postman Collection
→المصادقة
→نقاط النهاية
→معالجة الأخطاء
→أمثلة التعليمات البرمجية
→موارد إضافية

ℹ️

Base URL:
https://api.neuron-sa.com/api/v1

معدل الحد:
يتم تحديد معدل الطلبات بناءً على إعدادات App Key الخاصة بك (الافتراضي: 60 طلب في الدقيقة).

Postman Collection

قم بتنزيل ملفات Postman الجاهزة لاختبار API بسرعة. تتضمن المجموعة جميع نقاط النهاية مع أمثلة الطلبات والاستجابات.

تنزيل Collection تنزيل Environment

💡

كيفية الاستخدام:
1. قم باستيراد ملف Collection إلى Postman
2. قم باستيراد ملف Environment
3. قم بتحديث المتغيرات app_key و app_secret و base_url في Environment
4. ابدأ في إرسال الطلبات!

🔑 المصادقة

جميع طلبات API تتطلب مصادقة باستخدام App Key و Secret. يجب تضمينها في رؤوس الطلب:

رؤوس الطلب

X-App-Key: ak_live_xxxxxxxxxxxxxxxx
X-App-Secret: your_secret_key_here

إنشاء App Key

لإنشاء App Key:

سجل الدخول إلى لوحة التحكم الخاصة بك
انتقل إلى الإعدادات → App Keys
انقر فوق "إنشاء App Key جديد"
احفظ Secret بشكل آمن - لن يتم عرضه مرة أخرى!

⚠️

تحذير أمان
لا تشارك App Secret الخاص بك أو تلتزم به بالتحكم في المصدر. احفظه بشكل آمن في متغيرات البيئة.

📋 نقاط النهاية

GETالحصول على القوالب

احصل على قائمة بجميع القوالب المعتمدة المتاحة لحسابك.

http

GET /api/v1/templates

الرؤوس المطلوبة:

http

X-App-Key: ak_live_xxxxxxxxxxxxxxxx
X-App-Secret: your_secret_key_here

مثال الاستجابة:

json

{
  "success": true,
  "data": {
    "templates": [
      {
        "name": "welcome_message",
        "display_name": "Welcome Message",
        "category": "MARKETING",
        "language": "en",
        "header_type": "TEXT",
        "body_text": "Hello {{name}}, welcome to our service!",
        "footer_text": "Thank you for joining us.",
        "variables": [
          {
            "component": "BODY",
            "position": 1,
            "name": "name"
          }
        ],
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    ],
    "total": 1
  }
}

POSTإرسال رسالة قالب

إرسال رسالة قالب WhatsApp إلى رقم هاتف محدد.

http

POST /api/v1/messages/send

الرؤوس المطلوبة:

http

X-App-Key: ak_live_xxxxxxxxxxxxxxxx
X-App-Secret: your_secret_key_here
Content-Type: application/json

معلمات الجسم:

المعلمة	النوع	مطلوب	الوصف
`to`	string	✓	رقم الهاتف بصيغة E.164 (مثل +1234567890)
`template_name`	string	✓	اسم القالب المعتمد
`template_language`	string		كود اللغة (en أو ar). الافتراضي: en
`variables`	object		كائن يحتوي على أزواج key-value لمتغيرات القالب

مثال الطلب:

json

{
  "to": "+1234567890",
  "template_name": "welcome_message",
  "template_language": "en",
  "variables": {
    "name": "John Doe"
  }
}

مثال الاستجابة:

json

{
  "success": true,
  "message": "Template message sent successfully",
  "data": {
    "message_id": "wamid.HBgLMTIzNDU2Nzg5MAVCABEYEjQzRjA0QjBDOTREQTk0MkYwNwA=",
    "to": "+1234567890",
    "template_name": "welcome_message",
    "status": "sent",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

💡

نصيحة
استخدم نقطة النهاية GET /api/v1/templates أولاً لمعرفة المتغيرات المطلوبة لكل قالب.

GETالحصول على حالة الرسالة

تحقق من حالة تسليم رسالة معينة.

http

GET /api/v1/messages/status?message_id=xxx

الرؤوس المطلوبة:

http

X-App-Key: ak_live_xxxxxxxxxxxxxxxx
X-App-Secret: your_secret_key_here

معلمات الاستعلام:

المعلمة	النوع	مطلوب	الوصف
`message_id`	string	✓	معرف الرسالة الذي تم إرجاعه من نقطة النهاية /messages/send

مثال الاستجابة:

json

{
  "success": true,
  "data": {
    "message_id": "wamid.HBgLMTIzNDU2Nzg5MAVCABEYEjQzRjA0QjBDOTREQTk0MkYwNwA=",
    "status": "delivered",
    "timestamp": "1705315800",
    "message_type": "template",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:05.000Z"
  }
}

حالات الرسالة المحتملة:

sent - تم إرسال الرسالة بنجاح
delivered - تم تسليم الرسالة إلى المستلم
read - تمت قراءة الرسالة من قبل المستلم
failed - فشل تسليم الرسالة

❌ معالجة الأخطاء

يستخدم API رموز حالة HTTP القياسية للإشارة إلى النجاح أو الفشل:

رمز الحالة	الوصف
`200`	نجح الطلب
`400`	طلب غير صالح (معلمات مفقودة أو غير صالحة)
`401`	غير مصرح به (App Key أو Secret غير صالح)
`403`	ممنوع (أذونات غير كافية)
`404`	لم يتم العثور على المورد
`429`	تم تجاوز حد المعدل
`500`	خطأ داخلي في الخادم

مثال استجابة الخطأ:

json

{
  "success": false,
  "message": "Invalid or expired app key",
  "errors": []
}

💻 أمثلة التعليمات البرمجية

Node.js / JavaScript

const axios = require('axios');

const API_URL = 'https://api.neuron-sa.com/api/v1';
const APP_KEY = 'ak_live_xxxxxxxxxxxxxxxx';
const APP_SECRET = 'your_secret_key_here';

// Get templates
async function getTemplates() {
  const response = await axios.get(`${API_URL}/templates`, {
    headers: {
      'X-App-Key': APP_KEY,
      'X-App-Secret': APP_SECRET
    }
  });
  return response.data;
}

// Send template message
async function sendTemplate(to, templateName, variables = {}) {
  const response = await axios.post(
    `${API_URL}/messages/send`,
    {
      to,
      template_name: templateName,
      template_language: 'en',
      variables
    },
    {
      headers: {
        'X-App-Key': APP_KEY,
        'X-App-Secret': APP_SECRET,
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
}

// Get message status
async function getMessageStatus(messageId) {
  const response = await axios.get(
    `${API_URL}/messages/status?message_id=${messageId}`,
    {
      headers: {
        'X-App-Key': APP_KEY,
        'X-App-Secret': APP_SECRET
      }
    }
  );
  return response.data;
}

// Usage
(async () => {
  try {
    // Get all templates
    const templates = await getTemplates();
    console.log('Templates:', templates);

    // Send a message
    const result = await sendTemplate(
      '+1234567890',
      'welcome_message',
      { name: 'John Doe' }
    );
    console.log('Message sent:', result);

    // Check status
    const status = await getMessageStatus(result.data.message_id);
    console.log('Message status:', status);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
})();

📚 موارد إضافية

راجع دليل لوحة التحكم لإنشاء القوالب
اقرأ عن Webhooks لتلقي تحديثات حالة الرسالة في الوقت الفعلي
اتصل بالدعم إذا واجهت أي مشاكل

🎉

جاهز للبدء؟
انتقل إلى لوحة التحكم وأنشئ App Key الأول الخاص بك للبدء في إرسال الرسائل برمجياً!