HH/apps/social/setup_docs/tik_tok.md

TikTok Business API Setup Guide

This guide provides step-by-step instructions for setting up TikTok Business API integration for managing ad comments.

---

Table of Contents

1. Overview
2. Prerequisites
3. TikTok Business Center Setup
4. Environment Configuration
5. OAuth Redirect URI Configuration
6. Permissions & Scopes
7. Development vs Production
8. Troubleshooting

---

Overview

API Version: Business API v1.3 Base URL: https://business-api.tiktok.com/open_api/v1.3/ Auth Portal: https://business-api.tiktok.com/portal/auth Token Endpoint: oauth2/access_token/

Features Supported

• Fetch advertisements (which act as "content")
• Read comments on advertisements
• Reply to ad comments

⚠️ Critical Limitations

Important: This implementation only supports Ad Comments (Paid Ads). TikTok's API does NOT support organic video comment management. You cannot:

• Fetch comments on regular TikTok videos
• Reply to organic video comments
• Manage comments on non-ad content

This is a TikTok API limitation, not an application limitation.

---

Prerequisites

• A TikTok account with access to TikTok Business Center
• Admin or Analyst access to a TikTok Ad Account
• An approved TikTok App in Business Center

---

TikTok Business Center Setup

Step 1: Access TikTok Business Center

1. Navigate to TikTok Business Center
2. Sign in with your TikTok account
3. If you don't have a Business Center, create one

⚠️ Note: This is NOT the same as the "TikTok for Developers" portal used for the Display API. You must use the Business Center.

Step 2: Create or Access Your App

1. Go to User Center (top right) → App Management → My Apps
2. If you don't have an app, click "Create App"
3. Fill in the required details:
   • App Name: Your application name
   • App Description: Describe your use case
   • Category: Select "Business Tools" or similar
4. Submit for approval

Step 3: Get App Credentials

Once your app is created/approved:

1. Go to User Center → App Management → My Apps
2. Select your app
3. Find the credentials:
   • App ID → This is your TIKTOK_CLIENT_KEY
   • App Secret → Click "View" to reveal → This is your TIKTOK_CLIENT_SECRET

⚠️ Important: Store these credentials securely. The App Secret is only shown once.

---

Environment Configuration

Django Settings (settings.py)

# TikTok Business API Configuration
TIKTOK_CLIENT_KEY = 'your_app_id_here'
TIKTOK_CLIENT_SECRET = 'your_app_secret_here'
TIKTOK_REDIRECT_URI = 'https://yourdomain.com/social/callback/TT/'

Environment Variables (.env)

TIKTOK_CLIENT_KEY=your_app_id_here
TIKTOK_CLIENT_SECRET=your_app_secret_here
TIKTOK_REDIRECT_URI=https://yourdomain.com/social/callback/TT/

---

OAuth Redirect URI Configuration

Step 1: Configure Redirect URI in TikTok App

1. In your app settings, go to App Settings → Login Kit / Redirect URI settings
2. Add your callback URL:

Development:

http://127.0.0.1:8000/social/callback/TT/
http://localhost:8000/social/callback/TT/

⚠️ Note: TikTok often rejects localhost URLs. Use ngrok for local testing (see below).

Production:

https://yourdomain.com/social/callback/TT/

Using ngrok for Local Development

TikTok may reject HTTP/localhost redirect URIs. Use ngrok:

# Install ngrok
npm install -g ngrok

# Create tunnel
ngrok http 8000

# Use the ngrok URL as your redirect URI
# Example: https://abc123.ngrok.io/social/callback/TT/

# Update settings.py
TIKTOK_REDIRECT_URI = 'https://abc123.ngrok.io/social/callback/TT/'

---

Permissions & Scopes

The application requests the following OAuth scopes:

Scope	Description	Required
user.info.basic	Basic user information	✅ Yes
ad.read	Read advertisement data	✅ Yes
comment.manage	Manage ad comments	✅ Yes

Code Reference

# apps/social/utils/tiktok.py
class TikTokConstants:
    BASE_URL = "https://business-api.tiktok.com/open_api/v1.3/"
    
    SCOPES = "user.info.basic,ad.read,comment.manage"
    
    ENDPOINTS = {
        "AUTH": "https://business-api.tiktok.com/portal/auth",
        "TOKEN": "oauth2/access_token/",
        "USER_INFO": "user/info/",
        "AD_LIST": "ad/get/",
        "COMMENT_LIST": "comment/list/",
        "COMMENT_REPLY": "comment/reply/",
    }

Requesting Permissions

1. In TikTok Business Center, go to App Management → Permissions
2. Request permission for:
   • Ads Management (for ad.read)
   • Comments Management (for comment.manage)
