API & Desenvolvedores

Visão geral de API & Desenvolvedores

Visão geral A Conversa Labs oferece API REST, ferramentas MCP para agentes governados, webhooks em tempo real, um SDK de Dashboard Apps para contexto incorporado seguro, 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. 5. Use o SDK V2 de Dashboard Apps para um app incorporado limitado e REST ou MCP para administrar suas instalações nativas. 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. - Dashboard Apps: ponte versionada de contexto somente leitura; escritas ficam no REST/MCP. 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 - SDK, API REST e MCP de Dashboard Apps - API REST, tokens e webhooks - SDK de Custom Scripts - Referência de API (Swagger / OpenAPI)

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. - Segredo de assinatura: ele aparece uma única vez, logo após a criação do webhook. Copie e guarde com segurança; listagem e edição apenas confirmam que há um segredo configurado e nunca o revelam. Se ele for perdido, crie um webhook substituto e depois remova o destino antigo. - Entrega durável: cada envio de webhook de conta é registrado antes de entrar na fila. Erros de rede e respostas 5xx usam retentativas com backoff e permanecem visíveis no histórico. - Histórico e reenvio: em Configurações → Integrações → Webhooks, abra o histórico do destino para buscar, filtrar e ordenar tentativas. Um administrador pode reenviar uma ou várias linhas; em lote, a tela separa os IDs processados dos que falharam. - Payload de Commerce: o padrão envia somente os identificadores canônicos. Ative Incluir dados comerciais no destino apenas quando o sistema receptor precisar de comprador, produto/variação e itens normalizados. O opt-in não inclui credenciais nem o payload bruto do gateway. - Reentrega no receptor: use o cabeçalho X-Chatwoot-Delivery como chave de idempotência; um reenvio manual reutiliza o mesmo identificador. Catálogo de eventos (grupos de módulos) Todos os eventos abaixo são assinaturas de nível de conta (configuradas por conta, na tela de Webhooks). Para um módulo entregar seus eventos, o recurso do módulo precisa estar habilitado na conta — a assinatura é aceita mesmo com o recurso desligado, mas nada é entregue até ativá-lo. - Conversas, mensagens, contatos, caixa de entrada e digitação — ciclo de vida do atendimento. - CRM (negócios) — criação, etapa, ganho/perdido, prioridade, valor, saúde, checklist, SLA e datas de fechamento. - Catálogo e Commerce — produtos, variações/estoque e ciclo de pagamento do Commerce. - Pedidos e receita — registro de pedido, status, pago, reembolsado, receita e afiliados. - Tarefas, Agenda e agendamentos, Pagamentos e Follow-ups — ciclos de vida de cada módulo. - Contratos e assinatura eletrônica, Gestão de Vendas e Engajamento/Lead Score. - Account Brain — risco, insights, execução de departamento e melhorias propostas. - Distribuição (Grupos de Lançamento) — inscrição, convite, entrada de membros e conclusão de unidades. - Growth Social e Ads — comentários, leads de anúncio, status de campanha e janela do Clique-para-WhatsApp. - WhatsApp Hub — transmissões, eventos de participantes e boas-vindas/despedidas de grupo (Cloud e WazMeow). - Chamadas e respostas de Flow do WhatsApp — ciclo de vida das chamadas e respostas de WhatsApp Flows. - Gestão de Equipe — mudança de status, pausas e turnos dos agentes. - FlowBuilder — ciclo de vida das sessões de fluxo. - Roteamento Inteligente — atribuição de agente. Os campos reais de cada payload estão em Eventos por módulo. 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 com X-Chatwoot-Delivery, inclusive em retentativas e reenvios manuais. - 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: confirme se o receptor deduplica X-Chatwoot-Delivery. - Entrega falhou: abra o histórico do destino, confira status HTTP/erro e a próxima tentativa. Após corrigir o receptor, selecione a linha e confirme o reenvio. Veja também - SDK, API REST e MCP de Dashboard Apps - Visão geral de API & Desenvolvedores - Eventos por módulo - Referência de API (Swagger / OpenAPI)

Canal de API: o contrato de eventos estruturados

Visão geral O canal de API é uma caixa de entrada de primeira classe. Qualquer módulo da plataforma o alcança da mesma forma que alcança o WhatsApp ou o widget web: ele cria uma mensagem em uma conversa. Essa mensagem é então enviada via POST — assinada — para a URL do webhook da sua caixa de entrada. Como todo payload de mensagem carrega o content_type completo e os content_attributes, o conteúdo estruturado (botões interativos, CTAs de pagamento, cards de catálogo, eventos de agenda e reações) chega à sua integração de forma nativa — você o renderiza. Tudo aqui é aditivo e retrocompatível: integrações existentes continuam funcionando e podem ignorar qualquer campo que não reconheçam. Não há novos campos obrigatórios. Pré-requisitos - Uma caixa de entrada de API com uma URL de webhook configurada. - O secret da caixa de entrada para verificar a assinatura do webhook (e, opcionalmente, o hmac_token para HMAC de entrada). - Um access token para a API REST quando você enviar dados de volta. Passo a passo 1. Crie uma caixa de entrada de API e defina sua URL de webhook. 2. Receba eventos nessa URL e verifique a assinatura com o secret da caixa de entrada. 3. Leia content_type + content_attributes em cada payload de mensagem para renderizar conteúdo rico. 4. Envie mensagens de entrada, recibos de entrega e reações de volta através da API REST. 5. (Opcional) Restrinja quais eventos você recebe com webhook_subscriptions. Tipos de conteúdo de saída (o que o webhook entrega) Cada payload de message_created / message_updated inclui content_type, content, content_attributes e attachments. Além do text simples, a caixa de entrada de API pode entregar: - input_select — opções interativas em content_attributes.items ([{title, value}]). Quando um canal não consegue renderizar as opções, a plataforma também anexa um menu numerado ao content. - content_attributes.payment_interactive — uma ação de pagamento: { body, buttons: [{ type: "cta_url", text, url } | { type: "cta_copy", text, code }] }. A cobrança completa (valor, código PIX, boleto, links) também chega como content_attributes.payment_charge na mensagem de resumo. - content_attributes.catalog_product — um card de produto: { mode: "single" | "list", products: [{ id, name, price, currency, image_url, ... }] }. - content_attributes.calendar_event — uma confirmação de agendamento ou lembrete: { id, title, starts_at, ends_at, location, meet_url, kind: "confirmation" | "reminder" } (horários em ISO-8601). - content_attributes.reactions — um array de { emoji, sender_jid }. O operador é me; um contato é armazenado sob seu próprio identificador. As reações viajam no evento message_updated. - Templates — os metadados do template enviado viajam em additional_attributes.template_params ({ name, language, category, processed_params }). - Mídia, localização, contatos, stickers — entregues como attachments reais (além de content_attributes.media_kind para stickers). Entrada (o que você envia de volta) - Mensagem de entrada — POST /api/v1/accounts/{account_id}/conversations/{conversation_id}/messages com message_type: "incoming". Aceita content, content_type, content_attributes e attachments, de modo que uma resposta interativa é simétrica ao contrato de saída. - Recibos de entrega — PUT/PATCH .../messages/{id} (apenas caixas de entrada de API) com status de sent / delivered / read / failed (e um external_error opcional). Isso altera o status da mensagem, que é retransmitido via message_updated. - Reações — POST .../messages/{id}/react com emoji (um emoji vazio o remove). Passe by=contact para registrar a reação do contato (o padrão registra a do operador). Nenhum provedor é contatado para uma caixa de entrada de API — a reação é persistida e retransmitida via message_updated. Campanhas Campanhas pontuais podem direcionar uma caixa de entrada de API. Cada contato do público recebe uma conversa real e uma mensagem de saída, que viaja pelo seu webhook exatamente como qualquer outra mensagem de saída. Configurações & opções - webhook_subscriptions — um array opcional em additional_attributes do canal de API (atualize a caixa via API com channel[additional_attributes][webhook_subscriptions]). Quando definido, apenas esses eventos são entregues; quando ausente ou vazio, todos os eventos são entregues (o padrão). Os nomes de eventos devem ser eventos válidos da plataforma (por exemplo, message_created, message_updated, conversation_created, conversation_status_changed, conversation_typing_on). - hmac_mandatory — rejeita requisições de entrada que não podem ser verificadas por HMAC. Casos de uso - Conecte a caixa de entrada a um app personalizado que renderiza CTAs de pagamento, cards de catálogo e agendamentos de agenda. - Retransmita a reação de um contato do seu próprio cliente de volta para a mensagem. - Espelhe confirmações e lembretes de agendamento no canal de registro do cliente. Dicas, limites e boas práticas - Sempre verifique a assinatura do webhook antes de agir sobre um payload. - Faça deduplicação pelo id de entrega / evento; espere retentativas. - Prefira content_attributes para renderização estruturada; content é o fallback em texto simples. - Inscreva-se apenas nos eventos que você usa para reduzir ruído. Solução de problemas - Nenhum evento chegando: confirme que a URL do webhook está definida e, se você configurou webhook_subscriptions, que o evento esperado está na lista. - 422 nas inscrições: a lista contém um nome de evento desconhecido — remova-o. - Reação não atribuída ao contato: passe by=contact na chamada de react. Veja também - API REST, tokens e webhooks - Eventos por módulo - Referência da API (Swagger / OpenAPI)

Referência de API (Swagger / OpenAPI)

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 1. Abra a referência em https://app.conversalabs.com.br/swagger (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 https://app.conversalabs.com.br/swagger/ui.html. 4. Clique em Authorize e informe o seu token no cabeçalho api_access_token. 5. Escolha um endpoint, clique em Try it out, preencha os parâmetros e clique em Execute. 6. 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. Veja também - SDK, API REST e MCP de Dashboard Apps - API REST, tokens e webhooks - 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)

SDK, API REST e MCP de Dashboard Apps

