مرجع API

جميع طلبات API مُصادَق عليها باستخدام مفتاح API مُرسَل في رأس X-Api-Key.

الحصول على مفتاح API الخاص بك

1. اذهب إلى الإعدادات → مفاتيح API في لوحة التحكّم
2. انقر إنشاء مفتاح API وأعطه اسماً
3. انسخ المفتاح فوراً — يُعرض مرة واحدة فقط
4. خزّنه بأمان (متغيّر بيئة، مدير أسرار)

إجراء الطلبات

أدرِج المفتاح في كل طلب:

curl -H "X-Api-Key: tak_your_key_here" \
     https://api.enuchat.com/api/v1/tenant-api/widgets

جميع الاستجابات هي JSON. الاستجابات الناجحة لها حقل data. الأخطاء لها حقل error مع code وmessage.

الأمان: مفاتيح API مُجزَّأة (SHA-256) في قاعدة بياناتنا. لا نُخزّن المفتاح الخام أبداً. عامل مفتاحك كما تعامل كلمة المرور — لا تُدرجه في الكود أو تشاركه علناً.

GET /widgets

يسرد جميع الأدوات لحسابك.

الاستجابة

{'{'}
  "data": [
{'{'}
      "id": "019d19c6-7e0b-...",
      "name": "Main Website Chat",
      "isActive": true,
      "aiEnabled": true,
      "translationEnabled": true,
      "primaryColor": "#2563eb",
      "position": "bottom-right"
    }
  ]
}

GET /conversations

يسرد المحادثات، مرتّبة حسب الرسالة الأحدث.

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

مثال

curl -H "X-Api-Key: tak_..." \
     "https://api.enuchat.com/api/v1/tenant-api/conversations?status=open&limit=10"

الاستجابة

{'{'}
  "data": [
{'{'}
      "id": "019d6724-000e-...",
      "widgetId": "019d19c6-7e0b-...",
      "visitorId": "v-abc123",
      "visitorName": "John",
      "visitorEmail": "john{'@'}example.com",
      "visitorLanguage": "en",
      "status": "open",
      "assignedTo": null,
      "lastMessageAt": "2026-04-11T14:30:00+00:00",
      "startedAt": "2026-04-11T14:25:00+00:00"
    }
  ]
}

GET /conversations/{'{'}id}

يحصل على محادثة مع جميع الرسائل.

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

الاستجابة

{'{'}
  "data": {'{'}
    "id": "019d6724-000e-...",
    "visitorLanguage": "en",
    "status": "open",
    "messages": [
{'{'}
        "id": "019d6724-1234-...",
        "role": "visitor",
        "content": "Hello, how much does it cost?",
        "contentLanguage": "en",
        "translatedContent": "Cześć, ile to kosztuje?",
        "translatedLanguage": "pl",
        "isAutoReply": false,
        "createdAt": "2026-04-11T14:25:30+00:00"
      },
{'{'}
        "id": "019d6724-5678-...",
        "role": "ai",
        "content": "Our plans start at €19/month...",
        "isAutoReply": true,
        "createdAt": "2026-04-11T14:25:32+00:00"
      }
    ]
  }
}

POST /conversations/{'{'}id}/messages

يُرسل رسالة إلى محادثة. سيتم تسليم الرسالة إلى الزائر في الوقت الفعلي عبر أداة الدردشة.

نص الطلب

{'{'}
  "content": "Thanks for reaching out! We'll process your request.",
  "role": "system"
}

الاستجابة (201 Created)

{'{'}
  "data": {'{'}
    "id": "019d6725-abcd-...",
    "role": "system",
    "content": "Thanks for reaching out!",
    "createdAt": "2026-04-11T14:35:00+00:00"
  }
}

PATCH /conversations/{'{'}id}

يُحدّث حالة محادثة أو إسنادها.

نص الطلب

{'{'}
  "status": "closed"
}

GET /billing/balance

يحصل على خطتك الحالية ورصيد الائتمان.

الاستجابة

{'{'}
  "data": {'{'}
    "plan": "pro",
    "creditBalance": 4500000,
    "totalCreditsAdded": 10000000
  }
}

تكامل CRM

استطلع المحادثات الجديدة وزامِن بيانات الزائر (الاسم والبريد الإلكتروني واللغة) إلى CRM الخاص بك. استخدم معرّف المحادثة كمرجع خارجي.

متابعات آلية

بعد إغلاق محادثة، أرسل رسالة متابعة عبر API: "شكراً لك على الدردشة! هل هناك أي شيء آخر يمكننا المساعدة به؟"

بديل Webhook

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

العمليات المجمّعة

أغلق جميع المحادثات الأقدم من 7 أيام، أسند المحادثات إلى المشغّلين بناءً على منطق خارجي، أو صدّر سجل المحادثات للتحليلات.