Integração de API de chatbot: API REST, Zapier e webhooks explicados

Uma API de chatbot é uma interface HTTP que permite enviar mensagens para um chatbot de IA e receber respostas de forma programática — sem usar um widget visual. Em vez de um usuário digitando em um balão de chat, o seu código envia uma requisição, recebe uma resposta e faz algo com ela: renderiza uma UI personalizada, registra a resposta em log, aciona uma ação ou encaminha o resultado para outro sistema.

Este guia cobre o que é uma API de chatbot, quando usar uma em vez de um widget incorporado, os três principais métodos de conexão (REST, Zapier e webhooks) e padrões práticos para construir integrações reais.

O que é uma API de chatbot?

Uma API de chatbot expõe o seu chatbot de IA treinado como um serviço que qualquer código pode chamar via HTTP. Você envia a mensagem do usuário no corpo da requisição, e a API retorna a resposta do chatbot — extraída das fontes (conteúdo do site, documentos, pares de perguntas e respostas) que você usou para treiná-lo.

A principal diferença em relação a um widget pronto: a API retorna dados brutos. A sua aplicação decide como apresentá-los. Isso significa que você pode incorporar o mesmo chatbot em um app mobile, um bot do Slack, um painel interno e um pipeline de automação de backend — todos usando a mesma base de conhecimento treinada.

A maioria das APIs de chatbot segue um padrão semelhante:

1. Autenticar — inclua uma chave de API no cabeçalho Authorization.
2. Enviar uma mensagem via POST — envie o texto do usuário, um ID de chatbot e, opcionalmente, um ID de conversa para contexto de múltiplas interações.
3. Tratar a resposta — processe a resposta, opcionalmente transmita os tokens em streaming para uma sensação em tempo real, e armazene o conversationId para a próxima interação.

Para equipes que estão comparando opções de chatbot antes de se comprometer com uma plataforma, esta visão geral dos melhores chatbots de IA para sites cobre o que procurar entre as ferramentas.

Quando usar a API em vez do widget

O widget incorporado atende à maioria dos casos de uso em sites. A API é a escolha certa quando você precisa de algo que o widget não oferece.

Se o seu caso de uso se encaixa na coluna da direita, a API é a ferramenta certa. Para todas as opções de incorporação — widget, componente React, iframe e plugin para WordPress — veja o guia de integração de chatbot.

Métodos de conexão e disponibilidade por plano

Existem três formas de conectar o seu chatbot a sistemas externos. Elas servem a propósitos diferentes e estão disponíveis em planos diferentes.

A API REST oferece o maior controle. O Zapier é mais rápido de configurar se você não precisa de código personalizado. Os webhooks complementam ambos — eles enviam dados para você em vez de você precisar buscá-los.

Para uma análise completa do que cada plano inclui, veja o guia de custos e preços de chatbot.

Requisitos por plano

A cobrança anual reduz o preço de cada plano em aproximadamente 20%. As mensagens da API contam para a sua cota mensal da mesma forma que as mensagens do widget.

Autenticação

Toda requisição de API exige um token Bearer. Você gera chaves de API nas configurações do workspace, no painel do Agentkit.

Gerando uma chave de API

1. Abra o seu workspace do Agentkit.
2. Navegue até Configurações e depois Chaves de API.
3. Clique em Criar chave de API.
4. Dê um nome descritivo a ela (por exemplo, "Slack Bot Produção").
5. Copie a chave imediatamente. Ela não será exibida novamente.

Usando a chave nas requisições

Inclua a sua chave de API no cabeçalho Authorization:

Authorization: Bearer ak_live_your_api_key_here

Todas as requisições devem ser enviadas via HTTPS. Requisições sem um token válido retornam uma resposta 401 Unauthorized.

Boas práticas de gerenciamento de chaves

• Armazene as chaves de API em variáveis de ambiente, nunca em código do lado do cliente.
• Rotacione as chaves periodicamente, especialmente após mudanças na equipe.
• Crie chaves separadas para integrações separadas, para que você possa revogar uma sem afetar as outras.
• Exclua as chaves que você não usa mais.

