Referência de API (Swagger / OpenAPI)

Abrir em

Ver como Markdown

Abrir no ChatGPT Abrir no Claude

Conversa Labs

Última atualização em 21 de out de 2026

Visão geral

A ConversaLabs publica uma referência OpenAPI 3.1 de superfície pública, útil para descobrir e integrar os endpoints que fazem parte desse contrato. Ela é produzida a partir das rotas e de fontes curadas; não é uma garantia de que toda rota interna, todo módulo habilitável ou todo formulário da instalação tenha uma operação publicada automaticamente.

Há três formas de visualizar a mesma referência:

ReDoc (leitura) — uma documentação navegável, organizada por grupos e tags, ideal para entender o contrato de cada endpoint: https://app.conversalabs.com.br/swagger
Swagger-UI (interativa) — a mesma referência com o botão "Try it out" para fazer chamadas reais à API direto do navegador: https://app.conversalabs.com.br/swagger/ui.html
Definição OpenAPI (JSON) — o arquivo bruto para importar no Postman, Insomnia ou gerar SDKs: https://app.conversalabs.com.br/swagger/swagger.json

A referência agrupa, entre outras, estas famílias: Account/AgentBot em /api/v1, Platform em /platform, Widget em /api/v1/widget, rotas public em /public/api, desafios e metadados públicos necessários à descoberta, além dos caminhos de webhook que pertencem ao contrato. Leia a segurança declarada em cada operação: não existe um token universal.

Pré-requisitos

A credencial exigida pela operação: um token de conta/AgentBot, a chave de uma Platform App, um token público próprio do recurso ou nenhuma credencial, conforme o contrato.
Um navegador moderno. Para testar chamadas, prefira um token de um ambiente de testes.

Passo a passo

Abra a referência em https://app.conversalabs.com.br/swagger (ReDoc) e navegue pelos grupos de módulos na barra lateral.
Localize o endpoint desejado (por método e caminho) e leia parâmetros, corpo e respostas.
Para testar, abra a referência interativa em https://app.conversalabs.com.br/swagger/ui.html.
Leia o requisito de segurança da operação antes de clicar em Authorize; informe somente a credencial compatível com aquele caminho.
Escolha um endpoint, clique em Try it out, preencha os parâmetros e clique em Execute quando o ambiente de testes e a operação permitirem.
Confira a resposta (status, corpo) e use o exemplo de requisição (cURL) gerado na sua integração.

Configurações & opções

Cobertura e autenticação: rotas novas precisam ser incluídas e revisadas no contrato; operações diferentes podem usar api_access_token, uma chave de Platform App, token de recurso ou segurança explícita vazia. Nunca copie uma credencial entre superfícies por suposição.
Webhooks de entrada: um caminho só aceita chamadas quando o recurso que o configura está ativo e validado. A autenticação varia por provedor ou recurso (por exemplo, assinatura, segredo, token de verificação ou desafio), portanto ele não é uma API REST genérica para testar com um token de conta.
Metrics: /monitoring/metrics não é uma operação de cliente. Fica inerte até o operador definir OPERATIONS_METRICS_TOKEN e exige Authorization: Bearer <token> para uma coleta autorizada.
MCP e operador: o MCP usa seus próprios perfis, URLs e credenciais Bearer/OAuth. A REST do operador é uma referência separada e não é servida em /swagger.
Disponibilidade: em instalações self-hosted, a documentação é habilitada pelo operador por meio de uma variável de ambiente (ENABLE_API_DOCS). Na ConversaLabs hospedada, ela já fica disponível nos endereços acima.

Casos de uso

Descobrir se uma integração pertence à API de conta/AgentBot, Platform, Widget ou a uma superfície pública.
Conferir os requisitos de uma operação antes de testar uma chamada em ambiente controlado.
Importar a definição OpenAPI no Postman/Insomnia ou gerar um SDK cliente.

Dicas, limites e boas práticas

Trate qualquer token ou segredo como confidencial; não o exponha no front-end nem o reutilize entre Account/AgentBot, Platform, Widget, MCP e Metrics.
Para testes, use uma credencial de menor privilégio e confirme no contrato se a operação é autenticada, pública ou um webhook de entrada condicionado.
Respeite os limites de taxa e trate erros 429/5xx com backoff.

Tipos e respostas na integração

Use o schema de cada resposta, além do exemplo, ao gerar ou validar seu cliente:

Na agenda, all_day é booleano e os valores de reminders são inteiros em minutos.
No perfil, accounts[] inclui o andamento da configuração, o identificador do papel de acesso e api_and_webhooks. O objeto access_role aparece somente quando há um papel efetivo; dados condicionados à permissão continuam condicionados no servidor.
No Cérebro, signals e suggested_action podem preservar arrays JSON. Não os force a mapas; a leitura e a ocultação de dados continuam seguindo as permissões do solicitante.
Uma inscrição de Follow-up pode responder 422 com error (motivo de recusa) ou com message e attributes (falha de validação). Leia a variante recebida antes de decidir a próxima ação.

Solução de problemas

A página não abre (404): a documentação pode estar desabilitada no ambiente — o operador a habilita com ENABLE_API_DOCS.
401/403 ao testar: confirme a superfície e o esquema de segurança; um api_access_token não autoriza automaticamente Platform, MCP, Metrics ou rotas públicas.
Endpoint não aparece: ele pode não fazer parte da referência pública, exigir fonte curada ou pertencer à REST separada do operador.