> ## Documentation Index
> Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cấu hình TikTok

> Hướng dẫn đăng ký ứng dụng TikTok Developer, gửi xét duyệt Business Messaging API và cấu hình Credentials kết nối trên portal của bạn.

Kết nối kênh TikTok Business Messaging vào portal giúp khách hàng của bạn có thể quản lý các cuộc trò chuyện, nhận và phản hồi tin nhắn trực tiếp từ khách hàng trên TikTok ngay tại giao diện Inbox chung.

## Điều kiện chuẩn bị

Trước khi bắt đầu, hãy đảm bảo bạn có:

* Một portal được cấu hình tên miền riêng chạy giao thức bảo mật HTTPS và truy cập được công khai.
* Một **tài khoản TikTok Doanh nghiệp** (TikTok Business Account) đăng ký tại khu vực được hỗ trợ (tài khoản cá nhân không được hỗ trợ).
* Thiết lập nhận tin nhắn trực tiếp ở chế độ **Mọi người** (Everyone) trên ứng dụng TikTok.
* Một **tài khoản TikTok Developer** đăng ký tại trang [developers.tiktok.com](https://developers.tiktok.com/).
* Quyền quản trị cao nhất (Super Admin) trên Portal của bạn để thiết lập Credentials.

<Warning>
  Kênh TikTok Business Messaging API bị giới hạn theo quốc gia. Hiện tại, tính năng này không hỗ trợ cho các tài khoản đăng ký ở khu vực Kinh tế Châu Âu (EEA), Thụy Sĩ hoặc Vương quốc Anh (UK).
</Warning>

## Bước 1: Đăng ký tài khoản TikTok Developer

Để bắt đầu, bạn cần có tài khoản nhà phát triển trên hệ thống của TikTok để khởi tạo và quản lý ứng dụng kết nối.

<Steps>
  <Step title="Đăng ký tài khoản nhà phát triển">
    Truy cập [developers.tiktok.com](https://developers.tiktok.com/) và tiến hành đăng ký tài khoản.
  </Step>

  <Step title="Xác minh tài khoản">
    Xác minh địa chỉ email và đồng ý với các Điều khoản Dịch vụ để hoàn tất đăng ký.
  </Step>
</Steps>

## Bước 2: Đăng ký ứng dụng mới

Việc đăng ký ứng dụng trên cổng nhà phát triển giúp bạn lấy được các khóa bảo mật quan trọng (App ID và App Secret) nhằm liên kết hệ thống một cách an toàn.

<Steps>
  <Step title="Tạo ứng dụng">
    Truy cập trang quản trị ứng dụng doanh nghiệp tại [business-api.tiktok.com/portal/apps](https://business-api.tiktok.com/portal/apps) và nhấn **Create App**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/Vk4pTtGaUIGyb8QP/images/tiktok-create-app.avif?fit=max&auto=format&n=Vk4pTtGaUIGyb8QP&q=85&s=b54313749b78f2f3383b3ea1044c79a5" alt="Tiktok Create App" width="810" height="1009" data-path="images/tiktok-create-app.avif" />
    </Frame>
  </Step>

  <Step title="Nhập thông tin ứng dụng">
    Điền các thông tin theo yêu cầu:

    * **App Name**: Tên ứng dụng của bạn (ví dụ: `Tên_Thương_Hiệu - ChatconnectX`).
    * **App Description**: Mô tả ngắn gọn mục đích sử dụng ứng dụng (ví dụ: hỗ trợ khách hàng và tự động hóa tin nhắn).
    * **App Icon**: Tải lên logo thương hiệu của bạn.
    * **Terms of Service URL**: Đường dẫn đến trang Điều khoản dịch vụ của bạn.
    * **Privacy Policy URL**: Đường dẫn đến trang Chính sách bảo mật của bạn.
  </Step>

  <Step title="Sao chép Credentials của ứng dụng">
    Sau khi ứng dụng được tạo thành công, hãy sao chép mã **App ID** (Client Key) và **App Secret** (Client Secret). Bạn sẽ cần các thông số này để điền vào Portal quản trị.
  </Step>
</Steps>

## Bước 3: Gửi yêu cầu cấp quyền Business Messaging API

TikTok yêu cầu bạn gửi hồ sơ xin cấp quyền sử dụng API gửi/nhận tin nhắn để đảm bảo an toàn dữ liệu người dùng.

<Steps>
  <Step title="Yêu cầu sản phẩm Business Messaging">
    Mở ứng dụng của bạn trên cổng TikTok Developer Portal, tìm sản phẩm **Business Messaging API** và nhấn kích hoạt.
  </Step>

  <Step title="Gửi hồ sơ đăng ký quyền truy cập">
    Điền biểu mẫu đăng ký bao gồm các nội dung:

    * Mô tả chi tiết kịch bản sử dụng (ví dụ: cung cấp dịch vụ CSKH tự động cho doanh nghiệp).
    * Giải trình cách hệ thống của bạn xử lý và lưu trữ dữ liệu của người dùng TikTok.
    * Cung cấp thông tin đăng ký doanh nghiệp/tổ chức của bạn.
  </Step>

  <Step title="Chờ phê duyệt">
    Đội ngũ kiểm duyệt của TikTok sẽ đánh giá hồ sơ của bạn (thường mất một vài ngày làm việc). Bạn chỉ có thể tiếp tục tích hợp sau khi quyền này được phê duyệt thành công.
  </Step>
</Steps>

## Bước 4: Cấu hình Credentials trên Portal quản trị

Sau khi có các thông số khóa bảo mật từ ứng dụng TikTok, bạn tiến hành lưu chúng trên Portal quản trị của mình.

<Steps>
  <Step title="Mở trang quản trị Platform Credentials">
    Đăng nhập vào Portal của bạn dưới quyền Super Admin, truy cập đường dẫn:

    ```text theme={null}
    https://app.chatconnectx.com/manage/platform-credentials
    ```
  </Step>

  <Step title="Mở cấu hình TikTok">
    Tìm thẻ cấu hình TikTok, nhấn nút **Edit** để mở biểu mẫu và điền mã **Client ID** (App ID) cùng với **App Secret**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/Vk4pTtGaUIGyb8QP/images/chatbotx_super_admin_tiktok_edit.png?fit=max&auto=format&n=Vk4pTtGaUIGyb8QP&q=85&s=20b7ce7c7e3b1c31598af790ba621dc9" alt="Chatbotx Super Admin Tikotk Edit" width="2102" height="1286" data-path="images/chatbotx_super_admin_tiktok_edit.png" />
    </Frame>
  </Step>

  <Step title="Lưu cấu hình">
    Nhấn **Save** để áp dụng. Hệ thống sẽ hiển thị một đường dẫn **Webhook URL**. Đường dẫn này sẽ được sử dụng cho Bước 5.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/Vk4pTtGaUIGyb8QP/images/chatbotx_super_admin_integrations_tiktok.png?fit=max&auto=format&n=Vk4pTtGaUIGyb8QP&q=85&s=43cef9c6b43492ff3663fae5ab06b590" alt="Tiktok Create App" width="1027" height="896" data-path="images/chatbotx_super_admin_integrations_tiktok.png" />
    </Frame>
  </Step>
</Steps>

## Bước 5: Cấu hình Quyền ứng dụng và đường dẫn Redirect URL

Sau khi được phê duyệt quyền API, bạn cần chỉ định quyền cụ thể cho tài khoản và cấu hình nơi TikTok chuyển hướng người dùng về sau khi họ hoàn tất đăng nhập (Redirect URL).

<Steps>
  <Step title="Bật quyền tài khoản">
    Hãy đảm bảo quyền **TikTok Accounts** (Phạm vi truy cập thông tin tài khoản) đã được bật trong cấu hình ứng dụng của bạn trên TikTok Developer Portal.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/Vk4pTtGaUIGyb8QP/images/tiktok-accounts-permission.avif?fit=max&auto=format&n=Vk4pTtGaUIGyb8QP&q=85&s=4cfcafa295101109e5c7f40ec352f0c2" alt="Tiktok Accounts Permission" width="990" height="887" data-path="images/tiktok-accounts-permission.avif" />
    </Frame>
  </Step>

  <Step title="Thêm đường dẫn Redirect URL">
    Nhập đường dẫn chuyển hướng sau:

    ```text theme={null}
    https://app.chatconnectx.com/integrations/tiktok/webhook
    ```
  </Step>
</Steps>

## Hướng dẫn kết nối cho người dùng

Sau khi hoàn tất cấu hình ứng dụng trên TikTok Developer Portal và nhập Credentials vào Portal quản trị, khách hàng của bạn có thể tự kết nối tài khoản TikTok Business của họ.

Xem chi tiết tại [Hướng dẫn kết nối TikTok](/vi/channels/tiktok/connect-tiktok).

## Xử lý sự cố thường gặp

<AccordionGroup>
  <Accordion title="Kênh TikTok không xuất hiện trên trang Dashboard">
    Kiểm tra xem bạn đã kích hoạt tính năng TikTok cho tài khoản của mình trong trang quản trị Super Admin chưa, đồng thời đảm bảo các biến môi trường cấu hình liên quan đã được lưu và máy chủ đã được khởi động lại.
  </Accordion>

  <Accordion title="Xác thực OAuth thất bại">
    Hãy kiểm tra lại đường dẫn Redirect URL trên TikTok Developer Portal xem đã khớp chính xác với tên miền của bạn (`https://app.chatconnectx.com/tiktok/callback`) chưa. Đồng thời đảm bảo sản phẩm Business Messaging API đã hiển thị trạng thái phê duyệt (Approved).
  </Accordion>

  <Accordion title="Không nhận được tin nhắn gửi đến">
    Thử chạy lệnh kiểm tra webhook trong Rails console của hệ thống để xác minh webhook đã đăng ký thành công. Đảm bảo máy chủ của bạn có thể tiếp nhận các yêu cầu HTTPS công khai từ internet và tài khoản TikTok Business của khách được đăng ký tại khu vực địa lý được hỗ trợ.
  </Accordion>

  <Accordion title="Không thể gửi phản hồi tin nhắn">
    Đảm bảo bạn đang phản hồi tin nhắn trong khung thời gian quy định 48 giờ của TikTok. Hãy kiểm tra xem kênh có yêu cầu kết nối lại (Reauthorize) do token truy cập hết hạn hay không.
  </Accordion>

  <Accordion title="Kênh yêu cầu kết nối lại (Reauthorization)">
    Token làm mới (Refresh token) sẽ hết hạn nếu tài khoản không hoạt động liên tục trong 30 ngày. Hãy truy cập **Settings: Inboxes**, chọn hộp thư TikTok của bạn, nhấn **Reauthorize** và hoàn tất lại quy trình đăng nhập OAuth để khôi phục kết nối.
  </Accordion>
</AccordionGroup>