واجهة API لتكامل صندوق الوارد | وثائق WOZTELL

واجهة برمجة التطبيقات العامة

مقدمة​

تتيح لك واجهة برمجة التطبيقات العامة (Public Integration API) تنفيذ إجراءات معينة باستخدام تكامل صندوق الوارد دون الحاجة إلى استخدام واجهة المنصة. كما يمكنك من خلال API التحكم في تكامل صندوق الوارد باستخدام منطق روبوت المحادثة.

نقطة نهاية API​

يرجى استخدام عنوان نقطة النهاية التالي لواجهة Public Integration API:
https://api.inbox.woztell.sanuker.com/v1.0/

المصادقة​

لإجراء المصادقة على واجهات تكامل API، يجب استخدام Payload وSignedContext المطلوبين من قبل التكامل.

  • Payload: {"appIntegration":"appIntegrationId","app":"appId"}
  • SignedContext: (signature).{{base64(JSON.stringify(payload))}}
  1. احصل على معلومات تكامل صندوق الوارد عن طريق استعلام installedIntegrations باستخدام Open API.

الطلب:​


query {
  apiViewer {
    installedIntegrations {
      appId
      _id
      signature
      integrationId
    }
  }
}
نسخ

الاستجابة:​


{
  "data": {
    "apiViewer": {
      "installedIntegrations": [
        {
          "appId": "62062c0b717195320192b18f7",
          "_id": "6420fig28e65b466d4607ea2",
          "signature": "mKq60mpKn/YzaP5123tWU+AWX65LqT6BHkBIfq9d3os=",
          "integrationId": "inbox"
        }
      ]
    }
  }
}
نسخ

  1. قم بإنشاء Payload بالتنسيق التالي:

    {"appIntegration":"appIntegrationId","app":"appId"}

مثال على Payload:​


{"appIntegration":"6420fig28e65b466d4607ea2","app":"62062c0b717195320192b18f7"}
نسخ

  1. قم بترميز Payload باستخدام صيغة Base64.

  2. ادمج الـ Payload المشفر مع التوقيع لإنشاء SignedContext بالتنسيق التالي:

    (signature).{{base64(JSON.stringify(payload))}}

مثال على SignedContext​

Example SignedContext​

mKq60mpKn/YzaP5123tWU+AWX65LqT6BHkBIfq9d3os.eyJhcHBJbnRlZ3JhdGlvbiI6IjY0MjBmaWcyOGU2NWI0NjZkNDYwN2VhMiIsImFwcCI6IjYyMDYyYzBiNzE3MTk1MzIwMTkyYjE4ZjcifQ==
نسخ

  1. قم بإضافة القيم إلى ترويسة الطلب كالتالي: X-Woztell-Payload وX-Woztell-SignedContext.


GET /list-threads​

تُستخدم هذه الواجهة للحصول على قائمة المحادثات (الـ threads).

المصادقة​

للمصادقة، يرجى اتباع هذا الدليل وملء الحقول X-Woztell-Payload وX-Woztell-SignedContext في الترويسة.

المعلمات​

الاسم النوع الوصف إجباري
channelId string تصفية المحادثات حسب القناة لا
folderId string تصفية المحادثات حسب المجلد لا
memberId string تصفية المحادثات حسب العضو لا
externalId string تصفية المحادثات حسب externalId للعضو لا
threadId string تصفية حسب معرف المحادثة (Thread ID) لا
memberId string تصفية المحادثات حسب العضو لا
externalId string تصفية المحادثات حسب externalId للعضو لا
threadId string تصفية حسب معرف المحادثة (Thread ID) لا
userId string تصفية المحادثات حسب المعين المسؤول عنها لا
limit integer عدد المحادثات التي يتم إرجاعها (القيمة الافتراضية: 10) لا
after string للحصول على الدفعة التالية من المحادثات — يؤخذ من paging.cursors في الاستجابة لا
before string للحصول على الدفعة السابقة — يؤخذ من paging.cursors في الاستجابة لا

الطلب:​

curl --location --request GET 'https://api.inbox.woztell.sanuker.com/v1.0/api/list-threads?folderId=main&limit=10'
نسخ
الاستجابة:​
{
  "ok": 1,
  "data": [
    {
      "channelId": "string",
      "memberId": "string",
      "externalId": "string",
      "userId": "string",
      "threadId": "T0000027",
      "title": "Test User",
      "folder": "main"
    }
  ],
  "paging": {
    "cursors": {
      "after": "NjU5N2I1MDZkOTcyYTMzNzU3ZTM3ZDgz",
      "before": "NjRhZTE5Yjg3MzQ0YjA1YzM2ZmMyOWQw"
    },
    "hasPrevious": true,
    "hasNext": true
  }
}
نسخ

    



