- Crie uma conta de desenvolvedor do TikTok.
- Registre um aplicativo no Portal do Desenvolvedor do TikTok.
- Solicite acesso à API do Business Messaging.
- Configure as permissões do aplicativo e as URLs de redirecionamento.
- Configure o AirysChat com o
App IDe oApp Secretobtidos do TikTok. - Configure o webhook para mensagens recebidas.
- Conecte uma conta do TikTok Business a partir do painel do AirysChat.
Pré-requisitos
- Uma instância auto-hospedada do AirysChat acessível por meio de uma URL HTTPS pública
- Uma Conta do TikTok Business registrada em uma região qualificada
- 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.
- Uma Conta de Desenvolvedor do TikTok em developers.tiktok.com
- Acesso à API do TikTok Business Messaging (requer permissões especiais e aprovação)
- Acesso de Super Admin à sua instância do AirysChat
Passo 1: Crie uma Conta de Desenvolvedor do TikTok
- Acesse developers.tiktok.com e cadastre-se
- Verifique seu endereço de e-mail
- Aceite os Termos de Serviço
Passo 2: Registre seu Aplicativo
- Acesse business-api.tiktok.com/portal/apps e crie um novo aplicativo
- 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
- Uma vez criado, anote seu
App ID(client key) eApp 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.- Abra seu aplicativo no Portal do Desenvolvedor do TikTok
- Navegue até o produto Business Messaging API
- 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
- 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
- Faça login na sua instância do AirysChat como um Super Admin
- Navegue até
{AirysChat installation url}/super_admin/app_config?config=tiktok - Insira seu
TikTok App IDeTikTok App Secret - Clique em Submit
Habilitar Recurso do TikTok
- No Super Admin, navegue até Accounts
- Selecione a conta onde deseja habilitar o TikTok
- Em Features, habilite o canal TikTok
- 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:{AirysChat installation url}/webhooks/tiktok.
Você pode verificar a configuração do webhook executando:
Passo 7: Conectar o AirysChat à sua Conta do TikTok
Siga o Guia do usuário do canal TikTok 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_IDeTIKTOK_APP_SECRETestã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_callbackno 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.- Vá para Settings → Inboxes → selecione a caixa de entrada do TikTok
- Clique em Reauthorize
- Conclua o fluxo OAuth do TikTok novamente
Verificação de assinatura de webhook falha
- Certifique-se de que
TIKTOK_APP_SECRETcorresponde 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