API & Desenvolvedores
Por Conversa Labs
Por Conversa Labs
API REST, tokens, webhooks, SDK de Custom Scripts e eventos por módulo.
Visão geral de API & Desenvolvedores
Visão geral A ConversaLabs oferece recursos para desenvolvedores integrarem sistemas externos: uma API REST para ler e gravar dados, webhooks para receber eventos em tempo real, um SDK de Custom Scripts para estender as interfaces e eventos por módulo para reagir a mudanças. Pré-requisitos - Conta com permissão para gerar tokens de API. - Conhecimento básico de HTTP/JSON. Passo a passo 1. Gere um token de acesso nas configurações do seu perfil/conta. 2. Faça chamadas à API REST autenticando com o token. 3. Configure webhooks para receber eventos no seu endpoint. 4. Use Custom Scripts para personalizar o dashboard, o portal e o widget. Configurações & opções - Tokens: por usuário/conta, com escopo de acesso. - Webhooks: assinatura de eventos por inbox/conta. - Custom Scripts: JS/CSS injetados nas superfícies suportadas. Casos de uso - Sincronizar contatos e conversas com um CRM externo. - Disparar automações no seu sistema quando algo muda na plataforma. Dicas, limites e boas práticas - Trate tokens como segredos; nunca os exponha no front-end. - Respeite limites de taxa e trate erros/retentativas. Solução de problemas - 401/403: verifique o token e as permissões. - Webhook não chega: confira a URL, o status do endpoint e a assinatura. Veja também - API REST, tokens e webhooks - SDK de Custom Scripts
API REST, tokens e webhooks
Visão geral A API REST permite ler e gravar dados da plataforma (contatos, conversas, mensagens e mais). A autenticação é por token de acesso, e os webhooks entregam eventos ao seu sistema em tempo real. Pré-requisitos - Token de acesso válido. - Um endpoint HTTPS para receber webhooks. Passo a passo 1. Gere um token de acesso nas configurações. 2. Inclua o token no cabeçalho de autenticação das chamadas à API. 3. Faça requisições aos recursos da API (ex.: listar contatos, criar conversa). 4. Configure um webhook informando a URL e os eventos desejados. 5. Valide a assinatura/segredo do webhook antes de processar o payload. Configurações & opções - Escopo do token: limite o acesso ao necessário. - Eventos do webhook: assine apenas os eventos que você usa. - Reentrega: trate retentativas e idempotência no seu endpoint. Casos de uso - Espelhar conversas em um data warehouse. - Notificar um sistema externo quando uma conversa é criada ou resolvida. Dicas, limites e boas práticas - Sempre verifique a assinatura do webhook antes de agir. - Garanta idempotência (dedup por identificador do evento). - Respeite limites de taxa e use backoff em erros 429/5xx. Solução de problemas - 401/403: token inválido ou sem permissão. - Webhook duplicado: implemente dedup por ID do evento. Veja também - Visão geral de API & Desenvolvedores - Eventos por módulo
SDK de Custom Scripts
Visão geral Os Custom Scripts permitem injetar JavaScript/CSS em superfícies específicas da plataforma — o dashboard, o portal da Central de Ajuda e o widget de chat. Eles são úteis para pequenas personalizações de comportamento e estilo sem alterar o código-base. Pré-requisitos - Permissão de administrador para gerenciar Custom Scripts. - Conhecimento de JavaScript/CSS. Passo a passo 1. Acesse o módulo de Custom Scripts. 2. Crie um script e escolha a superfície (dashboard, portal ou widget). 3. Defina o tipo (JS ou CSS) e quando ele deve rodar. 4. Use o contexto ctx fornecido pelo runtime para interagir com a superfície de forma segura. 5. Implemente o teardown para limpar o que o script criou, quando aplicável. Configurações & opções - Superfície: dashboard / portal / widget. - Tipo: JS ou CSS. - Execução: regras de quando o script roda. Casos de uso - Adicionar um botão ou aviso em uma tela específica. - Ajustar estilos pontuais de uma superfície. - Registrar eventos de uso para análise interna. Dicas, limites e boas práticas - Escreva scripts idempotentes e com teardown para evitar duplicação. - Evite dependências pesadas; prefira código enxuto. - Teste em ambiente controlado antes de publicar. Solução de problemas - Script não executa: confirme a superfície e as regras de execução. - Comportamento duplicado: verifique o teardown e a idempotência. Veja também - Visão geral de API & Desenvolvedores - Custom Scripts (Administração)
Eventos por módulo
Visão geral Vários módulos da plataforma emitem eventos quando algo muda — uma conversa é criada, um pagamento é confirmado, um negócio muda de etapa, etc. Você pode reagir a esses eventos via webhooks ou pelas regras de automação internas. Pré-requisitos - Webhooks configurados (para consumo externo) ou acesso à Automação (para reações internas). Passo a passo 1. Identifique o evento do módulo que você quer consumir (ex.: conversa criada, pagamento pago). 2. Para consumo externo: assine o evento no webhook e trate o payload no seu endpoint. 3. Para reações internas: crie uma regra de automação com o gatilho correspondente. 4. Valide e processe o payload de forma idempotente. Configurações & opções - Webhooks: assinatura por inbox/conta. - Automação: gatilhos por evento, com condições e ações. - Payload: contém o contexto do evento (ids e dados relevantes). Casos de uso - Atualizar um sistema externo quando um pagamento é confirmado. - Disparar uma cadência de follow-up quando um negócio muda de etapa. Dicas, limites e boas práticas - Consulte sempre a fonte real do payload antes de mapear campos (não invente formato). - Garanta idempotência por identificador do evento. Solução de problemas - Evento não chega: confirme a assinatura e o status do endpoint. - Campos inesperados: revise o payload real recebido e ajuste o mapeamento. Veja também - API REST, tokens e webhooks - Regras de automação