← Voltar ao app

API & MCP

Controle seu chatbot a partir do seu próprio código ou de assistentes de IA.

Visão geral#

O Chatbotty pode ser usado e gerenciado fora do painel de duas maneiras: a REST API para o seu próprio código e o conector MCP para assistentes de IA como o Claude. Ambos trabalham com um chatbot por vez e usam as mesmas chaves de API. Comece por Autenticação.

Noções básicas

ItemValor
URL base da RESThttps://www.chatbotty.ai/api/v1
URL do servidor MCPhttps://www.chatbotty.ai/api/mcp
FormatoJSON sobre HTTPS
AutenticaçãoAuthorization: Bearer YOUR_API_KEY
Escopo de uma chaveUma chave pertence a exatamente um chatbot; o chatbot nunca é enviado na requisição, ele é derivado da chave

Qual usar

  • REST API - você escreve código que envia mensagens de chat ou gerencia documentos, conversas, tickets e ações de webhook. Veja Chatbot e as seções de endpoints seguintes.
  • Conector MCP - você conecta um assistente de IA e o deixa trabalhar com o chatbot sem programar. Veja Conector MCP e Clientes MCP.

Planos

As chaves de API, a REST API e o conector MCP estão disponíveis em todos os planos: Free, Evaluation, Support e Automate. Os recursos individuais dependem do plano.

RecursoFreeEvaluationSupportAutomate
Chat, documentos, conversas, analyticsSimSimSimSim
TicketsNãoSimSimSim
Ações de webhookNãoSimNãoSim
Importação de documentos a partir de uma URL webNãoSimSimSim

Uma chamada a um recurso que não está no seu plano retorna 403 FORBIDDEN. O conector MCP nem sequer oferece essas ferramentas. Uma mudança de plano se aplica à próxima requisição.

Cota

  • Somente as mensagens enviadas por meio do chat (REST POST /chat ou a ferramenta MCP send_message) contam na cota mensal de mensagens, exatamente como as mensagens do widget.
  • As outras chamadas (documentos, conversas, analytics, tickets, ações de webhook) não usam a cota.
  • Quando a cota se esgota, a chamada de chat retorna 403 QUOTA_EXCEEDED. Verifique a cota restante com GET /chatbot.
  • As chaves funcionam independentemente dos domínios permitidos do chatbot e mesmo quando o chatbot está inativo para o widget (exceto o envio de mensagens de chat, que um chatbot inativo recusa com 404 NOT_FOUND).

Formato da resposta

Toda resposta REST usa o mesmo envelope. Os erros são descritos em Erros.

{ "success": true, "data": { }, "timestamp": "2026-01-01T10:00:00.000Z" }

Autenticação#

Toda requisição deve levar uma chave de API do chatbot como token Bearer. A mesma chave funciona para a REST API e para o conector MCP.

curl -H "Authorization: Bearer YOUR_API_KEY" https://www.chatbotty.ai/api/v1/chatbot

Chaves de API

ItemValor
FormatoUma string hexadecimal aleatória de 64 caracteres
EscopoUm chatbot por chave
LimiteAté 50 chaves por chatbot (as chaves inativas também contam)
ArmazenamentoSomente um hash é armazenado; a chave completa é mostrada uma vez, logo após a criação

Trate as chaves como senhas: nunca as compartilhe e nunca as coloque em código do lado do cliente.

Gerenciar chaves no painel

  1. Abra API e MCP na barra lateral.
  2. No cartão do seu chatbot, clique em Criar nova chave de API, digite um nome (por exemplo "Production app") e clique em Criar.
  3. Copie a chave imediatamente. Ela não pode ser mostrada novamente ("Copie esta chave agora. Você não poderá vê-la novamente.").

Depois disso, a lista mostra o nome da chave, os seus primeiros 12 caracteres e Último uso.

AçãoEfeito
DesativarA chave deixa de funcionar imediatamente; Ativar a reativa
ExcluirA chave é removida permanentemente; os apps que a usam deixam de funcionar imediatamente

As chaves criadas ao conectar um assistente de IA são rotuladas como Conector MCP. Excluir essa chave desconecta o assistente. Conectar novamente o mesmo assistente ao mesmo chatbot substitui a sua chave antiga.

Erros de autenticação

