# Cách thiết lập công cụ tùy chỉnh cho Trợ lý Square?

> Khoa Tuyên · Cập nhật lần cuối ngày 2 thg 4, 2026

Công cụ tùy chỉnh cho phép Trợ lý Square gọi các API bên ngoài của bạn trong quá trình hội thoại — để kiểm tra trạng thái bảo hành, xác minh phạm vi dịch vụ, hoặc lấy dữ liệu từ các dịch vụ của bạn mà không cần chuyển tiếp cho nhân viên hỗ trợ.

Khi khách hàng đặt câu hỏi, Trợ lý Square trích xuất các giá trị liên quan từ cuộc hội thoại, đưa chúng vào yêu cầu API của bạn và sử dụng phản hồi để tạo câu trả lời.

Công cụ tùy chỉnh có sẵn trong gói **Business** trở lên.

## Tạo công cụ

Điều hướng đến **Trợ lý Square -> Công cụ** và nhấp vào **Tạo công cụ mới**.![](/assets/images/a11a1b37_image.png)Điền các trường sau:

**Tên công cụ** — Tên ngắn gọn như "Tra cứu bảo hành" hoặc "Kiểm tra khu vực dịch vụ" (tối đa 55 ký tự).

**Mô tả** — Cho Trợ lý Square biết khi nào nên dùng công cụ này. Đây là trường quan trọng nhất. Viết như bạn đang hướng dẫn một nhân viên hỗ trợ: "Kiểm tra trạng thái bảo hành của sản phẩm theo số serial." Các mô tả mơ hồ như "API bảo hành" sẽ khiến Trợ lý Square bỏ lỡ cơ hội sử dụng công cụ.

**Phương thức** — Chọn GET (để lấy dữ liệu) hoặc POST (để gửi dữ liệu).

**URL endpoint** — URL của API bạn. Dùng `{{ parameter_name }}` để chèn các giá trị được trích xuất từ cuộc hội thoại:

`https://api.yourcompany.com/v1/warranty/{{ serial_number }}`

URL phải dùng HTTPS, phải là tên miền (không phải địa chỉ IP), và không thể trỏ đến localhost hoặc mạng nội bộ.

**Xác thực** — Chọn cách API của bạn xác thực yêu cầu:

-   **Không có** — Không xác thực
    
-   **Bearer Token** — Gửi token trong header `Authorization`
    
-   **Basic Auth** — Gửi tên người dùng và mật khẩu
    
-   **API Key** — Gửi tên header và giá trị tùy chỉnh (ví dụ: `X-API-Key`)
    

Thông tin xác thực chỉ hiển thị cho quản trị viên tài khoản.

![](/assets/images/b1cc01dd_image.png)

**Tham số** — Xác định những gì Trợ lý Square cần trích xuất từ tin nhắn của khách hàng. Mỗi tham số cần có tên, kiểu dữ liệu và mô tả. Ví dụ: `serial_number` (String) — "Số serial của sản phẩm, có ở mặt sau thiết bị."

**Mẫu yêu cầu** (chỉ dành cho POST) — Mẫu nội dung JSON dùng cú pháp Liquid.

**Mẫu phản hồi** — Kiểm soát những gì Trợ lý Square nhận được từ phản hồi API của bạn. Nếu để trống, Trợ lý Square nhận JSON thô.

Dùng Liquid để trích xuất các trường liên quan, ví dụ: `Serial {{ response.serial_number }}: {{ response.warranty_status }}. Hết hạn: {{ response.expiry_date }}.`

Dùng `response` để truy cập phần thân JSON đã phân tích. Mẫu phản hồi giúp Trợ lý Square tập trung vào dữ liệu liên quan và tránh các trường nội bộ như ID cơ sở dữ liệu hoặc thông tin gỡ lỗi.

## Kiểm tra công cụ

Nhấp **Kiểm tra kết nối** trước khi lưu để xác minh endpoint của bạn có thể truy cập được. Quá trình kiểm tra báo cáo mã trạng thái HTTP.![](/assets/images/1b8029dd_image.png)Kết quả màu xanh (HTTP 200–299) có nghĩa là kết nối và xác thực đang hoạt động tốt. Lưu ý rằng quá trình kiểm tra gửi URL mà không điền giá trị tham số, vì vậy nó chỉ xác minh endpoint của bạn có thể truy cập được và thông tin xác thực được chấp nhận.

Nếu kiểm tra thất bại, hãy kiểm tra những điều sau:

-   401 Unauthorized — Thông tin xác thực của bạn không chính xác. Kiểm tra lại bearer token, API key, hoặc tên người dùng/mật khẩu.
    
-   403 Forbidden — API của bạn đang từ chối yêu cầu. Nếu bạn yêu cầu xác minh danh tính, lưu ý rằng các yêu cầu kiểm tra không bao gồm header liên hệ.
    
-   404 Not Found — URL endpoint sai. Kiểm tra lại đường dẫn và đảm bảo API của bạn đang chạy.
    
-   Timeout — API của bạn mất quá nhiều thời gian để phản hồi. Công cụ tùy chỉnh có thời gian chờ 30 giây; đảm bảo endpoint của bạn phản hồi trong khoảng thời gian đó
    

## Ngữ cảnh gửi kèm mỗi lần gọi công cụ

