SquareHub

Cách tạo inbox kênh API?

Mở trong
Xem dạng MarkdownMở trong ChatGPTMở trong Claude
TA

Tami

Cập nhật lần cuối ngày 8 thg 4, 2026

Để tạo và cấu hình một inbox kênh API trong các cài đặt SquareHub, hãy làm theo các bước được mô tả dưới đây.

Thiết lập kênh API

Bước 1. Vào Cài đặt → Inbox → "Thêm Inbox".

Bước 2. Nhấp vào biểu tượng "API".

Bước 3. Nhập tên cho kênh và URL callback. Dưới đây là một ví dụ:

Bước 4. "Thêm nhân viên hỗ trợ" vào inbox API của bạn.

Quá trình thiết lập inbox đã hoàn tất.

Gửi tin nhắn đến kênh API

Để gửi tin nhắn đến kênh API, hãy đảm bảo bạn hiểu các mô hình và thuật ngữ được sử dụng trong SquareHub sau đây.

  1. Kênh (Channel): Kênh xác định loại nguồn của các cuộc hội thoại. Ví dụ: Facebook, Twitter, API, v.v.

  2. Inbox: Bạn có thể tạo nhiều nguồn cuộc hội thoại cùng loại kênh. Ví dụ: bạn có thể kết nối nhiều hơn một trang Facebook vào một tài khoản SquareHub. Mỗi trang được gọi là một inbox trong SquareHub.

  3. Cuộc hội thoại (Conversation): Cuộc hội thoại là tập hợp các tin nhắn.

  4. Liên hệ (Contact): Mỗi cuộc hội thoại có một người thực tế được liên kết với nó, được gọi là liên hệ.

  5. Inbox của liên hệ (Contact Inboxes): Đây là phiên làm việc của mỗi liên hệ trong một inbox. Một liên hệ có thể có nhiều phiên và nhiều cuộc hội thoại trong cùng một inbox.

Cách gửi tin nhắn trong kênh API?

Để gửi tin nhắn trong kênh API, hãy tạo một liên hệ, khởi tạo cuộc hội thoại, và sau đó gửi tin nhắn.

Các API yêu cầu api_access_token trong tiêu đề yêu cầu. Bạn có thể lấy token này bằng cách truy cập Cài đặt hồ sơ → Access Token.

1. Tạo một liên hệ

Tham khảo: Tài liệu API

Truyền ID inbox của kênh API cùng với các tham số khác được chỉ định. Thao tác này sẽ tự động tạo một phiên cho bạn. Một phản hồi mẫu sẽ trông như sau.

{
  "email": "string",
  "name": "string",
  "phone_number": "string",
  "thumbnail": "string",
  "additional_attributes": {},
  "contact_inboxes": [
    {
      "source_id": "string",
      "inbox": {
        "id": 0,
        "name": "string",
        "website_url": "string",
        "channel_type": "string",
        "avatar_url": "string",
        "widget_color": "string",
        "website_token": "string",
        "enable_auto_assignment": true,
        "web_widget_script": "string",
        "welcome_title": "string",
        "welcome_tagline": "string",
        "greeting_enabled": true,
        "greeting_message": "string"
      }
    }
  ],
  "id": 0,
  "availability_status": "string"
}

Như bạn có thể thấy trong payload, bạn sẽ thấy contact_inboxes và mỗi contact_inbox sẽ có một source_id. Source ID có thể được hiểu là định danh phiên. Bạn sẽ sử dụng source_id này để tạo một cuộc hội thoại mới như được định nghĩa bên dưới.

2. Tạo một cuộc hội thoại

Tham khảo: Tài liệu API

Sử dụng source_id nhận được từ lệnh gọi API trước. Bạn sẽ nhận được ID cuộc hội thoại có thể dùng để tạo tin nhắn.

{
  "id": 0
}

3. Tạo tin nhắn mới

Tham khảo: Tài liệu API

Có 2 loại tin nhắn.

  1. Đến (Incoming): Tin nhắn do người dùng cuối gửi được phân loại là tin nhắn đến.

  2. Đi (Outgoing): Tin nhắn do nhân viên hỗ trợ gửi được phân loại là tin nhắn đi.

Nếu bạn gọi API với nội dung đúng, bạn sẽ nhận được payload tương tự như sau:

{
    "id": 0,
    "content": "This is a incoming message from API Channel",
    "inbox_id": 0,
    "conversation_id": 0,
    "message_type": 0,
    "content_type": null,
    "content_attributes": {},
    "created_at": 0,
    "private": false,
    "sender": {
        "id": 0,
        "name": "Pranav",
        "type": "contact"
    }
}