Visão geral Dashboard Apps nativos têm três contratos de integração separados: - O SDK V2 do navegador entrega contexto limitado por capacidades, eventos somente leitura, comandos seguros de quadro e identidade assinada opcional para um backend próprio. - A API REST da conta permite a administradores ou funções personalizadas com integration_manage criar, consultar, atualizar, reordenar e excluir apps e instalações. - O servidor MCP da conta expõe o mesmo contrato de instalações em quatro ferramentas opcionais de Canais e integrações → Dashboard Apps. O SDK autentica somente a identidade curta do app incorporado; não oferece um proxy genérico de API. Escritas de negócio devem passar pelo seu backend, autenticado na API REST com um token de privilégio mínimo. Pré-requisitos - dashboard_apps_native_surfaces habilitada na conta. - Dashboard App HTTPS em origem diferente do dashboard da Conversa Labs para o modo V2. - Uma pessoa administradora ou função personalizada com integration_manage e um api_access_token para gerenciamento REST. - Para MCP, perfil MCP cujo usuário atuante tenha essa permissão e que inclua Dashboard Apps. - CSP frame-ancestors permitindo a origem exata da Conversa Labs, sem X-Frame-Options conflitante. Passo a passo 1. Conecte o SDK V2 no navegador Importe o SDK pelo caminho estável e versionado da sua implantação da Conversa Labs. Ele redireciona para o build atual com fingerprint e expõe exportações nomeadas do módulo JavaScript. import { connect } from '/dashboard-app-sdk/v2.js'; try { // A origem e o installationId são descobertos dos parâmetros cl_* injetados pelo host. // Também podem ser fixados explicitamente para testes controlados. const client = await connect(); const stop = await client.subscribe( ['context.initialized', 'conversation.changed', 'theme.changed'], event => console.log(event.context_revision, event.data) ); await client.setHeight(520); document.querySelector('#documentacao').addEventListener('click', () => { client.openLink('https://app.exemplo.com/docs'); }); // Depois: await stop(); client.disconnect(); } catch (error) { console.error(error.code); } Use as importações nomeadas do módulo mostradas acima. Elas são o contrato estável para novos aplicativos. Se o seu app não consegue consumir exportações nomeadas, o mesmo arquivo também expõe window.ConversaLabsDashboardAppSDK, com as mesmas funções. Chame connect() assim que a página carregar, não atrás de autenticação ou de uma ida ao seu backend. O host inicia o handshake quando o quadro termina de carregar e insiste por até 10 segundos; um aplicativo que só começa a escutar depois desse prazo recebe handshake_timeout. Um import estático no topo de um <script type="module"> é a forma suportada. import() dinâmico funciona, desde que aguardado imediatamente — não deixe para carregar o SDK depois de renderizar a tela. connect lê cl_dashboard_origin e cl_installation_id da URL de lançamento, valida a origem exata, negocia o protocolo 2.0 e resolve depois do handshake. O cliente expõe installationId, capabilities, connected, subscribe, unsubscribe, setHeight, openLink, getIdentityAssertion e disconnect. Os eventos incluem inicialização de contexto, conversa, status/atribuição/labels, criação/atualização de mensagem, contato/usuário atual, idioma/tema/permissões e instalação. A superfície de conversa é omnichannel e funciona para e-mail, WhatsApp, SMS e outros inboxes; a barra lateral omite conversa e contato. Programe para as capabilities, campos opcionais e context_revision crescente; ressincronize em vez de aplicar dados antigos. Identificação segura para n8n e outros backends Não envie identidade nem credenciais pela query string do iframe. No evento context.initialized, use: - account.id e account.name para identificar a conta; - current_user.id, current_user.name, current_user.role e current_user.avatar_url para identificar a pessoa que abriu o app; - installation.id, surface e, na barra lateral, sidebar_category e sidebar_icon para identificar a instalação, o local, sua categoria nativa e o ícone escolhido; - na superfície de conversa, conversation, contact, permissions e eventos de mensagem para o contexto operacional. O bridge nunca expõe tokens de usuário, sessão, CSRF, REST, MCP ou credenciais do provedor do canal. Quando concedidos por instalação, current_user:email adiciona o e-mail do usuário atual; contact:email e contact:phone adicionam os dados do contato na conversa. Sem a capacidade, o campo é omitido em contexto e eventos. Para um backend próprio ou webhook n8n confirmar a identidade sem confiar em IDs enviados pelo navegador, peça uma asserção curta: const identity = await client.getIdentityAssertion(); await fetch('https://app.exemplo.com/api/dashboard-session', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(identity), }); O backend do app envia assertion por POST para a introspection_url recebida, opcionalmente com expected_origin: "https://app.exemplo.com". Uma resposta ativa contém claims de conta, usuário, instalação, superfície e capacidades. A asserção expira em dois minutos e é revalidada contra feature, instalação, usuário ativo, associação, público e origem a cada introspecção. O verificador público rejeita asserções maiores que 16 KiB antes de verificar a assinatura. Ela não é token REST/MCP e não deve ser armazenada nem usada como bearer. Para dados/escritas adicionais, o backend usa sua própria credencial REST de privilégio mínimo ou perfil MCP restrito. 2. Gerencie instalações por REST Todos os caminhos pertencem à conta. Com a feature desligada, a resposta é 404 resource_not_found; um membro autenticado sem permissão de gerenciamento recebe 403 forbidden nessas operações. # Lista instalações visíveis; administradores também recebem audience. curl -sS "https://suporte.exemplo.com/api/v1/accounts/1/dashboard_app_installations?surface=conversation" \ -H "api_access_token: API_TOKEN" # Cria uma instalação. dashboard_app_id não pode ser alterado depois. curl -sS -X POST "https://suporte.exemplo.com/api/v1/accounts/1/dashboard_app_installations" \ -H "api_access_token: API_TOKEN" -H "Content-Type: application/json" \ --data '{"dashboard_app_installation":{"dashboard_app_id":42,"surface":"conversation","compatibility_mode":"v2","enabled":true,"position":0,"capabilities":["account:read","current_user:read","current_user:email","permissions:read","appearance:read","installation:read","conversation:read","contact:read","contact:email","contact:phone","messages:read","identity:assertion"],"audience":{"type":"any","roles":["administrator"],"team_ids":[7],"user_ids":[]}}}' # Atualiza ou reordena com a lock_version da resposta mais recente. curl -sS -X PATCH "https://suporte.exemplo.com/api/v1/accounts/1/dashboard_app_installations/9" \ -H "api_access_token: API_TOKEN" -H "Content-Type: application/json" \ --data '{"dashboard_app_installation":{"sidebar_category":"applications","sidebar_icon":"rocket","position":1,"lock_version":3}}' # Exclui. curl -sS -X DELETE "https://suporte.exemplo.com/api/v1/accounts/1/dashboard_app_installations/9" \ -H "api_access_token: API_TOKEN" A lista retorna { "payload": [...], "meta": { "revision": N } }; criação, detalhe e atualização retornam { "payload": { ... } }; exclusão retorna 204. A instalação contém app id/título/URL, surface, compatibility_mode, enabled, visible operacional, position, sidebar_category e sidebar_icon na barra lateral, capabilities, audience apenas para administradores, transport_security, warnings, lock_version e updated_at. POST /api/v1/accounts/:account_id/dashboard_app_installations/:id/identity_assertion é a chamada autenticada usada internamente por getIdentityAssertion; respeita feature, instalação ativa, V2/dual, público e capacidades. Aplicativos devem preferir o SDK. A validação server-to-server usa o endpoint público POST /dashboard-apps/v2/assertions/introspect descrito acima. Também é possível criar app e instalações iniciais de forma atômica enviando installations no POST /dashboard_apps. Com a feature ligada, omitir a propriedade cria a compatibilidade padrão conversation + legacy + all; um array vazio cria somente o app. Com a feature desligada, enviar installations é rejeitado e omitir a propriedade preserva a criação legada. Cada app pode ter uma instalação por superfície. 3. Use as ferramentas MCP da conta Habilite Dashboard Apps no perfil MCP. O módulo permanece no grupo channels_integrations, preserva as ferramentas existentes de definição de app e adiciona: | Ferramenta | Efeito | Perfil somente leitura | |---|---|---| | list_dashboard_app_installations | Lista instalações visíveis ao usuário atuante | Disponível | | create_dashboard_app_installation | Cria uma instalação | Oculta | | update_dashboard_app_installation | Atualiza categoria, ícone, posição, público ou bridge | Oculta | | delete_dashboard_app_installation | Exclui uma instalação | Oculta | MCP usa o mesmo escopo da conta, política, público, feature e erros de validação da API REST. O detalhe REST e o alias PUT não viram ferramentas separadas: a lista é a leitura canônica e PATCH é a atualização e reordenação canônica. A mintagem de identidade não vira ferramenta MCP: ela pertence à sessão humana incorporada, enquanto o cliente MCP já possui seu próprio principal autenticado. Configurações e opções - Superfícies: conversation ou sidebar. - Modos: legacy, v2 ou dual. - Capacidades: núcleo obrigatório; conversa/contato/mensagens somente em conversation; dados pessoais opcionais current_user:email, contact:email, contact:phone; identidade opcional identity:assertion. Omitir aplica o padrão completo e útil da superfície; um array vazio explícito é rejeitado com invalid_capabilities. Remova apenas concessões opcionais e preserve todas as capacidades obrigatórias da superfície selecionada. - Público: { "type": "all" } ou { "type": "any", "roles": [...], "team_ids": [...], "user_ids": [...] }. Funções válidas: agent e administrator; any exige ao menos um seletor não vazio e concede acesso se qualquer seletor corresponder. - Categoria lateral: support, contacts_crm, applications, commercial, productivity, automation, growth ou analytics_config; é aceita somente em sidebar e o padrão é productivity. O grupo applications aparece logo abaixo de Contatos & CRM e é omitido quando vazio. - Ícone lateral: panels_top_left, layout_dashboard, app_window, boxes, briefcase, bot, calendar_days, chart_no_axes_combined, circle_dollar_sign, clipboard_list, database, folder, globe_2, headphones, life_buoy, messages_square, package, rocket, shopping_bag, sparkles, workflow ou wrench; aceito somente em sidebar, com panels_top_left como padrão. - Posição: índice a partir de zero, normalizado por superfície e, na barra lateral, por categoria. - Concorrência: envie lock_version; 409 stale_installation pede recarga e nova tentativa. - Erros estáveis: invalid_audience, invalid_capabilities, invalid_sidebar_category, invalid_sidebar_icon, installation_already_exists, invalid_dashboard_app_url, dashboard_app_migration_required, unsafe_same_origin_v2 e resource_not_found. O erro de migração exige um único quadro HTTP(S); query string e fragmento são aceitos. - Limites do SDK: mensagens de 64 KiB, 32 assinaturas, 30 comandos por 10 segundos e altura entre 160–2.000 px. - Prazos do handshake: são dois, independentes. O painel abre a janela quando o quadro carrega e reenvia o convite por até 10 segundos. O connect() do SDK tem o próprio limite de 10 segundos, contado a partir da chamada, ajustável por connect({ timeoutMs }). Aumentar o do SDK não ajuda: o painel para de insistir antes. - Ciclo de vida: o SDK dispara eventos de janela conversalabs.dashboard-apps:bridge.connected, :bridge.paused, :bridge.resumed e :context.resynced. Ouça-os para pausar trabalho quando a aba sai de foco e para ressincronizar. O código disconnected significa que todo comando seguinte será rejeitado; refaça a conexão em vez de repetir o comando. Códigos de erro e a primeira coisa a conferir | Código | Significa | Comece por | |---|---|---| | handshake_timeout | O painel insistiu por 10 s e o app não respondeu | O app chama connect() no carregamento? O bundle carregado expõe connect? | | invalid_origin | Origem configurada ou de destino inválida | URL HTTP(S) sem credenciais; em V2 a origem precisa ser diferente da do painel | | frame_blocked | O navegador recusou a incorporação | frame-ancestors e X-Frame-Options no servidor do app | | insecure_transport_blocked | App HTTP dentro de painel HTTPS | Publique o app em HTTPS | | unsupported_version | App e painel não compartilham a versão da bridge | Use o SDK da mesma implantação | | unsupported_command | Comando fora da allowlist | Use apenas os comandos anunciados | | invalid_payload | Mensagem fora do contrato | Versão, sequência, campos e tamanho | | invalid_sequence | Mensagem fora de ordem | Não reimplemente o protocolo à mão; use o SDK | | rate_limited | Mais de 30 comandos em 10 s | Reduza frequência e agrupe assinaturas | | disconnected | A ponte fechou | Reconecte; comandos pendentes não voltam | | user_denied | A pessoa recusou a confirmação | Esperado em openLink; não insista | | capability_denied | Capacidade não concedida | Habilite na instalação; dados de contato só existem em conversa | | identity_unavailable | Não foi possível emitir a asserção | Feature, modo V2/dual, instalação ativa e público | Casos de uso - Renderizar contexto da conversa e manter alterações de CRM em backend auditável. - Provisionar instalações por um serviço administrativo interno. - Permitir que um perfil de IA somente leitura inventarie apps sem direitos de escrita. - Usar MCP de escrita em perfil administrador restrito para automação controlada. Dicas, limites e boas práticas - Fixe dashboardOrigin na origem HTTPS exata. Não use *, não aceite origens postMessage não confiáveis e não reimplemente o protocolo quando houver SDK. - Query string e fragmento estáticos são preservados. Em V2/dual, o host acrescenta e sobrescreve apenas cl_dashboard_origin, cl_installation_id, cl_account_id, cl_surface, cl_protocol e cl_locale; trate todo nome cl_* como reservado. O host remove valores cl_* estáticos antes de escrever esses seis parâmetros. Nunca coloque tokens, asserções, segredos ou dados pessoais na URL ou no bundle do app. - Mantenha credenciais REST/MCP no servidor, rotacione-as e separe perfis de inventário dos administrativos. - Autorize o público no servidor. Esconder uma aba no iframe não é autorização. - openLink sempre mostra uma confirmação nativa do host. O link só abre depois que a pessoa clica em Abrir link; um timestamp enviado pelo iframe nunca é aceito como prova de gesto. - Trate códigos de DashboardAppSDKError, desconexões, limites e ressincronização explicitamente. - insecure_http é sinal de migração, não aprovação para produção. Solução de problemas - handshake_timeout: o painel reenviou o convite por 10 segundos e o aplicativo não respondeu. Comece pelo app, não pela rede: ele chama connect() assim que a página carrega? O bundle que ele carregou expõe connect? Só depois confira a origem e o modo V2/dual. Um quadro que fica em branco é outro problema — veja frame_blocked. - O modo Dual esconde a falha da V2: com Dual, o atendimento segue pelo lane legado e a superfície aparece pronta mesmo com a bridge V2 morta. O diálogo Testar mostra o resultado de cada bridge separadamente; para ver o erro cru, mude a instalação para V2 temporariamente. - invalid_origin: use URL HTTP(S) sem credenciais embutidas e mantenha a V2 numa origem diferente da do painel. - unsupported_version ou unsupported_command: use o SDK da mesma implantação e apenas capacidades anunciadas. - capability_denied: habilite a capacidade pedida na instalação; contato/e-mail do contato existem somente em conversation. - identity_unavailable ou introspecção inativa: obtenha uma nova asserção e confira feature, modo V2/dual, instalação ativa, público, associação e origem exata. - rate_limited ou invalid_payload: reduza frequência, tamanho e assinaturas. - REST/MCP retorna 404: confira conta, instalação e feature. O público também pode ocultar o recurso. - REST/MCP retorna 403: usuário autenticado ou atuante não é administrador nem possui uma função personalizada com integration_manage. - 409 ao atualizar: busque o estado atual e repita com sua lock_version. - 422 ao criar/atualizar: confira o error, URL, par app/superfície único, categoria lateral, público e origem do V2. Veja também - Dashboard Apps: superfícies nativas, público e segurança - API REST, tokens e webhooks - Referência da API (Swagger / OpenAPI) - MCP nativo: conexões, servidor e clientes

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). Novos eventos por módulo (payloads reais) Os campos abaixo vêm da fonte real de cada evento — não invente formato. Todos são entregues a webhooks de conta; chamadas e respostas de Flow também vão para o webhook do canal de API. A entrega de cada grupo exige o recurso do módulo habilitado na conta (a assinatura funciona mesmo com o recurso desligado, mas nada é entregue). Gestão de Equipe — recurso: Gestão de Equipe - wfm_status_changed, wfm_break_started — o agente mudou de status / entrou em pausa. Campos: account_id, account_user_id, user_id, status_key, status_event_id, base_availability, family. - wfm_break_breached — a pausa ultrapassou o limite. Campos: os acima mais expected_seconds e over_by_seconds. - wfm_break_ended — o agente saiu de uma pausa (qualquer caminho: troca manual, seletor nativo ou auto-offline). Campos: os do início de pausa mais duration_seconds, within_limit e, se estourou, over_by_seconds. - wfm_shift_started, wfm_shift_ended — o turno planejado do agente abriu/fechou a janela (avaliado a cada minuto pelo servidor). Campos: account_id, account_user_id, user_id, shift_id, schedule_id (quando gerado de um modelo), date, starts_at, ends_at. Cada evento do ciclo dispara exatamente uma vez por turno. Transmissões do WhatsApp Hub — recurso: WhatsApp Hub - whatsapp_broadcast_started, whatsapp_broadcast_completed, whatsapp_broadcast_failed — a transmissão mudou de estado. Campos (sem conteúdo de mensagem): account_id, inbox_id, broadcast_id, display_id, title, status, target_type, recipients_count. Funciona em caixas Cloud e WazMeow (WhatsApp Web). Boas-vindas e despedidas de grupo do WhatsApp — recurso: WhatsApp Hub - whatsapp_group_member_welcomed, whatsapp_group_member_farewelled — disparam somente quando a mensagem de boas-vindas/despedida foi realmente enviada (idempotente, uma vez por participante por janela de deduplicação). Campos: account_id, inbox_id, whatsapp_group_id, group_jid, participant_jid, participant_phone, trigger (welcome ou farewell). Sem conteúdo de mensagem. Ads Manager — recurso: Growth Ads ou Ads Manager - ads_campaign_status_changed — o status efetivo de uma campanha espelhada mudou. Campos: account_id, ad_account_id, campaign_id, remote_id, status, effective_status, previous_effective_status. - ctwa_conversation_started — uma conversa via Clique-para-WhatsApp abriu a janela gratuita de 72h. Campos: account_id, conversation_id, contact_id, inbox_id, window_id, expires_at. - ad_window_expiring — essa janela está perto de expirar. Mesmos campos. Chamadas e respostas de Flow do WhatsApp — recurso: WhatsApp Inbox Suite - whatsapp_call_started, whatsapp_call_ended, whatsapp_call_recording_ready — ciclo de vida da chamada. Campos (os presentes variam por etapa): provider_call_id, conversation_id, realtime, status, recording_url. Entregue a webhooks de conta e de canal de API. - whatsapp_flow_response_received — o cliente concluiu um WhatsApp Flow. Campos: o objeto flow_response (id, whatsapp_flow_id, screen, response, contact_id, conversation_id) e o objeto conversation. Entregue a webhooks de conta e de canal de API. Sessões do FlowBuilder — recurso: Flow Builder - flow_session_started, flow_session_updated, flow_session_completed, flow_session_failed — a sessão do fluxo iniciou, pausou, concluiu ou falhou. Campos: id, flow_id, status, current_node_id, conversation_id, account_id. 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 - Canal de API: o contrato de eventos estruturados