GET /list-users​
تُستخدم هذه الواجهة للحصول على قائمة مستخدمي Inbox.
المصادقة​
للمصادقة، يرجى اتباع هذا الدليل وملء الحقول X-Woztell-Payload وX-Woztell-SignedContext في الترويسة.
المعلمات​​
الاسمالنوعالوصف
إجباري
channelIdstringFتصفية المستخدمين حسب القناة (بيانات الوكيل مثل الدور والاسم والبريد الإلكتروني والصورة مستندة إلى القناة)

No
folderIdstringتصفية المستخدمين حسب من لديهم صلاحية الوصول إلى المجلدNo
userIdstringتصفية حسب معرف المستخدم في WoztellNo
memberIdstringتصفية المستخدم حسب العضوNo
externalIdstringتصفية المستخدم حسب العضو باستخدام ExternalIdNo
threadIdstringتصفية المستخدم حسب معرف الموضوعNo
limitintegerيتحكم في عدد المستخدمين الذين يعودون القيمة الافتراضية: 10No
afterstringللحصول على الدفعة التالية من المستخدمين، يمكن الحصول عليها من paging.cursors في الاستجابةNo
beforestringللحصول على الدفعة السابقة من المستخدمين، يمكن الحصول عليها من paging.cursors في الاستجابةNo
الطلب:​
curl --location --request GET 'https://api.inbox.woztell.sanuker.com/v1.0/api/list-users?folderId=main&userId=632a6743a63fdf590c994a77&channelId=6486be9adfc4ee3ff9d39348'

نسخ
الاستجابة:​
{
  "ok": 1,
  "data": [
    {
      "userId": "6474449cdfc4ee3646d392bf",
      "role": "ADMIN",
      "agentRole": "MANAGER",
      "channel": "6474449cdfc4ee3646d392bd",
      "name": "Test User",
      "email": "test_user@email.com",
      "icon": "string"
    }
  ],
  "paging": {
    "cursors": {
      "after": "NjU5N2I1MDZkOTcyYTMzNzU3ZTM3ZDgz",
      "before": "NjRhZTE5Yjg3MzQ0YjA1YzM2ZmMyOWQw"
    },
    "hasPrevious": true,
    "hasNext": true
  }
}
نسخ

    



POST /update-thread-folder​
تُستخدم هذه الواجهة البرمجية لتعيين محادثة (thread) إلى مجلد محدد.
المصادقة​
للمصادقة، يرجى اتباع هذا الدليل وملء الحقول X-Woztell-Payload وX-Woztell-SignedContext في الترويسة.
المعلمات:​

    
        

            الاسم
            النوع
            الوصف
            إجباري
        

    
    
        

            memberId
            string
            معرّف العضو
            نعم
        

        

            folderId
            string
            معرّف المجلد
            نعم
        

    

نقطة النهاية:​
https://api.inbox.woztell.sanuker.com/v1.0/update-thread-folder
نسخ
الطلب:​
{
    "memberId": "920o80371234550009a01abd",
    "folderId": "test-folder"
}
نسخ
الاستجابة:​
{
    "ok": 1,
    "thread": {
        "_id": "640a123opp71ee2b943ed283",
        "wAppId": "90283b9b71780112208b18f7",
        "wChannelId": "621f29ae4e11986de280e29d",
        "wMemberId": "630d8962168350009a01acd",
        "_version": 2,
        "createdAt": 1678377627235,
        "etag": "d-bkiiEXyVO8CtQ9cHw/5zjO581rM",
        "externalId": "8521234567",
        "folder": "test-folder",
        "lastChatAt": 1682454661289,
        "lastMessage": "[Bot] Hello there!",
        "threadId": "T0000999",
        "title": "John Lee",
        "updatedAt": 1682661372214,
        "lastReadAt": 1682487947711,
        "unreadCount": 0
    }
}
Copy
نسخ

    



POST /update-thread-agent​
تُستخدم هذه الواجهة لإضافة أو إزالة الشخص المسؤول عن المحادثة.
المصادقة​
للمصادقة، يرجى اتباع هذا الدليل وملء الحقول X-Woztell-Payload وX-Woztell-SignedContext في الترويسة.
المعلمات:​

    
        

            الاسم
            النوع
            الوصف
            إجباري
        

    
    
        

            memberId
            string
            معرّف العضو
            نعم
        

        

            userId
            string
            معرّف المستخدم في فريق العمل
            نعم
        

    

