Skip to main content
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.

​
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.
  • Super Admin access to your ChatbotX instance.
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.

​
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.
1

Register as a developer

Go to developers.tiktok.com and sign up.
2

Verify account

Verify your email address and accept the Terms of Service to complete the registration.

​
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.
1

Create a new app

Navigate to business-api.tiktok.com/portal/apps and click Create App.
Tiktok Create App
2

Fill in app details

Provide the required details:
  • App Name: e.g., 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 ToS page.
  • Privacy Policy URL: Your company’s privacy policy page.
3

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

Request Business Messaging product

Open your app in the TikTok Developer Portal and find the Business Messaging API product.
2

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

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 4: Configure ChatbotX Credentials

With your TikTok credentials generated and Webhooks configured in Meta, save these settings in ChatbotX to link the integration.
1

Configure via Super Admin Panel

Log in to ChatbotX as a Super Admin, then navigate to:
https://app.yourdomain.com/manage/platform-credentials
Enter your TikTok App ID and TikTok App Secret
2

Open the TikTok configuration

Click the Edit button on the TikTok card to open the configuration modal. Enter your Client ID and App Secret
Chatbotx Super Admin Tikotk Edit
3

Click Save. TikTok will now be available as a channel when creating chatbots.

After saving, ChatbotX will display a Webhook URL. Use it in Step 5.
Tiktok Create App

​
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).
1

Enable permissions

Ensure the TikTok Accounts permission scope is enabled in your app settings.
Tiktok Accounts Permission
2

Add redirect URL

Set the Redirect URL to:
https://app.yourdomain.com/integrations/tiktok/webhook

​
Step 6: Connect Your TikTok Account

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

Open Channels Settings

In your ChatbotX dashboard, go to Settings -> Channels, expand the TikTok section, and click + Add TikTok.
Tiktok Channel Setup
2

Authorize ChatbotX on TikTok

On the TikTok authorization screen, review the requested permissions and click Tiếp tục (Continue) to authorize the integration.
Tiktok Authorize Popup
3

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 page, and click Test Now to verify.
Tiktok Connected Dashboard

​
Troubleshooting

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.
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.
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.
Ensure you are replying within the standard 48-hour window. Verify the channel is not requesting reauthorization due to expired access tokens.
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.