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

# TikTok API

> Internal reference for the TikTok integration — OAuth callback, webhook event processing, and DM routing.

> **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

```
1. User clicks "Connect TikTok" in Integrations settings
2. Redirect to TikTok OAuth authorization URL
3. User grants permissions (DM access)
4. TikTok redirects to GET /api/tiktok/callback?code=...&state=...
5. Server exchanges code for access token
6. Token stored encrypted in DB
7. 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):**

```ts theme={null}
// 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):**

```ts theme={null}
// POST /api/tiktok
// Body: TikTok DM event payload
// Route to conversation engine → AI responds
```

***

## DM Event Payload

```json theme={null}
{
  "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.