Visão geral
A Conversa Labs publica uma referência completa da API no formato OpenAPI 3.1, gerada automaticamente a partir das rotas reais do produto. Ela cobre todos os módulos — conversas, contatos, CRM, catálogo, pagamentos, agenda, tarefas, follow-ups, vendas e gamificação, WhatsApp e muito mais — e fica sempre em sincronia com a API a cada build.
Há duas 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
Pré-requisitos
- Um token de acesso válido (gerado no seu perfil/conta). Veja o artigo de API REST e tokens.
- 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.
- Clique em Authorize e informe o seu token no cabeçalho
api_access_token. - Escolha um endpoint, clique em Try it out, preencha os parâmetros e clique em Execute.
- Confira a resposta (status, corpo) e use o exemplo de requisição (cURL) gerado na sua integração.
Configurações & opções
- Geração automática: a referência é montada a partir da introspecção das rotas reais da aplicação, então novos endpoints aparecem automaticamente.
- Autenticação: todos os endpoints autenticados usam o cabeçalho
api_access_token. - Disponibilidade: em instalações self-hosted, a documentação é habilitada pelo operador por
meio de uma variável de ambiente (
ENABLE_API_DOCS). Na Conversa Labs hospedada, ela já fica disponível nos endereços acima.
Casos de uso
- Descobrir rapidamente quais endpoints existem para um módulo (CRM, Pagamentos, Catálogo, etc.).
- Testar uma chamada com o seu token antes de escrevê-la no código.
- Importar a definição OpenAPI no Postman/Insomnia ou gerar um SDK cliente.
Dicas, limites e boas práticas
- Trate o token como segredo — não o compartilhe nem o exponha no front-end.
- Para testes, use um token com escopo mínimo e, de preferência, de um ambiente de testes.
- Respeite os limites de taxa e trate erros 429/5xx com backoff.
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: o token é inválido ou não tem permissão; gere um novo e confira o escopo.
- Endpoint não aparece: ele pode exigir um módulo/recurso não habilitado na sua conta.