Para detalhes completos de autenticação, veja a documentação de autenticação.

O endpoint de chat

O núcleo da API é um único endpoint que envia a mensagem de um usuário para o seu chatbot e retorna a resposta da IA.

Requisição

POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer ak_live_your_api_key_here

Corpo da requisição:

{
  "chatbotId": "your-chatbot-id",
  "message": "What are your shipping options?",
  "conversationId": "optional-conversation-id",
  "visitorId": "optional-visitor-id",
  "metadata": {
    "page": "/products/shoes",
    "userTier": "premium"
  }
}

Resposta

{
  "id": "msg_abc123",
  "conversationId": "conv_xyz789",
  "message": "We offer three shipping options: Standard (5-7 business days, free over $50), Express (2-3 business days, $9.99), and Overnight ($24.99). All orders include tracking.",
  "sources": [
    {
      "title": "Shipping Policy",
      "url": "https://example.com/shipping"
    }
  ],
  "createdAt": "2026-02-22T14:30:00Z"
}

O conversationId na resposta é importante. Armazene-o e envie-o de volta nas requisições seguintes para manter o contexto da conversa. Sem ele, cada mensagem inicia uma nova conversa e o chatbot perde o fio da conversa.

Respostas de erro

Para a referência completa do endpoint, veja a documentação da API.

Respostas em streaming

Para aplicações em tempo real em que você quer exibir a resposta conforme ela é gerada (o efeito de máquina de escrever que os usuários esperam de um chat de IA), use Server-Sent Events (SSE).

Adicione o parâmetro stream: true à sua requisição:

{
  "chatbotId": "your-chatbot-id",
  "message": "Explain your return policy",
  "conversationId": "conv_xyz789",
  "stream": true
}

A resposta chega como um stream de eventos SSE:

data: {"type": "token", "content": "Our"}
data: {"type": "token", "content": " return"}
data: {"type": "token", "content": " policy"}
data: {"type": "token", "content": " allows"}
...
data: {"type": "sources", "sources": [{"title": "Return Policy", "url": "https://example.com/returns"}]}
data: {"type": "done", "conversationId": "conv_xyz789", "messageId": "msg_def456"}

Tratando o stream em JavaScript

const response = await fetch('https://api.agentkit.com/api/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ak_live_your_api_key_here'
  },
  body: JSON.stringify({
    chatbotId: 'your-chatbot-id',
    message: 'Explain your return policy',
    stream: true
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.startsWith('data: '));

  for (const line of lines) {
    const data = JSON.parse(line.slice(6));
    if (data.type === 'token') {
      appendToUI(data.content);
    }
  }
}

O streaming é recomendado para qualquer integração voltada ao usuário. Ele faz o chatbot parecer mais ágil mesmo ao gerar respostas longas.

Webhooks

Enquanto o endpoint de chat permite enviar mensagens para o chatbot, os webhooks permitem que o chatbot envie dados para você. Quando eventos específicos acontecem, o Agentkit envia uma requisição HTTP POST para uma URL que você configura. Os webhooks estão disponíveis a partir do plano Hobby.

Configurando webhooks

1. Vá até Configurações do seu workspace e depois Webhooks.
2. Insira a URL do seu endpoint (deve ser HTTPS).
3. Selecione a quais eventos você quer se inscrever.
4. Salve. O Agentkit envia uma requisição de verificação para confirmar que o seu endpoint está acessível.

Eventos disponíveis

Payload do webhook

Todo POST de webhook inclui um corpo JSON com uma estrutura consistente:

{
  "event": "lead.captured",
  "timestamp": "2026-02-22T15:45:00Z",
  "chatbotId": "your-chatbot-id",
  "conversationId": "conv_xyz789",
  "data": {
    "name": "Alex Chen",
    "email": "[email protected]",
    "message": "Interested in the enterprise plan"
  },
  "signature": "sha256=abc123..."
}

Sempre verifique o campo signature em relação ao seu segredo de webhook para confirmar que a requisição veio do Agentkit, e não de terceiros.

Comportamento de retentativas