SituaçãoResposta
Cabeçalho ausente ou malformado401 UNAUTHORIZED "Missing or invalid Authorization header"
Chave desconhecida ou desativada401 UNAUTHORIZED "Invalid or inactive API key"

Veja Erros para todos os códigos e Limites de taxa para os limites de requisições.

Limites de taxa#

Os limites se aplicam por chave de API e por minuto. Cada classe de endpoints tem seu próprio contador, então muitas escritas não consomem o orçamento das leituras.

REST API

ClasseEndpointsLimite por minuto
ChatPOST /chat60
LeituraTodos os outros endpoints GET, exceto analytics (incluindo GET /chatbot)120
EscritaEndpoints POST, PATCH, DELETE60
AnalyticsGET /analytics/summary, /analytics/timeseries, /analytics/top-queries60
Teste de webhookPOST /webhooks/{id}/test20

Limite adicional: POST /documents/upload-url emite no máximo 50 URLs de envio por chatbot em 2 horas.

Conector MCP

O endpoint MCP permite 300 requisições por minuto por chave. Cada chamada de ferramenta fica então sujeita também ao limite REST do endpoint que ela usa, e send_message usa a cota de mensagens.

Quando você excede um limite

A API retorna 429 RATE_LIMITED com uma mensagem como "Rate limit exceeded. Maximum 60 requests per minute per API key." Aguarde o próximo minuto e tente novamente, de preferência com um atraso crescente.

Os limites de taxa são separados da cota mensal de mensagens; veja Visão geral e Erros.

Chatbot#

Identifique o chatbot ao qual a sua chave de API pertence e verifique o seu plano e a sua cota antes de começar a trabalhar com ele.

GET /chatbot

ItemValor
Método e caminhoGET https://www.chatbotty.ai/api/v1/chatbot
ParâmetrosNenhum
Limite de taxaClasse de leitura (veja Limites de taxa)
CotaNão utilizada
Ferramenta MCPget_chatbot_info

Resposta

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "CycleZone",
    "description": "Customer care chatbot",
    "is_active": true,
    "language": "auto",
    "timezone": "America/New_York",
    "handoff_contact": "info@example.com",
    "created_at": "2026-01-01T10:00:00.000Z",
    "dashboard_url": "https://www.chatbotty.ai/dashboard/chatbots/uuid",
    "plan": "Automate",
    "message_quota": { "used": 622, "monthly_limit": 9000, "extra_messages": 0 },
    "features": { "tickets": true, "upload_from_url": true, "webhook_actions": true },
    "knowledge_base": {
      "documents_total": 1,
      "documents_by_status": { "pending": 0, "processing": 0, "completed": 1, "failed": 0 },
      "last_updated_at": "2026-01-01T10:00:00.000Z"
    }
  }
}

Observações

  • plan e message_quota pertencem ao proprietário da conta; a cota é compartilhada por todos os chatbots da conta.
  • features mostra quais recursos dependentes do plano esta chave pode usar.
  • handoff_contact é o contato que o chatbot informa quando não sabe a resposta (somente leitura aqui; null quando não definido).
  • last_updated_at é o horário do documento enviado mais recentemente.

Chat#

Envie uma mensagem ao chatbot e receba a sua resposta, exatamente como um visitante no widget.

POST /chat

ItemValor
Método e caminhoPOST https://www.chatbotty.ai/api/v1/chat
Limite de taxaClasse de chat: 60 por minuto
CotaUma mensagem por chamada; acima da cota, a chamada retorna 403 QUOTA_EXCEEDED
Ferramenta MCPsend_message

Corpo da requisição

CampoObrigatórioDescrição
messageSimA pergunta do visitante (texto não vazio)
conversation_idNãoContinua uma conversa existente; omita para iniciar uma nova
optionsNãoObjeto opcional; não é necessário para o uso normal

Se conversation_id não existir ou pertencer a outro chatbot, a chamada retorna 400 CONVERSATION_NOT_FOUND. Um chatbot que não está ativo retorna 404 NOT_FOUND.

Resposta

{
  "success": true,
  "data": {
    "message": "Our warranty is two years.",
    "conversation_id": "uuid",
    "sources": [{ "content": "...", "similarity": 0.87 }],
    "metadata": {
      "tokensUsed": 312,
      "cached": false,
      "responseTime": 1240,
      "searchResults": 3,
      "quality": "answered",
      "confidence": 0.87,
      "tools_executed": [{ "name": "get_weather", "ok": true }]
    }
  }
}

