تحكم في مساحة عملك
من شيفرتك الخاصة.

§ 00ما هي واجهة REST API

تكشف EasyLiveChat عن واجهة REST API على /api/v1/* حتى يستطيع الكود الخارجي — خادمك الخلفي، أو تكامل CRM، أو سير عمل Zapier أو n8n، أو سكربت ترحيل — القراءة من مساحة عملك والكتابة فيها دون أن يكون هناك وكيل بشري مسجل الدخول. كل استدعاء يُصادَق عليه بمفتاح API يتم إنشاؤه في لوحة التحكم ومحصور بمستأجرك.

إذا سبق لك أن استدعيت واجهة Stripe أو Slack أو GitHub، فهذه تعمل بنفس الطريقة: رمز سري طويل الأمد في رأس Authorization، أجسام طلب واستجابة JSON، ورموز حالة HTTP قابلة للتنبؤ.

لا يحمل مفتاح API مصادقة ثنائية أو كلمة مرور — وهذا هو الهدف. إنه بيانات اعتماد تضمّنها في برنامج آخر حتى يتمكن ذلك البرنامج من العمل نيابةً عن مستأجرك، بالنطاقات التي تمنحها له فقط.

§ 01توفر الخطة

تتوفر واجهة REST API في كل خطة مدفوعة وتُفتح خلال التجربة المجانية لمدة 14 يومًا. لا توجد فوترة لكل استدعاء.

بمجرد انتهاء التجربة، تتحول الواجهة إلى وضع القراءة فقط — تُعيد عمليات الكتابة الرمز 402 حتى تتم ترقية مساحة العمل. تستمر القراءات في العمل حتى لا تنكسر عمليات تصدير البيانات التاريخية.

§ 02المصادقة

أنشئ مفتاحًا من https://app.livechattools.com/settings/api-keys. اختر أصغر مجموعة من النطاقات يحتاجها التكامل فعلاً. يمكنك إلغاء مفتاح من نفس الصفحة في أي وقت — يتوقف عن العمل فورًا، دون أي تأثير على لوحة عمل وكلائك أو تسجيلات دخول الجوال.

مرّر المفتاح في كل طلب، إما كرمز Bearer أو عبر x-api-key:

Authorization: Bearer plk_<your-key>
# — or, equivalently —
x-api-key: plk_<your-key>

تحقق من أن المفتاح يعمل قبل توصيله بأي شيء — تُرجع /me نطاقاتك ومستأجرك:

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<your-key>"

يتم عرض المفتاح الخام مرة واحدة فقط عند الإنشاء. فقدته؟ ألغِه وأنشئ مفتاحًا جديدًا — لا توجد طريقة لاسترداد القيمة الأصلية.

§ 03النطاقات

يتم التحقق من النطاقات في كل طلب. مفتاح يحمل نطاقات :read فقط لن يستطيع تعديل البيانات بطريق الخطأ — مفيد للوحات للقراءة فقط أو تصدير ذكاء الأعمال أو خطوط أنابيب التحليلات.

مبدأ الحد الأدنى من الامتيازات — مفتاح منفصل لكل تكامل. مفتاح للقراءة فقط مسرّب على خط أنابيب التقارير أقل ضررًا بكثير من مفتاح واحد "يفعل كل شيء" مشترك عبر مكدسك.

§ 04نقاط النهاية

كل المسارات تبدأ بـ /api/v1. الاستجابات بصيغة JSON. الأوقات بتنسيق ISO 8601 UTC.

GET /api/v1/me

تُرجع هوية المفتاح والمستأجر. لا يتطلب نطاقًا — مفيد لاختبار الاتصال.

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<key>"

{
  "apiKeyId": "ck...",
  "scopes": ["conversations:read","messages:write"],
  "tenant": { "id": "...", "name": "Acme", "slug": "acme", "planTier": "GROWTH" }
}

GET /api/v1/conversations

سرد المحادثات من الأحدث إلى الأقدم. كل المرشحات اختيارية.

• ?status= OPEN · SNOOZED · CLOSED
• ?channel= WIDGET · WHATSAPP · TELEGRAM · MESSENGER · INSTAGRAM
• ?limit= 1–200، الافتراضي 50
• ?cursor= معرّف آخر صف من الصفحة السابقة

curl "https://api.livechattools.com/api/v1/conversations?status=OPEN&limit=50" \
  -H "Authorization: Bearer plk_<key>"

{
  "data": [
    { "id":"...", "sourceChannel":"WHATSAPP", "status":"OPEN",
      "lastMessagePreview":"hi there", "lastMessageAt":"..." }
  ],
  "nextCursor": "..."
}

GET /api/v1/conversations/:id

جلب محادثة واحدة مع جهة الاتصال المرفقة بها.

GET /api/v1/conversations/:id/messages

سجل رسائل مقسّم إلى صفحات لمحادثة، الأحدث أولاً.

curl "https://api.livechattools.com/api/v1/conversations/<id>/messages?limit=50" \
  -H "Authorization: Bearer plk_<key>"

POST /api/v1/conversations/:id/messages

إرسال رسالة صادرة في محادثة. تُوزَّع إلى القناة المطابقة (الويدجت، واتساب، تيليغرام، ماسنجر، إنستغرام) تمامًا مثل ردّ وكيل بشري.

curl -X POST "https://api.livechattools.com/api/v1/conversations/<id>/messages" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Your order has shipped." }'

# → 201 Created
{ "message": { "id":"...", "senderType":"AGENT", "body":"Your order has shipped.", "createdAt":"..." } }

حقل senderAgentId اختياري — إذا حُذف، تُنسب الرسالة إلى أول OWNER أو ADMIN نشط في مساحة العمل. مرّر معرّفًا صريحًا عندما تريد ظهور حساب بوت محدد في المحادثة.

PATCH /api/v1/conversations/:id

تحديث حالة محادثة (OPEN · SNOOZED · CLOSED) أو الوكيل المعيّن لها. مرّر assignedAgentId: null لإلغاء التعيين.

curl -X PATCH "https://api.livechattools.com/api/v1/conversations/<id>" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "CLOSED" }'

GET /api/v1/contacts

سرد جهات الاتصال في مساحة العمل. ?q= يطابق الاسم أو البريد الإلكتروني أو الهاتف.

curl "https://api.livechattools.com/api/v1/contacts?q=acme" \
  -H "Authorization: Bearer plk_<key>"

§ 05ترقيم الصفحات

تستخدم كل نقاط نهاية القائمة ترقيم الصفحات بالمؤشر. شكل الاستجابة هو:

{
  "data": [ /* up to ?limit= rows */ ],
  "nextCursor": "<id of last row>"   // or null when there are no more
}