Se o seu endpoint retornar um código de status que não seja 2xx, o Agentkit tenta novamente com backoff exponencial: após 1 minuto, 5 minutos, 30 minutos, e então para. As entregas com falha ficam visíveis nos logs de webhook, no seu painel.

Padrões comuns de integração

Padrão 1: bot do Slack

Encaminhe as perguntas dos clientes feitas ao chatbot do seu site para um canal do Slack, e deixe a sua equipe responder quando a IA não conseguir.

1. Crie um app do Slack com webhooks de entrada habilitados.
2. Configure um webhook do Agentkit para eventos conversation.completed.
3. No seu handler de webhook, verifique se a conversa foi resolvida ou escalada.
4. Se escalada, envie via POST uma mensagem formatada para a URL do seu webhook do Slack com a transcrição da conversa.

Isso dá visibilidade à sua equipe de suporte, sem exigir que ela monitore o painel do Agentkit.

Padrão 2: UI de chat personalizada

Substitua o widget padrão por uma experiência de chat integrada à sua aplicação.

1. Construa a sua interface de chat com o framework de sua preferência.
2. Ao enviar uma mensagem, chame o endpoint de chat com stream: true.
3. Renderize os tokens conforme eles chegam, para feedback em tempo real.
4. Armazene o conversationId no estado local para manter o contexto entre as mensagens.

Essa é a abordagem certa para apps mobile, aplicações desktop ou qualquer produto em que o widget flutuante não se encaixa no design. Para equipes que querem continuar usando o widget, mas precisam de mais controle sobre o posicionamento, o guia de incorporação de chatbot no seu site cobre as quatro opções de incorporação.

Padrão 3: automação de backend

Use o chatbot como uma camada de IA em um fluxo de trabalho maior, sem envolver nenhuma UI de chat.

Exemplo: processamento de tickets de suporte.

1. Um novo ticket chega no seu sistema de tickets.
2. O seu backend envia o conteúdo do ticket para o endpoint de chat.
3. O chatbot gera uma resposta sugerida com base na sua base de conhecimento treinada.
4. O seu sistema responde automaticamente (se a confiança for alta) ou coloca a sugestão na fila para revisão humana.

Esse padrão funciona porque o chatbot é treinado com a mesma base de conhecimento que a sua equipe de suporte usa. A API te dá acesso programático a essa inteligência. Para saber mais sobre com que você pode treinar um chatbot — rastreamento de site, PDFs, CSVs, pares de perguntas e respostas — veja como treinar um chatbot.

Padrão 4: pipeline de análise

Capture cada conversa para análise.

1. Inscreva-se nos eventos de webhook message.received e message.sent.
2. O seu handler de webhook grava os eventos no seu data warehouse (BigQuery, Snowflake etc.).
3. Crie painéis mostrando as perguntas mais comuns, taxas de resolução, horários de pico e tendências de conversa.

O campo metadata no endpoint de chat permite anexar contexto (URL da página, segmento de usuário, variante de teste A/B) que enriquece as suas análises.

Limite de taxa

A API aplica limites de taxa para garantir a confiabilidade para todos os usuários.

Quando você atinge o limite, a API retorna um código de status 429 com um cabeçalho Retry-After indicando quantos segundos esperar. Construa uma lógica de retentativa na sua integração:

async function sendMessage(payload, retries = 3) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload)
  });

  if (response.status === 429 && retries > 0) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '5');
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return sendMessage(payload, retries - 1);
  }

  return response.json();
}

Considerações de segurança

Ao construir integrações de API, tenha estas práticas em mente:

• Nunca exponha chaves de API em código do lado do cliente. Se você está construindo uma UI de chat personalizada para uma aplicação web, faça proxy das requisições pelo seu próprio backend.
• Valide as assinaturas de webhook. Sempre verifique a assinatura HMAC antes de processar os payloads de webhook.
• Use restrições de domínio. Nas configurações do seu chatbot, restrinja quais domínios podem interagir com ele.
• Monitore o uso. Verifique regularmente o seu uso de API no painel para identificar picos inesperados que possam indicar uma chave vazada.
• Use o princípio do menor privilégio. Se uma integração só precisa enviar mensagens, não dê a ela uma chave com permissões de administrador.