Contexto da conversa

A primeira chamada cria uma conversa e retorna o seu conversation_id. Envie esse id com cada mensagem seguinte para manter o contexto. As conversas criadas por meio da API aparecem no painel com a origem api.

tools_executed

metadata.tools_executed lista as ferramentas que o chatbot chamou ao responder (ações de webhook, criação de ticket de suporte). Cada item tem name, ok e, em caso de falha, um code curto como webhook_timeout, webhook_redirect, webhook_blocked ou invalid_args. Uma lista vazia significa que nenhuma ferramenta foi chamada. Use-a para verificar se uma ação de webhook realmente foi executada.

Documentos#

Gerencie a base de conhecimento do chatbot: envie, leia, edite, liste e exclua documentos. Essas chamadas não usam a cota de mensagens.

Endpoints

Método e caminhoDescriçãoParâmetros principaisFerramenta MCP
GET /documentsListar documentoslimit (padrão 20, máx. 100), offset, statuslist_documents
POST /documentsEnviar um documento; retorna 202Veja abaixoupload_document
POST /documents/upload-urlObter uma URL assinada para um arquivo grande ou localfilenamecreate_upload_url
GET /documents/{id}Status e detalhes de um documento-get_document
DELETE /documents/{id}Excluir um documento-delete_document
GET /documents/{id}/contentLer o texto, paginadooffset, limit (padrão 20000, máx. 50000)read_document
PATCH /documents/{id}/contentEditar um documento .md ou .txtedits, append, expected_hashedit_document, append_to_document

Limites: as chamadas GET usam o limite de leitura, as outras o limite de escrita (veja Limites de taxa).

Envio

Tipos permitidos: .pdf, .docx, .txt, .md, até 10 MB. Envie multipart/form-data ou JSON.

CampoDescrição
fileO arquivo (somente multipart)
contentTexto de um documento .md ou .txt (JSON; filename obrigatório)
content_base64Arquivo binário em base64 (JSON; use até cerca de 3 MB)
urlURL pública de um arquivo que o servidor baixa (JSON; somente planos com importação de URL web)
upload_idId de POST /documents/upload-url depois que você enviou o arquivo
filenameNome do arquivo com extensão
descriptionDescrição opcional
replace_existingPadrão true: um arquivo com o mesmo nome é substituído pela nova versão

Em JSON, envie exatamente um entre content, content_base64, url, upload_id.

{ "filename": "faq.md", "content": "# FAQ\n\n## Opening hours\n..." }

Arquivos grandes ou locais

  1. POST /documents/upload-url com { "filename": "price-list.pdf" }. A resposta contém upload_id, upload_url e cabeçalhos; a URL é válida por 2 horas e funciona uma única vez.
  2. Envie o arquivo bruto com PUT para upload_url.
  3. POST /documents com { "upload_id": "...", "filename": "price-list.pdf" }.

Processamento e status

O processamento é assíncrono. O status passa de pending por processing até completed, ou termina como failed com um error_message. Um documento com falha permanece na lista; exclua-o ou envie-o novamente. Consulte GET /documents/{id} até completed.

Editar e substituir

  • PATCH /documents/{id}/content envia apenas a alteração: edits (lista de old_text e new_text, cada old_text deve ocorrer exatamente uma vez, até 100) e/ou append (text, after_heading opcional).
  • expected_hash (de GET .../content) protege contra a sobrescrita de uma versão mais nova (409 CONFLICT).
  • Somente documentos .md e .txt em UTF-8 podem ser editados (400 NOT_EDITABLE caso contrário).
  • Toda edição ou substituição cria um novo document_id; a versão antiga continua respondendo até a nova estar completed.
  • Uma segunda alteração enquanto o documento ainda está sendo processado retorna 409 REPLACE_IN_PROGRESS.

Conversas#

Leia o histórico de conversas do chatbot, incluindo as conversas criadas no widget. Essas chamadas são somente leitura e não usam a cota de mensagens.

Endpoints

Método e caminhoDescriçãoParâmetros principaisFerramenta MCP
GET /conversationsListar conversasVeja abaixolist_conversations
GET /conversations/{id}Uma conversa-get_conversation
GET /conversations/{id}/messagesMensagens em ordem cronológicalimit (padrão 50, máx. 200), offsetget_conversation_messages

