> ## 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.

# Configure TikTok

> Learn how to register a TikTok Developer app, apply for Business Messaging API access, and configure credentials on your portal.

Connecting the TikTok Business Messaging channel to your portal allows your customers to manage customer chat conversations, receive, and reply to direct messages right from the unified Inbox.

## Prerequisites

Before starting the setup, ensure you have:

* A portal configured with a custom domain, running HTTPS protocol, and publicly accessible.
* A **TikTok Business Account** registered in a supported region (personal TikTok accounts are not supported).
* Direct messages set to **Everyone** in your TikTok app settings.
* A **TikTok Developer Account** created at [developers.tiktok.com](https://developers.tiktok.com/).
* Super Admin access to your portal to set up Credentials.

<Warning>
  The TikTok Business Messaging API is region-restricted. It is currently unavailable for accounts registered in the European Economic Area (EEA), Switzerland, or the United Kingdom.
</Warning>

## Step 1: Create a TikTok Developer Account

To get started, you must register a developer account on TikTok to create and manage the connection app.

<Steps>
  <Step title="Register as a developer">
    Go to [developers.tiktok.com](https://developers.tiktok.com/) and sign up.
  </Step>

  <Step title="Verify account">
    Verify your email address and accept the Terms of Service to complete the registration.
  </Step>
</Steps>

## Step 2: Register Your App

Registering your application in the developer portal provides you with the key credentials (App ID and App Secret) needed to securely link the portal to TikTok.

<Steps>
  <Step title="Create a new app">
    Navigate to [business-api.tiktok.com/portal/apps](https://business-api.tiktok.com/portal/apps) and click **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="Fill in app details">
    Provide the required details:

    * **App Name**: e.g., `Your Brand - ChatconnectX`
    * **App Description**: Explain your messaging and support use case.
    * **App Icon**: Upload your company logo.
    * **Terms of Service URL**: Your company's ToS page.
    * **Privacy Policy URL**: Your company's privacy policy page.
  </Step>

  <Step title="Copy App credentials">
    Once the app is created, copy the **App ID** (Client Key) and **App Secret** (Client Secret). You will need these to configure the Admin Portal.
  </Step>
</Steps>

## Step 3: Apply for Business Messaging API Access

TikTok requires you to request access to the messaging endpoints. This is a security review step to ensure data is handled safely.

<Steps>
  <Step title="Request Business Messaging product">
    Open your app in the TikTok Developer Portal and find the **Business Messaging API** product.
  </Step>

  <Step title="Submit the access application">
    Fill out the application form with:

    * Your use case (e.g., providing automated customer support).
    * Details on how you handle user data.
    * Your business/organization details.
  </Step>

  <Step title="Wait for review">
    TikTok reviews the request, which typically takes a few business days. You cannot proceed with the integration until this is approved.
  </Step>
</Steps>

## Step 4: Configure Credentials in the Admin Portal

After obtaining the security credentials from TikTok, save these settings in the Admin Portal.

<Steps>
  <Step title="Navigate to Platform Credentials">
    Log in to your portal as a Super Admin, then navigate to:

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

  <Step title="Open the TikTok configuration">
    Click the **Edit** button on the TikTok card to open the configuration modal and fill in your **Client ID** (App ID) and **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="Save">
    Click **Save**. The system will display a **Webhook URL** which will be used in Step 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>

## Step 5: Configure App Permissions and Redirect URLs

Once approved, you need to enable the specific account permissions and configure where TikTok redirects users after they log in (Redirect URL).

<Steps>
  <Step title="Enable permissions">
    Ensure the **TikTok Accounts** permission scope is enabled in your app settings.

    <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="Add redirect URL">
    Set the Redirect URL to:

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

## User Connection Guide

After completing the app configuration on the TikTok Developer Portal and entering the Credentials in the Admin Portal, your customers can connect their TikTok Business accounts.

For step-by-step instructions, see the [TikTok Connection Guide](/channels/tiktok/connect-tiktok).

## Troubleshooting

<AccordionGroup>
  <Accordion title="TikTok Channel not appearing in dashboard">
    Verify that you have enabled the TikTok feature for your account in the Super Admin panel, and confirm that the environment variables are saved and the server has been restarted.
  </Accordion>

  <Accordion title="OAuth authorization fails">
    Check that the authorization redirect URL in your TikTok Developer Portal exactly matches your domain (`https://app.chatconnectx.com/tiktok/callback`). Ensure that the Business Messaging API product is marked as approved.
  </Accordion>

  <Accordion title="Not receiving incoming messages">
    Run `Tiktok::AuthClient.webhook_callback` in the Rails console to verify that the webhook is registered. Check that your server can receive public HTTPS requests and that your business account is registered in a supported region.
  </Accordion>

  <Accordion title="Messages failing to send">
    Ensure you are replying within the standard 48-hour window. Verify the channel is not requesting reauthorization due to expired access tokens.
  </Accordion>

  <Accordion title="Channel requires Reauthorization">
    Refresh tokens expire after 30 days of inactivity. Go to **Settings: Inboxes**, select your TikTok inbox, click **Reauthorize**, and complete the OAuth flow again to restore the connection.
  </Accordion>
</AccordionGroup>