Session Link

API توسعه‌دهندگان

از سیستم‌های خودتان پیوند مستقیم گفتگوی یک مشتری را بگیرید؛ اگر مشتری یا گفتگو هنوز وجود نداشته باشد، ساخته می‌شود.

واتس‌اپ
Instagram
REST API

بررسی کلی

یک فراخوانی API با یک کانال و شماره تلفن یا ایمیل مشتری، پیوندی برمی‌گرداند که گفتگوی آن مشتری را در MonoChat باز می‌کند. اگر مشتری یا گفتگو هنوز وجود نداشته باشد، ساخته می‌شوند.

پیوند را در CRM، سیستم پشتیبانی یا صفحهٔ سفارش قرار دهید تا تیم شما از همان‌جا مستقیم به چت برود.

ویژگی‌های برجسته

باز کردن یا ساختن. برای مشتری در یک کانال مشخص واتس‌اپ، اینستاگرام یا کانال دیگر، با شماره تلفن یا ایمیل کار می‌کند.
مسیریابی در همان لحظه. گفتگو را در همان فراخوانی به یک کارشناس، با شناسه یا ایمیل، یا به یک گروه کاری واگذار کنید.
همان مشتری، همان گفتگو. فراخوانی دوباره برای همان مشتری و کانال، گفتگوی موجود را برمی‌گرداند.

نصب و راه‌اندازی

Session Link را از تنظیمات › MonoStore › برنامه‌ها نصب کنید، یا لینک نصب app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA را باز کنید. اگر حساب MonoChat ندارید، این لینک ابتدا شما را به ثبت‌نام می‌برد و سپس برنامه را برایتان نصب می‌کند.
در پروفایل › توکن‌های API یک توکن API بسازید. توکن فقط یک بار نمایش داده می‌شود، پس بلافاصله آن را کپی کنید. توکن‌های API را ببینید.
تنظیمات › Session Link API را باز کنید. مستندات آنجا نشانی دقیق اندپوینت فضای کاری شما و نمونه درخواست‌های آمادهٔ کپی را نشان می‌دهد. نمونه را با یکی از کانال‌هایتان امتحان کنید.
به 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> شناسهٔ (slug) سازمان فضای کاری شماست، یعنی بخشی از نشانی MonoChat شما که بعد از /tenants/ می‌آید.
<app-folder> پوشه‌ای است که برنامه در آن نصب شده است. صفحهٔ تنظیمات › Session Link API نشانی کامل را با هر دو مقدار پر شده نشان می‌دهد.
توکن را در پروفایل › توکن‌های API بسازید. توکن‌های API را ببینید.

فیلدهای درخواست

فیلد	الزامی	توضیحات
`connectorBrand`	بله	نوع کانال، مثلاً `whatsapp` یا `instagram`.
`channelUsername`	بله	نام کاربری کانال شما در MonoChat، مثلاً شمارهٔ واتس‌اپ شما بدون `+`.
`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` وجود ندارد یا توکن نامعتبر است.