Khi Trợ lý Square gọi API của bạn, nó bao gồm các header siêu dữ liệu để backend của bạn biết ngữ cảnh:

-   `X-SquareHub-Account-Id` — ID tài khoản của bạn
    
-   `X-SquareHub-Conversation-Id` — ID cuộc hội thoại
    
-   `X-SquareHub-Contact-Email` — Email của khách hàng (nếu có)
    
-   `X-SquareHub-Contact-Inbox-Verified` — Danh tính khách hàng có được xác minh HMAC không
    
-   `X-SquareHub-Assistant-Id` — Trợ lý Trợ lý Square đang thực hiện cuộc gọi
    
-   `X-SquareHub-Tool-Slug` — Định danh nội bộ của công cụ
    
-   `X-SquareHub-Contact-Id` — ID liên hệ của khách hàng
    
-   `X-SquareHub-Contact-Phone` — Số điện thoại của khách hàng (nếu có)
    
-   `X-SquareHub-Conversation-Display-Id` — Số hiển thị của cuộc hội thoại
    

Bạn có thể dùng các header này để tra cứu khách hàng trong hệ thống của mình, ghi lại cuộc hội thoại nào đã kích hoạt lệnh gọi API, và xác minh tính xác thực của yêu cầu.

## Bảo mật

**Các biện pháp bảo vệ tích hợp sẵn:**

-   Tất cả endpoint phải dùng HTTPS
    
-   Các yêu cầu đến dải IP nội bộ, localhost và tên miền `.local` đều bị chặn
    
-   Không theo dõi chuyển hướng HTTP
    
-   Phản hồi được giới hạn tối đa 1 MB
    
-   Thông tin xác thực chỉ hiển thị cho quản trị viên
    

**Xác minh danh tính:** Nếu công cụ của bạn trả về dữ liệu dành riêng cho khách hàng (đơn hàng, thanh toán, thông tin tài khoản), API của bạn nên kiểm tra header `X-SquareHub-Contact-Inbox-Verified`. Nếu không bật xác minh HMAC trên inbox, khách truy cập có thể nhập bất kỳ địa chỉ email nào trong widget chat. Chỉ trả về dữ liệu nhạy cảm khi header này là `true`. Đối với các công cụ trả về dữ liệu công khai, không cần kiểm tra này.

**Prompt injection:** Nếu API của bạn trả về nội dung do người dùng tạo (đánh giá, bài đăng diễn đàn), văn bản độc hại có thể ảnh hưởng đến hành vi của Trợ lý Square. Dùng mẫu phản hồi để chỉ trích xuất các trường có cấu trúc, và làm sạch nội dung ở phía API của bạn.

## Giới hạn

-   **Số công cụ tối đa mỗi tài khoản** — 15
    
-   **Khuyến nghị** — 10 hoặc ít hơn. Cảnh báo xuất hiện khi vượt quá 10; càng nhiều công cụ càng khó để Trợ lý Square chọn đúng công cụ.
    
-   **Độ dài tên công cụ** — 55 ký tự
    
-   **Kích thước phản hồi** — Tối đa 1 MB
    
-   **Thời gian chờ yêu cầu** — 30 giây
    

## Khi nào nên dùng công cụ tùy chỉnh

Công cụ tùy chỉnh phù hợp nhất cho các tra cứu có cấu trúc với đầu vào có thể dự đoán — kiểm tra trạng thái hệ thống, lấy lịch trình, hoặc tra cứu bản ghi theo ID. Nếu bạn đã có tích hợp SquareHub chuyên dụng cho trường hợp sử dụng của mình (ví dụ: Shopify cho thương mại điện tử), hãy dùng tích hợp đó — các tích hợp chuyên dụng xử lý tìm kiếm, khớp mờ và đồng bộ dữ liệu đáng tin cậy hơn một lệnh gọi API đơn lẻ.

## Ví dụ

### Tra cứu bảo hành

Khi khách hàng hỏi liệu sản phẩm của họ còn trong thời hạn bảo hành không, Trợ lý Square có thể kiểm tra bằng số serial.

-   **Tên công cụ:** Tra cứu bảo hành
    
-   **Mô tả:** Kiểm tra trạng thái bảo hành của sản phẩm theo số serial. Dùng khi khách hàng hỏi sản phẩm của họ có được bảo hành không, khi nào hết hạn bảo hành, hoặc loại bảo hành họ có.
    

![](/assets/images/dd14e7cc_CleanShot_2026-04-01_at_18.40.03_2x.png)

### **Kiểm tra khu vực dịch vụ**

Đối với các doanh nghiệp hoạt động ở các khu vực cụ thể — khách hàng hỏi liệu dịch vụ có sẵn ở vị trí của họ không.

-   **Tên công cụ:** Kiểm tra khu vực dịch vụ
    
-   **Mô tả:** Kiểm tra xem dịch vụ hoặc giao hàng có sẵn ở một khu vực cụ thể không, dựa trên mã bưu chính hoặc tên thành phố của khách hàng.
    

![](/assets/images/21e4f03f_CleanShot_2026-04-01_at_18.38.23_2x.png)

Công cụ tùy chỉnh hoạt động tốt nhất khi đầu vào đơn giản và phản hồi API có thể dự đoán — kiểm tra trạng thái, tra cứu và các truy vấn có cấu trúc khác là những trường hợp rất phù hợp.