API TikTok

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

​

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

• dm.conversation.readonly — Leia mensagens diretas
• dm.conversation.write — Enviar mensagens diretas

​

Arquitetura de webhook

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

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

​

Carga útil do evento DM

{
  "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

​

Variáveis ​​de ambiente necessárias

​

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.