Os três usam o limite de leitura de 120 requisições por minuto (veja Limites de taxa). Uma conversa de outro chatbot retorna 404 NOT_FOUND.

Filtros da lista

ParâmetroDescrição
limit, offsetPaginação (padrão 20, máx. 100)
statusactive, completed ou ticket_created
sourcewidget ou api
from, toDatas ISO 8601; filtram pelo início da conversa
qualityConversas com pelo menos uma pergunta deste tipo: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified
qBusca de texto completo no texto das mensagens (2 a 200 caracteres)

Resposta

{
  "success": true,
  "data": {
    "conversations": [
      {
        "id": "uuid",
        "started_at": "2026-01-01T10:00:00Z",
        "last_activity_at": "2026-01-01T10:15:00Z",
        "message_count": 5,
        "status": "active",
        "source": "widget",
        "email": "visitor@example.com",
        "phone": null
      }
    ],
    "pagination": { "limit": 20, "offset": 0, "total": 42 }
  }
}

Nos planos com tickets, o detalhe de uma conversa também contém os tickets criados nela. As mensagens têm id, role (user ou assistant), content e created_at.

Dica

Para encontrar perguntas que o chatbot não conseguiu responder, use GET /analytics/top-queries?quality=not_answered (veja Analytics) e abra as conversas relacionadas por meio de conversation_ids.

Analytics#

Estatísticas agregadas do chatbot. O analytics está disponível em todos os planos, inclusive no Free. Essas chamadas não usam a cota de mensagens.

Endpoints

Método e caminhoDescriçãoFerramenta MCP
GET /analytics/summaryTotais do períodoget_analytics_summary
GET /analytics/timeseriesContagens por hora, dia ou semanaget_analytics_timeseries
GET /analytics/top-queriesPerguntas mais frequentesget_top_queries, list_knowledge_gaps

Os três usam o limite de analytics de 60 requisições por minuto (veja Limites de taxa).

Parâmetros comuns

ParâmetroDescrição
periodtoday (padrão), week, month ou quarter, avaliado no fuso horário do chatbot
from, toDatas ISO 8601; substituem period; o intervalo é de no máximo 366 dias
sourcewidget ou api

Parâmetros adicionais

EndpointParâmetroDescrição
timeseriesgranularityauto (padrão), hour, day ou week; hour com quarter é recusado
top-querieslimit, offsetPaginação (padrão 20, máx. 100)
top-queriesqualityanswered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified

Resposta do summary

{
  "period": "week",
  "total_queries": 7,
  "answered_queries": 5,
  "not_answered_queries": 1,
  "conversation_queries": 1,
  "off_topic_queries": 0,
  "ticket_created_queries": 0,
  "tool_call_queries": 0,
  "success_rate": 83.3,
  "widget_queries": 6,
  "api_queries": 1
}

success_rate é o número de respondidas dividido por respondidas mais não respondidas, em porcentagem.

Perguntas sem resposta

GET /analytics/top-queries?quality=not_answered&period=month retorna as perguntas que o chatbot não conseguiu responder, das mais frequentes para as menos frequentes. Cada item tem content, count, last_asked e até 5 conversation_ids que você pode abrir por meio de conversas. Adicione os fatos que faltam à base de conhecimento e verifique o resultado com o chat.

Tickets#

Leia tickets de suporte, altere o status deles e adicione notas internas. Os tickets estão disponíveis nos planos Evaluation, Support e Automate; o Free retorna 403 FORBIDDEN. Os tickets não podem ser criados por meio da API: o chatbot os cria durante uma conversa.

Endpoints

Método e caminhoDescriçãoParâmetros principaisFerramenta MCP
GET /ticketsListar tickets, os mais recentes primeirolimit (padrão 20, máx. 100), offset, status, conversation_id, from, tolist_tickets
GET /tickets/{id}Um ticket-get_ticket
PATCH /tickets/{id}Alterar o statusstatus no corpoupdate_ticket_status
GET /tickets/{id}/notesNotas internas, as mais antigas primeiro-list_ticket_notes
POST /tickets/{id}/notesAdicionar uma nota; retorna 201content no corpoadd_ticket_note