Nếu mọi thứ thành công, bạn sẽ thấy cuộc hội thoại trên bảng điều khiển như sau.

Bạn sẽ được thông báo khi có tin nhắn mới được tạo trên URL đã chỉ định khi tạo kênh API. Bạn có thể đọc về payload tin nhắn tại đây.

Nhận tin nhắn qua URL callback

Khi một tin nhắn mới được tạo trong kênh API, bạn sẽ nhận được yêu cầu POST đến URL Callback đã chỉ định khi tạo kênh API. Payload sẽ trông như thế này.

Xem danh sách đầy đủ các sự kiện được webhook hỗ trợ tại đây.

Loại sự kiện: message_created

{
  "id": 0,
  "content": "This is a incoming message from API Channel",
  "created_at": "2020-08-30T15:43:04.000Z",
  "message_type": "incoming",
  "content_type": null,
  "content_attributes": {},
  "source_id": null,
  "sender": {
    "id": 0,
    "name": "contact-name",
    "avatar": "",
    "type": "contact"
  },
  "inbox": {
    "id": 0,
    "name": "API Channel"
  },
  "conversation": {
    "additional_attributes": null,
    "channel": "Channel::Api",
    "id": 0,
    "inbox_id": 0,
    "status": "open",
    "agent_last_seen_at": 0,
    "contact_last_seen_at": 0,
    "timestamp": 0
  },
  "account": {
    "id": 1,
    "name": "API testing"
  },
  "event": "message_created"
}

Tạo giao diện bằng Client API

Các Client API có sẵn cho kênh API sẽ giúp bạn xây dựng các giao diện hướng đến khách hàng cho SquareHub.

Các API này hữu ích cho các trường hợp như những trường hợp được liệt kê bên dưới.

  1. Sử dụng giao diện chat tùy chỉnh thay vì widget chat của SquareHub.

  2. Tích hợp giao diện hội thoại vào ứng dụng di động của bạn.

  3. Thêm SquareHub vào các nền tảng khác mà SquareHub chưa có SDK chính thức.

Tạo đối tượng khách hàng

Bạn có thể tạo và truy xuất các đối tượng dữ liệu khách hàng bằng cách sử dụng inbox_identifier và customer_identifier.

Định danh Inbox

Bạn có thể lấy inbox_identifier từ kênh API của bạn → Cài đặt → Cấu hình.

Định danh khách hàng

customer_identifier hay source_id có thể được lấy khi tạo khách hàng bằng API tạo. Bạn cần lưu trữ định danh này ở phía client để thực hiện các yêu cầu tiếp theo thay mặt cho khách hàng. Điều này có thể được thực hiện trong cookies, local storage, v.v.

Các API khả dụng

Các Client API khả dụng được tài liệu hóa tại đây. Một số việc bạn có thể làm với các API bao gồm:

  • Tạo, xem và cập nhật liên hệ

  • Tạo và liệt kê cuộc hội thoại

  • Tạo, liệt kê và cập nhật tin nhắn

Xác thực HMAC

Các Client API cũng hỗ trợ xác thực HMAC. HMAC token cho kênh có thể được lấy bằng cách chạy lệnh sau trên rails console của bạn.

# replace api_inbox_id with your inbox id
Inbox.find(api_inbox_id).channel.hmac_token

Kết nối với WebSockets của SquareHub

Để nhận cập nhật theo thời gian thực từ bảng điều khiển nhân viên hỗ trợ, hãy kết nối với WebSockets của SquareHub bằng URL sau.

<your installation url>/cable

Xác thực kết nối WebSocket của bạn

Sau khi đăng ký bằng pubsub_token của khách hàng, bạn sẽ nhận được các sự kiện hướng đến đối tượng khách hàng của bạn. pubsub_token được cung cấp trong lệnh gọi API tạo khách hàng.

Ví dụ

const connection = new WebSocket('ws://localhost:3000/cable');
connection.send(JSON.stringify({ command:"subscribe", identifier: "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\""+ customer_pubsub_token+"\\"}" }));

Xem danh sách đầy đủ các sự kiện được WebSockets hỗ trợ tại đây.

Xác minh Webhook

Khi bạn tạo kênh API, chúng tôi tự động tạo một secret mà bạn có thể dùng để xác minh payload mà ứng dụng của bạn nhận được. Bạn có thể đọc thêm về xác minh webhook tại đây.

Triển khai thực tế

Đây là một ví dụ về giao diện chat được xây dựng trên các Client API.