MCP nativo: Conexões MCP, servidor do Maestro e cliente (Model Context Protocol)

Visão geral O MCP (Model Context Protocol) é o padrão aberto que permite a assistentes de IA (Claude, IDEs, agentes) usarem ferramentas e dados de sistemas externos de forma segura. A Conversa Labs traz MCP nativo, e você opera tudo por telas — sem escrever integração. São três superfícies: - Conexões MCP da conta (perfis de acesso) — em vez de uma única configuração da conta, você cria N perfis nomeados. A conexão de Bearer estático de cada perfil tem sua seleção de módulos, modo somente leitura, usuário de execução (membro da conta) e URL + segredo bearer próprios. Essa conexão estática opera como o usuário de execução e só consegue restringir o que ele já pode fazer, nunca ampliar. Quando a instalação habilita o OAuth nativo, o mesmo perfil também tem uma URL OAuth separada: as ferramentas continuam limitadas pelo perfil, mas cada chamada opera como o membro da conta que aprovou o consentimento OAuth — nunca como o usuário estático do perfil. - Servidor MCP do Maestro — expõe os departamentos do Maestro como ferramentas ask_<departamento> para clientes externos, sob um token por conta. O cliente nunca ganha mais autonomia do que o departamento já tem configurada. - Robô como cliente MCP — cada Robô pode consumir servidores MCP externos (Linear, Notion, Stripe, GitHub, ERP interno) como ferramentas adicionais, com as mesmas regras de aprovação (HITL), orçamento de ferramentas e auditoria dos demais recursos. A conexão estática da conta e o servidor do Maestro usam o cabeçalho padrão Authorization: Bearer <credencial>. Os exemplos abaixo configuram esse caminho estático: na conta, a credencial é o segredo do perfil; no Maestro, o token do Maestro. Eles são exemplos de configuração, não prova de que todo produto ou versão foi validado nesta instalação. O OAuth nativo da conta é um recurso separado e condicional, com discovery, PKCE e consentimento no navegador; não aponte um cliente OAuth para a URL estática nem suponha compatibilidade sem testá-la. Identidade visual do conector Na inicialização MCP com o protocolo 2025-11-25, o servidor envia o nome e o título da instalação, descrição, site e os ícones da marca (um principal e variantes clara/escura). As telas de login e de consentimento OAuth usam a mesma identidade; se a imagem configurada não carregar, exibem as iniciais da instalação. Esses dados só são publicados quando há uma origem canônica pública e segura em HTTPS. Sem ela, o servidor omite URLs e ícones em vez de expor um endereço interno ou não confiável. O cliente decide se e como mostra esses campos. Clientes que negociam uma versão MCP mais antiga ainda recebem o nome técnico do servidor, mas o protocolo não entrega os ícones. No Conector personalizado do Claude, use o nome que você digitou na configuração: a interface pode continuar mostrando esse nome até que ela use os metadados do servidor. A aparência não altera escopos, consentimento nem credenciais. Os endpoints de Conta, Plataforma e Super Admin montam esse retrato seguro a cada inicialização MCP. Depois de uma alteração de White Label ou do emissor canônico, o mesmo retrato versionado é enfileirado para o endpoint direto do Maestro; a próxima requisição autenticada usa o retrato válido persistido mais novo. Uma indisponibilidade temporária do Maestro nunca desfaz a marca salva: o reconciliador agendado tenta de novo. Se o provedor já criou um conector, desconecte e adicione o servidor novamente para forçar um novo initialize — isso não rotaciona token nem muda permissões. A URL do ícone precisa ser um ativo de primeira parte nessa própria origem canônica, público, HTTPS e acessível sem login; CDN externo ou outro host não é publicado como metadado de marca MCP. Um cliente de terceiro pode manter o ícone em cache ou optar por não renderizar metadados de ícone MCP; o servidor não consegue substituir esse comportamento do cliente. Pré-requisitos - Recurso MCP habilitado para a conta. Sem a flag, a página Configurações → MCP simplesmente não aparece no menu (e o interruptor global da instalação também precisa estar ligado). - Perfil de administrador da conta para gerenciar as Conexões MCP (a página e a criação/edição de perfis são restritas a administradores). - Para a conexão da conta: nenhum token pessoal. Cada perfil (Conexão MCP) gera o seu próprio segredo bearer na criação/rotação — é essa a credencial do cliente. O usuário de execução do perfil precisa ser membro da conta. Tokens de Robô (AgentBot) e o token pessoal de API não são a credencial da conexão da conta. - Para a conexão opcional de OAuth nativo da conta: o responsável pela instalação precisa habilitar o OAuth nativo do MCP, aplicar as migrations de banco do OAuth MCP desta versão e configurar um emissor público HTTPS válido, além do recurso MCP da conta e do interruptor global. Uma flag não substitui a migration da estrutura do banco nem prova o fluxo. A URL OAuth é diferente da conexão estática; o segredo estático do perfil nunca a autentica. Quem aprova o consentimento no navegador precisa ser membro ativo da conta. - O host do emissor deve resolver e rotear pelo gateway público para esta mesma instalação. Ele precisa servir os endpoints MCP OAuth e os documentos de Metadados de Recurso Protegido e discovery do servidor de autorização; um endereço HTTPS sintaticamente válido que roteia para outro lugar não basta. - Antes de adotar OAuth nativo em um cliente de terceiros, exercite discovery, PKCE e consentimento em ambiente controlado. Um endpoint baseado em padrão não prova que um produto, aplicativo desktop ou superfície de IA hospedada suporte o fluxo exigido. - Para o servidor do Maestro: o Maestro provisionado para a conta. Sem isso, o card do Maestro é substituído por um aviso. - Para conectar um servidor MCP externo por OAuth: o Robô já salvo e o navegador liberado para abrir pop-ups (a tela de consentimento do provedor abre em uma janela). Passo a passo 1. Abrir a página MCP Vá em Configurações → MCP. A tela traz o card Conexões MCP da conta (os perfis de acesso) e o card Servidor MCP do Maestro. 2. Criar uma Conexão MCP (perfil de acesso) No card Conexões MCP da conta, clique em Novo perfil. Cada perfil é uma conexão independente: 1. Dê um nome ao perfil (por exemplo claude-code-suporte ou bi-somente-leitura) — ele ajuda a identificar qual cliente usa cada conexão. 2. Escolha o usuário de execução — um membro da conta. O perfil executa como esse usuário: a lista de ferramentas efetiva é a interseção da sua seleção com o teto do Super Admin e com as permissões desse usuário. Ou seja, um perfil só restringe — nunca concede mais do que o usuário já tem. Só pertencem a este servidor rotas enraizadas em /api/v{N}/accounts/{account}: rotas pessoais de perfil, MFA, sessões e notificações ficam fora da conexão da conta, mesmo quando o usuário também pertence a outras contas. 3. Escolha os módulos que ficam expostos. É o mesmo seletor de sempre: toda a plataforma (mais de 100 módulos), organizada em áreas recolhíveis — Conversas e atendimento, Contatos e CRM, Catálogo e vendas, Pagamentos, Tarefas e agenda, WhatsApp, Canais e integrações, Automação e IA, Growth e vendas, Relatórios, Equipe e administração e Conteúdo. Use a busca para achar um módulo pelo nome ou pela descrição, e o Selecionar tudo de cada área para ligar a área inteira de uma vez. Cada linha mostra o que o módulo faz e quantas ferramentas ele adiciona (o preço da caixinha); o resumo embaixo da busca soma a seleção atual e avisa se ela passar do teto de ferramentas — que continua valendo por perfil: Alguns exemplos (a lista completa está na tela, por área): | Exemplos de módulo | O que expõe | |---|---| | Conversas | ler, responder, mudar status, atribuir, aplicar labels (ligado por padrão) | | Contatos | buscar, criar e atualizar contatos (ligado por padrão) | | Relatórios | métricas e análises (somente leitura) | | Tarefas | módulo nativo de tarefas | | Itens de CRM | negócios e pipeline | | Central de Ajuda | artigos da base de conhecimento | | Catálogo | produtos | | Follow-up | cadências de follow-up | | Biblioteca de Mídia | arquivos de mídia | Toolsets ligados por padrão trazem o selo default. Se o Super Admin não liberou um toolset no teto global, a linha aparece desabilitada e com o selo bloqueado pelo super admin — você não consegue marcá-la. Acima da lista há atalhos de ponto de partida: Essencial, Atendimento, Comercial e Tudo. Eles apenas somam módulos à seleção atual — nada é removido, e nenhum módulo some da lista porque um atalho não o menciona. Use um deles para começar e ajuste na mão; módulos bloqueados pelo teto continuam de fora, como sempre. 4. Modo somente leitura: marque a caixa para o perfil expor apenas ferramentas que leem dados (nada de criar, atualizar ou apagar). 5. Compatibilidade com a pesquisa profunda do ChatGPT (opcional): o conector de pesquisa profunda do ChatGPT exige, pelo nome, duas ferramentas chamadas search e fetch, e recusa um servidor que não as tenha. Marque a caixa só nos perfis usados por esse conector. As duas ferramentas apenas descrevem o que o perfil já expõe — não concedem nenhum acesso extra —, mas ocupam espaço na lista dos outros clientes. Deixe desmarcado para Claude, Claude Code e clientes genéricos. 6. Salve o perfil. Nesse momento o segredo bearer é exibido em texto puro uma única vez (formato mcp_...) — copie na hora. Só o hash e os quatro últimos caracteres ficam guardados; a plataforma nunca mostra o segredo de novo. 7. Copie a URL da conexão. O formato é https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/c/ID_PUBLICO, onde ID_PUBLICO é um identificador não secreto (um slug na URL) — quem autentica é o segredo bearer, não a URL. Essa é a URL de Bearer estático. Se a instalação habilitou OAuth nativo do MCP, o mesmo perfil tem outro recurso exato: https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/oauth/c/ID_PUBLICO. Não troque mcp/c por esse caminho em um cliente estático existente e não cole nele o segredo do perfil. O perfil continua selecionando as ferramentas, mas chamadas OAuth executam como o membro que aprovar o consentimento. Depois, cada perfil tem, no card, os botões Editar (troca nome, usuário de execução, módulos e modo somente leitura), Rotacionar token (gera um novo segredo e invalida o anterior na hora) e Excluir. Desativar ou excluir o perfil — ou o usuário de execução deixar de ser membro da conta — faz a conexão parar de responder (401/404). 3. Configurar o servidor MCP do Maestro 1. No card Servidor MCP do Maestro, veja o status: Token configurado ou Ainda sem token. 2. Clique em Gerar token (ou Rotacionar token, se já existir um). 3. O token em texto puro é exibido uma única vez — copie na hora. Ele nunca mais é mostrado. Rotacionar invalida o token anterior imediatamente. 4. Copie a URL do endpoint do Maestro (termina em /mcp). 5. Um cliente externo com essa URL + token enxerga uma ferramenta ask_<departamento> por departamento ativo da conta. Se o Maestro não estiver configurado para a conta, o card é substituído por um aviso — provisione o Maestro antes. 4. Conectar um cliente MCP com Bearer estático Esta seção configura somente a conexão de Bearer estático: use Streamable HTTP, a URL estática do perfil no passo 2 (ou a URL do Maestro no passo 3) e a credencial no cabeçalho Authorization: Bearer .... Na conta, ela é o segredo do perfil (o mcp_... revelado ao criar ou rotacionar); no Maestro, o token do Maestro. Formatos de configuração dos clientes mudam fora desta documentação; valide a versão exata em ambiente controlado. Nenhum snippet abaixo configura OAuth nativo. Claude Code — pelo terminal: claude mcp add --transport http helpdesk \ https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/c/ID_PUBLICO \ --header "Authorization: Bearer SEGREDO_DO_PERFIL" Ou no .mcp.json do projeto: { "mcpServers": { "helpdesk": { "type": "http", "url": "https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/c/ID_PUBLICO", "headers": { "Authorization": "Bearer SEGREDO_DO_PERFIL" } } } } Cursor — em ~/.cursor/mcp.json (global) ou .cursor/mcp.json (projeto): { "mcpServers": { "helpdesk": { "url": "https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/c/ID_PUBLICO", "headers": { "Authorization": "Bearer SEGREDO_DO_PERFIL" } } } } VS Code (modo agente) — em .vscode/mcp.json: { "servers": { "helpdesk": { "type": "http", "url": "https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/c/ID_PUBLICO", "headers": { "Authorization": "Bearer SEGREDO_DO_PERFIL" } } } } MCP Inspector — para depurar a conexão e ver a lista crua de ferramentas: npx @modelcontextprotocol/inspector No painel: Transport Type = Streamable HTTP, URL = a URL da conexão, e em Authentication informe o Bearer Token — o segredo do perfil para a conexão da conta, ou o token do Maestro para o servidor do Maestro (ou um header Authorization com o valor Bearer <credencial>). Clique em Connect e depois em List Tools. Windsurf — mesma ideia: servidor remoto com a URL da conexão e headers contendo Authorization: Bearer SEGREDO_DO_PERFIL (ou o token do Maestro). Em todos eles o cliente faz initialize, depois tools/list (lista as ferramentas expostas) e finalmente tools/call para executar uma delas. Se o cliente exibir menos ferramentas do que o esperado, é o teto de exibição: use search_tools para achar qualquer outra ferramenta (ele devolve o schema dela) e call_tool para executá-la. Nada fica inalcançável — só fora da lista. 4a. Conectar o recurso OAuth nativo da conta (condicional) Este é um caminho de conexão separado, disponível somente quando o OAuth nativo do MCP está habilitado na instalação e o recurso/perfil MCP da conta estão disponíveis. Ele não converte a conexão de Bearer estático e não é uma alternativa para um segredo de perfil perdido. 1. Configure o cliente com a URL exata do recurso OAuth: https://SEU-DOMINIO/api/v1/accounts/ID_DA_CONTA/mcp/oauth/c/ID_PUBLICO. 2. Comece pelos Metadados de Recurso Protegido desse recurso, não por uma URL de host adivinhada: https://SEU-DOMINIO/.well-known/oauth-protected-resource/mcp/oauth/accounts/ID_DA_CONTA/connections/ID_PUBLICO. Eles só anunciam o servidor de autorização canônico enquanto o recurso estiver disponível. 3. Descubra o servidor de autorização em https://SEU-DOMINIO/.well-known/oauth-authorization-server/oauth/mcp (ou use o emissor anunciado pelos metadados). O servidor usa Authorization Code público, PKCE S256 obrigatório, vínculo ao recurso exato e nenhum segredo de cliente. Os metadados de discovery declaram authorization_response_iss_parameter_supported: valide o emissor canônico retornado no parâmetro iss nos callbacks de sucesso e de erro redirecionável. O handoff de navegador guarda os valores da autorização de forma assinada e aceita no máximo 1.024 bytes somados entre os parâmetros persistidos (incluindo client_id, redirect_uri, resource e state). Use um state curto e opaco; não tente ampliar o fluxo com URLs ou estados grandes. 4. Um cliente público pode usar Client ID Metadata público verificado (CIMD). Registro Dinâmico de Cliente (DCR) é condicional e desligado por padrão: só aparece no discovery depois que um Super Admin habilita Dynamic Client Registration em MCP Settings. Se estiver desligado, o discovery omite registration_endpoint e o registro devolve 404 — isso não é falha de OAuth. Quando ligado, o operador acompanha o cliente em MCP OAuth clients e pode desativá-lo; a desativação confirmada, com razão e reautenticação, é irreversível e revoga a família de consentimento/tokens. DCR continua sendo um caminho governado de teste, não uma promessa de compatibilidade de fornecedor. Nunca envie para esse fluxo segredo de perfil, token pessoal de API, credencial de Super Admin ou segredo de cliente. 5. No navegador, se já houver uma sessão ativa do painel da conta ou do Console do Super Admin para uma identidade que seja membro da conta alvo, ela é validada no servidor e reutilizada: você vai direto à revisão do consentimento, sem digitar a senha novamente. A aprovação continua obrigatória. Uma identidade Super Admin só entra por este fluxo quando também possui vínculo de membro da conta, e o grant/token permanece limitado à conta, ao perfil e aos escopos — nenhuma autoridade global é herdada. Se a sessão estiver ausente, expirada, inválida ou for de outra conta, o formulário manual aparece e exige uma identidade de membro válida. mcp:read é o escopo de leitura; ferramentas de escrita também exigem mcp:write e um perfil que não seja somente leitura. offline_access pede explicitamente um refresh token rotativo. 6. Em Configurações → Perfil → Conexões MCP, um membro revisa e revoga suas próprias conexões aprovadas. Um administrador da conta revisa todos os grants da conta e precisa selecionar uma razão fechada quando revoga pelo fluxo administrativo. Revogar invalida a família de credenciais conectada. 4b. Verificar o recurso público antes de conectar um cliente OAuth Antes de abrir o Claude.ai, Claude Code ou outro cliente remoto, um operador pode verificar o contrato público sem fornecer credencial alguma: ruby scripts/mcp_oauth_preflight.rb \ --base-url https://SEU-DOMINIO \ --account-id ID_DA_CONTA \ --profile-public-id ID_PUBLICO Para a autoridade separada do Super Admin, use: ruby scripts/mcp_oauth_preflight.rb \ --base-url https://SEU-DOMINIO \ --super-admin O verificador aceita somente origem HTTPS pública com nome DNS (recusa IP literal e host interno), não segue redirecionamentos e confere os Metadados de Recurso Protegido exatos, emissor e audiência, discovery, Client ID Metadata (CIMD), PKCE S256, retorno iss, escopos e o desafio 401 de um tools/list JSON-RPC sem Bearer. Quando o discovery anunciar DCR, ele confere também o endpoint exato; a ausência explícita por gate desligado é um estado válido. Só avance para o teste controlado quando ele terminar com RESULT: PASS. Em falha, corrija a publicação antes de conectar qualquer cliente. Esse resultado confirma a publicação do servidor; não comprova compatibilidade de um provedor externo. Ele não registra cliente, não abre consentimento, não troca/revoga token e não altera perfil, grant ou credencial. A instância remota pode gravar a telemetria de auditoria sem segredo normal de discovery e do desafio 401; isso é observabilidade, não um cliente OAuth criado pelo verificador. Claude.ai — Conector personalizado Depois de o operador habilitar o OAuth MCP e a página Configurações → MCP mostrar o Endereço de conexão OAuth do perfil, use a área de conectores correspondente ao seu plano do Claude: Use este roteiro como teste controlado da versão de Claude disponível na sua organização. Só libere a conexão para outras pessoas depois de registrar discovery, consentimento, tools/list, uma leitura e uma revogação bem-sucedidos. O conector remoto do Claude alcança o servidor pela infraestrutura de nuvem do Claude, inclusive quando você está no Claude Desktop. Portanto o issuer precisa ser HTTPS público e alcançável fora da VPN/rede privada; estar acessível apenas pelo seu navegador não basta. Conectores personalizados remotos estão disponíveis no Claude, Cowork e Claude Desktop nos planos Free, Pro, Max, Team e Enterprise; no Free há limite de um conector personalizado. Consulte também o guia atual de conectores remotos do Claude. 1. Em Team/Enterprise, Owner ou Primary Owner abre Organization settings → Connectors → Add → Custom → Web e cadastra a URL MCP remota. Depois cada membro vai a Customize → Connectors e clica em Connect. Em Free/Pro/Max, vá a Customize → Connectors → + → Add custom connector na própria conta (Free permite um conector). 2. Dê um nome claro, por exemplo Conversa Labs — Suporte, e cole o Endereço de conexão OAuth em URL MCP remota. Não use a URL Bearer estática. 3. Advanced settings é opcional. Neste servidor de cliente público, nunca preencha Client Secret nem use token Bearer, segredo do perfil ou credencial de Super Admin em qualquer campo. Se a versão do Claude precisar de DCR, habilite-o previamente e de forma explícita pelo Super Admin; caso contrário, ela precisa usar CIMD ou cliente já provisionado. 4. Clique em adicionar, entre como membro ativo da conta e leia/aprove o consentimento. O Claude passa a agir como essa pessoa, limitado pelo perfil, pelos seus próprios papéis e pelos scopes. O callback é controlado pelo cliente e é informação de registro, não uma URL que você deve trocar manualmente no recurso MCP. Registre a versão do Claude e o callback efetivamente recebido no teste; não cole tokens, códigos ou parâmetros de callback na evidência. Para desconectar, revogue o grant em Configurações → Perfil → Conexões MCP (ou, sendo administrador, na mesma tela da conta). Não rotacione um token bearer estático: ele é outro tipo de conexão e não desconecta o Claude OAuth. Não marque um produto de terceiro como compatível apenas porque ele oferece MCP ou OAuth. Valide produto, versão, redirecionamento e resultado do consentimento ponta a ponta antes de liberá-lo para usuários. Matriz de conectores externos — teste controlado Estado de todas as linhas abaixo: não validado nesta instalação. A matriz explica como preparar uma tentativa segura; ela não declara suporte do fornecedor. Comece sempre por mcp:read, initialize, tools/list e uma leitura em dado de teste. Só teste escrita depois de autorização explícita. | Cliente | Pré-requisitos externos | Passos do teste | Revogação | Estado | |---|---|---|---|---| | Claude.ai — Conector personalizado | Plano Claude com conectores personalizados (Free: um); em Team/Enterprise, Owner/Primary Owner cadastra antes; issuer HTTPS público alcançável pela nuvem do Claude e preflight aprovado | Usar a URL OAuth exata, manter Advanced settings opcional/sem segredo e concluir browser/PKCE/consentimento | Revogar em Configurações → Perfil → Conexões MCP e confirmar que a próxima chamada falha | ⏳ não validado | | Claude Desktop | Claude Desktop atualizado e conta com conectores personalizados; o servidor também precisa estar alcançável pela nuvem do Claude, não apenas pela máquina local | Configurar somente a URL OAuth exata e registrar versão, sistema e callback/erro seguro | Revogar o mesmo grant e testar nova chamada | ⏳ não validado | | Codex | Organização/produto elegível para conexão MCP remota e método atual de conexão disponível | Adicionar somente a URL OAuth exata no fluxo atual do produto; não usar segredo Bearer como segredo de cliente | Revogar o grant e confirmar negação posterior | ⏳ não validado | | ChatGPT / GPT Platform | Plano/workspace elegível, administrador ou Developer Mode quando aplicável, autorização explícita para o teste | Usar o fluxo de connector/app efetivamente disponível, a URL OAuth exata e o consentimento no navegador | Revogar o grant e confirmar negação posterior | ⏳ não validado | O recurso OAuth de Super Admin é outro plano de autoridade e usa outra URL; nunca substitua a URL de Conta acima por /super_admin/mcp/oauth. Para ele, siga o artigo de Operador e faça um teste separado. Registre versão, plano/entitlement, resultado de discovery, consentimento, tools/list, leitura, evento de auditoria, revogação e a chamada negada — sem copiar tokens, códigos, verifiers ou URLs com parâmetros. Claude Code: a autorização local usa callback loopback com porta efêmera. A política restrita de redirect RFC 8252 para esse callback já tem matcher e teste HTTP locais; uma URL fixa localhost/127.0.0.1 não representa sozinha a porta real. Isso não é prova de compatibilidade: o E2E externo continua bloqueado até haver issuer HTTPS público, Inspector e evidência do cliente real. 5. Dar servidores MCP externos a um Robô (o Robô como cliente) 1. Vá em Configurações → Robôs, abra o Robô e localize a seção Servidores MCP. 2. Clique em Adicionar servidor e preencha: - Nome técnico — letras minúsculas, números e _, começando por letra (2 a 33 caracteres), por exemplo github. É o prefixo das ferramentas desse servidor. - URL do servidor MCP (a que o provedor publica). - Transporte: Streamable HTTP (recomendado) ou SSE (legado). - Timeout em segundos. 3. Autenticação: escolha o tipo — nenhuma, bearer, header, query, basic ou OAuth. Nos tipos com segredo, informe o nome do segredo — nunca o valor. O valor fica no cofre de segredos e nunca é enviado ao modelo. No tipo OAuth não há campo de segredo: a credencial é obtida no passo 6. 4. Cabeçalhos adicionais (opcional): pares chave/valor, só se o servidor exigir. 5. Marque Exigir aprovação (HITL) para que toda chamada às ferramentas desse servidor passe por aprovação humana. 6. Clique em Descobrir: a plataforma conecta ao servidor agora e lista as ferramentas antes de você salvar. Servidores grandes (Linear, Notion) devolvem dezenas de ferramentas com descrições longas — use a busca e o Selecionar tudo / Limpar para curar sem rolar a lista inteira; o contador mostra quantas você marcou. Você pode selecionar um subconjunto (allowlist) — se não selecionar nenhuma, todas as ferramentas do servidor ficam disponíveis. 7. Salve o Robô. As ferramentas são descobertas e armazenadas no momento de salvar; o turno do agente nunca faz descoberta de rede. Para que a descoberta resolva segredos já armazenados, salve o Robô primeiro e só então clique em Descobrir. 6. Conectar um servidor externo por OAuth (botão Conectar) Alguns servidores (o Notion, por exemplo) só aceitam OAuth — não existe chave estática. Nesses casos: 1. No servidor MCP do Robô, escolha Autenticação → OAuth. Os campos de segredo somem — não há o que preencher. 2. Salve o Robô (a conexão é guardada por Robô + nome do servidor). 3. Clique em Conectar. Uma janela neutra de autorização abre imediatamente; mantenha-a aberta. Quando a plataforma recebe o endereço do provedor, a janela navega para a tela de consentimento em contexto isolado — o provedor não recebe acesso à aba do Studio. Faça login e autorize. 4. A janela se fecha sozinha ao terminar e o status vira Conectado (com validade e escopo, quando o provedor informa). Se ela permanecer aberta depois da confirmação do provedor, feche-a para que o Studio consulte o status. Se o navegador bloquear a janela, permita popups para este site e tente de novo. 5. Clique em Descobrir e siga normalmente: as ferramentas do servidor passam a valer para o Robô. 6. Desconectar esquece as credenciais desse par Robô + servidor. Para trocar de conta no provedor: desconecte e conecte de novo. As credenciais OAuth ficam cifradas no Maestro, atreladas ao par Robô + servidor. Elas nunca são guardadas na Conversa Labs, nunca aparecem em telas ou logs e nunca são enviadas ao modelo. Configurações & opções - Perfis (Conexões MCP) da conta: cada perfil tem nome, usuário de execução estático, seleção de toolsets, modo somente leitura, URL estática (com public_id) e segredo bearer próprio (revelado uma única vez, rotacionável). A seleção estática efetiva é sempre seleção ∩ teto do Super Admin ∩ permissões do usuário de execução. - OAuth nativo da conta (condicional): o recurso OAuth é a URL separada /mcp/oauth/c/ID_PUBLICO. Ele usa a superfície de ferramentas do perfil, mas o membro que consentiu, não o usuário estático. Seus grants são visíveis/revogáveis em Configurações → Perfil → Conexões MCP; grants existentes continuam visíveis para revogação se o servidor for desabilitado depois. - Modo somente leitura: por perfil, expõe só ferramentas de leitura. - Compatibilidade com a pesquisa profunda do ChatGPT: por perfil, acrescenta as duas ferramentas search e fetch que aquele conector exige pelo nome. Elas apenas descrevem o que o perfil já expõe. Custam duas vagas do teto de ferramentas (o servidor reserva quatro em vez de duas quando ligado), então deixe desligado para Claude e clientes genéricos. - Teto de ferramentas: há um limite por servidor (512), aplicado por perfil — ele corta a lista, não o acesso. As meta-ferramentas search_tools (descobre, com o schema) e call_tool (executa pelo nome) alcançam tudo o que o perfil habilitou, sempre respeitando o modo somente leitura, as permissões do usuário de execução e o teto do Super Admin. - Token do Maestro: um por conta, revelado uma única vez, rotacionável a qualquer momento. - Servidores externos por Robô: nome técnico, URL, transporte, timeout, autenticação, cabeçalhos extras, aprovação (HITL) e allowlist de ferramentas. - Tipos de autenticação (servidor externo): | Tipo | Como funciona | Quando usar | |---|---|---| | nenhuma | nada é enviado | servidores realmente públicos (raro) | | bearer | envia Authorization: Bearer <segredo> | o caso mais comum — segredo guarda a chave de API | | header | envia um cabeçalho com nome à sua escolha e valor do segredo | o provedor usa um esquema próprio | | query | envia o segredo como parâmetro na URL | provedores legados | | basic | usuário + senha (dois segredos) | servidores internos | | OAuth | botão Conectar → consentimento no provedor | o provedor só aceita OAuth (Notion) | - Orçamento de ferramentas: as ferramentas de cada servidor externo contam no orçamento de ferramentas do Robô — servidores demais estouram o limite. - Proteção SSRF: endereços privados/internos são bloqueados ao adicionar um servidor externo. Casos de uso - Operar a caixa de entrada a partir do Claude Code ou de uma IDE: listar conversas, responder, resolver. - Um perfil por cliente: cada IDE, script ou parceiro recebe a sua própria conexão, com escopo mínimo e — nos clientes de leitura — o modo somente leitura ligado. - Puxar relatórios da conta para dentro de um assistente com um perfil somente leitura, executado por um usuário de perfil restrito. - Revogar um único cliente: rotacione (ou exclua) o perfil daquele cliente — os demais perfis continuam funcionando. - Dar ao Robô acesso a um sistema interno (ERP, base de conhecimento) via servidor MCP externo, com aprovação humana nas ações sensíveis. - Deixar o Robô abrir tarefas no Linear ou ler uma base no Notion durante o atendimento. - Deixar o time de dados perguntar ask_risco / ask_financeiro e receber as descobertas do departamento sem abrir o painel. Dicas, limites e boas práticas - Qual autenticação escolher em cada servidor externo popular (a maioria responde 401 com desafio OAuth, mas aceita uma chave de API comum em Authorization: Bearer — deixar em nenhuma é a causa número 1 de falha na descoberta): | Servidor MCP externo | Autenticação a escolher | |---|---| | Linear | bearer + segredo com a chave de API | | Stripe | bearer + segredo com a chave restrita | | GitHub | bearer + segredo com um token pessoal (PAT) | | Atlassian (Jira/Confluence) | bearer + segredo com o token de API | | Sentry | header com nome Authorization e segredo cujo valor é Sentry-Bearer SEU_TOKEN | | Notion | OAuth (botão Conectar) — não aceita chave estática | | Servidor interno próprio | conforme o servidor exigir | - Segredo estático versus consentimento OAuth: o segredo estático do perfil carrega as permissões do usuário de execução estático — nunca mais do que ele já tem. Um grant OAuth nativo roda como o membro que consentiu e fica vinculado ao recurso OAuth exato. Trate ambos como credenciais e nunca os troque entre as duas URLs. - Um perfil por cliente: assim você dá escopo mínimo a cada um e pode rotacionar/excluir um perfil para cortar só aquele cliente, sem tocar nos outros. - Somente leitura primeiro: comece cada perfil com o modo somente leitura ligado e habilite a escrita por toolset conforme a confiança no cliente. - Menos é mais: exponha só os toolsets que o cliente realmente usa — listas enormes de ferramentas pioram a escolha do modelo. - Copie o segredo do perfil na hora: ele não é exibido de novo. Perdeu? Rotacione o token do perfil (o anterior é invalidado na hora) e atualize o cliente que o usava. - Segredos por referência: em servidores MCP externos, nunca cole o valor do segredo no campo — informe a chave do segredo. - Copie o token do Maestro na hora: ele não é exibido de novo. Perdeu? Rotacione (e atualize os clientes que usavam o anterior). - Aprovação (HITL): para servidores externos que escrevem em sistemas críticos, marque Exigir aprovação. Solução de problemas - O cliente mostra menos ferramentas do que os módulos que liguei no perfil: é o teto de exibição do servidor. As demais continuam alcançáveis: peça ao cliente para usar search_tools (encontra a ferramenta e devolve o schema dela) e call_tool (executa pelo nome). Para vê-las na lista, desmarque módulos ou peça ao operador para aumentar o teto. - O card do Maestro mostra um endereço interno (aviso âmbar): a instalação não declarou o endereço público do Maestro. Um cliente na mesma máquina conecta; uma IDE fora da rede, não. O operador precisa definir MAESTRO_PUBLIC_BASE_URL com o endereço público do Maestro (e reiniciar a aplicação). - O cliente conecta pelo endereço público do Maestro e recebe "Invalid Host header" (ou 421): o Maestro só aceita o Host que a instalação declarou. É o mesmo MAESTRO_PUBLIC_BASE_URL — depois de defini-lo, o host público passa a ser aceito (a proteção contra DNS rebinding continua ligada). - Um conector ainda mostra ícone antigo ou genérico: confirme que a origem canônica pública HTTPS e a URL do ícone carregam sem autenticação, salve o White Label e reconecte o provedor para ele executar initialize outra vez. O servidor preserva a última marca válida enquanto o Maestro tenta novamente após uma indisponibilidade temporária; o provedor ainda pode manter cache ou decidir não exibir seus metadados de ícone. - A página MCP não aparece no menu: o recurso MCP está desligado para a conta (peça ao operador) ou o seu usuário não é administrador. - 404 no endpoint da conexão: o recurso está desligado para a conta, o interruptor global da instalação está desativado, ou o ID_PUBLICO da URL não existe (perfil excluído ou desativado). - 401 na conexão da conta: o segredo do perfil está errado ou foi rotacionado (o anterior é invalidado na hora), o perfil foi excluído/desativado, ou o usuário de execução deixou de ser membro da conta. Use o segredo revelado ao criar/rotacionar o perfil — token pessoal de API e token de Robô não são a credencial dessa conexão. - Um cliente estático tenta fazer login por OAuth: a URL estática da conta termina em /mcp/c/ID_PUBLICO e aceita apenas o segredo do perfil em Authorization: Bearer ...; ela não anuncia servidor OAuth. Mantenha esse cliente na configuração de Bearer estático. - O recurso OAuth ou o discovery retorna 404: o OAuth nativo é propositalmente dark-shipped. Confira a habilitação do OAuth nativo, o recurso/perfil MCP da conta e o emissor público; então recomece pelos Metadados de Recurso Protegido exatos. Não substitua por segredo estático nem token de outro plano. - A URL OAuth retorna 401: o Bearer OAuth está ausente, expirou, foi revogado ou pertence a outro recurso/plano. Leia o cabeçalho WWW-Authenticate: ele aponta para os Metadados de Recurso Protegido exatos (e traz invalid_token apenas quando um Bearer enviado foi recusado). Recomece por esse metadado; nunca cole o segredo estático do perfil nessa URL. - A URL OAuth retorna 403: o Bearer é válido, mas a chamada pediu uma ferramenta de escrita sem o escopo mcp:write. Peça esse escopo no consentimento e confirme que o perfil não é somente leitura; um mcp:write também não libera ferramentas fora do perfil. - A URL OAuth retorna 413: a requisição JSON-RPC ou a resposta ultrapassou 1 MiB. Reduza a carga ou use paginação. Uma requisição grande é recusada antes da execução; uma resposta grande só é medida após a operação terminar, então não repita uma escrita cegamente — confira o recurso ou a auditoria primeiro. - Um cliente OAuth ainda não conclui o consentimento: registre cliente e versão, URI de redirecionamento, resultado do discovery e código de erro seguro em um teste controlado. Não contorne PKCE, vínculo ao recurso ou consentimento no navegador; compatibilidade só existe após prova ponta a ponta. - Toolset acinzentado com selo “bloqueado”: o Super Admin não liberou esse toolset no teto global. Só ele pode liberar. - Perdi o segredo do perfil: gere outro com Rotacionar token no perfil — o anterior é invalidado na hora. - Perdi o token do Maestro: gere outro com Rotacionar token no card do Maestro — o anterior é invalidado na hora. - A descoberta (“Descobrir”) falha com 401: quase sempre a autenticação está em nenhuma. Escolha bearer e aponte o segredo com a chave de API do provedor (Sentry usa header; Notion usa OAuth). - A descoberta falha por outro motivo: confira URL, transporte (Streamable HTTP ou SSE) e credenciais; salve o Robô antes se a autenticação usa um segredo armazenado; endereços privados/internos são recusados pela proteção SSRF. - O botão Conectar não abre nada: o navegador bloqueou o pop-up — libere pop-ups para o domínio e clique de novo. - Conectado, mas a ferramenta falha depois de um tempo: a autorização do provedor expirou — Desconecte e Conecte de novo. - Ferramenta externa falha em uso: o erro volta como texto para o agente (que se autocorrige) e nunca derruba o turno. - ask_<departamento> responde “disabled”: o departamento está desativado para a conta — ative-o na tela do Cérebro (Account Brain). Veja também - SDK, API REST e MCP de Dashboard Apps - Referência da API (Swagger/OpenAPI) - Tokens REST, webhooks e autenticação - Robôs e canal de API