3. Submit a use case explaining:

   "We are building a Social Media Management Tool for managing ad comments. This allows advertisers to respond to user engagement on their TikTok advertisements from a centralized dashboard."

⚠️ Note: TikTok may reject generic requests. Be specific about your use case.

---

Ad Account Access Requirements

User Permissions

When connecting via OAuth, the authenticating user must have proper access to the Ad Account:

Role	Can Sync Ads	Can Reply to Comments
Admin	✅ Yes	✅ Yes
Analyst	✅ Yes	❌ No (read-only)
Operator	✅ Yes	✅ Yes

Granting Access

1. In TikTok Business Center, go to Ad Accounts
2. Select your ad account
3. Go to User Permissions
4. Add users with appropriate roles

---

Development vs Production

Development Setup

Setting	Value
TIKTOK_REDIRECT_URI	https://xxx.ngrok.io/social/callback/TT/ (via ngrok)
Protocol	HTTPS recommended (ngrok)
App Status	Sandbox/Testing mode

Production Setup

Setting	Value
TIKTOK_REDIRECT_URI	https://yourdomain.com/social/callback/TT/
Protocol	HTTPS required
App Status	Approved/Production mode

---

Troubleshooting

Common Error: "Invalid Redirect URI"

Cause: The redirect URI doesn't match TikTok's configuration.

Solution:

1. Verify exact URL in TikTok Business Center → App Settings → Redirect URI
2. Ensure HTTPS is used (or ngrok URL)
3. Check for trailing slashes
4. Wait a few minutes for changes to propagate

---

Common Error: "Permission Denied for Ad Account"

Cause: User doesn't have access to the ad account.

Solution:

1. Verify user has Admin, Operator, or Analyst role
2. Check ad account permissions in Business Center
3. Ensure correct ad account is selected during OAuth flow

---

Common Error: "Scope Not Authorized"

Cause: App hasn't been approved for requested permissions.

Solution:

1. Go to App Management → Permissions
2. Request required permissions with detailed use case
3. Wait for TikTok approval (can take several days)

---

Common Error: "No Ads Found"

Cause: No active ads in the ad account, or ads don't have comments.

Solution:

1. Verify ads exist and are active in TikTok Ads Manager
2. Ensure ads have received comments
3. Check that ad account is properly linked

---

Common Error: "API Rate Limit Exceeded"

Cause: Too many API requests.

Solution:

• TikTok Business API has rate limits (varies by endpoint)
• Implement exponential backoff
• Wait for limit to reset

---

Common Error: "Cannot Reply to Comment"

Cause: User has Analyst role (read-only) or comment is deleted.

Solution:

1. Ensure user has Admin or Operator role
2. Verify the comment still exists
3. Check that the ad is still active

---

API Rate Limits

Endpoint	Rate Limit
Ad List	10 requests/second
Comment List	10 requests/second
Comment Reply	10 requests/second

The application implements rate limiting to stay within these bounds.

---

API Endpoints Used

Endpoint	Purpose
oauth2/access_token/	Exchange auth code for access token
user/info/	Get authenticated user information
ad/get/	Fetch advertisements for an advertiser
comment/list/	List comments on an advertisement
comment/reply/	Reply to a comment

---

Verification

After setup, verify the integration:

1. Navigate to /social/ in your application
2. Click "Connect TikTok"
3. Authorize with TikTok Business account
4. Select your advertiser account
5. Verify ads are fetched
6. Check if comments on ads are loaded
7. Test replying to an ad comment

Testing in Django Shell

from apps.social.services.tiktok import TikTokService
from apps.social.models import SocialAccount

account = SocialAccount.objects.filter(platform='TT').first()

# Test getting ads
ads = TikTokService.fetch_ads(account)
print(f"Found {len(ads)} ads")

# Test getting comments
if ads:
    comments = TikTokService.fetch_comments(account, ads[0]['ad_id'])
    print(f"Found {len(comments)} comments")

---

Important Notes

1. Organic Content Not Supported: TikTok's Business API only supports ad management. You cannot manage comments on organic (non-ad) videos.

2. Advertiser ID Required: You need a valid TikTok Advertiser ID with active ads to use this integration.

3. App Approval: TikTok may take several days to approve your app and permission requests.

4. HTTPS Required: Production redirect URIs must use HTTPS.

5. Regional Availability: TikTok Business API may not be available in all regions.

---

Support Resources

• TikTok Business API Documentation
• TikTok Business Center
• TikTok Marketing API Forum
• TikTok Ads Manager

---

Last Updated: February 2026 API Version: TikTok Business API v1.3