As chamadas GET usam o limite de leitura (120 por minuto), PATCH e POST o limite de escrita (60 por minuto); veja Limites de taxa.

Valores

ItemValor
Statusopen, in_progress, resolved, closed
NotaTexto não vazio, até 5000 caracteres

Um status inválido retorna 400 INVALID_REQUEST. Um ticket de outro chatbot retorna 404 NOT_FOUND.

Objeto de ticket

{
  "id": "uuid",
  "ticket_number": "TKT-000015",
  "conversation_id": "uuid",
  "email": "visitor@example.com",
  "phone": null,
  "summary": "The visitor asked to speak with a person.",
  "status": "open",
  "created_at": "2026-01-01T10:00:00Z",
  "updated_at": "2026-01-01T10:00:00Z"
}

Exemplo

curl -X PATCH https://www.chatbotty.ai/api/v1/tickets/TICKET_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'

Ações de webhook#

Gerencie as ações de webhook do chatbot: APIs externas ou webhooks de automação (por exemplo n8n) que o chatbot chama como ferramentas ao responder. Disponível no plano Automate (10 webhooks e 10 ferramentas por chatbot) e no teste Evaluation (5 webhooks e 5 ferramentas por chatbot). Os outros planos recebem 403 FORBIDDEN; ultrapassar os limites retorna 403 LIMIT_EXCEEDED. As chamadas não usam a cota de mensagens.

Endpoints

Método e caminhoDescriçãoFerramenta MCP
GET /webhooksListar webhooks e o uso dos seus limiteslist_webhook_actions
POST /webhooksCriar um webhook, opcionalmente com ferramentas; retorna 201create_webhook_action
GET /webhooks/{id}Um webhook com suas ferramentasget_webhook_action
PATCH /webhooks/{id}Alterar um webhookupdate_webhook_action
DELETE /webhooks/{id}Excluir um webhook com suas ferramentasdelete_webhook_action
POST /webhooks/{id}/toolsAdicionar uma ferramenta; retorna 201add_webhook_tool
PATCH /webhooks/{id}/tools/{toolId}Alterar uma ferramentaupdate_webhook_tool
DELETE /webhooks/{id}/tools/{toolId}Excluir uma ferramentadelete_webhook_tool
POST /webhooks/{id}/testChamar o webhook como o chatbot faztest_webhook_action

As leituras usam o limite de leitura (120 por minuto), as alterações o limite de escrita (60) e o teste tem seu próprio limite de 20 por minuto; veja Limites de taxa. A ferramenta MCP get_webhook_guide retorna um guia curto para assistentes de IA.

Campos do webhook

CampoDescrição
nameObrigatório, até 100 caracteres
webhook_urlObrigatório, endereço HTTPS público
http_methodPOST (padrão) ou GET
send_metadataPadrão true: a chamada também leva tool_name, args e metadata (chatbot_id, conversation_id, timestamp); false envia apenas os argumentos
timeout_ms1000 a 30000, padrão 10000
headersAté 20 cabeçalhos personalizados
secret_queryAté 10 parâmetros de query secretos, por exemplo uma chave de API
toolsFerramentas que o chatbot pode chamar (veja abaixo)

Campos da ferramenta

CampoDescrição
nameLetras minúsculas, dígitos e sublinhados, começa com uma letra, até 64 caracteres, único por chatbot; create_support_ticket é reservado
descriptionAté 500 caracteres; diz ao chatbot quando usar a ferramenta
parametersAté 10 itens com name, type (string, number, boolean), description (até 200 caracteres), required

Regras

  • Os valores de headers e secret_query nunca são retornados, apenas os seus nomes. Uma chave encontrada em webhook_url é movida automaticamente para secret_query e informada em warnings.
  • Alterar o endpoint de um webhook exige reenviar todos os headers e as chaves de secret_query armazenados, para que segredos não possam migrar para outro servidor sem serem notados.
  • O chatbot faz uma rodada de chamadas de ferramentas por resposta. Uma resposta é cortada em 10 KB, os redirecionamentos não são seguidos e os endereços internos são recusados.

Teste

POST /webhooks/{id}/test com um corpo opcional { "tool_name": "get_weather", "arguments": { "q": "Prague" } } retorna ok, status, response_time_ms, body_preview (primeiros 2 KB), truncated e warnings. Após um teste, faça ao chatbot uma pergunta correspondente por meio do chat e verifique tools_executed.