لجلب الصفحة التالية، مرّر nextCursor كـ ?cursor= في الطلب التالي. عندما تكون nextCursor تساوي null تكون قد وصلت إلى النهاية.

§ 06الأخطاء

تُرجع الأخطاء دائمًا جسم JSON برمز خطأ ورسالة قابلة للقراءة (عند الفائدة). تعكس حالة HTTP المعنى:

§ 07Webhooks (مكمّل)

واجهة REST API ممتازة للسحب والدفع وفق جدولك. لإشعارات الدفع عند حدوث شيء من جانب EasyLiveChat — رسالة عميل جديدة، إغلاق محادثة، انضمام وكيل — اضبط الويبهوكس الصادرة من الإعدادات ← Webhooks.

الرسائل التي ترسلها عبر POST /api/v1/conversations/:id/messages تُطلق أيضًا ويبهوك message.created، لذلك إذا كان لديك تكامل يُرسل الرسائل وآخر يستمع لها، سترى عمليات الكتابة الخاصة بك تصلك مرة أخرى عبر قناة الويبهوك.

§ 08حدود المعدل

يحصل كل مستأجر على ما يصل إلى 240 طلبًا في الدقيقة لكل مسار، مشتركة عبر كل المفاتيح على ذلك المستأجر. تجاوز الحد يُرجع 429 مع رأس Retry-After.

إذا كان تكاملك يحتاج بشكل مشروع إلى سقف أعلى (استيراد جماعي، إرسال جماعي للرسائل)، راسل الدعم — سنرفعه لمستأجرك.