TikTok

TikTok Integration is a next-generation communication channel that connects direct messages (DMs) sent to your TikTok Business account to the Supsis AI omnichannel communication platform via the official TikTok Business Messaging API.

With this integration, businesses no longer need to constantly monitor the inbox on the TikTok mobile app. All customer messages are centralized into the same Supsis inbox alongside other channels (WhatsApp, Instagram, Telegram, Live Chat, Email, etc.). Inbound queries can be distributed across support agent pools, answered 24/7 automatically via Chatbot workflows, and included in comprehensive customer service analytics. When the channel is first connected, the past 90 days of conversation history are automatically synchronized to Supsis.

ℹ️ Scope Note: This guide specifically covers the Direct Messaging (DM) capabilities, connection prerequisites, the 48-hour messaging window, and message limits of the TikTok Integration. TikTok Comments/Mention management, TikTok Automatic Messages (Welcome Message / Suggested Questions / Chat Prompts), and TikTok Leads features are covered in separate documentation sections.

1- Overview of TikTok Integration

1.a – What is TikTok Integration and What is Its Purpose?

TikTok is a rapidly growing engagement and sales channel, especially for modern retail and service brands catering to dynamic audiences. However, the standard TikTok mobile app inbox is not designed as an enterprise customer service desk: * Chats cannot be routed or assigned to multiple agents, * There is no support for canned responses, Chatbot automations, or CRM contact profile sync, * First response times, resolution rates, and representative workloads cannot be tracked or audited, * Operations remain tied to a single mobile device or individual staff member.

Supsis TikTok Integration connects directly via official TikTok Business Messaging API and OAuth authorization, transforming TikTok DM communication into an enterprise-grade, multi-agent, and auditable omnichannel customer service pipeline.

1.b – Two-Way Operational Architecture and Message Flow

The integration operates seamlessly across two primary data streams:

1.c – Glossary of Terms

The core concepts appearing across integration interfaces, TikTok developer infrastructure, and documentation are outlined below:

2- 3 Critical Prerequisites Before Connecting

Before linking your TikTok channel to Supsis, verify that the following 3 technical and operational prerequisites are satisfied on TikTok. If any of these are missing, the integration cannot receive messages or complete setup.

2.a – Requirement 1: TikTok Account Must Be a "Business Account"

The TikTok Business Messaging API operates solely on Business Accounts. Personal and Creator accounts are strictly unsupported by TikTok's messaging API.

• How to Check and Switch to a Business Account:
• Open the TikTok mobile app and go to your Profile.
• Tap the Menu (☰) icon in the top right corner.
• Navigate to Settings and privacy → Account → Switch to Business Account.
• Select your business category and complete the setup.

⚠️ Important: If the account remains a personal account, API access will be rejected even if permissions are granted during OAuth.

2.b – Requirement 2: "Receive Direct Messages from Everyone" Must Be Enabled

The most common reason for "Connected successfully, but customer messages are not showing up in Supsis" is mobile privacy settings. According to TikTok privacy policies, if your DM inbox is restricted to followers or mutual friends, TikTok disables webhook event dispatching to third parties. For your business account to receive inbound messages from any user, you must complete four essential configurations inside the TikTok mobile app.

Step-by-Step Mobile Configuration

1. Accessing Settings and Privacy (General Screen):
2. Open the TikTok mobile app and go to your Profile.
3. Tap the Menu (☰) icon in the top right corner and choose Settings and privacy.
4. Under the Interactions section, locate and tap Direct messages.

1. Configuring Direct Messages Settings:
2. The Direct messages settings screen is the control hub for messaging permissions, read status, and safety preferences.
3. Verify Permission settings and Activity status from this screen.
4. Ensure that Safe mode is turned Off. When safe mode is enabled, inbound inquiries from unrecognized users might get diverted to filtered message requests rather than reaching the main inbox immediately.

1. Setting Activity Status to Public:
2. In the Direct messages menu, tap Activity status.
3. Select Public as your visibility option.
4. This ensures your active business availability is broadcasted across the TikTok messaging network, allowing seamless session handoff to live agents and bots.

1. Permission Settings - Receiving Inbound Messages from Everyone:
2. In the Direct messages menu, tap Permission settings.
3. Configure both options under Who can send you messages to Inbox:
   • Potential connections → Inbox
   • Others on TikTok → Inbox