Erros#

As chamadas REST com falha retornam um status HTTP diferente de 2xx e este envelope:

{
  "success": false,
  "error": { "code": "INVALID_REQUEST", "message": "message is required and cannot be empty", "details": {} },
  "timestamp": "2026-01-01T10:00:00.000Z"
}

details está presente apenas em alguns erros. Trate os erros pelo code; as mensagens podem mudar.

Códigos de erro

CódigoHTTPSignificado
UNAUTHORIZED401Chave de API ausente, inválida ou desativada
QUOTA_EXCEEDED403Cota mensal de mensagens esgotada (details.quota_info)
FORBIDDEN403O recurso não está no seu plano
LIMIT_EXCEEDED403Limite do plano para webhooks ou ferramentas atingido (details.resource, used, max)
INVALID_REQUEST400Corpo ou parâmetros inválidos
INVALID_URL400A URL do webhook é inválida, não é HTTPS ou não é pública
INVALID_FILE400O arquivo está ausente no envio
FILE_TOO_LARGE400Arquivo acima de 10 MB
UNSUPPORTED_FILE_TYPE400Somente .pdf, .docx, .txt, .md são aceitos
CONVERSATION_NOT_FOUND400conversation_id não existe ou pertence a outro chatbot
EDIT_FAILED400Texto a substituir não encontrado, ou encontrado mais de uma vez
NOT_EDITABLE400Somente documentos .md e .txt em UTF-8 podem ser editados
NOT_FOUND404Documento, ticket, webhook, ferramenta ou envio não encontrado, ou chatbot inativo
DUPLICATE_FILENAME409Já existe um documento com este nome (details.existing_document_id)
DUPLICATE_CONTENT409O mesmo conteúdo já está indexado
REPLACE_IN_PROGRESS409O documento está sendo substituído ou processado; aguarde até ele estar completed
CONFLICT409O nome da ferramenta já existe, ou o documento mudou desde que você o leu
STORAGE_LIMIT_EXCEEDED413Limite de armazenamento do chatbot excedido
RATE_LIMITED429Requisições demais; veja Limites de taxa
GONE_USE_V1410O antigo endpoint /api/chat foi removido; use /api/v1/chat
INTERNAL_ERROR500Erro inesperado do servidor

Erros do MCP

O endpoint MCP responde com erros JSON-RPC: 401 para um token ausente ou inválido, 429 para requisições demais e 403 quando o plano não inclui MCP. Quando uma ferramenta falha, o resultado é marcado como erro e contém o código da API, por exemplo Chatbotty API error [NOT_FOUND] (HTTP 404). Veja Conector MCP.

Suporte

Se um erro persistir, escreva para support@chatbotty.ai e inclua o código, o horário e o endpoint.

Conector MCP#

O conector MCP permite que um assistente de IA como o Claude, o n8n ou o Cursor trabalhe com o seu chatbot: converse com ele, gerencie a sua base de conhecimento, configure ações de webhook e leia conversas, analytics e tickets. Um conector pertence a um chatbot; para usar outro chatbot, adicione outro conector.

Conexão

ItemValor
URL do servidorhttps://www.chatbotty.ai/api/mcp
TransporteStreamable HTTP sobre POST
PlanosTodos os planos; verificado a cada requisição
Limite300 requisições por minuto por chave (veja Limites de taxa)

Login ou chave

MétodoUsado porComo
Login (OAuth)claude.ai, Claude Desktop, Claude mobile, Claude CodeO cliente abre uma página do Chatbotty; você entra, escolhe o chatbot e clica em Permitir. Uma chave é criada automaticamente
Chave de APIn8n, Cursor, VS Code, outros clientesEnvie o cabeçalho Authorization: Bearer YOUR_API_KEY (Autenticação)

Uma chave criada por meio do login é rotulada como Conector MCP em API e MCP. Exclua-a ali para desconectar o assistente. Os tickets e as ferramentas de webhook aparecem somente se o seu plano os incluir. As etapas de configuração estão em Clientes MCP.

Ferramentas

