Visão geral

O Quickchat AI oferece uma REST API para acesso programático à configuração do seu Agente de IA, à Base de Conhecimento, às Conversas, às AI Actions e muito mais.

Verificações opcionais com exemplos

• Comparar métodos de implantação. Compare os canais, o acesso ao site e os recursos declarados com as opções do Quickchat AI. Seu site e sua conta não são inspecionados.

• Verificar uma conexão MCP de exemplo. Inicialize e liste ferramentas somente no endpoint da documentação Cloudflare ou do Microsoft Learn. Não faz login nem executa ferramentas.

Autenticação

Todos os endpoints da API usam autenticação por Bearer token. Inclua seu token de API no header Authorization de cada requisição:

Authorization: Bearer <API_TOKEN>

Os tokens são criados no Dashboard do Quickchat em External Apps > API. Cada token é um JWT que contém seu scenario_id, então nenhum header de identificador adicional é necessário.

• Validade do token: 52 semanas a partir da criação
• Os tokens podem ser revogados a qualquer momento pelo Dashboard
• Cada token é vinculado a um único Agente de IA (scenario)
• A criação de tokens requer o plano Business ou superior; em planos inferiores a opção fica desativada e o endpoint retorna 402 Payment Required

Nota

O endpoint de Chat em tempo real (POST https://app.quickchat.ai/chat) aceita o mesmo Bearer token que o restante desta API, mas fica fora do caminho base /v1/api/ e exige scenario_id no corpo da requisição. Consulte a página Chat para a referência completa.

Escopos de Token

Os tokens de API são criados com um de dois escopos:

Scope	Access Level	Description
read_all	Read-only	Pode ler todos os recursos, mas não pode criar, atualizar ou excluir
write_all	Read + Write	Acesso total a todos os endpoints, incluindo operações de escrita

• Um escopo é atribuído aos tokens quando são criados no Dashboard em External Apps > API
• O escopo write_all inclui automaticamente todas as permissões de read_all
• Usar um token read_all em um endpoint de escrita retorna 403 com "Insufficient token scope. Required: write_all"

Dica

Use tokens read_all para monitoramento, analytics e integrações somente leitura. Use tokens write_all apenas quando sua integração precisar criar ou modificar recursos.

Requisitos de escopo por grupo de endpoints:

Endpoint Group	Read Operations	Write Operations
Chatbot Settings	read_all	write_all
Knowledge Base Settings	read_all	write_all
Articles	read_all	write_all
Article Language URLs	read_all	write_all
Tags	read_all	—
File Upload	—	write_all
Import External Content	—	write_all
Intercom Knowledge Base	read_all	write_all
Widget Configuration	read_all	write_all
Conversations	read_all	—
Conversation Metadata	read_all	write_all
Handoff Configuration	read_all	write_all
Conversation Rating	read_all	write_all
AI Actions	read_all	write_all

URL Base

Endpoint Group	Base URL
Knowledge Base, AI Actions, File Upload, Import, Chatbot Settings, Widget, Handoff, Conversation Rating	https://app.quickchat.ai/v1/api/
Conversations	https://app.quickchat.ai/v1/api_core/
Realtime Chat	https://app.quickchat.ai/chat

Limites de Requisições

Os limites de requisições são aplicados por token, por endpoint.

Tier	Limit	Applies To
READ	120 requisições/min	Operações GET e de listagem
WRITE	60 requisições/min	POST, PATCH, PUT, DELETE
HEAVY	20 requisições/min	Upload de arquivos, importações, scraping

Quando um limite de requisições é excedido, a API retorna HTTP 429 Too Many Requests.

Webhooks

A Quickchat AI não envia webhooks de saída. Não há como assinar um evento e fazer com que a gente envie um POST para o seu endpoint quando uma mensagem chega, uma conversa é transferida ou uma conversa é encerrada.

As alternativas disponíveis têm finalidades diferentes:

• AI Actions: chamam sua API durante uma conversa. As API Actions oferecem os modos A AI decide, Antes da primeira resposta e Quando os metadados correspondem. Os modos automáticos tentam fazer uma chamada uma vez por conversa, nas condições documentadas; eles não são assinaturas de cada mensagem ou transferência. Use-os para tarefas como registrar um lead ou avisar seu sistema quando os dados necessários estiverem disponíveis.
• Google Sheets: adiciona uma linha quando sua Action é executada. Não registra automaticamente cada mensagem ou transferência.
• Consultar periodicamente a API de Conversations: recupera as conversas armazenadas e seus eventos, incluindo mensagens e os marcadores de transferência que tenham sido registrados. Siga a paginação e respeite o limite de requisições READ acima. O polling introduz um atraso; comparar o estado da conversa entre consultas pode deixar passar alterações intermediárias. Não presuma que isso fornece um histórico completo de todas as transferências ou mudanças de atribuição.

O acesso à API exige o plano Business; veja Planos e limites.

Paginação

Os endpoints de listagem suportam paginação via query parameters:

Parameter	Description
limit integer	Número de itens por página
offset integer	Número de itens a pular

As respostas paginadas seguem esta estrutura:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Tratamento de Erros

Todos os erros são retornados em JSON no seguinte formato:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Status	Code	Description
400	BAD_REQUEST	Entrada inválida ou campos obrigatórios ausentes
401	PERMISSION_DENIED	Token inválido, expirado ou revogado
402	PAYMENT_REQUIRED	Assinatura ativa necessária
403	PERMISSION_DENIED	O token não tem o escopo necessário para esta operação
404	NOT_FOUND	Recurso não encontrado
409	CONFLICT	Operação conflitante (ex.: modificação simultânea)
422	VALIDATION_ERROR	O corpo da requisição falhou na validação do schema
429	TOO_MANY_REQUESTS	Limite de requisições excedido
500	UNKNOWN	Erro interno do servidor
503	SERVICE_UNAVAILABLE	Indisponibilidade temporária

---