Tùy chỉnh thương hiệu và giao diện trung tâm trợ giúp bằng API Notiondesk

API Notiondesk cho phép bạn đọc và thay đổi thương hiệu của trung tâm trợ giúp: màu sắc, phông chữ, bố cục, tiêu đề và chân trang, liên kết, hiển thị tìm kiếm và phản hồi, và chủ đề. Sử dụng nó để triển khai cùng một thương hiệu trên nhiều trung tâm trợ giúp, hoặc để giữ thương hiệu của bạn trong mã nguồn bên cạnh phần còn lại của hệ thống thiết kế.

Thương hiệu hiển thị trên mọi trang công khai, vì vậy việc cập nhật cần phạm vi admin, chứ không phải write. Chỉ khóa do chủ sở hữu không gian làm việc hoặc Quản trị viên tạo mới có quyền admin.

Để thay đổi thương hiệu trong bảng điều khiển, hãy xem Tùy chỉnh màu sắc và phông chữ của trung tâm trợ giúp .

Những gì API không thay đổi

Những mục này chỉ hiển thị trên bảng điều khiển. Tuyến đọc không trả về chúng và một bản cập nhật đặt tên cho một mục sẽ trả về lỗi 400 validation_error:

• Tùy chỉnh CSS và JavaScript. Xem phần "Tùy chỉnh trung tâm trợ giúp của bạn với CSS tùy chỉnh ";

• Logo (sáng và tối), logo chân trang (sáng và tối), favicon, hình ảnh mạng xã hội và hình ảnh đầu trang (sáng và tối).

Hãy đọc kỹ thông tin thương hiệu của bạn.

Phản hồi chứa chính xác các trường mà bản cập nhật chấp nhận, với cùng tên gọi. Ví dụ rút gọn:

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "colors": {
    "primary": "#2563eb",
    "text": "#111827",
    "link": "#2563eb",
    "link_hover": "#1d4ed8",
    "header": "#2563eb",
    "header_text": "#ffffff",
    "background": "#ffffff",
    "footer_background": ""
  },
  "appearance": null,
  "layout_collection": "column_2",
  "layout_article": "column_1",
  "footer_layout": "compact",
  "primary_font": "Inter",
  "header_links": [{"title": "Docs", "url": "https://example.com/docs"}],
  "footer_links": [{"title": "Product", "links": [{"title": "Pricing", "url": "https://example.com/pricing"}]}],
  "show_powered_by_badge": false,
  "theme": null
}

• Màu chưa từng được thiết lập sẽ hiển thị là "". colors.dark chứa các màu của chế độ tối và sẽ không xuất hiện khi trung tâm trợ giúp không có bảng màu tối.

• Một danh sách không chứa gì sẽ hiển thị là [].

• theme là code của chủ đề hiện tại, hay null.

Cập nhật thương hiệu của bạn

Tuyến đường trả lời 204 No Content. Hãy đọc lại phần mô tả thương hiệu để xác nhận sự thay đổi.

curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"primary_font": "Inter", "colors": {"primary": "#2563eb"}, "header_links": [{"title": "Docs", "url": "https://example.com/docs"}]}'

• Một trường bạn bỏ trống vẫn giữ nguyên giá trị của nó. Bên trong colors, một màu bạn bỏ trống cũng giữ nguyên giá trị của nó.

• Danh sách bạn gửi sẽ thay thế toàn bộ danh sách đã lưu trữ, và [] sẽ xóa sạch danh sách đó.

• Màu sắc được biểu diễn bằng mã thập lục phân #rrggbb hoặc "". Các dạng viết tắt như #fff sẽ bị từ chối.

• Gửi các giá trị boolean JSON. Các giá trị 0 và "false" được đọc là true, và null là false.

Mỗi bản cập nhật được chấp nhận sẽ làm mới toàn bộ trung tâm trợ giúp: Notiondesk xóa các trang đã lưu trong bộ nhớ cache và xây dựng lại mọi trang, bất kể bản cập nhật đã thay đổi điều gì. Hãy gửi tất cả các thay đổi trong một yêu cầu duy nhất, chứ không phải một yêu cầu riêng cho từng trường.