API e MCP de mensagens agendadas

Visão geral A API de mensagens agendadas expõe o mesmo módulo usado no dashboard. Ela opera sempre dentro de uma conta e sobre uma conversa existente. As ferramentas MCP são geradas desse contrato OpenAPI e aplicam as mesmas permissões e validações. Pré-requisitos - Feature Mensagens agendadas habilitada na conta. - Token de usuário com acesso à conta, Inbox e conversa. - Políticas completas configuradas na conta. - Para criação, uma chave X-Idempotency-Key estável de 1 a 128 caracteres. Passo a passo 1. Consulte GET /api/v1/accounts/{account_id}/message_scheduling/settings e confirme a política efetiva. 2. Envie a definição para POST .../message_schedules/preview. A prévia não persiste nem envia. 3. Corrija todos os blockers e crie com POST .../message_schedules mais X-Idempotency-Key. 4. Guarde id e lock_version. Repetir a mesma chave e conteúdo devolve o agendamento existente; conteúdo diferente devolve 409. 5. Liste ocorrências em GET .../message_schedules/{id}/occurrences. 6. Em alterações e ações, envie o lock_version atual e o scope exigido. Configurações & opções - Tipos: one_time, sequence, recurring_single e recurring_sequence. - Escopos de ocorrência: this_occurrence, this_and_future e all_future. - send_now exige escolher entre consumir a ocorrência ou criar uma cópia imediata. - reconcile exige um resultado observado: sent, failed ou canceled. - Ações de agenda usam all_future; resume também informa a ação de retomada publicada. - O alvo, remetente efetivo, capabilities e draft normalizado são autoritativos no servidor. No MCP, procure as ferramentas pelo grupo Message Schedules. Os nomes são derivados do operationId; argumentos e respostas são os mesmos do Swagger. Casos de uso - Um CRM externo agenda um retorno idempotente após uma atualização de negócio. - Um operador de IA usa MCP para consultar bloqueios e pausar uma sequência com confirmação humana. - Um processo de reconciliação registra o resultado de um envio incerto sem duplicá-lo. Dicas, limites e boas práticas - Nunca reutilize uma chave idempotente para uma definição diferente. - Ao receber 409, releia o recurso; não incremente o lock localmente por suposição. - Não envie campaign_id, audiência, segmento ou lista de contatos. O contrato é de uma conversa. - Use a prévia antes da criação e trate a validação no vencimento como uma segunda autoridade. - Não faça retry automático de needs_attention; confirme primeiro o efeito no provedor. - Consulte o OpenAPI publicado para schemas e exemplos completos, inclusive drafts multipartes. Solução de problemas - 400 invalid_idempotency_key: ajuste formato/tamanho do header. - 401/403: confira token, feature, papel, Inbox e acesso à conversa. - 409 stale_lock_version: recarregue o agendamento ou ocorrência e reaplique a intenção. - 422 preview_blocked: leia cada código em blockers e corrija política, canal, remetente ou conteúdo. - MCP não mostra a ferramenta: confirme que o servidor publicou o Swagger atual e atualize a sessão/catálogo MCP. Veja também - Criar e gerenciar mensagens agendadas - Referência da API (Swagger/OpenAPI) - Servidor e cliente MCP