Para equipes que estão explorando como as APIs de chatbot de IA se conectam a ecossistemas de ferramentas maiores, vale a pena entender o MCP (Model Context Protocol) — um padrão emergente para dar a modelos de IA acesso estruturado a ferramentas e dados externos.

Como começar

O caminho mais rápido do zero a uma integração funcionando:

1. Cadastre-se no Agentkit e crie o seu primeiro chatbot.
2. Treine o chatbot com o seu conteúdo (veja como treinar um chatbot).
3. Faça upgrade para o plano Hobby ($29.99/mês) para habilitar o acesso à API.
4. Gere uma chave de API nas configurações do seu workspace.
5. Envie a sua primeira requisição de teste usando cURL ou Postman.
6. Construa a partir daí: UI personalizada, bot do Slack, automação, ou o que o seu caso de uso exigir.

Perguntas frequentes

O que é uma chave de API de chatbot?

Uma chave de API de chatbot é um token secreto que autentica a sua aplicação quando ela faz requisições à API do chatbot. Você a gera nas configurações do seu workspace, a inclui no cabeçalho Authorization: Bearer de cada requisição e a trata como uma senha — armazene-a em variáveis de ambiente, nunca em código do lado do cliente, e rotacione-a se suspeitar que foi exposta. Cada chave pode ser vinculada a uma integração específica, para que você possa revogar uma sem afetar as outras.

Existe uma API de chatbot gratuita?

O plano Free do Agentkit ($0/mês) não inclui acesso à API REST — isso exige o plano Hobby, a $29.99/mês. O plano Free inclui o widget JS incorporável, a captura de leads e as restrições de domínio, o que cobre a maioria dos casos de uso em sites sem nenhum código. Se você precisa de acesso programático desde o primeiro dia, o plano Hobby é o ponto de entrada, e você pode testar a plataforma completa gratuitamente antes de fazer upgrade.

Preciso programar para usar uma API de chatbot?

Nem sempre. Se você precisa de acesso à API REST para integrações personalizadas, vai precisar escrever código — ou usar uma ferramenta como o Postman para testar chamadas manualmente. Mas se o seu objetivo é conectar o chatbot a outros apps sem código, a integração com Zapier (disponível no plano Hobby ou superior) conecta a mais de 7.000 apps por meio de uma interface sem código. Para incorporação no site, não é preciso nenhum código além de colar uma tag <script>.

Quais modelos de IA a API de chatbot suporta?

O modelo de IA subjacente é configurado por chatbot no painel. O Agentkit suporta modelos de três provedores: OpenAI (GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna), Anthropic (Claude Opus 5, Claude Sonnet 5, Claude Haiku 4.5) e Google (Gemini 3.7 Flash, Gemini 3.1 Pro). O padrão é o GPT-5.6 Luna. As suas chamadas de API usam o modelo que estiver selecionado para aquele chatbot — você não especifica o modelo no nível da chamada de API.

Posso usar a API de chatbot para incorporar o chat no meu site?

Sim, mas a incorporação via widget JS geralmente é mais simples para casos de uso em sites. O widget carrega de forma assíncrona por meio de uma única tag <script> e cuida automaticamente da UI, do estado da conversa e do streaming. Use a API quando precisar de uma UI totalmente personalizada, integração com app mobile ou automação de backend. Para uma comparação lado a lado de todas as opções de incorporação, veja o guia de incorporação de chatbot no seu site.

Uma API de chatbot transforma uma base de conhecimento treinada em um serviço que pode ser chamado — as mesmas respostas de IA que aparecem no widget ficam disponíveis para qualquer sistema que consiga fazer uma requisição HTTP. Seja construindo uma interface personalizada, automatizando um fluxo de suporte ou conectando o seu chatbot a um ecossistema de ferramentas mais amplo, a API te dá o controle que um widget pronto não consegue oferecer.

Crie seu chatbot gratuitamente → Não é necessário cartão de crédito.