## 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: - **Swagger-UI (interativa)** — a mesma referência com o botão **"Try it out"** para fazer chamadas reais à API direto do navegador: - **Definição OpenAPI (JSON)** — o arquivo bruto para importar no Postman, Insomnia ou gerar SDKs: 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 1. Abra a referência em (ReDoc) e navegue pelos grupos de módulos na barra lateral. 2. Localize o endpoint desejado (por método e caminho) e leia parâmetros, corpo e respostas. 3. Para **testar**, abra a referência interativa em . 4. Leia o requisito de segurança da operação antes de clicar em **Authorize**; informe somente a credencial compatível com aquele caminho. 5. 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. 6. 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 ` 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. ## Veja também - [SDK, API REST e MCP de Dashboard Apps](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-pt-br) - [API REST, tokens e webhooks](/hc/ajuda/articles/api-developers-rest-tokens-webhooks-pt-br) - [Visão geral de API & Desenvolvedores](/hc/ajuda/articles/api-developers-overview-pt-br) - [Eventos por módulo](/hc/ajuda/articles/api-developers-eventos-por-modulo-pt-br)