4. This guarantees that anyone on TikTok—even non-followers and first-time visitors—can initiate a conversation that routes straight into your inbox and triggers an immediate webhook to Supsis.

Summary of Required Mobile Settings

🛑 Critical Verification: If either "Others on TikTok" or "Potential connections" is restricted ("Friends" or "No one"), TikTok will drop inbound webhook dispatches. To eliminate silent message delivery issues, always ensure all four settings match the screenshots above.

2.c – Requirement 3: Regional Availability & Supported Countries

TikTok enables the Business Messaging API infrastructure in designated global markets based on regional data regulations and policy guidelines. For the integration to deliver and receive messages seamlessly, your TikTok Business account must be registered in one of the supported service countries.

Complete List of Supported Service Countries

2.d – Package and Channel Quota Requirements

TikTok Integration operates under an active channel subscription: * You can connect up to the channel limit defined under Billing → Plans → TikTok (x / y channels). * If your quota is reached, upgrade your plan to connect additional accounts. * Permissions such as "Manage Inbox", "Manage with Chatbot", and "Comment to Message" are activated according to your plan tier.

3- Steps to Connect a TikTok Channel to Supsis

3.a – Accessing the Integrations Menu

1. Log in to your Supsis Customer Panel.
2. Click Integrations on the left main navigation menu.
3. Under the Social Media category, locate and click the TikTok Integration card.

3.b – Adding a Channel and Agreeing to Terms

1. On the TikTok Channels page, click the + Add Channel button in the top right.
2. A modal displays the 3 prerequisites and official policy notices.
3. Review the TikTok Terms of Service, TikTok Privacy Policy, and Supsis user agreement, then check the confirmation box.
4. Click the now-active Connect to TikTok button.

3.c – Granting Official TikTok OAuth Permissions

Log in on the secure TikTok OAuth pop-up window. TikTok displays the 3 scopes requested by Supsis:

• message.list.read — View conversations and inbound message history.
• message.list.send — Send responses to customers via Supsis.
• message.list.manage — Manage conversation states, read markers, and configuration.

Click Authorize. The pop-up closes automatically, returning you to the Supsis setup wizard.

3.d – Saving and Configuring the Channel

1. The modal confirms the authenticated account username and avatar.
2. Click Create Channel to finalize.
3. The new channel appears in your list. Click it to customize settings:

• Channel Name: Assign an internal display label (e.g., TikTok Global Support).
• Routing Mode: Choose whether incoming DMs route directly to live agents or to a Chatbot.
• Visibility Tab: Specify which departments or agents have access to view and answer chats from this channel.

4- TikTok Conversations in the Chat Interface

4.a – Contact Profile and Channel Badges

Every new inbound message automatically generates or matches a Supsis contact profile: * The conversation displays a black TikTok icon in the inbox list. * The customer's TikTok username (@username), profile picture, and channel source are displayed in the Contact Card. * If the user previously messaged from WhatsApp or Web Chat, profiles can be merged into a single omnichannel contact.

4.b – Rule: Businesses Cannot Initiate First Messages

Under TikTok platform policy, conversations must always be initiated by the end user: * Businesses cannot send cold outbound or unsolicited marketing broadcasts to TikTok users. * A live agent cannot open a new chat window to an arbitrary TikTok username from the panel. * If attempted, the system blocks the message and alerts:
"Business cannot initiate conversation; user must write first."

4.c – Echo Messages (Mobile App Sync)

If a team member replies to a customer directly from the TikTok mobile application: * Supsis captures the outbound message via webhook (Echo Message). * The message is recorded in the Supsis conversation thread, preserving historical continuity. * Important: Messages sent from the mobile app are also counted against the 48-hour messaging limit counter.

4.d – Ad Attribution Tracking (TikTok Ads)

When a customer messages via a TikTok Ad (Spark Ads, Lead Generation, or DM objective ads): * Supsis extracts the associated ad metadata (Ad ID, Campaign ID). * Attribution tags are attached to the contact card and chat session. * Marketing teams can directly analyze which creative drove inquiries and customer acquisition.

5- 48-Hour Messaging Window and Limits

TikTok enforces a strict messaging window and counter to prevent spam. Supsis proactively validates these limits prior to API dispatch, preventing rejected deliveries and informing agents in real time.