ÁreaFerramentas
Chatbot e chatget_chatbot_info, send_message
Documentoslist_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document
Lacunas de conhecimentolist_knowledge_gaps
Conversaslist_conversations, get_conversation, get_conversation_messages
Analyticsget_analytics_summary, get_analytics_timeseries, get_top_queries
Tickets (planos com tickets)list_tickets, get_ticket, update_ticket_status, list_ticket_notes, add_ticket_note
Ações de webhook (planos com ações de webhook)get_webhook_guide, list_webhook_actions, get_webhook_action, create_webhook_action, update_webhook_action, test_webhook_action, delete_webhook_action, add_webhook_tool, update_webhook_tool, delete_webhook_tool

Cada ferramenta funciona como o endpoint REST correspondente descrito nas seções acima e tem os mesmos limites e erros.

Bom saber

  • send_message conversa com o chatbot como um visitante e usa a cota mensal de mensagens. test_webhook_action não usa.
  • list_knowledge_gaps lista as perguntas que o chatbot não conseguiu responder e precisa de um período; use-o para descobrir o que adicionar à base de conhecimento.
  • Um cliente pode manter em cache as descrições das ferramentas. Se as ferramentas parecerem desatualizadas, remova o conector e adicione-o novamente.

Clientes MCP#

Como conectar clientes comuns a https://www.chatbotty.ai/api/mcp. Para clientes que enviam uma chave, crie-a primeiro como descrito em Autenticação. Contexto: Conector MCP.

Claude (claude.ai, Claude Desktop, mobile)

  1. Abra Configurações, depois Conectores, e adicione um conector personalizado.
  2. Cole a URL do servidor e clique em Conectar.
  3. Entre no Chatbotty, escolha o chatbot e clique em Permitir.

Nenhuma chave de API é necessária. O conector também funciona, então, no app Claude para celular.

Claude Code

Entre pelo navegador:

claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp

Ou use uma chave de API:

claude mcp add --transport http chatbotty https://www.chatbotty.ai/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Quando a página de login avisar que o app é executado no seu próprio computador, permita o acesso somente se você mesmo iniciou a conexão.

n8n

  1. Adicione o nó MCP Client Tool.
  2. Endpoint: a URL do servidor.
  3. Server Transport: HTTP Streamable.
  4. Authentication: Bearer Auth com a sua chave de API.

Cursor, VS Code e outros clientes

Adicione um servidor MCP remoto com a URL do servidor e o cabeçalho Authorization: Bearer YOUR_API_KEY. No Cursor, por exemplo:

{
  "mcpServers": {
    "chatbotty": {
      "url": "https://www.chatbotty.ai/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Solução de problemas

ProblemaO que verificar
401A chave está errada, desativada ou excluída
Tickets ou ferramentas de webhook ausentesO seu plano não os inclui
Um cliente manual recebe 406O cliente deve enviar Accept: application/json, text/event-stream

Exemplos#

Exemplos prontos para copiar e colar das tarefas mais comuns. Substitua YOUR_API_KEY por uma chave de API e MCP e https://www.chatbotty.ai pela URL base. Veja Autenticação.

Verificar o chatbot e a cota

curl https://www.chatbotty.ai/api/v1/chatbot \
  -H "Authorization: Bearer YOUR_API_KEY"

Fazer uma pergunta e continuar a conversa

curl -X POST https://www.chatbotty.ai/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your opening hours?"}'

Pegue o conversation_id da resposta e envie-o com a mensagem seguinte:

curl -X POST https://www.chatbotty.ai/api/v1/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "And on Sunday?", "conversation_id": "CONVERSATION_ID"}'

Enviar um documento

curl -X POST https://www.chatbotty.ai/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@./faq.md"

Depois verifique o status até ele ser completed:

curl https://www.chatbotty.ai/api/v1/documents/DOCUMENT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Encontrar perguntas sem resposta

curl "https://www.chatbotty.ai/api/v1/analytics/top-queries?quality=not_answered&period=month" \
  -H "Authorization: Bearer YOUR_API_KEY"

Listar conversas que contêm uma palavra

curl "https://www.chatbotty.ai/api/v1/conversations?q=refund&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Tratar erros

{ "success": false, "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Maximum 60 requests per minute per API key." }, "timestamp": "2026-01-01T10:00:00.000Z" }

Trate com base em error.code e veja Erros. Para os limites, veja Limites de taxa. Dúvidas: support@chatbotty.ai.