واجهة المطورين API مُتاح في كل الباقات

🔑 المصادقة وعنوان الواجهة

أنشئ مفاتيح API من لوحة التحكم: صفحة Messaging API (كل مفتاح نسخة مستقلة بقنواتها المسموحة وويب هوك خاص بها). يظهر المفتاح مرة واحدة فقط — احفظه بأمان.

Base URL:  https://thikaa.com/<your-store>/api/messaging/

Authorization: Bearer <api_key>      (أو X-API-Key: <api_key>)

POST إرسال رسالة

POST /api/messaging/?action=send

cURL

curl -X POST "https://thikaa.com/<your-store>/api/messaging/?action=send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "wd",
    "to": "9647701234567",
    "message": "تحديث الوظائف الأسبوعي 👇 ..."
  }'

الاستجابة

{ "ok": true, "message_id": "...", "channel": "wd", "to": "9647701234567" }

💬 قوالب رسائل واتساب

القالب المعتمد مسبقًا هو الطريقة الوحيدة المسموحة لمراسلة عميل على واتساب API (wa) لم يراسلك من قبل، أو لإعادة فتح محادثة بعد انتهاء نافذة الـ24 ساعة. بدونه يعيد action=send الخطأ 409 no_existing_conversation.

1. اعرض قوالبك المعتمدة

GET /api/messaging/?action=templates

curl "https://thikaa.com/<your-store>/api/messaging/?action=templates" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "ok": true, "count": 1, "templates": [
    { "name": "order_update", "language": "en", "status": "APPROVED",
      "category": "UTILITY", "body": "Hi {{1}}, your order {{2}} is ready.", "variables": 2 }
] }

2. أرسل قالبًا

POST /api/messaging/?action=send — القناة wa فقط

curl -X POST "https://thikaa.com/<your-store>/api/messaging/?action=send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "wa",
    "to": "+994105156977",
    "template": {
      "name": "order_update",
      "language": "en",
      "variables": ["Nurlan", "#1042"]
    }
  }'

{ "ok": true, "message_id": "wamid...", "conversation_id": 87,
  "template": "order_update", "language": "en", "delivery": "sent" }

GET حالة الحساب

GET /api/messaging/?action=status — يعيد حالة المفتاح والقنوات المسموحة والرصيد الحالي.

curl "https://thikaa.com/<your-store>/api/messaging/?action=status" \
  -H "Authorization: Bearer YOUR_API_KEY"

📥 ويب هوك استقبال الرسائل

حدّد رابط ويب هوك لكل مفتاح (من صفحة Messaging API). كل رسالة واردة من عملائك على قنوات المفتاح تُرسل POST إلى نقطتك بصيغة JSON وموقّعة بسرّ المفتاح:

POST <your-webhook-url>
Content-Type: application/json
X-Thikaa-Event: message.received
X-Thikaa-Signature: sha256=<hmac_sha256(body, webhook_secret)>

{ "event": "message.received", "instance_id": "...", "data": {
    "channel": "wa",
    "conversation_id": 1290,
    "message_id": 84990,
    "from": "+9665XXXXXXXX",
    "account": { "id": "1297236690138576", "number": "+994 10 515 69 77", "label": "nurlan_dev" },
    "text": "Where is my order?",
    "attachments": []
} }

التحقق من التوقيع (PHP)

$body = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_X_THIKAA_SIGNATURE'] ?? '';
$ok   = hash_equals('sha256=' . hash_hmac('sha256', $body, $secret), $sig);

التحقق من التوقيع (Node.js)

const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-thikaa-signature'] || ''));

🧾 أنواع أحداث واجهة الرسائل

فعّل الأحداث التي تريدها لكل مفتاح. ترويسة X-Thikaa-Event وحقل event يوضّحان دائماً أي حدث تتعامل معه.

🔌 اربط قنوات عملائك من لوحتك الخاصة

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

اعرف ما هو مربوط

curl "https://thikaa.com/<your-store>/api/messaging/?action=channels" \
  -H "Authorization: Bearer YOUR_API_KEY"

{ "ok": true, "channels": [
    { "channel": "wd", "id": "1000017", "name": "Lavida Travel", "identifier": "96555060830", "status": "connected" },
    { "channel": "fb", "id": "100877191952677", "name": "Pawlo Butchery", "status": "connected" },
    { "channel": "ig", "id": "17841478342647968", "name": "Pawlo Butchery", "status": "connected" },
    { "channel": "tt", "id": "-000HFd...", "name": "pawlo_butcher", "status": "connected" } ],
  "counts": { "wd": 1, "fb": 1, "ig": 1, "tt": 1 } }