Bots de atendimento e canal de API

Visão geral A Conversa Labs oferece dois pontos de extensão complementares para desenvolvedores: - Canal de API: um inbox programável. Em vez de um canal pronto (WhatsApp, e-mail etc.), você cria uma caixa de entrada do tipo API e conecta o seu próprio aplicativo. Mensagens de entrada chegam via API REST e as respostas dos agentes são entregues no seu webhook_url. - Agent bot: um bot via webhook (bot_type: webhook). Ele é atribuído a um inbox (de qualquer canal) e recebe os eventos de conversa/mensagem no seu outgoing_url. O bot processa o evento e pode responder chamando a API de volta com o seu token de acesso. Quando usar cada um: - Use o canal de API quando precisar de um canal sob medida que a plataforma não oferece de forma nativa. - Use um agent bot quando quiser automatizar respostas (triagem, respostas automáticas, IA) antes ou junto do atendimento humano, em qualquer inbox. Os dois podem ser combinados: um inbox de API que também tem um agent bot atribuído. Pré-requisitos - Permissão de administrador na conta (criação de inbox e de agent bots é restrita a admins). - Um endpoint HTTPS acessível para receber webhooks (webhook_url do canal e/ou outgoing_url do bot). - Um token de acesso válido para autenticar as chamadas à API REST. Passo a passo 1. Crie um inbox do tipo API: vá em Configurações → Caixas de entrada → Adicionar → API. Informe um nome e, opcionalmente, o webhook_url. Após criar, anote o identifier gerado para o canal. 2. Envie uma mensagem de entrada: crie/abra uma conversa nesse inbox e poste a mensagem do cliente via API (POST .../conversations/:id/messages), autenticando com o token de acesso. 3. Configure o webhook_url do canal para receber as mensagens de saída: quando um agente responde na conversa, o payload é entregue no seu endpoint. 4. (Opcional) Crie um agent bot: em Configurações → Bots de IA/Agent bots, informe nome, descrição e o outgoing_url (bot_type = webhook). Depois atribua o bot ao inbox para que ele passe a receber os eventos daquela caixa de entrada. Configurações & opções - Token de acesso do bot: usado pelo bot para chamar a API de volta (criar respostas, reagir, atualizar status). Pode ser regenerado por reset_access_token. - Segredo do bot: usado para assinar/verificar o payload do webhook enviado ao outgoing_url. Pode ser regenerado por reset_secret. - Verificação HMAC do canal (hmac_token, hmac_mandatory): valida a identidade do contato. Com hmac_mandatory ativo, contatos só são aceitos com o hash de identificação válido, calculado a partir do hmac_token. - Atualização de status de mensagem: permitida apenas em inboxes de API (por exemplo, marcar entregue/lida ou registrar erro de envio). - Payload do bot (webhook_data): identifica o bot no evento com { id, name, type: "agent_bot" }. Casos de uso - Canal sob medida: conectar um aplicativo próprio (um app interno, um marketplace, um canal proprietário) como um inbox via API. - Respostas automáticas: um agent bot que faz a triagem inicial, responde dúvidas frequentes e só então passa a conversa para um agente humano. Dicas, limites e boas práticas - Sempre verifique a assinatura HMAC do webhook (canal e/ou segredo do bot) antes de processar o payload. - Garanta idempotência: ao criar mensagens de entrada, use um source_id único para deduplicar reentregas. - Defina um ponto de handoff claro do bot para o humano (por exemplo, atribuir a conversa a um agente/time e parar de responder pelo bot). - Trate tokens e segredos como credenciais: nunca os exponha no front-end. Solução de problemas - 401/403: token de acesso inválido, expirado ou sem permissão. - O bot não recebe eventos: confirme que o outgoing_url está correto, acessível e que o bot está atribuído ao inbox. - HMAC inválido: o hash de identificação não confere com o hmac_token; recalcule a assinatura e confira a ordem/codificação dos campos. Veja também - API REST, tokens e webhooks - Eventos por módulo - Canal de API: o contrato de eventos estruturados

