Seu chatbot Chatbotty já responde perguntas no seu site através do seu widget. Mas e se você quiser que seu chatbot de IA também esteja em outro lugar — dentro do seu próprio aplicativo móvel, um portal para clientes ou uma ferramenta interna que sua equipe usa todos os dias? É exatamente para isso que serve uma **API**. Este guia explica o que é uma API em linguagem simples, como a API do Chatbotty funciona, o que você pode construir com ela e como criar sua primeira chave de API. Não é necessário diploma em ciência da computação — apenas uma visão clara de como as peças se encaixam. Este é o primeiro artigo de uma série. Aqui cobrimos o panorama geral; artigos posteriores mergulham em cada parte da API em detalhes. ## O que é exatamente uma API? API significa *Interface de Programação de Aplicações*. Isso soa técnico, mas a ideia é simples: uma API é uma forma de dois softwares conversarem diretamente, sem que um humano precise clicar em botões no meio do caminho. Pense nisso como fazer um pedido em um restaurante. Você não entra na cozinha para cozinhar sua própria refeição. Você diz ao garçom o que quer, o garçom passa seu pedido para a cozinha, e a comida volta para sua mesa. O garçom é a API — um mensageiro que leva seu pedido, entrega ao sistema que faz o trabalho e traz a resposta de volta. Com o Chatbotty, a "cozinha" é seu chatbot de IA e sua base de conhecimento. A API é o mensageiro com quem seu software conversa. Seu app envia uma pergunta, o chatbot descobre a resposta, e a API envia essa resposta direto para seu app — tudo em fração de segundo. ## Por que conectar seu chatbot a uma API? O widget de chat é perfeito para seu site. Mas uma API abre todas as outras possibilidades: - **Construa um chatbot no seu próprio app.** Coloque seu assistente de IA dentro de um app móvel ou um app web personalizado, com seu próprio design ao redor. - **Conecte seu chatbot a outras ferramentas.** Alimente respostas em um help desk, um canal do Slack ou um painel interno. - **Automatize sua base de conhecimento.** Faça upload de novos documentos para seu chatbot automaticamente sempre que as informações do seu produto mudarem. - **Gere seus próprios relatórios.** Leia o histórico de conversas e análises nos seus sistemas em vez de verificar o painel manualmente. Em resumo: o widget é a porta pronta para uso, e a API é o conjunto de chaves que permite que você construa suas próprias portas onde precisar. ## O que você pode fazer com a API do Chatbotty A API do Chatbotty está organizada em cinco áreas. Você encontrará exemplos de código prontos para copiar para cada uma delas diretamente no seu painel, em **API Integration**. - **Chat API** — envie uma mensagem para seu chatbot e receba a resposta da IA, o mesmo cérebro que alimenta seu widget. - **Documents API** — faça upload, liste e remova os documentos que compõem a base de conhecimento do seu chatbot. - **Conversations API** — leia conversas passadas e suas mensagens. - **Analytics API** — obtenha estatísticas agregadas como total de perguntas e taxa de sucesso. - **Tickets API** — liste tickets de suporte, altere seus status e adicione notas internas. Não se preocupe com os detalhes ainda. Cada um desses terá seu próprio artigo dedicado. Por enquanto, saiba que quase tudo que você vê no painel, você também pode acessar pela API. ## Como as chaves de API mantêm seu chatbot seguro Software não pode fazer login com email e senha como você. Em vez disso, ele prova quem é com uma **chave de API** — uma longa e secreta sequência de caracteres. Cada requisição que seu app envia inclui essa chave para que o Chatbotty saiba que a requisição realmente vem de você e a qual chatbot ela pertence. A chave é enviada em uma parte da requisição chamada *cabeçalho Authorization*, como algo chamado **Bearer token**. Você não precisa decorar esses termos — os exemplos de código no seu painel já os incluem. Basta substituir o espaço reservado `YOUR_API_KEY` pela sua chave real e pronto. Uma chave está vinculada a um chatbot específico. Você nunca precisa enviar um ID de chatbot — o Chatbotty descobre qual chatbot você quer pelo próprio chave. Uma chave de API é como uma senha para seu chatbot. Quem a tiver pode conversar com seu chatbot e ler seus dados. Nunca cole essa chave em código público, no front-end de um site ou em um documento compartilhado — mantenha-a em seu próprio servidor seguro. ## Como criar sua primeira chave de API Criar uma chave leva cerca de dez segundos. Aqui está o processo completo. 1. Abra seu painel e vá para **API Integration** no menu à esquerda. 2. Encontre o chatbot que deseja conectar. Cada chatbot tem sua própria seção **API Keys**. 3. Clique em **Create new API key**. 4. Dê um nome à chave que você reconhecerá depois, como *Site de produção* ou *App móvel*. O nome é só para você — ajuda a lembrar onde cada chave é usada. 5. Clique em **Create**. Sua chave novinha aparece imediatamente. Copie sua chave agora e guarde em um lugar seguro. Por segurança, a chave completa é mostrada apenas uma vez. Depois que fechar esta janela, o painel exibirá apenas os primeiros caracteres. Se perder a chave, basta apagar a antiga e criar uma nova. Você pode criar várias chaves por chatbot — uma forma prática de dar a cada app sua própria chave. Pode desativar uma chave a qualquer momento sem apagá-la, ou removê-la definitivamente quando não precisar mais. ## Sua primeira requisição à API Depois de ter uma chave, conversar com seu chatbot é uma requisição simples. Aqui está o menor exemplo possível usando cURL, uma ferramenta básica de linha de comando: ```bash curl -X POST "https://www.chatbotty.ai/api/v1/chat" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"message": "Quais são seus horários de funcionamento?"}' ``` Seu chatbot lê a mensagem, busca na base de conhecimento e responde — exatamente como faria no widget. A primeira requisição de chat também cria uma *conversa*, e você pode enviar o ID dela na próxima requisição para continuar a conversa com todo o contexto. Prefere JavaScript, Python ou Node.js? Todos os exemplos no painel estão disponíveis nessas linguagens também, prontos para copiar. ## Quem pode usar a API? A API do Chatbotty está disponível nos planos **Evaluation**, **Elite** e **Enterprise**. Se seu plano atual ainda não inclui acesso à API, a página de API Integration mostrará as opções de upgrade. As requisições de chat enviadas pela API contam para sua cota mensal de mensagens, assim como os chats do widget — as outras áreas, como análises e conversas, não consomem mensagens. ## Pronto para começar a construir? Esse é o panorama completo: uma API permite que seu próprio software converse diretamente com seu chatbot, uma chave de API mantém essa conexão segura, e o painel oferece código funcional para cada parte. Abra a página API Integration, crie sua primeira chave e faça uma requisição de chat — quando você vir seu chatbot responder pela API, o resto fará sentido. Fique atento aos próximos artigos desta série, onde exploraremos as APIs de Chat, Documentos, Conversas, Análises e Tickets uma a uma.