Notes
Tيمكن الحصول على معرف المستخدم لعضو الفريق من teamMembers في Open API.

query {
    apiViewer{
        app {
            _id
            teamMembers{
                user{
                    _id
                    email{
                        email
                    }
                }
            }
        }
    }
} 



نقطة النهاية​:
https://api.inbox.woztell.sanuker.com/v1.0/update-thread-agent
نسخ
لإزالة المسؤول:
{
    "memberId": "64744e15bdcca70008a4358f",
    "userId": null
}
نسخ
الاستجابة:​
{
    "ok": 1,
    "thread": {
        "_id": "66892602f94ff12ece18f325",
        "wAppId": "62062b9b71780332208b18f7",
        "wChannelId": "636ccf9ff3cfa1164f3e1d1d",
        "wMemberId": "636cd3d81daca40008296f08",
        "_version": 2,
        "createdAt": 1685530114217,
        "etag": "d-NHYurKhPB+vkbZKV87SrRXRvl+0",
        "externalId": "85254063598",
        "folder": "main",
        "lastChatAt": 1705381701000,
        "lastMessage": "image_test",
        "threadId": "T0000035",
        "title": "Decco Ip",
        "updatedAt": 1705487316616,
        "lastReadAt": 1705461548278,
        "unreadCount": 0,
        "wUserId": "5c0e33c7502129b7ac9e143f"
    }
}
نسخ

    



POST /update-thread-title​
تُستخدم هذه الواجهة البرمجية لتحديث عنوان محادثة (thread).
المصادقة​
للمصادقة، يرجى اتباع هذا الدليل وملء الحقول X-Woztell-Payload وX-Woztell-SignedContext في الترويسة.
المعلمات:​

    
        

            الاسم
            النوع
            الوصف
            إجباري
        

    
    
        

            memberId
            string
            معرّف العضو المرتبط بالمحادثة
            إما memberId أو threadId
        

        

            threadId
            string
            معرّف المحادثة
            إما threadId أو memberId
        

        

            title
            string
            العنوان الجديد للمحادثة
            نعم
        

    

نقطة النهاية​
https://api.inbox.woztell.sanuker.com/v1.0/update-thread-title

نقطة النهاية​
{
  "memberId": "6475559cdfc4ee3646d392bb",
// or "threadId": "T0000027",
  "title": "John (Key Client)"
}
Copy
نسخ
الطلب​
{
  "ok": 1,
  "thread": {
    "_id": "6475559cdfc4ee3646d392bb",
    "_version": 2,
    "etag": "d-x9crPvAd751WYspgcj0cBtisySE",
    "wAppId": "6475559cdfc4ee3646d392bb",
    "wChannelId": "6474449cdfc4ee3646d392bd",
    "wMemberId": "6474449cdfc4ee3646d392be",
    "externalId": "5466281980129353",
    "wUserId": "6474449cdfc4ee3646d392bf",
    "threadId": "T0000027",
    "createdAt": 1686541076488,
    "updatedAt": 1686541076488,
    "lastReadAt": 1686541076488,
    "lastChatAt": 1686541076488,
    "unreadCount": 0,
    "title": "John (Key Client)",
    "folder": "main"
  }
}
نسخ

    



POST /internal-message​
تُستخدم هذه الواجهة لإرسال رسالة داخلية ضمن محادثة.
المصادقة​
للمصادقة، يرجى اتباع هذا الدليل وملء الحقول X-Woztell-Payload وX-Woztell-SignedContext في الترويسة.
المعلمات:​

    
        

            الاسم
            النوع
            الوصف
            إجباري
        

    
    
        

            threadId
            string
            معرّف المحادثة الخاصة بالعضو
            إما memberId أو threadId
        

        

            memberId
            string
            معرّف العضو
            إما threadId أو memberId
        

        

            message
            string
            الرسالة الداخلية المراد إرسالها
            نعم
        

    

نقطة النهاية​
https://api.inbox.woztell.sanuker.com/v1.0/internal-message
نسخ
الطلب​
{
    "threadId": "T0000001",
    // or "memberId": "6475559cdfc4ee3646d392bb",
    "message": "Test Internal Message"
}
نسخ
الاستجابة​
{
    "ok": 1,
    "message": "Test Internal Message",
    "memberId": "6475559cdfc4ee3646d392bb",
    "threadId": "T0000001"
}
نسخ

آخر تحديث بتاريخ 18/03/2024