API de Plataforma (provisionamento multi-conta)

Visão geral A API de Plataforma opera acima das contas: ela permite criar e gerenciar contas, usuarios, vinculos usuario-conta e agent bots de forma programatica. Tudo fica sob um Platform App — uma aplicacao de plataforma que o operador cria e que recebe um token proprio. Diferenca para a API REST da conta: - A API REST trabalha dentro de uma unica conta (contatos, conversas, mensagens) e usa o token de um usuario/agente daquela conta. - A API de Plataforma trabalha entre contas (provisionamento e ciclo de vida) e usa o token do Platform App. Os endpoints ficam sob o prefixo /platform/api/v1. Um Platform App so enxerga e altera os objetos que estao na sua lista de permissiveis (as contas, usuarios e bots que ele mesmo criou ou que foram associados a ele). Pre-requisitos - Um Platform App criado pelo operador (em Super Admin -> Platform Apps). - O token de acesso desse Platform App (gerado junto com o app). - O token deve trafegar apenas no backend do operador — nunca no front-end. Passo a passo 1. O operador cria um Platform App em Super Admin -> Platform Apps. Ao salvar, a plataforma gera um token de acesso vinculado ao app. 2. Autentique cada chamada incluindo o cabecalho api_access_token com o token do Platform App. Se o token nao pertencer a um Platform App, a resposta e 401 Invalid access_token. 3. Crie uma conta: POST /platform/api/v1/accounts api_access_token: <token-da-plataforma> Content-Type: application/json { "name": "Cliente XPTO", "locale": "pt_BR", "support_email": "suporte@cliente.com" } A conta criada e adicionada automaticamente aos permissiveis do app. 4. Crie um usuario: POST /platform/api/v1/users { "name": "Maria", "email": "maria@cliente.com", "password": "<senha-forte>" } O usuario tambem entra nos permissiveis do app. Se ja existir um usuario com aquele e-mail, a plataforma reaproveita o usuario existente. 5. Vincule usuario e conta (account_user) com papel: POST /platform/api/v1/accounts/<account_id>/account_users { "user_id": <user_id>, "role": "administrator" } Use administrator ou agent no campo role. 6. Provisione agent bots: POST /platform/api/v1/agent_bots { "name": "Bot de Vendas", "account_id": <account_id>, "outgoing_url": "https://meu-bot/webhook" } Endpoints complementares: GET/PATCH/DELETE /platform/api/v1/accounts/:id, GET :id e DELETE :id de usuarios, GET .../account_users (listar), DELETE .../account_users (remover vinculo), GET :id/login (gera um link de acesso SSO para o usuario) e POST :id/token. Configuracoes & opcoes - Objetos permissiveis: cada Platform App mantem uma lista de contas, usuarios e agent bots que pode gerenciar. Objetos que o app cria entram nessa lista automaticamente. - Escopo do token: o token do Platform App so atua sobre os permissiveis do app — ele nao alcanca contas/usuarios de outros apps nem dados internos de uma conta (para isso, use a API REST da conta). - Parametros de conta: name, locale, domain, support_email, status, alem de features, limits e custom_attributes. - Parametros de usuario: name, display_name, email, password e custom_attributes. Casos de uso - Onboarding multi-tenant / revenda: criar uma conta por cliente e popular usuarios em massa. - Provisionamento estilo SSO: criar o usuario e gerar o link de login (GET :id/login) para levar o usuario direto ao painel sem senha manual. - Ciclo de vida automatizado: criar, atualizar e desativar contas e vinculos a partir do seu proprio sistema (ex.: ao concluir ou cancelar uma assinatura). Dicas, limites e boas praticas - Mantenha o token do Platform App somente no backend do operador. Ele tem poder de provisionamento — nunca o exponha no front-end nem em apps cliente. - Trabalhe com permissoes restritas: o app so deve tocar nos objetos que ele mesmo criou. - A remocao de contas e usuarios e assincrona (enfileirada) — a resposta 200 indica que a exclusao foi agendada, nao concluida no mesmo instante. - Trate idempotencia: criar um usuario com e-mail ja existente reaproveita o registro; criar o mesmo vinculo conta-usuario nao duplica. Solucao de problemas - 401 Invalid access_token: o token nao pertence a um Platform App (ou esta ausente/incorreto no cabecalho api_access_token). - 401 Non permissible resource: o objeto (conta/usuario/bot) nao esta na lista de permissiveis do app — voce esta tentando alterar algo que o app nao gerencia. - 404: o id informado nao existe. Veja tambem - API REST, tokens e webhooks - Referencia de API (Swagger / OpenAPI) - Visao geral de API & Desenvolvedores