Configurando uma integração de API personalizada com o AI Assist
Antes de começar
As instruções abaixo são apenas para computadores de mesa e notebooks.
O AI Assist do tawk.to oferece suporte a integrações de API personalizadas que permitem que seu agente de IA execute pesquisas e ações de backend automaticamente — semelhante ao que um agente humano faria.
Por exemplo, seu agente de IA pode:
- Pesquisar seu catálogo de produtos
- Verificar o status do pedido ou pagamento
- Pesquisar detalhes de faturamento
- Recuperar compras anteriores
Isso permite que os clientes obtenham respostas instantaneamente, sem esperar por um agente humano.
As integrações de API são configuradas por propriedade. Se você usar vários agentes de IA, poderá ativar ou desativar cada integração individualmente para cada agente.
Este guia abrange:
- O que você precisa antes de começar
- Como configurar a integração no tawk.to
- Como testar a integração
- Uma referência técnica para desenvolvedores que estão criando a API
Observação: As integrações estão disponíveis apenas nos planos Growth, Business e Enterprise.
Antes de começar
Para configurar uma integração de API personalizada, você precisará:
- Um endpoint de API
Uma URL para a qual o AI Assist pode enviar solicitações e receber dados.
- Um esquema OpenAPI
Um arquivo que descreve os endpoints, parâmetros e respostas da sua API para que o AI Assist saiba como usá-la.
- Credenciais de autenticação (se necessárias)
Por exemplo: chave de API, nome de usuário e senha ou outros métodos de autenticação suportados pela sua API.
Usando Shopify, WooCommerce ou BigCommerce?
Em vez de uma integração de API personalizada, você pode usar as integrações nativas do tawk.to. Consulte estes guias para obter instruções passo a passo:
Como integrar o AI Assist com o Shopify
Como integrar o AI Assist com o WooCommerce
Como integrar o AI Assist com o BigCommerce
Para outras plataformas
Se você estiver usando outras plataformas, como:
- Wix
- Squarespace
- Magento
- PrestaShop
- Um produto SaaS com sua própria API
- Um sistema backend personalizado
Se sua plataforma não expuser uma API direta, seu desenvolvedor pode precisar criar um serviço proxy. As ferramentas comuns usadas para isso incluem:
- Google Apps Script
- Cloudflare Workers
- Um servidor Node.js
Se você não se sentir à vontade para construir isso sozinho, compartilhe este guia com um desenvolvedor. A seção Referência técnica para desenvolvedores abaixo explica exatamente o que eles precisam implementar.
Adicionar a integração no tawk.to
2. Clique em Automação (Automation) na barra de navegação esquerda.
3. Clique em Integrações (Integrations) no submenu esquerdo.
4. Clique em OpenAPI Server em Ferramenta Personalizada (Custom Tool).
Você também pode pesquisar por “OpenAPI” usando a barra de Pesquisa (Search) no topo.
5. Isso abre a página Visão Geral (Overview) do OpenAPI Server. Clique em Instalar (Install) no canto superior direito.
No formulário de configuração, insira os seguintes detalhes:
- URL do Arquivo de Esquema (Schema File URL)
Esta deve ser uma URL de acesso público que aponta diretamente para um arquivo de esquema OpenAPI YAML ou JSON.
Você pode hospedar seu esquema usando serviços como:
- GitHub (use the Raw file URL)
- GitHub Gist
- Amazon S3
- Qualquer serviço de hospedagem web
Você também pode selecionar Colar Esquema (Paste Schema) e colar seu esquema em JSON.
If you don’t yet have a schema file, see the Technical reference for developers section below.
- URL base da API (API base URL):
Esta é a URL raiz da sua API. Os endpoints definidos no seu esquema serão acessados em relação a esta URL.
Exemplo:
Se sua URL base da API for:
https://script.google.com/macros/s/ABC123
e seu esquema definir o endpoint:
/exec
O AI Assist chamará:
https://script.google.com/macros/s/ABC123/exec
7. Escolha o Método de Autenticação (Authentication method) exigido pela sua API.
- Sem Autenticação (No Auth) — se sua API não exigir autenticação.
- Chave de API (API key) — insira a Chave (Key) e o Valor (Value). (por exemplo, chave: “x-api-key”, valor: “sua-chave-secreta”)
- Básico (Basic) — insira seu nome de usuário e senha.
8. Clique em Salvar (Save).
10. Selecione seu agente de IA. Em seguida, clique em Ferramentas (Tools) no menu esquerdo e certifique-se de que a integração esteja ativada em Status.
Configurar seu Base Prompt (opcional)
Se as descrições do seu esquema forem claras e específicas, o AI Assist deverá chamar automaticamente os endpoints de API corretos. No entanto, se o AI Assist não acionar a chamada de API correta, você pode adicionar uma instrução ao seu Base Prompt.
Exemplo:
“Se o cliente perguntar sobre o status do pedido, use a chamada de ferramenta de API trackOrder.”
Para obter etapas detalhadas sobre como configurar seu Base Prompt, consulte este guia:
Modificando o Base Prompt
Teste sua integração
Antes de implantar sua integração, teste-a cuidadosamente.
Teste a API diretamente
Use uma ferramenta como Postman ou um navegador para chamar seu endpoint de API e confirmar se ele retorna as respostas esperadas.
Teste usando a prévia do AI Assist
Na página de configurações do AI Assist, use o painel de prévia do chatbot para simular perguntas de clientes. Exemplos de testes:
- Pesquisa de produto: “Mostre-me bolsas de couro”
Comportamento esperado: aciona uma chamada de API de pesquisa de produto.
- Rastreamento de pedido: “Onde está meu pedido nº 12345?”
Comportamento esperado: aciona uma chamada de API de rastreamento de pedido.
- Pergunta não relacionada: “Qual é o clima hoje?”
Comportamento esperado: não deve acionar uma chamada de API.
Teste casos extremos
Certifique-se de que sua API lida com situações como:
- Nenhum produto encontrado
- Pedido não encontrado
- Atrasos ou timeouts da API
- Erros de API
Solução de problemas
Abaixo são alguns problemas comuns que você pode encontrar ao configurar uma integração de API.
O AI Assist nunca chama a API
Causas possíveis:
O AI Assist diz que a solicitação não funcionou
No chat, o AI Assist pode responder com uma mensagem como: “Não foi possível recuperar essa informação.”
Isso geralmente significa que a chamada de API foi tentada, mas não retornou dados utilizáveis.
O arquivo de esquema não carrega
Causas possíveis:
Como corrigir:
As respostas da IA contêm informações incorretas ou geradas
Isso pode acontecer se o AI Assist gerar informações não presentes na resposta da API.
Para reduzir esse comportamento, adicione a seguinte instrução ao seu Base Prompt:
“Compartilhe apenas as informações retornadas pela API.”
Não tem certeza se o AI Assist está chamando a API
Atualmente, as chamadas de ferramenta de API não são exibidas no detalhamento da fonte de dados do painel de prévia. Se você precisar de confirmação de que a API está sendo chamada, entre em contato conosco via chat ao vivo. Nossa equipe pode revisar os logs de solicitação.
O AI Assist nunca chama a API
Causas possíveis:
- O botão de Status da integração está desativado
- As descrições do esquema são muito vagas
- As instruções do Base Prompt não fazem referência à ferramenta correta
- Vá para Integração/API e confirme se a integração está ativada para o seu agente.
- Revise as descrições do seu esquema e certifique-se de que elas expliquem claramente quando a API deve ser usada.
- Adicione uma instrução ao Base Prompt, se necessário, para guiar o AI Assist.
O AI Assist diz que a solicitação não funcionou
No chat, o AI Assist pode responder com uma mensagem como: “Não foi possível recuperar essa informação.”
Isso geralmente significa que a chamada de API foi tentada, mas não retornou dados utilizáveis.
- A API não retornou resultados correspondentes
- Os parâmetros da solicitação estavam incorretos
- Um problema de autenticação
- Um erro ou timeout da API
- Teste o endpoint da API diretamente usando Postman ou um navegador.
- Verifique se os mesmos parâmetros retornam resultados válidos.
- Verifique se as credenciais de autenticação e a URL Base da API estão corretas.
O arquivo de esquema não carrega
Causas possíveis:
- O arquivo de esquema não é acessível publicamente
- O esquema não está no formato OpenAPI 3.0 válido
Como corrigir:
- Abra a URL do esquema em um navegador para confirmar se ele está acessível.
- Valide o esquema usando editor.swagger.io
As respostas da IA contêm informações incorretas ou geradas
Isso pode acontecer se o AI Assist gerar informações não presentes na resposta da API.
Para reduzir esse comportamento, adicione a seguinte instrução ao seu Base Prompt:
“Compartilhe apenas as informações retornadas pela API.”
Não tem certeza se o AI Assist está chamando a API
Atualmente, as chamadas de ferramenta de API não são exibidas no detalhamento da fonte de dados do painel de prévia. Se você precisar de confirmação de que a API está sendo chamada, entre em contato conosco via chat ao vivo. Nossa equipe pode revisar os logs de solicitação.
Coisas para lembrar
- O AI Assist usa as descrições em seu esquema para determinar quando e como chamar sua API. Descrições claras melhoram a confiabilidade.
- Cada solicitação de API é independente. O AI Assist não acessa diretamente as respostas de API anteriores. No entanto, o AI Assist pode fazer referência a mensagens já enviadas na conversa.
- As respostas da API têm prioridade sobre outras fontes de dados. Se os dados da API estiverem disponíveis, o AI Assist os priorizará ao gerar respostas.
- Conversas longas podem ser truncadas, o que pode impedir o AI Assist de fazer referência a mensagens anteriores.
Atualizações de esquema
Embora a URL Base da API (API Base URL) possa be editada a qualquer momento, a URL do Arquivo de Esquema (Schema File URL) não pode ser visualizada ou editada.
O esquema é armazenado como um instantâneo (snapshot). Se você atualizar o arquivo de esquema na URL de origem, a integração não será atualizada automaticamente.
Para aplicar alterações de esquema:
- Exclua a integração existente.
- Adicione a integração novamente usando o esquema atualizado.
Melhores práticas
- Teste sua API quanto à precisão, latência e segurança.
- Siga as melhores práticas para autenticação e criptografia.
- Configure caminhos de escalonamento para que o agente de IA possa transferir a conversa para um humano quando necessário. Consulte estes guias para saber mais: Usando instruções do Base Prompt para escalonamento Como treinar o AI Assist para transferir chats para agentes humanos
Referência técnica para desenvolvedores
As seções abaixo são destinadas a desenvolvedores que estão construindo o endpoint de API e o esquema OpenAPI. Se você estiver trabalhando com um desenvolvedor, compartilhe esta seção com ele.
Construindo o endpoint de API
Seu endpoint de API deve:
- Aceitar solicitações HTTP (GET ou POST)
- Retornar respostas JSON
- Ser acessível publicamente
A estrutura da resposta é flexível, mas deve ser clara e descritiva.
Exemplo: Resposta de pesquisa de produto
Exemplo: Resposta de rastreamento de pedido
Respostas de erro
Escreva mensagens de erro como se pudessem ser mostradas ao cliente.
Exemplo:
AI Assist pode usar essas mensagens ao gerar respostas.
Criando o esquema OpenAPI
Ferramentas recomendadas:
- Swagger Editor – para escrever e visualizar seu esquema
- Swagger Validator – para validá-lo
Escrevendo boas descrições de esquema
Os campos de descrição em seu esquema ajudam o AI Assist a entender quando chamar sua API e como usá-la. Pense nessas descrições como instruções para o agente de IA, não como documentação para desenvolvedores.
Suas descrições devem explicar:
- Quando usar o endpoint
Exemplo: “Use quando o cliente perguntar sobre produtos, estoque ou quiser navegar por itens.”
- Quais parâmetros enviar
Explique de onde vêm os valores e como eles devem ser formatados. Exemplo:
“Extraia a palavra-chave da mensagem do cliente.”
- Como interpretar a resposta
Exemplo:
- “Se o estoque for 0, diga ao cliente que o item está esgotado.”
- “Se uma URL de rastreamento estiver presente, sempre a inclua na resposta.”
- “A ação a ser executada”
- “Palavra-chave de pesquisa”
Quanto mais específicas forem suas descrições, mais precisamente o AI Assist poderá acionar a chamada de API correta com os parâmetros corretos.
Guias relacionados
Primeiros passos com o AI Assist
Modificando o Base Prompt
Como integrar o AI Assist com o Shopify
Como integrar o AI Assist com o WooCommerce
Como integrar o AI Assist com o BigCommerce
Como integrar o AI Assist com o Picqer
Entendendo as Fontes de Dados do AI Assist
Implantando múltiplos Agentes de IA em canais de suporte
Usando instruções do Base Prompt para escalonamento
Como treinar o AI Assist para transferir chats para agentes humanos
Se você tiver comentários sobre este artigo, ou se precisar de mais ajuda:
- Clique no ícone verde de chat ao vivo
- Agende uma ligação conosco
- Visite nossa comunidade