Session Link

API cho nhà phát triển

Nhận liên kết trực tiếp đến cuộc trò chuyện của khách hàng từ chính hệ thống của bạn; khách hàng và cuộc trò chuyện sẽ được tạo nếu chưa tồn tại.

WhatsApp
Instagram
REST API

Cài đặt từ MonoStore Xem trên monochat.ai

Tổng quan

Một lệnh gọi API với kênh và số điện thoại hoặc email của khách hàng trả về liên kết mở cuộc trò chuyện của khách hàng đó trong MonoChat. Nếu khách hàng hoặc cuộc trò chuyện chưa tồn tại, chúng sẽ được tạo.

Đặt liên kết vào CRM, help desk hoặc màn hình đơn hàng của bạn và đội ngũ có thể chuyển thẳng từ đó sang cuộc trò chuyện.

Điểm nổi bật

Mở hoặc tạo. Dùng được cho khách hàng trên một kênh WhatsApp, Instagram hoặc kênh khác, theo số điện thoại hoặc email.
Phân công ngay trong lúc gọi. Giao cuộc trò chuyện cho một nhân viên, theo id hoặc email, hoặc cho một nhóm làm việc ngay trong cùng lệnh gọi.
Cùng khách hàng, cùng cuộc trò chuyện. Gọi lại cho cùng khách hàng và cùng kênh sẽ trả về cuộc trò chuyện hiện có.

Cài đặt và thiết lập

Cài đặt Session Link từ Cài đặt › MonoStore › Ứng dụng, hoặc mở liên kết cài đặt app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA. Nếu chưa có tài khoản MonoChat, liên kết sẽ cho phép bạn đăng ký trước rồi cài đặt ứng dụng cho bạn.
Tạo token API trong Hồ sơ › Token API. Token chỉ hiển thị một lần, vì vậy hãy sao chép ngay. Xem Token API.
Mở Cài đặt › Session Link API. Tài liệu ở đó cho thấy địa chỉ endpoint chính xác của workspace và các yêu cầu mẫu sẵn sàng để sao chép. Hãy thử ví dụ với một trong các kênh của bạn.
Thêm nút "Chat on WhatsApp" vào CRM, help desk hoặc màn hình đơn hàng của bạn để gọi API và mở url được trả về.

ghi chú

Liên kết mở MonoChat cho những người đã đăng nhập và được phép xem cuộc trò chuyện đó.
Lệnh gọi chỉ mở cuộc trò chuyện; không gửi tin nhắn cho khách hàng. Hãy dùng WhatsApp Template API để nhắn trước.

Tính năng

Liên kết cuộc trò chuyện

Phản hồi cung cấp liên kết mở cuộc trò chuyện trong MonoChat và id của cuộc trò chuyện.

Tự tạo khách hàng nếu cần

Khách hàng mới được tạo với họ và tên bạn gửi; phản hồi cho biết khách hàng đã được biết từ trước hay chưa.

Phân công

Giao cho một nhân viên theo id hoặc email, hoặc cho một nhóm làm việc.

Màn hình tài liệu

Tài liệu API với địa chỉ endpoint chính xác của workspace và các yêu cầu mẫu sẵn sàng để sao chép.

Tài liệu tham khảo API

Lệnh gọi là POST với nội dung JSON, được xác thực bằng token 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> là tenant slug của workspace bạn, phần nằm sau /tenants/ trong địa chỉ MonoChat của bạn.
<app-folder> là thư mục nơi ứng dụng được cài đặt. Màn hình Cài đặt › Session Link API hiển thị địa chỉ đầy đủ với cả hai phần đã được điền.
Tạo token trong Hồ sơ › Token API. Xem Token API.

Các trường của yêu cầu

Trường	Bắt buộc	Mô tả
`connectorBrand`	có	Loại kênh, ví dụ `whatsapp` hoặc `instagram`.
`channelUsername`	có	Tên người dùng của kênh bạn trong MonoChat, ví dụ số WhatsApp của bạn không có `+`.
`customer.identityType`	có	`phoneNumber` hoặc `email`.
`customer.identity`	có	Số điện thoại của khách hàng (mã quốc gia, không có `+`) hoặc địa chỉ email.
`customer.firstname`, `customer.lastname`	không	Được dùng khi khách hàng chưa có trong MonoChat. Mặc định `-`.
`assignment.type`	không	`agent` (id người dùng của nhân viên), `agentIdentity` (email nhân viên) hoặc `workgroup` (id nhóm làm việc).
`assignment.value`	khi có `assignment.type`	Id hoặc email để giao cuộc trò chuyện.

Yêu cầu ví dụ

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" }
}'

Phản hồi

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

Trường	Mô tả
`url`	Mở cuộc trò chuyện trong MonoChat.
`sessionId`	Id của cuộc trò chuyện. Cùng một khách hàng trên cùng một kênh luôn nhận được cùng một cuộc trò chuyện.
`isOldUser`	`false` khi khách hàng được tạo bởi lệnh gọi này.

Lỗi

Lệnh gọi thất bại sẽ trả về mã trạng thái lỗi và một thông báo:

Thông báo	Nguyên nhân
`connectorBrand, channelUsername and customer fields are required`	Thiếu một trường cấp cao nhất bắt buộc.
`customer.identityType must be one of: phoneNumber, email`	`identityType` bị thiếu hoặc có giá trị khác.
`customer.identity field is required`	Thiếu số điện thoại hoặc email của khách hàng.
`Channel not found`	Không có kênh nào thuộc loại đó với tên người dùng đó trong workspace của bạn.
`Customer Channel not found`	Không thể khớp khách hàng với một danh tính kênh.
`Agent user not found`	Không có nhân viên nào có email được nêu trong `assignment.value`.
`401`	Thiếu header `Authorization` hoặc token không hợp lệ.