فيسبوك وإنستقرام وتيك توك — رابط واحد

GET /api/messaging/?action=connect-link&channel=fb        # fb | ig | tt
      &redirect_url=https://your-app.com/done?client=42

{ "ok": true, "channel": "fb",
  "connect_url": "https://www.facebook.com/v21.0/dialog/oauth?...",
  "redirect_url": "https://your-app.com/done?client=42" }

أرسل عميلك إلى connect_url. عند الانتهاء نعيده إلى redirect_url مع النتيجة مضافة — ?thikaa_status=success&channel=fb&connected=2&ids=... — ونرسل لك حدثاً موقّعاً channel.connected لكل قناة تم ربطها.

موافقة واحدة على Meta تغطي الاثنين: ربط صفحة فيسبوك يربط رسائل إنستقرام معها، وتصلك حدثان channel.connected لذلك.

تيليجرام — بدون OAuth، الرمز فقط

POST /api/messaging/?action=connect-telegram
{ "bot_token": "8765196861:AAG..." }      # من @BotFather
{ "ok": true, "channel": "tg", "status": "connected", "bot_username": "YourBot" }

واتساب QR — اقترن برقم عميلك

رمز الاقتران هو الطريقة الأساسية: عميلك عادةً يحمل نفس الهاتف الذي يُربَط، ولا يمكن مسح QR على نفس الشاشة.

POST /api/messaging/?action=create-session   { "label": "Clinic Riyadh" }
   -> { "session_token": "wds_...", "account_id": 1000021 }
POST /api/messaging/?action=pair-code        { "session_token": "wds_...", "phone": "+9665XXXXXXXX" }
   -> { "pairing_code": "ABCD-EFGH" }        # العميل يكتبه في واتساب
GET  /api/messaging/?action=session-status&session_token=wds_...
GET  /api/messaging/?action=session-qr&session_token=wds_...      # بديل لسطح المكتب
POST /api/messaging/?action=delete-session

إلغاء الربط

POST /api/messaging/?action=disconnect-channel
{ "channel": "fb", "id": "100877191952677" }       # fb | ig | tg | tt

{ "ok": true, "channel": "fb", "status": "disconnected",
  "also_disconnected": [ { "channel": "ig", "id": "17841478342647968" } ] }

في فيسبوك هذه إزالة كاملة: نلغي اشتراك تطبيقنا بالصفحة عند Meta حتى يتوقف الاستقبال فعلاً، ثم نحذف توجيهها وروابط البوت. أما channel=ig فيفصل حساب إنستقرام فقط ويُبقي ماسنجر يعمل. واتساب QR يستخدم delete-session.

💭 التعليقات — فيسبوك وإنستقرام وتيك توك

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

{ "event": "comment.received", "data": {
    "platform": "fb",                      # fb | ig | tt
    "comment_id": "1221...._1795...",
    "post_id": "113700101731161_1220987...",
    "parent_id": null,
    "text": "بكم هذا؟",
    "from": { "id": "7051...", "name": "Adham Ammar" },
    "conversation_id": 1841
} }

POST /api/messaging/?action=comment-reply
{ "comment_id": "1221...._1795...",
  "message": "السعر ٢٠٠ ريال",
  "private_message": "هذه القائمة كاملة..." }   # رد خاص عبر Meta، يفتح محادثة حقيقية

GET /api/messaging/?action=comments&platform=tt&limit=50

🔔 ويب هوك أحداث المنصة

بشكل منفصل عن واجهة الرسائل، يمكن للمنصة إرسال أحداث إدارية إلى رابط واحد (الإعدادات ← Webhooks). من أهم الأحداث:

🧠 اربط مفتاح الذكاء الاصطناعي الخاص بك

يمكنك تشغيل بوتاتك على حسابك الخاص في مزود الذكاء الاصطناعي بدل رصيد المنصة: اربط مفتاح OpenAI أو Google Gemini أو Anthropic Claude من صفحة مزودي الذكاء الاصطناعي في لوحة التحكم، ثم اختر هذا الاتصال في إعدادات نموذج البوت. مفتاحك محفوظ داخل حسابك فقط ويُستخدم لبوتاتك وحدها.

⚠️ الأخطاء والحدود

عندك سؤال؟ راسلنا على واتساب من الموقع — سيساعدك فريقنا (أو بوتنا نفسه 😄).