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

# API TikTok

> Referência interna para integração do TikTok — retorno de chamada OAuth, processamento de eventos de webhook e roteamento DM.

> **Documentação interna para desenvolvedores.** Esta página aborda a integração da API do TikTok for Business: retorno de chamada OAuth, arquitetura de webhook e roteamento de eventos. Não se destina a usuários finais.

***

## Mapa de rotas

| Método     | Ponto final            | Arquivo manipulador        | Descrição                          |
| ---------- | ---------------------- | -------------------------- | ---------------------------------- |
| `GET`      | `/api/tiktok/callback` | `tiktok/callback/route.ts` | Retorno de chamada do TikTok OAuth |
| `GET/POST` | `/api/tiktok/route.ts` | `tiktok/route.ts`          | Registro/verificação de webhook    |
| `POST`     | `/api/tiktok/webhook`  | (via route.ts)             | Manipulador de eventos Webhook     |

***

## Fluxo OAuth do TikTok

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

**Escopos OAuth necessários:**

* `dm.conversation.readonly` — Leia mensagens diretas
* `dm.conversation.write` — Enviar mensagens diretas

***

## Arquitetura de webhook

O TikTok envia eventos de webhook para o endpoint registrado para eventos DM.

**Verificação do Webhook (resposta ao desafio):**

```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 });
```

**Processamento de eventos do Webhook (POST):**

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

***

## Carga útil do evento DM

```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!"
    }
  }
}
```

***

## Roteamento de conversa

DM recebido do TikTok → identificado por `sender_id` → criar ou continuar a conversa ZappWay com `channel: 'tiktok'` → encaminhar para o funcionário AI atribuído.

***

## Variáveis ​​de ambiente necessárias

| Variável                | Descrição                                 |
| ----------------------- | ----------------------------------------- |
| `TIKTOK_CLIENT_KEY`     | Chave do cliente do aplicativo TikTok     |
| `TIKTOK_CLIENT_SECRET`  | Segredo do cliente do aplicativo TikTok   |
| `TIKTOK_WEBHOOK_SECRET` | Para verificação de assinatura de webhook |

***

## Problemas conhecidos/pegadinhas

* **A API TikTok é estritamente interna** — atualmente não há interface de configuração voltada para o usuário. A conexão é feita pela equipe de desenvolvimento em nome dos clientes.
* **Atualização de token:** Os tokens de acesso do TikTok expiram. Uma tarefa em segundo plano deve atualizá-los antes da expiração usando `refresh_token`.
* **Disponibilidade de DM:** O acesso à API TikTok DM é restrito a contas comerciais aprovadas. O aplicativo deve estar na lista de permissões do TikTok.
* **Limites de taxas:** O TikTok impõe limites de taxas rigorosos por conta empresarial. Monitore as respostas `429`.