TikTok API

Internal documentation for developers. This page covers the TikTok for Business API integration: OAuth callback, webhook architecture, and event routing. Not intended for end users.

Route Map

Method	Endpoint	Handler File	Description
`GET`	`/api/tiktok/callback`	`tiktok/callback/route.ts`	TikTok OAuth callback
`GET/POST`	`/api/tiktok/route.ts`	`tiktok/route.ts`	Webhook registration/verification
`POST`	`/api/tiktok/webhook`	(via route.ts)	Webhook event handler

TikTok OAuth Flow

User clicks "Connect TikTok" in Integrations settings
Redirect to TikTok OAuth authorization URL
User grants permissions (DM access)
TikTok redirects to GET /api/tiktok/callback?code=...&state=...
Server exchanges code for access token
Token stored encrypted in DB
Redirect to dashboard with success message

OAuth scopes required:

dm.conversation.readonly — Read DMs
dm.conversation.write — Send DMs

Webhook Architecture

TikTok sends webhook events to the registered endpoint for DM events. Webhook verification (challenge-response):

// GET /api/tiktok (webhook registration)
// TikTok sends: ?challenge=xxx
// Server must respond with the same challenge value
const challenge = url.searchParams.get('challenge');
return new Response(challenge, { status: 200 });

Webhook event processing (POST):

// POST /api/tiktok
// Body: TikTok DM event payload
// Route to conversation engine → AI responds

DM Event Payload

{
  "event": "direct_message",
  "timestamp": 1705312800,
  "data": {
    "conversation_id": "tiktok_conv_abc",
    "sender_id": "tiktok_user_xyz",
    "message": {
      "id": "msg_abc",
      "type": "text",
      "content": "Hi, I saw your product!"
    }
  }
}

Conversation Routing

Incoming TikTok DM → identified by sender_id → create or continue ZappWay conversation with channel: 'tiktok' → route to assigned AI Employee.

Environment Variables Required

Variable	Description
`TIKTOK_CLIENT_KEY`	TikTok app client key
`TIKTOK_CLIENT_SECRET`	TikTok app client secret
`TIKTOK_WEBHOOK_SECRET`	For webhook signature verification

Known Issues / Gotchas

TikTok API is strictly internal — no user-facing setup UI currently. Connection is done by dev team on behalf of customers.
Token refresh: TikTok access tokens expire. A background job must refresh them before expiry using the refresh_token.
DM availability: TikTok DM API access is restricted to approved business accounts. The app must be whitelisted by TikTok.
Rate limits: TikTok imposes strict rate limits per business account. Monitor for 429 responses.

API Internals

Infrastructure

Route Map

TikTok OAuth Flow

Webhook Architecture

DM Event Payload

Conversation Routing

Environment Variables Required

Known Issues / Gotchas

​Route Map

​TikTok OAuth Flow

​Webhook Architecture

​DM Event Payload

​Conversation Routing

​Environment Variables Required

​Known Issues / Gotchas

Route Map

TikTok OAuth Flow

Webhook Architecture

DM Event Payload

Conversation Routing

Environment Variables Required

Known Issues / Gotchas