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

# Connect TikTok Business Messaging API to ChatbotX

> 6-step guide to integrate TikTok Business Messaging with ChatbotX — register a developer app, apply for API access, configure credentials, and authorize.

Connecting your TikTok Business account to ChatbotX allows you to manage customer chat conversations directly from your workspace. Your support agents can receive and reply to TikTok messages, view shared videos, and handle incoming images — all from a single, unified inbox alongside your other messaging channels.

## Prerequisites

Before starting the setup, ensure you have:

* A self-hosted ChatbotX instance accessible via a public HTTPS URL
* 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 (otherwise, you will need to manually accept new message requests)
* A **TikTok Developer Account** created at [developers.tiktok.com](https://developers.tiktok.com/)
* Super Admin access to your ChatbotX instance

<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. This account lets you manage and configure the messaging link between TikTok and ChatbotX.

<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 ChatbotX 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**.
  </Step>

  <Step title="Fill in app details">
    Provide the required details:

    * **App Name** — for example, `Your Company - ChatbotX`
    * **App Description** — explain your messaging and support use case
    * **App Icon** — upload your company logo
    * **Terms of Service URL** — your company's Terms of Service 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 ChatbotX.
  </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 (for example, 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.

    <Note>
      You will receive an email notification when your Business Messaging API access is approved. Keep an eye on the inbox associated with your TikTok Developer Account.
    </Note>
  </Step>
</Steps>

***

## Step 4: Configure ChatbotX Credentials

With your TikTok credentials generated, save these settings in ChatbotX to link the integration.

<Steps>
  <Step title="Open the Super Admin Panel">
    Log in to ChatbotX as a Super Admin, then navigate to:

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

  <Step title="Open the TikTok configuration">
    Find the **TikTok** card and click the **Edit** button to open the configuration modal.
  </Step>

  <Step title="Enter your credentials">
    In the configuration modal, enter your **Client ID** (App ID) and **App Secret** (Client Secret) from Step 2.
  </Step>

  <Step title="Save">
    Click **Save**. TikTok will now be available as a channel when creating chatbots.

    After saving, ChatbotX will display a **Webhook URL**. Copy this URL — you will use it in Step 5.
  </Step>
</Steps>

***

## Step 5: Configure App Permissions and Redirect URLs

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

<Steps>
  <Step title="Enable permissions">
    In your TikTok Developer Portal app settings, ensure the **TikTok Accounts** permission scope is enabled.
  </Step>

  <Step title="Add redirect URL">
    Set the Redirect URL to your ChatbotX webhook endpoint:

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

***

## Step 6: Connect Your TikTok Account

With the technical setup finished, you can now link your actual TikTok Business account to ChatbotX.

<Steps>
  <Step title="Open Channels Settings">
    In your ChatbotX dashboard, go to **Settings → Channels**, expand the **TikTok** section, and click **+ Add TikTok**.
  </Step>

  <Step title="Authorize ChatbotX on TikTok">
    On the TikTok authorization screen, review the requested permissions and click **Continue** to authorize the integration.
  </Step>

  <Step title="Verify connection in ChatbotX">
    After authorization succeeds, you will be redirected back to the ChatbotX dashboard. Confirm that the TikTok channel appears on the dashboard, and click **Test Now** to verify the connection is working.
  </Step>
</Steps>

***

## 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 that your App ID and App Secret credentials have been saved correctly. If you are on a self-hosted installation, confirm the server has been restarted after saving the credentials.
  </Accordion>

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

  <Accordion title="Not receiving incoming messages">
    Verify that the webhook URL configured in your TikTok Developer Portal points to your ChatbotX instance and that your server is accessible via public HTTPS. Also confirm that your TikTok Business Account is registered in a supported region (not EEA, Switzerland, or the UK).
  </Accordion>

  <Accordion title="Messages failing to send">
    Ensure you are replying within the standard **48-hour** messaging 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 → Channels**, select your TikTok channel, click **Reauthorize**, and complete the OAuth flow again to restore the connection.
  </Accordion>
</AccordionGroup>