Cập nhật an toàn: đọc, chỉnh sửa, gửi lại

Cách an toàn nhất để cập nhật thương hiệu là gửi lại nội dung bạn đã đọc, sau khi đã áp dụng các thay đổi của bạn. Một trường được gửi với giá trị hiện tại sẽ được chấp nhận trên mọi gói dịch vụ, vì vậy cách này sẽ không bao giờ vượt quá giới hạn của gói dịch vụ đối với các trường mà bạn không chỉnh sửa.

Nội dung gửi trả vẫn có thể bị từ chối trong hai trường hợp. Sửa giá trị trong bảng điều khiển hoặc bỏ trường đó ra khỏi nội dung:

const url = "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize";
const headers = {
  Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
  "nd-version": "2026-10-16",
  "Content-Type": "application/json",
};

const branding = await (await fetch(url, { headers })).json();
branding.colors.primary = "#7c3aed";
branding.colors.link = "#7c3aed";

const response = await fetch(url, { method: "PATCH", headers, body: JSON.stringify(branding) });
console.log(response.status);

• một màu được lưu trữ dưới dạng viết tắt như #fff;

• Một danh sách được lưu trữ dài hơn các giới hạn bên dưới.

Các trường bạn có thể thay đổi

Các liên kết là các đối tượng có title và url. Các nhóm liên kết chân trang là các đối tượng có title và danh sách links. Bản dịch là các đối tượng có locale và bản dịch tương ứng có links, groups hoặc value.

Giới hạn kế hoạch

Việc thay đổi một trong số chúng trên gói cước không có tính năng đó sẽ trả về lỗi 403 permission_denied, thông báo nêu tên tính năng nhưng không có nội dung nào được ghi lại.

Nếu không tùy chỉnh nâng cao, màu sắc chân trang sẽ giữ nguyên giá trị đã lưu mà không có lỗi. Nếu không bật chatbot AI, ai_search_display_mode, ai_search_aside_position và ai_search_enabled: true cũng giữ nguyên giá trị đã lưu.

Giới hạn danh sách

• Mỗi danh sách chứa tối đa 100 mục, và mỗi danh sách links hoặc groups bên trong nó cũng vậy.

• Tổng cộng tất cả các danh sách có thể chứa tối đa 3.000 mục, bao gồm cả các mục lồng nhau và các danh sách đã lưu trữ mà phần thân danh sách không hiển thị.

Nút liên hệ sẽ bật biểu mẫu liên hệ.

Trong khi show_contact_us_button là true trên gói có tùy chỉnh nâng cao, mỗi lần cập nhật thương hiệu sẽ bật biểu mẫu liên hệ của trung tâm trợ giúp, giống như thao tác lưu trong bảng điều khiển. Xem phần biểu mẫu liên hệ của Cập nhật cài đặt trung tâm trợ giúp bằng API Notiondesk .

Chọn một chủ đề

Danh sách luôn chứa mọi chủ đề trong một phản hồi duy nhất, theo thứ tự hiển thị. Áp dụng một chủ đề bằng cách gửi code của nó dưới dạng theme:

Việc thiết lập chủ đề cần tùy chỉnh nâng cao. Gửi "theme": null sẽ giữ nguyên chủ đề.

Lỗi

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/themes" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "object": "list",
  "data": [
    {
      "code": "ocean",
      "name": "Ocean",
      "description": "A calm, airy theme",
      "preview_image_url": "https://example.com/ocean.png",
      "layout": "default"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/customize" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"theme": "ocean"}'

Lỗi trường sẽ đặt tên cho giá trị, ví dụ: colors.primary hoặc footer_links[0].links. Xem Xử lý lỗi API Notiondesk, giới hạn tỷ lệ và số lần thử lại .

Câu hỏi thường gặp

Tiếp theo là gì?

• Cập nhật cài đặt trung tâm trợ giúp bằng API Notiondesk

• Quản lý việc tích hợp trung tâm trợ giúp với API Notiondesk

• Tự động hóa các tác vụ thường gặp trong trung tâm trợ giúp bằng API Notiondesk