Session Link

API للمطورين

احصلوا على رابط مباشر إلى محادثة عميل من أنظمتكم الخاصة؛ ويُنشأ العميل والمحادثة إن لم يكونا موجودين بعد.

WhatsApp
Instagram
REST API

التثبيت من MonoStore اطّلع عليه في monochat.ai

نظرة عامة

استدعاء API واحد بقناة ورقم هاتف العميل أو بريده الإلكتروني يعيد رابطاً يفتح محادثة ذلك العميل في MonoChat. وإذا لم يكن العميل أو المحادثة موجودين بعد، يُنشآن.

ضعوا الرابط في نظام CRM أو مكتب المساعدة أو شاشة الطلبات، وينتقل فريقكم من هناك مباشرة إلى الدردشة.

أبرز المزايا

فتح أو إنشاء. يعمل لعميل على قناة WhatsApp أو Instagram أو أي قناة أخرى محددة، برقم الهاتف أو البريد الإلكتروني.
التوجيه أثناء الطريق. أسندوا المحادثة إلى موظف، بالمعرّف أو البريد الإلكتروني، أو إلى مجموعة عمل في الاستدعاء نفسه.
العميل نفسه، المحادثة نفسها. استدعاؤه مرة أخرى لنفس العميل والقناة يعيد المحادثة الموجودة.

التثبيت والإعداد

ثبّتوا Session Link من الإعدادات › MonoStore › التطبيقات، أو افتحوا رابط التثبيت app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA. إذا لم يكن لديكم حساب MonoChat، يتيح لكم الرابط التسجيل أولاً ثم يثبّت التطبيق لكم.
أنشئوا رمز API من الملف الشخصي › رموز API. يظهر الرمز مرة واحدة فقط، لذا انسخوه فوراً. راجعوا رموز API.
افتحوا الإعدادات › Session Link API. تعرض الوثائق هناك عنوان نقطة النهاية الدقيق لمساحة عملكم وأمثلة طلبات جاهزة للنسخ. جرّبوا المثال مع إحدى قنواتكم.
أضيفوا زر "الدردشة على WhatsApp" إلى نظام CRM أو مكتب المساعدة أو شاشة الطلبات يستدعي API ويفتح url المُعاد.

ملاحظة

يفتح الرابط MonoChat للأشخاص الذين سجّلوا الدخول ويُسمح لهم برؤية تلك المحادثة.
الاستدعاء يفتح المحادثة فقط؛ ولا يرسل رسالة إلى العميل. استخدموا WhatsApp Template API للكتابة أولاً.

الميزات

رابط المحادثة

تتضمن الإجابة الرابط الذي يفتح المحادثة في MonoChat ومعرّف المحادثة.

إنشاء العميل عند الحاجة

يُنشأ عميل جديد بالاسم الأول واسم العائلة اللذين ترسلونهما؛ وتخبركم الإجابة ما إذا كان العميل معروفاً من قبل.

الإسناد

أسندوا إلى موظف بالمعرّف أو البريد الإلكتروني، أو إلى مجموعة عمل.

شاشة التوثيق

مرجع API مع عنوان نقطة النهاية الدقيق لمساحة عملكم وأمثلة طلبات جاهزة للنسخ.

مرجع API

الاستدعاء طلب POST بجسم JSON، ويُصادَق عليه برمز API.

POST https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

<slug> هو tenant slug لمساحة عملكم، أي الجزء الذي يلي /tenants/ في عنوان MonoChat الخاص بكم.
<app-folder> هو المجلد الذي ثُبّت فيه التطبيق. تعرض شاشة الإعدادات › Session Link API العنوان الكامل وقد مُلئ فيه الاثنان.
أنشئوا الرمز من الملف الشخصي › رموز API. راجعوا رموز API.

حقول الطلب

الحقل	مطلوب	الوصف
`connectorBrand`	نعم	نوع القناة، مثل `whatsapp` أو `instagram`.
`channelUsername`	نعم	اسم مستخدم قناتكم في MonoChat، مثل رقم WhatsApp الخاص بكم بدون `+`.
`customer.identityType`	نعم	`phoneNumber` أو `email`.
`customer.identity`	نعم	رقم هاتف العميل (مع رمز الدولة، بدون `+`) أو بريده الإلكتروني.
`customer.firstname`, `customer.lastname`	لا	تُستخدم عندما يكون العميل جديداً على MonoChat. القيمة الافتراضية `-`.
`assignment.type`	لا	`agent` (معرّف مستخدم الموظف) أو `agentIdentity` (البريد الإلكتروني للموظف) أو `workgroup` (معرّف مجموعة العمل).
`assignment.value`	مع `assignment.type`	المعرّف أو البريد الإلكتروني الذي تُسند إليه المحادثة.

مثال على طلب

curl --location 'https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "connectorBrand": "whatsapp",
  "channelUsername": "905334445566",
  "customer": {
    "identityType": "phoneNumber",
    "identity": "905306667788",
    "firstname": "Ayşe",
    "lastname": "Yılmaz"
  },
  "assignment": { "type": "agentIdentity", "value": "sarah@yourcompany.com" }
}'

الاستجابة

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "Zeii7vpeeFFnsJepZ",
    "isOldUser": true
  }
}

الحقل	الوصف
`url`	يفتح المحادثة في MonoChat.
`sessionId`	معرّف المحادثة. العميل نفسه على القناة نفسها يحصل دائماً على المحادثة نفسها.
`isOldUser`	تكون `false` عندما أُنشئ العميل بهذا الاستدعاء.

الأخطاء

يردّ الاستدعاء الفاشل بحالة خطأ ورسالة:

الرسالة	السبب
`connectorBrand, channelUsername and customer fields are required`	حقل مطلوب من المستوى الأعلى مفقود.
`customer.identityType must be one of: phoneNumber, email`	`identityType` مفقود أو له قيمة أخرى.
`customer.identity field is required`	رقم هاتف العميل أو بريده الإلكتروني مفقود.
`Channel not found`	لا توجد قناة من هذا النوع بهذا اسم المستخدم في مساحة عملكم.
`Customer Channel not found`	تعذّر مطابقة العميل مع هوية قناة.
`Agent user not found`	لا يوجد موظف بالبريد الإلكتروني المذكور في `assignment.value`.
`401`	ترويسة `Authorization` مفقودة أو الرمز غير صالح.