5.a – Mechanics of the 48-Hour Rule

5.b – 10-Message Cap and 11th Message Warning

If a business sends successive messages without receiving a reply: 1. Messages 1 through 10 are delivered normally. 2. After 10 outbound messages, the quota is temporarily locked until the user responds. 3. Attempting an 11th message marks it as Failed in the chat interface. 4. An alert banner appears across the chat header:
"TikTok 48-hour messaging window is closed. You can only send limited messages; awaiting customer reply."

6- Supported and Unsupported Message Types

6.a – Comparative Message Types Matrix

6.b – Agent Alerts for Unsupported Media

When an agent attempts to send an unsupported attachment format (video, voice note, PDF, or location) to a TikTok customer: * Dispatch is blocked proactively. * The system displays an error dialog:
"Only text, images, and button cards can be sent via TikTok. Video and document formats are not supported."

7- Historical Message Synchronization

Upon initial connection of a TikTok channel, an automated background synchronization job imports past interactions without interrupting panel operations.

• Import Boundaries (TikTok API Constraints):
• Time Range: Past 90 days of conversations.
• Conversation Count: Up to 100 conversations.
• Message Depth: Up to the most recent 20 messages per conversation.
• Rate Limiting Protection: Sync operates at a controlled throttle of 1 request per second (1 req/sec) to safeguard API integrity.
• Deduplication: Messages received simultaneously via webhook and historical import are deduplicated automatically.

8- Managing TikTok Channels with Chatbots

TikTok channels integrate natively with the Supsis Chatbot engine for 24/7 automated resolution and intelligent routing.

8.a – Routing Modes

• Live Agents Only: Inbound messages queue directly to human agents.
• Chatbot Only: Chatbot handles conversations autonomously, escalating to agents when needed.
• Hybrid Mode: Live support during business operating hours; automated Chatbot during off-hours.

8.b – Chatbot Block Adaptations for TikTok

Due to TikTok messaging constraints, standard web chatbot blocks are adapted automatically:

• Button Blocks: Converted into QA Button Cards (max 3 buttons per card; blocks with more buttons split into successive cards).
• Carousel / Gallery Blocks: Converted into sequential image messages followed by button cards.
• Location Request Blocks: Converted into plain guidance text.
• Suggested Questions: Pre-configured starter buttons can be set up in the channel's "Suggested Questions" tab.

9- Connection Health, Security & Token Lifecycle

• Token Lifecycle:
• TikTok Access Tokens are valid for 1 day.
• TikTok Refresh Tokens remain valid for ~1 year.
• Supsis runs hourly background routines to automatically renew any tokens expiring in less than 2 hours, requiring zero manual action.
• Revocation and Invalidation:
• If permissions are revoked via the TikTok mobile app or Business Suite, token renewal will fail.
• The channel enters a Token-Invalid state. Reconnect with one click from the channel settings.
• Data Retention on Channel Deletion:
• Removing a TikTok channel from Supsis retains all past conversations and customer records. Only live messaging and webhooks are terminated.

10- Business Use Cases and Value

11- Troubleshooting Guide

11.a – "Channel is connected, but inbound TikTok messages do not appear in Supsis"

1. Check "Direct Messages from Everyone": In TikTok app, verify Settings and privacy → Privacy → Direct messages is set to Everyone.
2. Verify Account Tier: Ensure the account is a Business Account (Personal/Creator accounts cannot dispatch webhooks).
3. Verify Geographical Location: Ensure the account is registered in a supported market (Turkey, Middle East, Africa, or Pakistan), and not registered in an excluded region (EEA, UK, Switzerland, USA).

11.b – "Cannot send messages; messaging window is closed"

• More than 48 hours have passed since the customer's last message, or your 3 follow-up message quota is exhausted. Await the customer's next message to reopen the window. You can continue sending messages via the TikTok mobile app. These limitations only apply to messages sent through the Supsis panel.

11.c – "Cannot send videos or PDF documents"

• TikTok Business Messaging API forbids outbound videos, audio files, and documents from businesses. Send clear images (JPG/PNG) or structured link cards instead.

11.d – "Channel status shows Token Invalid"

• Password changes or security resets on TikTok invalidate active tokens. Open Integrations → TikTok Channels → Channel Details and click Reconnect to re-authorize.