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.

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.

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

---