> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airys.chat/llms.txt
> Use this file to discover all available pages before exploring further.
# Configurando o Canal do TikTok
> Configure a integração do TikTok Business Messaging para gerenciar as conversas do TikTok pelo AirysChat
A integração do canal TikTok permite que você gerencie as conversas do TikTok Business Messaging diretamente do AirysChat. Os agentes podem receber e responder mensagens de usuários do TikTok, visualizar postagens compartilhadas e lidar com anexos de imagem - tudo no painel do AirysChat.
Configurar o canal do TikTok envolve 7 etapas.
1. Crie uma conta de desenvolvedor do TikTok.
2. Registre um aplicativo no Portal do Desenvolvedor do TikTok.
3. Solicite acesso à API do Business Messaging.
4. Configure as permissões do aplicativo e as URLs de redirecionamento.
5. Configure o AirysChat com o `App ID` e o `App Secret` obtidos do TikTok.
6. Configure o webhook para mensagens recebidas.
7. Conecte uma conta do TikTok Business a partir do painel do AirysChat.
## Pré-requisitos
1. Uma instância auto-hospedada do AirysChat acessível por meio de uma URL HTTPS pública
2. Uma **Conta do TikTok Business** registrada em uma região qualificada
3. Sua conta do TikTok Business deve estar configurada para **aceitar mensagens diretas de todos**. Caso contrário, você precisará aceitar mensagens manualmente no aplicativo TikTok. [Saiba como atualizar suas configurações de mensagens](https://ads.tiktok.com/help/article/how-to-update-your-tiktok-direct-message-permission-for-tiktok-messaging-ads?lang=en).
4. Uma **Conta de Desenvolvedor do TikTok** em [developers.tiktok.com](https://developers.tiktok.com)
5. Acesso à [API do TikTok Business Messaging](https://business-api.tiktok.com/portal/docs?id=1832183871604753) (requer permissões especiais e aprovação)
6. Acesso de Super Admin à sua instância do AirysChat
A API do TikTok Business Messaging tem **restrição de região**. Atualmente, ela não está disponível para contas registradas na **Área Econômica Europeia (AEE), Suíça ou Reino Unido**. Contas pessoais do TikTok não são suportadas - apenas contas do TikTok Business podem usar essa integração.
## Passo 1: Crie uma Conta de Desenvolvedor do TikTok
1. Acesse [developers.tiktok.com](https://developers.tiktok.com) e cadastre-se
2. Verifique seu endereço de e-mail
3. Aceite os Termos de Serviço
## Passo 2: Registre seu Aplicativo
1. Acesse [business-api.tiktok.com/portal/apps](https://business-api.tiktok.com/portal/apps) e crie um novo aplicativo
2. Preencha os campos obrigatórios:
* **App Name**: ex., "Sua Empresa - AirysChat"
* **App Description**: Breve descrição do seu caso de uso de mensagens
* **App Icon**: Envie o logotipo da sua empresa
* **Terms of Service URL**: A URL dos Termos de Serviço da sua empresa
* **Privacy Policy URL**: A URL da política de privacidade da sua empresa
3. Uma vez criado, anote seu `App ID` (client key) e `App Secret` (client secret)
## Passo 3: Solicite Acesso à API do Business Messaging
Você precisa conceder ao seu aplicativo acesso à API do Business Messaging. Para obter instruções detalhadas, consulte o [Guia de acesso à API do TikTok Business Messaging](https://business-api.tiktok.com/portal/docs?id=1832184145137922).
1. Abra seu aplicativo no Portal do Desenvolvedor do TikTok
2. Navegue até o produto **Business Messaging API**
3. Envie uma solicitação com:
* Seu caso de uso (ex., suporte ao cliente via AirysChat)
* Como você lidará com os dados do usuário
* Os detalhes da sua organização
4. Aguarde a análise e aprovação do TikTok
A aprovação normalmente leva alguns dias, mas pode demorar mais para acessos especializados. Você não pode prosseguir com a integração até que sua solicitação seja aprovada.
## Passo 4: Configure as Permissões do Aplicativo e URLs
Uma vez aprovado, configure o seguinte no Portal do Desenvolvedor do TikTok.
### Permissões Necessárias
Após a aprovação do seu aplicativo, certifique-se de que a permissão **TikTok Accounts** esteja habilitada em **Scope of permission** nas configurações do seu aplicativo.
### URL de Redirecionamento de Autorização
Defina a URL de redirecionamento de autorização para:
`{AirysChat installation url}/tiktok/callback`
## Passo 5: Configure o AirysChat
### Configuração de Super Admin
1. Faça login na sua instância do AirysChat como um Super Admin
2. Navegue até `{AirysChat installation url}/super_admin/app_config?config=tiktok`
3. Insira seu `TikTok App ID` e `TikTok App Secret`
4. Clique em **Submit**
Alternativamente, você pode defini-los como variáveis de ambiente:
```bash theme={null}
TIKTOK_APP_ID=your_tiktok_app_id
TIKTOK_APP_SECRET=your_tiktok_app_secret
```
Reinicie o servidor do AirysChat depois de fazer as alterações.
### Habilitar Recurso do TikTok
1. No Super Admin, navegue até **Accounts**
2. Selecione a conta onde deseja habilitar o TikTok
3. Em **Features**, habilite o canal **TikTok**
4. Salve as alterações
O TikTok só aparecerá nas opções do canal de caixa de entrada depois que você tiver configurado o App ID e o App Secret e ativado o recurso para a conta.
## Passo 6: Configurar o Webhook
Configure o webhook do TikTok para receber mensagens recebidas. Abra um console Rails no seu servidor do AirysChat:
```bash theme={null}
bundle exec rails console
```
Execute o seguinte comando para registrar a URL de retorno do webhook:
```ruby theme={null}
Tiktok::AuthClient.update_webhook_callback
```
Isso define a URL do webhook como `{AirysChat installation url}/webhooks/tiktok`.
Você pode verificar a configuração do webhook executando:
```ruby theme={null}
Tiktok::AuthClient.webhook_callback
```
O webhook deve ser configurado **após** definir o TikTok App ID e o App Secret no Super Admin. Se você alterar seu domínio do AirysChat, precisará executar esse comando novamente.
## Passo 7: Conectar o AirysChat à sua Conta do TikTok
Siga o [Guia do usuário do canal TikTok](https://www.airyschat.com/hc/user-guide/articles/1769595702-how-to-setup-a-tik_tok-channel) para concluir a integração com o TikTok.
## Solução de Problemas
### Canal TikTok não aparece nas opções da caixa de entrada
* Verifique se o recurso do TikTok está habilitado para a conta no Super Admin
* Confirme se `TIKTOK_APP_ID` e `TIKTOK_APP_SECRET` estão definidos corretamente
* Reinicie o servidor do AirysChat após alterações de configuração
### Autorização OAuth falha
* Certifique-se de que a URL de redirecionamento no Portal do Desenvolvedor do TikTok corresponda exatamente a `{AirysChat installation url}/tiktok/callback`
* Verifique se seu aplicativo TikTok tem todos os escopos necessários habilitados
* Verifique se o seu aplicativo TikTok foi aprovado para a API do Business Messaging
### Não recebendo mensagens de entrada
* Verifique se o webhook está configurado executando `Tiktok::AuthClient.webhook_callback` no console Rails
* Certifique-se de que a URL do webhook seja publicamente acessível por HTTPS
* Verifique se sua conta do TikTok Business está em uma região qualificada
* Analise os logs do Sidekiq em busca de erros no `Webhooks::TiktokEventsJob`
### Falha ao enviar mensagens
* Verifique se a janela de resposta de 48 horas expirou
* Verifique se o token de acesso é válido - o AirysChat atualiza os tokens automaticamente, mas se o token de atualização expirar (30 dias), o canal precisará ser reautorizado
* Certifique-se de que você está enviando um tipo de mensagem compatível (apenas texto ou uma única imagem)
* Verifique os logs do Sidekiq em busca de erros no `SendReplyJob`
### Canal exibe "Reauthorization Required"
Isso acontece quando o token de acesso (cerca de 24 horas) e o token de atualização (cerca de 30 dias) expiram, geralmente devido à inatividade.
1. Vá para **Settings** → **Inboxes** → selecione a caixa de entrada do TikTok
2. Clique em **Reauthorize**
3. Conclua o fluxo OAuth do TikTok novamente
### Verificação de assinatura de webhook falha
* Certifique-se de que `TIKTOK_APP_SECRET` corresponde ao segredo no seu Portal do Desenvolvedor do TikTok
* Verifique a sincronização do relógio do servidor - a verificação de assinatura do TikTok requer timestamps dentro de 5 segundos