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
| Item | Valor |
|---|---|
| URL base da REST | https://www.chatbotty.ai/api/v1 |
| URL do servidor MCP | https://www.chatbotty.ai/api/mcp |
| Formato | JSON sobre HTTPS |
| Autenticação | Authorization: Bearer YOUR_API_KEY |
| Escopo de uma chave | Uma 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.
| Recurso | Free | Evaluation | Support | Automate |
|---|---|---|---|---|
| Chat, documentos, conversas, analytics | Sim | Sim | Sim | Sim |
| Tickets | Não | Sim | Sim | Sim |
| Ações de webhook | Não | Sim | Não | Sim |
| Importação de documentos a partir de uma URL web | Não | Sim | Sim | Sim |
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 /chatou a ferramenta MCPsend_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 comGET /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
| Item | Valor |
|---|---|
| Formato | Uma string hexadecimal aleatória de 64 caracteres |
| Escopo | Um chatbot por chave |
| Limite | Até 50 chaves por chatbot (as chaves inativas também contam) |
| Armazenamento | Somente 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
- Abra API e MCP na barra lateral.
- No cartão do seu chatbot, clique em Criar nova chave de API, digite um nome (por exemplo "Production app") e clique em Criar.
- 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ção | Efeito |
|---|---|
| Desativar | A chave deixa de funcionar imediatamente; Ativar a reativa |
| Excluir | A 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ção | Resposta |
|---|---|
| Cabeçalho ausente ou malformado | 401 UNAUTHORIZED "Missing or invalid Authorization header" |
| Chave desconhecida ou desativada | 401 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
| Classe | Endpoints | Limite por minuto |
|---|---|---|
| Chat | POST /chat | 60 |
| Leitura | Todos os outros endpoints GET, exceto analytics (incluindo GET /chatbot) | 120 |
| Escrita | Endpoints POST, PATCH, DELETE | 60 |
| Analytics | GET /analytics/summary, /analytics/timeseries, /analytics/top-queries | 60 |
| Teste de webhook | POST /webhooks/{id}/test | 20 |
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
| Item | Valor |
|---|---|
| Método e caminho | GET https://www.chatbotty.ai/api/v1/chatbot |
| Parâmetros | Nenhum |
| Limite de taxa | Classe de leitura (veja Limites de taxa) |
| Cota | Não utilizada |
| Ferramenta MCP | get_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
planemessage_quotapertencem ao proprietário da conta; a cota é compartilhada por todos os chatbots da conta.featuresmostra 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;nullquando 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
| Item | Valor |
|---|---|
| Método e caminho | POST https://www.chatbotty.ai/api/v1/chat |
| Limite de taxa | Classe de chat: 60 por minuto |
| Cota | Uma mensagem por chamada; acima da cota, a chamada retorna 403 QUOTA_EXCEEDED |
| Ferramenta MCP | send_message |
Corpo da requisição
| Campo | Obrigatório | Descrição |
|---|---|---|
message | Sim | A pergunta do visitante (texto não vazio) |
conversation_id | Não | Continua uma conversa existente; omita para iniciar uma nova |
options | Não | Objeto 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 caminho | Descrição | Parâmetros principais | Ferramenta MCP |
|---|---|---|---|
GET /documents | Listar documentos | limit (padrão 20, máx. 100), offset, status | list_documents |
POST /documents | Enviar um documento; retorna 202 | Veja abaixo | upload_document |
POST /documents/upload-url | Obter uma URL assinada para um arquivo grande ou local | filename | create_upload_url |
GET /documents/{id} | Status e detalhes de um documento | - | get_document |
DELETE /documents/{id} | Excluir um documento | - | delete_document |
GET /documents/{id}/content | Ler o texto, paginado | offset, limit (padrão 20000, máx. 50000) | read_document |
PATCH /documents/{id}/content | Editar um documento .md ou .txt | edits, append, expected_hash | edit_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.
| Campo | Descrição |
|---|---|
file | O arquivo (somente multipart) |
content | Texto de um documento .md ou .txt (JSON; filename obrigatório) |
content_base64 | Arquivo binário em base64 (JSON; use até cerca de 3 MB) |
url | URL pública de um arquivo que o servidor baixa (JSON; somente planos com importação de URL web) |
upload_id | Id de POST /documents/upload-url depois que você enviou o arquivo |
filename | Nome do arquivo com extensão |
description | Descrição opcional |
replace_existing | Padrã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
POST /documents/upload-urlcom{ "filename": "price-list.pdf" }. A resposta contémupload_id,upload_urle cabeçalhos; a URL é válida por 2 horas e funciona uma única vez.- Envie o arquivo bruto com
PUTparaupload_url. POST /documentscom{ "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}/contentenvia apenas a alteração:edits(lista deold_textenew_text, cadaold_textdeve ocorrer exatamente uma vez, até 100) e/ouappend(text,after_headingopcional).expected_hash(deGET .../content) protege contra a sobrescrita de uma versão mais nova (409 CONFLICT).- Somente documentos
.mde.txtem UTF-8 podem ser editados (400 NOT_EDITABLEcaso contrário). - Toda edição ou substituição cria um novo
document_id; a versão antiga continua respondendo até a nova estarcompleted. - 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 caminho | Descrição | Parâmetros principais | Ferramenta MCP |
|---|---|---|---|
GET /conversations | Listar conversas | Veja abaixo | list_conversations |
GET /conversations/{id} | Uma conversa | - | get_conversation |
GET /conversations/{id}/messages | Mensagens em ordem cronológica | limit (padrão 50, máx. 200), offset | get_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âmetro | Descrição |
|---|---|
limit, offset | Paginação (padrão 20, máx. 100) |
status | active, completed ou ticket_created |
source | widget ou api |
from, to | Datas ISO 8601; filtram pelo início da conversa |
quality | Conversas com pelo menos uma pergunta deste tipo: answered, not_answered, conversation, off_topic, ticket_created, tool_call, not_classified |
q | Busca 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 caminho | Descrição | Ferramenta MCP |
|---|---|---|
GET /analytics/summary | Totais do período | get_analytics_summary |
GET /analytics/timeseries | Contagens por hora, dia ou semana | get_analytics_timeseries |
GET /analytics/top-queries | Perguntas mais frequentes | get_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âmetro | Descrição |
|---|---|
period | today (padrão), week, month ou quarter, avaliado no fuso horário do chatbot |
from, to | Datas ISO 8601; substituem period; o intervalo é de no máximo 366 dias |
source | widget ou api |
Parâmetros adicionais
| Endpoint | Parâmetro | Descrição |
|---|---|---|
timeseries | granularity | auto (padrão), hour, day ou week; hour com quarter é recusado |
top-queries | limit, offset | Paginação (padrão 20, máx. 100) |
top-queries | quality | answered, 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 caminho | Descrição | Parâmetros principais | Ferramenta MCP |
|---|---|---|---|
GET /tickets | Listar tickets, os mais recentes primeiro | limit (padrão 20, máx. 100), offset, status, conversation_id, from, to | list_tickets |
GET /tickets/{id} | Um ticket | - | get_ticket |
PATCH /tickets/{id} | Alterar o status | status no corpo | update_ticket_status |
GET /tickets/{id}/notes | Notas internas, as mais antigas primeiro | - | list_ticket_notes |
POST /tickets/{id}/notes | Adicionar uma nota; retorna 201 | content no corpo | add_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
| Item | Valor |
|---|---|
| Status | open, in_progress, resolved, closed |
| Nota | Texto 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 caminho | Descrição | Ferramenta MCP |
|---|---|---|
GET /webhooks | Listar webhooks e o uso dos seus limites | list_webhook_actions |
POST /webhooks | Criar um webhook, opcionalmente com ferramentas; retorna 201 | create_webhook_action |
GET /webhooks/{id} | Um webhook com suas ferramentas | get_webhook_action |
PATCH /webhooks/{id} | Alterar um webhook | update_webhook_action |
DELETE /webhooks/{id} | Excluir um webhook com suas ferramentas | delete_webhook_action |
POST /webhooks/{id}/tools | Adicionar uma ferramenta; retorna 201 | add_webhook_tool |
PATCH /webhooks/{id}/tools/{toolId} | Alterar uma ferramenta | update_webhook_tool |
DELETE /webhooks/{id}/tools/{toolId} | Excluir uma ferramenta | delete_webhook_tool |
POST /webhooks/{id}/test | Chamar o webhook como o chatbot faz | test_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
| Campo | Descrição |
|---|---|
name | Obrigatório, até 100 caracteres |
webhook_url | Obrigatório, endereço HTTPS público |
http_method | POST (padrão) ou GET |
send_metadata | Padrão true: a chamada também leva tool_name, args e metadata (chatbot_id, conversation_id, timestamp); false envia apenas os argumentos |
timeout_ms | 1000 a 30000, padrão 10000 |
headers | Até 20 cabeçalhos personalizados |
secret_query | Até 10 parâmetros de query secretos, por exemplo uma chave de API |
tools | Ferramentas que o chatbot pode chamar (veja abaixo) |
Campos da ferramenta
| Campo | Descrição |
|---|---|
name | Letras minúsculas, dígitos e sublinhados, começa com uma letra, até 64 caracteres, único por chatbot; create_support_ticket é reservado |
description | Até 500 caracteres; diz ao chatbot quando usar a ferramenta |
parameters | Até 10 itens com name, type (string, number, boolean), description (até 200 caracteres), required |
Regras
- Os valores de
headersesecret_querynunca são retornados, apenas os seus nomes. Uma chave encontrada emwebhook_urlé movida automaticamente parasecret_querye informada emwarnings. - Alterar o endpoint de um webhook exige reenviar todos os
headerse as chaves desecret_queryarmazenados, 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ódigo | HTTP | Significado |
|---|---|---|
UNAUTHORIZED | 401 | Chave de API ausente, inválida ou desativada |
QUOTA_EXCEEDED | 403 | Cota mensal de mensagens esgotada (details.quota_info) |
FORBIDDEN | 403 | O recurso não está no seu plano |
LIMIT_EXCEEDED | 403 | Limite do plano para webhooks ou ferramentas atingido (details.resource, used, max) |
INVALID_REQUEST | 400 | Corpo ou parâmetros inválidos |
INVALID_URL | 400 | A URL do webhook é inválida, não é HTTPS ou não é pública |
INVALID_FILE | 400 | O arquivo está ausente no envio |
FILE_TOO_LARGE | 400 | Arquivo acima de 10 MB |
UNSUPPORTED_FILE_TYPE | 400 | Somente .pdf, .docx, .txt, .md são aceitos |
CONVERSATION_NOT_FOUND | 400 | conversation_id não existe ou pertence a outro chatbot |
EDIT_FAILED | 400 | Texto a substituir não encontrado, ou encontrado mais de uma vez |
NOT_EDITABLE | 400 | Somente documentos .md e .txt em UTF-8 podem ser editados |
NOT_FOUND | 404 | Documento, ticket, webhook, ferramenta ou envio não encontrado, ou chatbot inativo |
DUPLICATE_FILENAME | 409 | Já existe um documento com este nome (details.existing_document_id) |
DUPLICATE_CONTENT | 409 | O mesmo conteúdo já está indexado |
REPLACE_IN_PROGRESS | 409 | O documento está sendo substituído ou processado; aguarde até ele estar completed |
CONFLICT | 409 | O nome da ferramenta já existe, ou o documento mudou desde que você o leu |
STORAGE_LIMIT_EXCEEDED | 413 | Limite de armazenamento do chatbot excedido |
RATE_LIMITED | 429 | Requisições demais; veja Limites de taxa |
GONE_USE_V1 | 410 | O antigo endpoint /api/chat foi removido; use /api/v1/chat |
INTERNAL_ERROR | 500 | Erro 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
| Item | Valor |
|---|---|
| URL do servidor | https://www.chatbotty.ai/api/mcp |
| Transporte | Streamable HTTP sobre POST |
| Planos | Todos os planos; verificado a cada requisição |
| Limite | 300 requisições por minuto por chave (veja Limites de taxa) |
Login ou chave
| Método | Usado por | Como |
|---|---|---|
| Login (OAuth) | claude.ai, Claude Desktop, Claude mobile, Claude Code | O cliente abre uma página do Chatbotty; você entra, escolhe o chatbot e clica em Permitir. Uma chave é criada automaticamente |
| Chave de API | n8n, Cursor, VS Code, outros clientes | Envie 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
| Área | Ferramentas |
|---|---|
| Chatbot e chat | get_chatbot_info, send_message |
| Documentos | list_documents, get_document, read_document, upload_document, create_upload_url, edit_document, append_to_document, delete_document |
| Lacunas de conhecimento | list_knowledge_gaps |
| Conversas | list_conversations, get_conversation, get_conversation_messages |
| Analytics | get_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_messageconversa com o chatbot como um visitante e usa a cota mensal de mensagens.test_webhook_actionnão usa.list_knowledge_gapslista 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)
- Abra Configurações, depois Conectores, e adicione um conector personalizado.
- Cole a URL do servidor e clique em Conectar.
- 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
- Adicione o nó MCP Client Tool.
- Endpoint: a URL do servidor.
- Server Transport: HTTP Streamable.
- 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
| Problema | O que verificar |
|---|---|
401 | A chave está errada, desativada ou excluída |
| Tickets ou ferramentas de webhook ausentes | O seu plano não os inclui |
Um cliente manual recebe 406 | O 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.