# Recursos Disponíveis Source: https://docs.evolutionfoundation.com.br/evolution-api/configuration/available-resources ## Recursos de Mensagens e Grupos ### Mensagens (Individuais ou em Grupo) | Recurso | Disponibilidade | Descrição | | --------------------------------: | :-------------: | ---------------------------------------------------------------------------- | | Envio de Texto | ✅ | (Texto simples, em negrito, itálico, riscado, em formato de código e emojis) | | Envio de Mídia | ✅ | (Vídeo, imagem e documento) | | Envio de Áudio Narrado | ✅ | (Funcionando bem no Android e iOS) | | Envio de Localização | ✅ | (Com nome e descrição do local) | | Envio de Contato | ✅ | (Com Nome, Empresa, Telefone, E-mail e URL) | | Envio de Reação | ✅ | (Envie qualquer emoji para reação) | | Envio de Pré-visualização de Link | ✅ | (Busca por informações de SEO) 🆕 | | Envio de Resposta | ✅ | (Marcar mensagens em resposta) 🆕 | | Envio de Menção | ✅ | (Individual, para alguns ou todos os membros) 🆕 | | Envio de Enquete | ✅ | (Enviar e receber votos de uma enquete) 🆕 | | Envio de Status/História | ✅ | (Texto, pré-visualização de link, vídeo, imagem e forma de onda) 🆕 | | Envio de Adesivo | ✅ | (Imagem estática) 🆕 | | Envio de Lista (Homologação) | ✅ | (Testando) | | Envio de Botões (Descontinuado) | ❌ | (Só funciona na API em nuvem) | ### Perfil | Recurso | Disponibilidade | Descrição | | ------------------ | :-------------: | ----------------------------------------- | | Atualizar Nome | ✅ | (Alterar o nome do perfil conectado) | | Atualizar Foto | ✅ | (Alterar a foto do perfil conectado) 🆕 | | Atualizar Status | ✅ | (Alterar o status do perfil conectado) 🆕 | | E muitos outros... | | | ### Grupo | Recurso | Disponibilidade | Descrição | | --------------------- | :-------------: | ------------------------------------------ | | Criar Grupo | ✅ | (Novos grupos) | | Atualizar Foto | ✅ | (Alterar foto do grupo) | | Atualizar Assunto | ✅ | (Alterar o nome do grupo) 🆕 | | Atualizar Descrição | ✅ | (Alterar a descrição do grupo) 🆕 | | Obter Todos os Grupos | ✅ | (Obter todos os grupos e participantes) 🆕 | | E muitos outros... | | | # Variáveis de Ambiente Source: https://docs.evolutionfoundation.com.br/evolution-api/configuration/env Veja o arquivo de exemplo do env no repositório oficial. ## Server | Variável | Valor | Exemplo | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | | SERVER\_TYPE | O tipo de servidor (http ou https) | http | | SERVER\_PORT | Porta em que o servidor será executado | 8080 | | SERVER\_URL | O endereço para seu servidor em execução. Esse endereço é utilizado para retornar dados de requisição interna, como links de webhook. | `https://exemplo.evolution-api.com` | ## Telemetria | Variável | Valor | Exemplo | | -------------- | --------------------------------------------------- | ------------------------------- | | TELEMETRY | Habilita ou desabilita a telemetria (true ou false) | true | | TELEMETRY\_URL | URL do servidor de telemetria | `https://telemetry.example.com` | ## CORS | Variável | Valor | Exemplo | | ----------------- | --------------------------------------------------------------------------------------------------------------- | ------------------- | | CORS\_ORIGIN | As origens permitidas pela API separadas por vírgula (utilize "\*" para aceitar requisições de qualquer origem) | \* | | CORS\_METHODS | Métodos HTTP permitidos separados por vírgula | GET,POST,PUT,DELETE | | CORS\_CREDENTIALS | Permissão de cookies em requisições (true ou false) | true | ## Logs | Variável | Valor | Exemplo | | ------------ | ----------------------------------------------------------------------------------------------- | ----------------------------------------------- | | LOG\_LEVEL | Logs que serão mostrados entre: ERROR, WARN, DEBUG, INFO, LOG, VERBOSE, DARK, WEBHOOKS | ERROR,WARN,DEBUG,INFO,LOG,VERBOSE,DARK,WEBHOOKS | | LOG\_COLOR | Mostrar ou não cores nos Logs (true ou false) | true | | LOG\_BAILEYS | Quais logs da Baileys serão mostrados entre: "fatal", "error", "warn", "info", "debug", "trace" | error | ## Instâncias | Variável | Valor | Exemplo | | ------------- | ----------------------------------------------------------------------------------------------- | ------- | | DEL\_INSTANCE | Em quantos minutos uma instância será excluída se não conectada. Use "false" para nunca excluir | false | ## Armazenamento Persistente | Variável | Valor | Exemplo | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | DATABASE\_ENABLED | Se o armazenamento persistente está habilitado (true ou false) | true | | DATABASE\_PROVIDER | Provedor de banco de dados (postgresql ou mysql) | postgresql | | DATABASE\_CONNECTION\_URI | A URI de conexão do banco de dados | `postgresql://user:pass@localhost:5432/evolution?schema=public` | | DATABASE\_CONNECTION\_CLIENT\_NAME | Nome do cliente para a conexão com o banco de dados, usado para separar uma instalação da API de outra que usa o mesmo banco | evolution\_exchange | ### Quais dados serão salvos (true ou false) | Variável | Valor | | ---------------------------------- | ------------------------------- | | DATABASE\_SAVE\_DATA\_INSTANCE | Salva dados de instâncias | | DATABASE\_SAVE\_DATA\_NEW\_MESSAGE | Salva novas mensagens | | DATABASE\_SAVE\_MESSAGE\_UPDATE | Salva atualizações de mensagens | | DATABASE\_SAVE\_DATA\_CONTACTS | Salva contatos | | DATABASE\_SAVE\_DATA\_CHATS | Salva conversas | | DATABASE\_SAVE\_DATA\_LABELS | Salva etiquetas | | DATABASE\_SAVE\_DATA\_HISTORIC | Salva histórico de eventos | ## RabbitMQ | Variável | Valor | Exemplo | | ------------------------- | --------------------------------------------------- | ------------------ | | RABBITMQ\_ENABLED | Habilita o RabbitMQ (true ou false) | false | | RABBITMQ\_URI | URI de conexão do RabbitMQ | `amqp://localhost` | | RABBITMQ\_EXCHANGE\_NAME | Nome do exchange | evolution | | RABBITMQ\_GLOBAL\_ENABLED | Habilita o RabbitMQ de forma global (true ou false) | false | ### Escolha os eventos que deseja enviar para o RabbitMQ | Variável | Valor | Exemplo | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------- | | RABBITMQ\_EVENTS\_APPLICATION\_STARTUP | Envia um evento na inicialização do app (true ou false) | false | | RABBITMQ\_EVENTS\_INSTANCE\_CREATE | Envia eventos de criação de instância (true ou false) | false | | RABBITMQ\_EVENTS\_INSTANCE\_DELETE | Envia eventos de deleção de instância (true ou false) | false | | RABBITMQ\_EVENTS\_QRCODE\_UPDATED | Envia eventos de atualização do QR Code (true ou false) | false | | RABBITMQ\_EVENTS\_MESSAGES\_SET | Envia eventos de criação de mensagens (recuperação de mensagens) (true ou false) | false | | RABBITMQ\_EVENTS\_MESSAGES\_UPSERT | Envia eventos de recebimento de mensagens (true ou false) | false | | RABBITMQ\_EVENTS\_MESSAGES\_EDITED | Envia eventos de edição de mensagens (true ou false) | false | | RABBITMQ\_EVENTS\_MESSAGES\_UPDATE | Envia eventos de atualização de mensagens (true ou false) | false | | RABBITMQ\_EVENTS\_MESSAGES\_DELETE | Envia eventos de deleção de mensagens (true ou false) | false | | RABBITMQ\_EVENTS\_SEND\_MESSAGE | Envia eventos de envio de mensagens (true ou false) | false | | RABBITMQ\_EVENTS\_CONTACTS\_SET | Envia eventos de criação de contatos (true ou false) | false | | RABBITMQ\_EVENTS\_CONTACTS\_UPSERT | Envia eventos de recuperação de contatos (true ou false) | false | | RABBITMQ\_EVENTS\_CONTACTS\_UPDATE | Envia eventos de atualização de contatos (true ou false) | false | | RABBITMQ\_EVENTS\_PRESENCE\_UPDATE | Envia eventos de atualização de presença ("digitando..." ou "gravando...") (true ou false) | false | | RABBITMQ\_EVENTS\_CHATS\_SET | Envia eventos de criação de conversas (recuperação de conversas) (true ou false) | false | | RABBITMQ\_EVENTS\_CHATS\_UPSERT | Envia eventos de criação de conversas (recebimento ou envio de mensagens em novos chats) (true ou false) | false | | RABBITMQ\_EVENTS\_CHATS\_UPDATE | Envia eventos de atualização de conversas (true ou false) | false | | RABBITMQ\_EVENTS\_CHATS\_DELETE | Envia eventos de deleção de conversas (true ou false) | false | | RABBITMQ\_EVENTS\_GROUPS\_UPSERT | Envia eventos de criação de grupos (true ou false) | false | | RABBITMQ\_EVENTS\_GROUP\_UPDATE | Envia eventos de atualização de grupos (true ou false) | false | | RABBITMQ\_EVENTS\_GROUP\_PARTICIPANTS\_UPDATE | Envia eventos de atualização nos participantes de grupos (true ou false) | false | | RABBITMQ\_EVENTS\_CONNECTION\_UPDATE | Envia eventos de atualização de conexão (true ou false) | false | | RABBITMQ\_EVENTS\_CALL | Envia eventos de chamadas (true ou false) | false | | RABBITMQ\_EVENTS\_TYPEBOT\_START | Envia eventos de início de fluxo do Typebot (true ou false) | false | | RABBITMQ\_EVENTS\_TYPEBOT\_CHANGE\_STATUS | Envia eventos de atualização no status do Typebot (true ou false) | false | ## SQS | Variável | Valor | Exemplo | | ------------------------ | ---------------------------------------- | ------- | | SQS\_ENABLED | Se o SQS está habilitado (true ou false) | false | | SQS\_ACCESS\_KEY\_ID | O ID de chave do SQS | - | | SQS\_SECRET\_ACCESS\_KEY | Chave de acesso | - | | SQS\_ACCOUNT\_ID | ID da conta | - | | SQS\_REGION | Região do SQS | - | ## WebSocket | Variável | Valor | Exemplo | | ------------------------- | ----------------------------------------------------- | ------- | | WEBSOCKET\_ENABLED | Habilita o WebSocket (true ou false) | false | | WEBSOCKET\_GLOBAL\_EVENTS | Habilita eventos globais no WebSocket (true ou false) | false | ## WhatsApp Business API | Variável | Valor | Exemplo | | ---------------------------- | -------------------------------------------------- | ---------------------------- | | WA\_BUSINESS\_TOKEN\_WEBHOOK | Token usado para validar o webhook no Facebook APP | evolution | | WA\_BUSINESS\_URL | URL da API do WhatsApp Business | `https://graph.facebook.com` | | WA\_BUSINESS\_VERSION | Versão da API do WhatsApp Business | v20.0 | | WA\_BUSINESS\_LANGUAGE | Idioma da API do WhatsApp Business | en\_US | ## Webhook Global | Variável | Valor | Exemplo | | ------------------------------------ | ------------------------------------------------------------------------------------------ | ----------------------------- | | WEBHOOK\_GLOBAL\_ENABLED | Se os webhooks estão habilitados globalmente (true ou false) | false | | WEBHOOK\_GLOBAL\_URL | URL que receberá as requisições de webhook | `https://webhook.example.com` | | WEBHOOK\_GLOBAL\_WEBHOOK\_BY\_EVENTS | Ativa webhook por evento, respeitando a URL global e o nome de cada evento (true ou false) | false | ### Eventos de webhook com valor true ou false | Variável | | -------------------------------------------- | | WEBHOOK\_EVENTS\_APPLICATION\_STARTUP | | WEBHOOK\_EVENTS\_QRCODE\_UPDATED | | WEBHOOK\_EVENTS\_MESSAGES\_SET | | WEBHOOK\_EVENTS\_MESSAGES\_UPSERT | | WEBHOOK\_EVENTS\_MESSAGES\_EDITED | | WEBHOOK\_EVENTS\_MESSAGES\_UPDATE | | WEBHOOK\_EVENTS\_MESSAGES\_DELETE | | WEBHOOK\_EVENTS\_SEND\_MESSAGE | | WEBHOOK\_EVENTS\_CONTACTS\_SET | | WEBHOOK\_EVENTS\_CONTACTS\_UPSERT | | WEBHOOK\_EVENTS\_CONTACTS\_UPDATE | | WEBHOOK\_EVENTS\_PRESENCE\_UPDATE | | WEBHOOK\_EVENTS\_CHATS\_SET | | WEBHOOK\_EVENTS\_CHATS\_UPSERT | | WEBHOOK\_EVENTS\_CHATS\_UPDATE | | WEBHOOK\_EVENTS\_CHATS\_DELETE | | WEBHOOK\_EVENTS\_GROUPS\_UPSERT | | WEBHOOK\_EVENTS\_GROUPS\_UPDATE | | WEBHOOK\_EVENTS\_GROUP\_PARTICIPANTS\_UPDATE | | WEBHOOK\_EVENTS\_CONNECTION\_UPDATE | | WEBHOOK\_EVENTS\_LABELS\_EDIT | | WEBHOOK\_EVENTS\_LABELS\_ASSOCIATION | | WEBHOOK\_EVENTS\_CALL | | WEBHOOK\_EVENTS\_TYPEBOT\_START | | WEBHOOK\_EVENTS\_TYPEBOT\_CHANGE\_STATUS | | WEBHOOK\_EVENTS\_ERRORS | | WEBHOOK\_EVENTS\_ERRORS\_WEBHOOK | ## Configurações de Sessão | Variável | Valor | Exemplo | | ------------------------------ | -------------------------------------------------------- | ------------- | | CONFIG\_SESSION\_PHONE\_CLIENT | Nome que será exibido na conexão do smartphone | Evolution API | | CONFIG\_SESSION\_PHONE\_NAME | Nome do navegador (Chrome, Firefox, Edge, Opera, Safari) | Chrome | ## QR Code | Variável | Valor | Exemplo | | ------------- | --------------------------------- | ------- | | QRCODE\_LIMIT | Por quanto tempo o QR code durará | 30 | | QRCODE\_COLOR | Cor do QR code gerado | #175197 | ## Typebot | Variável | Valor | Exemplo | | --------------------- | ------------------------------------- | ------- | | TYPEBOT\_API\_VERSION | Versão da API (versão fixa ou latest) | latest | ## Chatwoot | Variável | Valor | Exemplo | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | CHATWOOT\_ENABLED | Habilita a integração com Chatwoot (true ou false) | false | | CHATWOOT\_MESSAGE\_READ | Marca como lida a última mensagem do cliente no WhatsApp ao enviar uma mensagem no Chatwoot (true ou false) | true | | CHATWOOT\_MESSAGE\_DELETE | Deleta a mensagem no Chatwoot quando deletada no WhatsApp (true ou false) | true | | CHATWOOT\_IMPORT\_DATABASE\_CONNECTION\_URI | URI de conexão com o banco de dados do Chatwoot para importar mensagens | `postgresql://user:password@host:5432/chatwoot?sslmode=disable` | | CHATWOOT\_IMPORT\_PLACEHOLDER\_MEDIA\_MESSAGE | Importa as mensagens de mídia como placeholder no Chatwoot (true ou false) | true | ## OpenAI | Variável | Valor | Exemplo | | --------------- | ------------------------------------------------ | ------- | | OPENAI\_ENABLED | Habilita a integração com OpenAI (true ou false) | false | ## Dify | Variável | Valor | Exemplo | | ------------- | ---------------------------------------------- | ------- | | DIFY\_ENABLED | Habilita a integração com Dify (true ou false) | false | ## Cache | Variável | Valor | Exemplo | | ----------------------------- | -------------------------------------------------------------------------------- | -------------------------- | | CACHE\_REDIS\_ENABLED | Habilita o cache Redis (true ou false) | true | | CACHE\_REDIS\_URI | A URI de conexão do Redis | `redis://localhost:6379/6` | | CACHE\_REDIS\_PREFIX\_KEY | Prefixo para diferenciar dados de uma instalação para outra usando o mesmo Redis | evolution | | CACHE\_REDIS\_SAVE\_INSTANCES | Salva as credenciais de conexão do WhatsApp no Redis (true ou false) | false | | CACHE\_LOCAL\_ENABLED | Habilita o cache local em memória como alternativa ao Redis (true ou false) | false | ## Amazon S3 / MinIO | Variável | Valor | Exemplo | | --------------- | ---------------------------------------------- | ---------------- | | S3\_ENABLED | Habilita o armazenamento no S3 (true ou false) | false | | S3\_ACCESS\_KEY | Chave de acesso do S3 | - | | S3\_SECRET\_KEY | Chave secreta do S3 | - | | S3\_BUCKET | Nome do bucket no S3 | evolution | | S3\_PORT | Porta de conexão ao S3 | 443 | | S3\_ENDPOINT | Endpoint do S3 (ou MinIO) | s3.amazonaws.com | | S3\_USE\_SSL | Usa SSL para conexão ao S3 (true ou false) | true | ## Autenticação | Variável | Valor | Exemplo | | -------------------------------------------- | -------------------------------------------------------- | -------------------------------- | | AUTHENTICATION\_API\_KEY | Chave da API usada para autenticação global | 429683C4C977415CAAFCCE10F7D57E11 | | AUTHENTICATION\_EXPOSE\_IN\_FETCH\_INSTANCES | Exibe as instâncias no endpoint de fetch (true ou false) | true | ## Idioma | Variável | Valor | Exemplo | | -------- | ------------- | ------- | | LANGUAGE | Idioma da API | en | # Webhooks Source: https://docs.evolutionfoundation.com.br/evolution-api/configuration/webhooks Os Webhooks permitem integração em tempo real entre a Evolution API e o WhatsApp™, permitindo sincronização e compartilhamento automatizados de dados. É exatamente esse recurso que possibilita a criação de bots de autoatendimento e sistemas multi-serviço. ## Ativando Webhooks Existem duas maneiras de ativar o webhook: * No arquivo `.env` com eventos globais * Chamando o endpoint `/webhook/instance` ### Eventos de webhook da instância A maioria dos usuários preferirá a ativação por instância, desta forma é mais fácil controlar os eventos recebidos, no entanto em alguns casos é necessário um webhook global, isso pode ser feito usando a variável de webhook global. Aqui está um exemplo com alguns eventos comuns ouvidos: ```json /webhook/instance theme={null} { "url": "{{webhookUrl}}", "webhook_by_events": false, "webhook_base64": false, "events": [ "QRCODE_UPDATED", "MESSAGES_UPSERT", "MESSAGES_UPDATE", "MESSAGES_DELETE", "SEND_MESSAGE", "CONNECTION_UPDATE", "TYPEBOT_START", "TYPEBOT_CHANGE_STATUS" ] } ``` ### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | ------------------- | ------- | ----------- | --------------------------------------------------------------------------------------------------------------- | | enabled | boolean | Sim | Insira "true" para criar ou alterar dados do Webhook, ou "false" se quiser parar de usá-lo. | | url | string | Sim | URL do Webhook para receber dados do evento. | | webhook\_by\_events | boolean | Não | Deseja gerar uma URL específica do Webhook para cada um dos seus eventos. | | events | array | Não | Lista de eventos a serem processados. Se você não quiser usar alguns desses eventos, apenas remova-os da lista. | É extremamente necessário que o payload obedeça às regras para criar um arquivo JSON, considerando o arranjo correto de itens, formatação, colchetes, chaves e vírgulas, etc. Antes de consumir o endpoint, se tiver dúvidas sobre a formatação JSON, vá para [https://jsonlint.com/](https://jsonlint.com/) e valide. ### Eventos Globais de Webhook Cada URL e eventos de Webhook da instância serão solicitados no momento em que forem criados Defina um webhook global que ouvirá eventos habilitados de todas as instâncias ```bash .env theme={null} WEBHOOK_GLOBAL_URL='' WEBHOOK_GLOBAL_ENABLED=false # Com esta opção ativada, você trabalha com uma URL por evento de webhook, respeitando a URL global e o nome de cada evento WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS=false ## Defina os eventos que você deseja ouvir, todos os eventos listados abaixo são suportados WEBHOOK_EVENTS_APPLICATION_STARTUP=false WEBHOOK_EVENTS_QRCODE_UPDATED=true # Alguns eventos extras para erros WEBHOOK_EVENTS_ERRORS=false WEBHOOK_EVENTS_ERRORS_WEBHOOK= ``` ## Eventos Suportados Estes são os eventos de webhook disponíveis e suportados: | **Variável de ambiente** | **URL** | **Descrição** | | --------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | APPLICATION\_STARTUP | /application-startup | Notifica quando uma inicialização de aplicativo ocorre | | QRCODE\_UPDATED | /qrcode-updated | Envia o base64 do qrcode para leitura | | CONNECTION\_UPDATE | /connection-update | Informa o status da conexão com o WhatsApp | | MESSAGES\_SET | /messages-set | Envia uma lista de todas as suas mensagens carregadas no WhatsApp. Este evento ocorre apenas uma vez | | MESSAGES\_UPSERT | /messages-upsert | Notifica quando uma mensagem é recebida | | MESSAGES\_UPDATE | /messages-update | Informa quando uma mensagem é atualizada | | MESSAGES\_DELETE | /messages-delete | Informa quando uma mensagem é excluída | | SEND\_MESSAGE | /send-message | Notifica quando uma mensagem é enviada | | CONTACTS\_SET | /contacts-set | Realiza o carregamento inicial de todos os contatos. Este evento ocorre apenas uma vez | | CONTACTS\_UPSERT | /contacts-upsert | Recarrega todos os contatos com informações adicionais. Este evento ocorre apenas uma vez | | CONTACTS\_UPDATE | /contacts-update | Informa quando o contato é atualizado | | PRESENCE\_UPDATE | /presence-update | Informa se o usuário está online, se ele está realizando alguma ação como escrever ou gravar e seu último visto: 'indisponível', 'disponível', 'compondo', 'gravando', 'pausado' | | CHATS\_SET | /chats-set | Envia uma lista de todos os chats carregados | | CHATS\_UPDATE | /chats-update | Informa quando o chat é atualizado | | CHATS\_UPSERT | /chats-upsert | Envia qualquer nova informação de chat | | CHATS\_DELETE | /chats-delete | Notifica quando um chat é excluído | | GROUPS\_UPSERT | /groups-upsert | Notifica quando um grupo é criado | | GROUPS\_UPDATE | /groups-update | Notifica quando um grupo tem suas informações atualizadas | | GROUP\_PARTICIPANTS\_UPDATE | /group-participants-update | Notifica quando uma ação ocorre envolvendo um participante: 'adicionar', 'remover', 'promover', 'rebaixar' | | NEW\_TOKEN | /new-jwt | Notifica quando o token (jwt) é atualizado | ## Webhook por eventos Ao habilitar as opções WEBHOOK\_BY\_EVENTS nos webhooks globais e locais, os seguintes caminhos serão adicionados ao final do webhook. Adicione ao final da URL o nome do evento com um traço (-) entre as palavras que compõem o evento. ### Exemplo Supondo que sua URL de webhook fosse `https://sub.domain.com/webhook/`. A Evolution adicionará automaticamente ao final da URL o nome do evento quando `webhook_by_events` estiver definido como verdadeiro. | **Evento** | **Nova URL de Webhook por Eventos** | | --------------------------- | ---------------------------------------------------------- | | APPLICATION\_STARTUP | `https://sub.domain.com/webhook/application-startup` | | QRCODE\_UPDATED | `https://sub.domain.com/webhook/qrcode-updated` | | CONNECTION\_UPDATE | `https://sub.domain.com/webhook/connection-update` | | MESSAGES\_SET | `https://sub.domain.com/webhook/messages-set` | | MESSAGES\_UPSERT | `https://sub.domain.com/webhook/messages-upsert` | | MESSAGES\_UPDATE | `https://sub.domain.com/webhook/messages-update` | | MESSAGES\_DELETE | `https://sub.domain.com/webhook/messages-delete` | | SEND\_MESSAGE | `https://sub.domain.com/webhook/send-message` | | CONTACTS\_SET | `https://sub.domain.com/webhook/contacts-set` | | CONTACTS\_UPSERT | `https://sub.domain.com/webhook/contacts-upsert` | | CONTACTS\_UPDATE | `https://sub.domain.com/webhook/contacts-update` | | PRESENCE\_UPDATE | `https://sub.domain.com/webhook/presence-update` | | CHATS\_SET | `https://sub.domain.com/webhook/chats-set` | | CHATS\_UPDATE | `https://sub.domain.com/webhook/chats-update` | | CHATS\_UPSERT | `https://sub.domain.com/webhook/chats-upsert` | | CHATS\_DELETE | `https://sub.domain.com/webhook/chats-delete` | | GROUPS\_UPSERT | `https://sub.domain.com/webhook/groups-upsert` | | GROUPS\_UPDATE | `https://sub.domain.com/webhook/groups-update` | | GROUP\_PARTICIPANTS\_UPDATE | `https://sub.domain.com/webhook/group-participants-update` | | NEW\_TOKEN | `https://sub.domain.com/webhook/new-jwt` | ## Localizando Webhook Se necessário, há uma opção para localizar qualquer webhook ativo na instância específica. | Método | Endpoint | | ------ | ----------------------------------- | | GET | \[baseUrl]/webhook/find/\[instance] | ### Dados retornados da solicitação: Chamando o endpoint retornará todas as informações sobre o webhook que está sendo usado pela instância. ```json Resultado theme={null} { "enabled": true, "url": "[url]", "webhookByEvents": false, "events": [ [eventos] ] } ``` # Evolution API Source: https://docs.evolutionfoundation.com.br/evolution-api/index API REST completa para WhatsApp com suporte multi-provedor A **Evolution API** é a API REST principal do ecossistema Evolution para integração com WhatsApp. Construída com Node.js e TypeScript, oferece uma solução completa e robusta para comunicação via WhatsApp, suportando tanto a conexão via Baileys (WhatsApp Web) quanto a API oficial do WhatsApp Business (Meta Cloud API). ## Principais recursos * **Multi-provedor** — Suporte a Baileys (WhatsApp Web), Meta Business API e Evolution Provider * **API RESTful** — Endpoints REST completos para gerenciamento de instâncias, mensagens, grupos e contatos * **Multi-tenant** — Isolamento completo por instância com autenticação independente * **Integrações nativas** — Typebot, Chatwoot, OpenAI, Dify, N8N, Flowise e EvoAI * **Sistema de eventos** — WebSocket, RabbitMQ, Amazon SQS, Kafka, NATS e Pusher * **Armazenamento de mídia** — Suporte a Amazon S3 e MinIO para arquivos de mídia * **Multi-banco** — Compatível com PostgreSQL e MySQL via Prisma ORM * **Cache Redis** — Cache distribuído para alta performance * **QR Code** — Geração de QR Code para pareamento de dispositivos * **Docker** — Configuração Docker pronta para produção ## Stack tecnológica | Tecnologia | Uso | | --------------------------------------------------------------- | --------------------------------- | | Node.js 20+ | Runtime principal | | TypeScript 5+ | Linguagem principal | | Express.js | Framework HTTP | | Prisma ORM | Acesso a dados (PostgreSQL/MySQL) | | Redis | Cache e filas | | Baileys | Cliente WhatsApp Web | | Meta Cloud API | WhatsApp Business API oficial | | Socket.io | Eventos em tempo real | | Docker | Containerização | ## Tipos de conexão A Evolution API suporta dois tipos de conexão com o WhatsApp: * **WhatsApp API - Baileys**: API gratuita baseada no WhatsApp Web, ideal para automações e chatbots * **WhatsApp Cloud API**: API oficial da Meta para empresas, com suporte a mensagens em escala e templates ## Seções Guia rápido de instalação e configuração Deploy com Docker e Docker Swarm Instalação local com Node Version Manager Proxy reverso com certificado SSL Referência completa de variáveis de configuração Configuração de webhooks e eventos Chatbots, eventos e canais Documentação técnica completa dos endpoints Como manter sua instância atualizada # Docker Source: https://docs.evolutionfoundation.com.br/evolution-api/install/docker **Pré-requisitos:** Antes de prosseguir com a instalação da Evolution API v2 utilizando Docker, certifique-se de que você já tenha configurado os serviços necessários, como PostgreSQL e Redis. Siga os links abaixo para mais detalhes: * [Configuração do Banco de Dados](/evolution-api/requirements/database) * [Configuração do Redis](/evolution-api/requirements/redis) Estas instruções de instalação assumem que você já instalou o Docker em sua máquina. Você pode encontrar informações sobre como instalar o Docker na Documentação Oficial do Docker. A Evolution API v2 está pronta para o Docker e pode ser facilmente implantada com Docker no modo standalone ou swarm. O repositório oficial do Evolution API contém todos os arquivos de composição necessários para instalar e executar a API. ## Docker Compose Implantar a Evolution API v2 usando o Docker Compose simplifica a configuração e o gerenciamento de seus contêineres Docker. Ele permite que você defina seu ambiente Docker em um arquivo `docker-compose.yaml` e, em seguida, use um único comando para iniciar tudo. ### Arquivo Docker Compose O exemplo a seguir ilustra como configurar o Docker Compose para ambientes standalone, ou seja, um único servidor em execução. Para a sincronização de dois servidores em paralelo ou maior escalabilidade, utilize o Docker Swarm, recomendado para usuários mais avançados. #### Configuração Standalone **Atenção:** Os comandos aqui descritos como `docker compose`, podem não funcionar em versões mais antigas do Docker. Caso você esteja usando uma versão mais antiga, substitua por `docker-compose`. O Docker standalone é adequado quando a Evolution API será executada em apenas uma máquina, sem a necessidade de escalabilidade imediata. Esta é a forma mais conveniente para a maioria dos usuários. Para começar, crie um arquivo `docker-compose.yml` com o seguinte conteúdo: ```yaml theme={null} version: '3.9' services: evolution-api: container_name: evolution_api image: evoapicloud/evolution-api:v2.1.1 restart: always ports: - "8080:8080" env_file: - .env volumes: - evolution_instances:/evolution/instances volumes: evolution_instances: ``` Em seguida, crie um arquivo `.env` no mesmo diretório com o seguinte conteúdo mínimo: ```bash theme={null} AUTHENTICATION_API_KEY=mude-me ``` Para mais configurações, você pode pegar o arquivo de exemplo no repositório oficial. Confira também o guia de variáveis de ambiente [aqui](/evolution-api/configuration/env). ### Inicializando a API Navegue até o diretório que contém o arquivo `docker-compose.yml` e execute o seguinte comando para iniciar os serviços definidos no arquivo: ```bash theme={null} docker compose up -d ``` Esse comando baixará as imagens Docker necessárias, criará os serviços, redes e volumes definidos, e iniciará o serviço da Evolution API. ### Verificando os Logs Após executar o comando `docker compose up`, você pode verificar os logs para confirmar se os serviços estão em execução corretamente: ```bash theme={null} docker logs evolution_api ``` ### Parando o Serviço Para parar o serviço, utilize o comando: ```bash theme={null} docker compose down ``` ### Acessando a API Abra seu navegador e acesse [http://localhost:8080](http://localhost:8080) para verificar se a Evolution API está operacional. ## Docker Swarm Para configurar e gerenciar um cluster Docker Swarm para a Evolution API v2, siga as instruções abaixo. O Docker Swarm é ideal para ambientes que exigem escalabilidade e alta disponibilidade. ### Instalação do Docker Swarm #### Configurando o Servidor Manager Se estiver utilizando um servidor da Hetzner, execute: ```bash theme={null} sudo apt-get update && apt-get install -y apparmor-utils ``` **Etapa 1: Configuração do Hostname** 1. Mude o hostname da máquina para identificá-la no cluster: ```bash theme={null} hostnamectl set-hostname manager1 ``` 2. Edite o arquivo `/etc/hosts` para adicionar o novo nome: ```bash theme={null} nano /etc/hosts ``` Adicione a linha: ```bash theme={null} 127.0.0.1 manager1 ``` 3. Reinicie o sistema para aplicar as alterações: ```bash theme={null} reboot ``` 4. Verifique o hostname: ```bash theme={null} hostnamectl ``` **Etapa 2: Instalação do Docker** Instale o Docker executando: ```bash theme={null} curl -fsSL https://get.docker.com | bash ``` **Etapa 3: Iniciando o Swarm** Inicie o Docker Swarm: ```bash theme={null} docker swarm init --advertise-addr IP_SERVER ``` **Etapa 4: Configuração da Rede do Docker Swarm** Crie a rede overlay para o Docker Swarm: ```bash theme={null} docker network create --driver=overlay network_public ``` Anote o comando gerado para registrar os Workers: ```bash theme={null} docker swarm join --token HASH IP_SERVER:2377 ``` #### Configurando o Servidor Worker Se estiver utilizando um servidor da Hetzner, execute: ```bash theme={null} sudo apt-get update && apt-get install -y apparmor-utils ``` **Etapa 1: Configuração do Hostname** 1. Mude o hostname da máquina para identificá-la no cluster: ```bash theme={null} hostnamectl set-hostname worker1 ``` 2. Edite o arquivo `/etc/hosts` para adicionar o novo nome: ```bash theme={null} nano /etc/hosts ``` Adicione a linha: ```bash theme={null} 127.0.0.1 worker1 ``` 3. Reinicie o sistema para aplicar as alterações: ```bash theme={null} reboot ``` **Etapa 2: Instalação do Docker** Instale o Docker executando: ```bash theme={null} curl -fsSL https://get.docker.com | bash ``` **Etapa 3: Adicionar o Worker ao Cluster** Execute o comando obtido anteriormente para adicionar o Worker ao cluster: ```bash theme={null} docker swarm join --token HASH IP_SERVER:2377 ``` ### Pré-requisitos para a Evolution API via Swarm #### Instalação do Traefik Para instalar o Traefik no Docker Swarm, siga as instruções abaixo: 1. No servidor manager, crie um arquivo `traefik.yaml`: ```bash theme={null} nano traefik.yaml ``` 2. Adicione o seguinte conteúdo ao arquivo: ```yaml theme={null} version: "3.7" services: traefik: image: traefik:2.11.2 command: - "--api.dashboard=true" - "--providers.docker.swarmMode=true" - "--providers.docker.endpoint=unix:///var/run/docker.sock" - "--providers.docker.exposedbydefault=false" - "--providers.docker.network=network_public" - "--entrypoints.web.address=:80" - "--entrypoints.web.http.redirections.entryPoint.to=websecure" - "--entrypoints.web.http.redirections.entryPoint.scheme=https" - "--entrypoints.web.http.redirections.entrypoint.permanent=true" - "--entrypoints.websecure.address=:443" - "--certificatesresolvers.letsencryptresolver.acme.httpchallenge=true" - "--certificatesresolvers.letsencryptresolver.acme.httpchallenge.entrypoint=web" - "--certificatesresolvers.letsencryptresolver.acme.email=seu@email.com" - "--certificatesresolvers.letsencryptresolver.acme.storage=/etc/traefik/letsencrypt/acme.json" - "--log.level=DEBUG" - "--log.format=common" - "--log.filePath=/var/log/traefik/traefik.log" - "--accesslog=true" - "--accesslog.filepath=/var/log/traefik/access-log" deploy: placement: constraints: - node.role == manager restart_policy: condition: on-failure delay: 5s labels: - "traefik.enable=true" - "traefik.http.middlewares.redirect-https.redirectscheme.scheme=https" - "traefik.http.middlewares.redirect-https.redirectscheme.permanent=true" - "traefik.http.routers.http-catchall.rule=hostregexp(`{host:.+}`)" - "traefik.http.routers.http-catchall.entrypoints=web" - "traefik.http.routers.http-catchall.middlewares=redirect-https@docker" - "traefik.http.routers.http-catchall.priority=1" volumes: - "/var/run/docker.sock:/var/run/docker.sock:ro" - "vol_certificates:/etc/traefik/letsencrypt" ports: - target: 80 published: 80 mode: host - target: 443 published: 443 mode: host networks: - network_public volumes: vol_certificates: external: true name: volume_swarm_certificates networks: network_public: external: true name: network_public ``` 3. Execute o comando abaixo para fazer o deploy da stack Traefik: ```bash theme={null} docker stack deploy --prune --resolve-image always -c traefik.yaml traefik ``` ### Deploy da Evolution API v2 Finalmente, para implantar a Evolution API v2 no Docker Swarm, use o arquivo de configuração disponível aqui com o seguinte conteúdo: ```yaml theme={null} version: "3.7" services: evolution_v2: image: evoapicloud/evolution-api:v2.1.1 volumes: - evolution_instances:/evolution/instances networks: - network_public environment: - SERVER_URL=https://evo2.site.com - DEL_INSTANCE=false - DATABASE_ENABLED=true - DATABASE_PROVIDER=postgresql - DATABASE_CONNECTION_URI=postgresql://postgres:SENHA@postgres:5432/evolution - DATABASE_SAVE_DATA_INSTANCE=true - DATABASE_SAVE_DATA_NEW_MESSAGE=true - DATABASE_SAVE_MESSAGE_UPDATE=true - DATABASE_SAVE_DATA_CONTACTS=true - DATABASE_SAVE_DATA_CHATS=true - DATABASE_SAVE_DATA_LABELS=true - DATABASE_SAVE_DATA_HISTORIC=true - DATABASE_CONNECTION_CLIENT_NAME=evolution_v2 - RABBITMQ_ENABLED=false - RABBITMQ_URI=amqp://admin:admin@rabbitmq:5672/default - CACHE_REDIS_ENABLED=true - CACHE_REDIS_URI=redis://evo_redis:6379/1 - CACHE_REDIS_PREFIX_KEY=evolution_v2 - CACHE_REDIS_SAVE_INSTANCES=false - CACHE_LOCAL_ENABLED=false - S3_ENABLED=true - S3_ACCESS_KEY= - S3_SECRET_KEY= - S3_BUCKET=evolution - S3_PORT=443 - S3_ENDPOINT=files.site.com - S3_USE_SSL=true - AUTHENTICATION_API_KEY=429683C4C977415CAAFCCE10F7D57E11 deploy: mode: replicated replicas: 1 placement: constraints: - node.hostname == evolution-manager labels: - traefik.enable=true - traefik.http.routers.evolution_v2.rule=Host(`evo2.site.com`) - traefik.http.routers.evolution_v2.entrypoints=websecure - traefik.http.routers.evolution_v2.tls.certresolver=letsencryptresolver - traefik.http.routers.evolution_v2.service=evolution_v2 - traefik.http.services.evolution_v2.loadbalancer.server.port=8080 - traefik.http.services.evolution_v2.loadbalancer.passHostHeader=true volumes: evolution_instances: external: true name: evolution_v2_data networks: network_public: external: true name: network_public ``` Após configurar e salvar o arquivo, faça o deploy da stack com o comando: ```bash theme={null} docker stack deploy --prune --resolve-image always -c evolution_api_v2.yaml evolution_v2 ``` ### Acessando a API Abra seu navegador e acesse [https://evo2.site.com](https://evo2.site.com) para verificar se a Evolution API está operacional. # Easypanel Source: https://docs.evolutionfoundation.com.br/evolution-api/install/easypanel Instale a Evolution API no Easypanel usando o template oficial 1-clique ou configurando os serviços manualmente. **Pré-requisitos antes de começar:** * VPS com Linux (Ubuntu ou Debian recomendado) e acesso root * Easypanel instalado no servidor ([documentação oficial](https://easypanel.io/docs)) * Domínio com **registro A apontando para o IP do servidor** — configure o DNS **antes** de iniciar o deploy. O Let's Encrypt falha se o domínio não estiver propagado no momento da emissão do certificado. O Easypanel é um painel de controle baseado em Docker Swarm com Traefik e SSL automático via Let's Encrypt. A Evolution API possui um **template oficial** no Easypanel que provisiona automaticamente todos os serviços necessários. ## O que será provisionado Independente do método escolhido, a instalação cria três serviços dentro do seu projeto: | Serviço | Função | Porta interna | | -------------------- | ------------------- | ------------- | | `evolution-api` | Aplicação principal | 8080 | | `evolution-postgres` | Banco de dados | 5432 | | `evolution-redis` | Cache e sessões | 6379 | *** ## Método A — Template 1-clique O método mais rápido. O Easypanel provisiona os três serviços automaticamente a partir do template oficial. **1. Crie um projeto no Easypanel** No painel, clique em **"+ Projeto"**, escolha um nome (ex: `evolution`) e confirme. **2. Adicione o template** Dentro do projeto, clique em **"+ Serviço"** → **"Templates"**. Busque por `Evolution API` e selecione o template oficial. **3. Configure e crie** Revise o nome dos serviços e clique em **"Create"**. O Easypanel irá provisionar os três serviços (api, postgres e redis) automaticamente. **4. Configure o domínio** Acesse o serviço `evolution-api` → aba **"Domains"**. Adicione seu domínio e marque-o como **primário** (ícone de estrela). O certificado SSL será emitido automaticamente. Certifique-se de que o registro A do domínio já está apontando para o IP do servidor antes de salvar. Sem isso, a emissão do SSL via Let's Encrypt falhará. **5. Acesse o Evolution Manager** Após o SSL ser emitido, acesse `https://seu-dominio/manager` e autentique-se com a API Key definida nas variáveis de ambiente do serviço. *** ## Método B — Instalação manual Recomendado quando você precisa de controle total sobre a configuração, usar um banco de dados ou Redis já existente, ou customizar os serviços antes do primeiro deploy. **1. Crie um projeto** No painel, clique em **"+ Projeto"** e escolha um nome (ex: `evolution`). Anote o nome exato — ele será usado nas strings de conexão. **2. Crie o serviço de banco de dados** Dentro do projeto: **"+ Serviço"** → **"Postgres"**. Anote a senha gerada — você vai precisar dela nas variáveis de ambiente. **3. Crie o serviço Redis** **"+ Serviço"** → **"Redis"**. Anote também a senha gerada. **4. Crie o serviço da aplicação** **"+ Serviço"** → **"App"** → selecione **"Docker Image"** como source. Use a imagem: ``` evoapicloud/evolution-api:v2.3.7 ``` **5. Configure o domínio com a porta correta** Na aba **"Domains"** do serviço `evolution-api`, adicione seu domínio e defina a porta como **`8080`**. Informar a porta `8080` no mapeamento do domínio é obrigatório. Sem ela, o Traefik não consegue rotear as requisições para o serviço e ele ficará inacessível. **6. Configure as variáveis de ambiente** Na aba **"Environment"**, preencha as variáveis conforme a seção abaixo. **7. Configure o volume persistente** Na aba **"Storage"**, crie um volume apontando para `/evolution/instances`. **Não pule esta etapa.** Sem o volume persistente, todas as sessões WhatsApp conectadas serão perdidas a cada restart ou redeploy do serviço. **8. Faça o deploy** Clique em **"Deploy"**. Após a inicialização, configure o domínio (como no Método A, passo 4) e acesse `https://seu-dominio/manager`. *** ## Variáveis de ambiente Preencha as variáveis na aba **"Environment"** do serviço `evolution-api`. O exemplo abaixo considera que o projeto foi criado com o nome `evolution`. Se você usou outro nome, ajuste o hostname nas variáveis de banco de dados e Redis — o padrão é sempre `NOME_DO_PROJETO_NOME_DO_SERVICO`. ```dotenv theme={null} # === SERVIDOR === SERVER_URL=https://$(PRIMARY_DOMAIN) # === INSTÂNCIAS === DEL_INSTANCE=false DEL_TEMP_INSTANCES=false # === PROVIDER === PROVIDER_ENABLED=false PROVIDER_HOST=127.0.0.1 PROVIDER_PORT=5656 PROVIDER_PREFIX=evolution_v2 # === BANCO DE DADOS === DATABASE_ENABLED=true DATABASE_PROVIDER=postgresql DATABASE_CONNECTION_URI=postgres://postgres:SENHA_POSTGRES@NOME_DO_PROJETO_evolution-postgres:5432/evolution DATABASE_CONNECTION_CLIENT_NAME=evolution_v2 # === CACHE REDIS === CACHE_REDIS_ENABLED=true CACHE_REDIS_URI=redis://default:SENHA_REDIS@NOME_DO_PROJETO_evolution-redis:6379 CACHE_REDIS_PREFIX_KEY=evolution_v2 CACHE_REDIS_SAVE_INSTANCES=false CACHE_LOCAL_ENABLED=false # === S3 (opcional) === S3_ENABLED=false S3_ACCESS_KEY= S3_SECRET_KEY= # === RABBITMQ (opcional) === RABBITMQ_ENABLED=false RABBITMQ_URI=amqp://admin:admin@rabbitmq:5672/default # === AUTENTICAÇÃO === AUTHENTICATION_API_KEY=CHAVE_256_BITS_AQUI # === LOG === LOG_LEVEL=ERROR,WARN,INFO ``` **Rede interna do Easypanel:** serviços do mesmo projeto se comunicam usando o padrão `NOME_DO_PROJETO_NOME_DO_SERVICO`. Por exemplo, se o projeto se chama `evolution`, o host do Postgres será `evolution_evolution-postgres`. Esse é o erro mais comum em tutoriais antigos — não use `localhost` nem o IP do servidor. A variável `$(PRIMARY_DOMAIN)` é preenchida automaticamente pelo Easypanel com o domínio marcado como primário no serviço. Não é necessário substituí-la manualmente. *** ## Primeiro acesso ao Evolution Manager O Evolution Manager está embutido na aplicação a partir da v2. Após o deploy: 1. Acesse `https://seu-dominio/manager` 2. Autentique-se com o valor definido em `AUTHENTICATION_API_KEY` 3. Clique em **"New Instance"** para criar sua primeira instância WhatsApp 4. Escaneie o QR Code com o WhatsApp do celular para conectar *** ## Pontos críticos | # | Ponto | Impacto se ignorado | | - | ------------------------------------------------------ | ------------------------------------------------------- | | 1 | Volume persistente em `/evolution/instances` | Perda de todas as sessões WhatsApp a cada restart | | 2 | DNS configurado antes do deploy | Falha na emissão do certificado SSL | | 3 | Porta `8080` no mapeamento de domínio | Serviço inacessível via domínio | | 4 | Padrão de rede interna `PROJETO_servico` | Falha na conexão com Postgres e Redis | | 5 | `AUTHENTICATION_API_KEY` com 256 bits de entropia | Qualquer pessoa pode controlar as instâncias conectadas | | 6 | Imagem `evoapicloud/evolution-api` (não `atendai/...`) | Deploy com versão desatualizada (v1.x) | # Nginx e SSL Source: https://docs.evolutionfoundation.com.br/evolution-api/install/nginx ## Configuração do Nginx Para expor a Evolution API na web de forma segura, você pode configurar o Nginx como um proxy reverso. ### Instalação do Nginx Instale, inicie e habilite o Nginx: ```bash theme={null} apt-get install -y nginx systemctl start nginx systemctl enable nginx systemctl status nginx ``` Se a informação "Ativo: ativo (em execução)" aparecer, o Nginx está funcionando corretamente. ### Configuração do Nginx Remova a configuração padrão do Nginx: ```bash theme={null} rm /etc/nginx/sites-enabled/default ``` Crie um novo arquivo de configuração: ```bash theme={null} nano /etc/nginx/conf.d/default.conf ``` Adicione a seguinte configuração: ```nginx theme={null} server { listen 80; listen [::]:80; server_name _; location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_cache_bypass $http_upgrade; } location ~* \.(jpg|jpeg|gif|png|webp|svg|woff|woff2|ttf|css|js|ico|xml)$ { expires 360d; } location ~ /\.ht { deny all; } } ``` Recarregue o Nginx para aplicar as alterações: ```bash theme={null} systemctl reload nginx ``` Se necessário, faça o usuário `nginx` ser o proprietário do diretório da web: ```bash theme={null} chown www-data:www-data /usr/share/nginx/html -R ``` Para configurar um Virtual Host, crie um arquivo de configuração: ```bash theme={null} nano /etc/nginx/sites-available/api ``` Adicione a seguinte configuração: ```nginx theme={null} server { server_name substitua-isso-pelo-seu-domínio-legal.com; location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_cache_bypass $http_upgrade; } } ``` Crie um link simbólico para habilitar a configuração: ```bash theme={null} ln -s /etc/nginx/sites-available/api /etc/nginx/sites-enabled nginx -t ``` Recarregue o Nginx: ```bash theme={null} systemctl reload nginx ``` ## Instalar o Certbot para o Certificado SSL Para proteger sua Evolution API com SSL, instale o Certbot: ```bash theme={null} snap install --classic certbot ``` ### Configurar SSL com Certbot Para configurar o SSL, use o comando: ```bash theme={null} certbot --nginx -d substitua-isso-pelo-seu-domínio-legal.com ``` Se o processo for bem-sucedido, você verá a mensagem "Congratulations! You have successfully enabled HTTPS". # NVM Source: https://docs.evolutionfoundation.com.br/evolution-api/install/nvm ## Pré-requisitos Antes de iniciar a instalação da Evolution API v2, certifique-se de que você já configurou os serviços necessários, como PostgreSQL e Redis. Siga os links abaixo para mais detalhes: * [Configuração do Banco de Dados](/evolution-api/requirements/database) * [Configuração do Redis](/evolution-api/requirements/redis) ## Instalação do NVM A Evolution API pode ser facilmente instalada usando o Node Version Manager (NVM). Siga estas etapas para configurar seu ambiente e iniciar a Evolution API em seu servidor. ### Instalar NVM Primeiro, baixe e instale o Node.js com os seguintes comandos: ```bash theme={null} curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash ``` Agora, carregue o ambiente e instale o Node.js: ```bash theme={null} # Carregar o NVM no ambiente atual source ~/.bashrc # Instalar e usar a versão necessária do Node.js nvm install v20.10.0 && nvm use v20.10.0 ``` Confirme que o NVM foi instalado com sucesso: ```bash theme={null} command -v nvm ``` Se você ainda não configurou, também pode configurar o fuso horário do seu servidor com o comando: ```bash theme={null} dpkg-reconfigure tzdata ``` ## Clonando o Repositório e Instalando Dependências Clone o repositório oficial da Evolution API v2 a partir da branch correta: ```bash theme={null} git clone -b v2.0.0 https://github.com/evolution-foundation/evolution-api.git ``` Acesse o diretório do projeto e instale as dependências: ```bash theme={null} cd evolution-api npm install ``` ## Configuração de Variáveis de Ambiente Agora vamos configurar as variáveis de ambiente. Primeiro, copie o arquivo `.env.example` para `.env`: ```bash theme={null} cp ./.env.example ./.env ``` Edite o arquivo `.env` com suas configurações específicas: ```bash theme={null} nano ./.env ``` Substitua os valores padrão pelas suas configurações, como strings de conexão de banco de dados, chaves de API, portas do servidor, etc. Acesse a [seção de variáveis de ambiente](/evolution-api/configuration/env) para instruções detalhadas sobre como configurar seu arquivo `.env`. ## Geração e Deploy do Banco de Dados Após configurar o ambiente, você precisará realizar a geração dos arquivos do cliente Prisma e o deploy das migrations no banco de dados. Utilize os comandos abaixo, dependendo do banco de dados que você está utilizando (PostgreSQL ou MySQL): 1. Gerar os arquivos do cliente Prisma: ```bash theme={null} npm run db:generate ``` 2. Realizar o deploy das migrations: ```bash theme={null} npm run db:deploy ``` ## Inicializando a Evolution API Após a configuração, você pode iniciar a Evolution API com o seguinte comando: ```bash theme={null} npm run build npm run start:prod ``` ## Instalação e Configuração do PM2 Use o PM2 para gerenciar o processo da API: ```bash theme={null} npm install pm2 -g pm2 start 'npm run start:prod' --name ApiEvolution pm2 startup pm2 save --force ``` Se o seu servidor tiver mais memória, considere configurar o PM2 para utilizar mais recursos: ```bash theme={null} pm2 start 'npm run start:prod' --name ApiEvolution -- start --node-args="--max-old-space-size=4096" --max-memory-restart 4G ``` Isso é recomendado para servidores com pelo menos 4GB de RAM disponíveis exclusivamente para a Evolution API. Para verificar se a API está em execução, acesse [http://localhost:8080](http://localhost:8080). Você deve ver a seguinte resposta: ```json theme={null} { "status": 200, "message": "Welcome to the Evolution API, it is working!", "version": "2.0.10", "clientName": "evolution01", "manager": "https://evo2.site.com/manager", "documentation": "https://docs.evolutionfoundation.com.br" } ``` Facilite sua vida com a extensão JSON Formatter no Google Chrome ou Microsoft Edge. # SetupOrion Source: https://docs.evolutionfoundation.com.br/evolution-api/install/setup-orion Instalação automatizada da Evolution API com SetupOrion O SetupOrion é um instalador automatizado que configura toda a infraestrutura necessária para rodar a Evolution API em uma VPS limpa, incluindo Docker, Traefik, Portainer e Docker Swarm. ## Pré-requisitos * VPS com **Debian 11** ou **Ubuntu 20.04** (sistema limpo) * Registro DNS (tipo A) apontando para o IP da VPS * Acesso root ao servidor *** ## Passo 1: Executar o SetupOrion Em uma VPS vazia, execute o comando abaixo e aguarde enquanto o SetupOrion instala todas as dependências necessárias. Ao finalizar, você será direcionado ao menu de ferramentas. ```bash theme={null} bash <(curl -sSL setup.oriondesign.art.br) ``` ## Passo 2: Instalar Traefik e Portainer No menu de ferramentas, selecione a **Opção 1** para instalar: * Docker * Docker Swarm (inicialização e criação de redes) * Traefik (proxy reverso com SSL automático) * Portainer (gerenciamento visual de containers) Responda as perguntas que aparecem na tela para que o Setup possa realizar as instalações corretamente. ## Passo 3: Instalar a Evolution API Retorne ao menu de ferramentas e selecione a **Opção 3 (Evolution)**: 1. Escolha a versão: **Evolution API** 2. Informe o domínio configurado no DNS para a aplicação ## Passo 4: Verificar a instalação Após a instalação ser finalizada, você verá uma tela informando: * **Dados de acesso** da aplicação * **Links** para a documentação Anote as credenciais exibidas no terminal. Elas serão necessárias para acessar a Evolution API. # Instalação da Evolution API Source: https://docs.evolutionfoundation.com.br/evolution-api/installation Escolha o método de instalação ideal para seu cenário Este guia irá ajudá-lo a instalar e configurar a **Evolution API**, nossa API REST principal para integração com WhatsApp. ## Pré-requisitos Antes de iniciar, configure os serviços de infraestrutura necessários: PostgreSQL ou MySQL com Prisma ORM Cache distribuído para alta performance *** ## Métodos de instalação Escolha o método mais adequado para o seu cenário: **Recomendado** para produção. Inclui Docker Compose standalone e Docker Swarm com Traefik para alta disponibilidade. Instalação local com Node Version Manager. Ideal para desenvolvimento ou quando você precisa de controle total sobre o ambiente. Configuração de proxy reverso com Nginx e certificado SSL via Let's Encrypt. Instalador automatizado com Traefik, Portainer e Docker Swarm. Ideal para VPS limpa. Painel de controle baseado em Docker com template 1-clique e SSL automático. Ideal para quem quer simplicidade sem abrir mão do self-hosted. *** ## Verificação rápida Após instalar por qualquer método, verifique se a API está funcionando: ### Teste de saúde ```bash theme={null} curl http://localhost:8080/ ``` ### Crie sua primeira instância WhatsApp ```bash theme={null} curl -X POST http://localhost:8080/instance/create \ -H "Content-Type: application/json" \ -H "apikey: sua-chave-segura-aqui" \ -d '{ "instanceName": "minha-instancia", "integration": "WHATSAPP-BAILEYS", "qrcode": true }' ``` ### Obtenha o QR Code para conectar ```bash theme={null} curl http://localhost:8080/instance/connect/minha-instancia \ -H "apikey: sua-chave-segura-aqui" ``` Escaneie o QR Code com o WhatsApp do seu celular para conectar a instância. ### Verifique o status da conexão ```bash theme={null} curl http://localhost:8080/instance/connectionState/minha-instancia \ -H "apikey: sua-chave-segura-aqui" ``` *** ## Próximos passos Referência completa de todas as variáveis de configuração Configure webhooks para receber eventos em tempo real Conecte com Chatwoot, Typebot, OpenAI, Dify e mais Mantenha sua instância sempre atualizada # Chatwoot Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/chatwoot A Evolution API permite uma integração direta com o **Chatwoot**, uma plataforma de suporte ao cliente que centraliza comunicações de múltiplos canais. Esta documentação detalha como configurar essa integração tanto durante a criação de uma nova instância quanto em uma instância já existente. ## Configuração da Integração com Chatwoot ### 1. Configuração na Criação da Instância Você pode configurar o Chatwoot diretamente ao criar uma nova instância na Evolution API. Use o seguinte corpo de requisição para o endpoint `/instance/create`: #### Endpoint ```http theme={null} POST {{baseUrl}}/instance/create ``` #### Corpo da Requisição ```json theme={null} { "instanceName": "NOME DA INSTANCIA", "number": "NUMERO DO WHATSAPP PARA GERAR O PAIRING CODE", "qrcode": true, "integration": "WHATSAPP-BAILEYS", "chatwootAccountId": "1", "chatwootToken": "TOKEN", "chatwootUrl": "https://chatwoot.com", "chatwootSignMsg": true, "chatwootReopenConversation": true, "chatwootConversationPending": false, "chatwootImportContacts": true, "chatwootNameInbox": "evolution", "chatwootMergeBrazilContacts": true, "chatwootImportMessages": true, "chatwootDaysLimitImportMessages": 3, "chatwootOrganization": "Evolution Bot", "chatwootLogo": "https://evolution-api.com/files/evolution-api-favicon.png" } ``` ### 2. Configuração para Instâncias Existentes Se você já tem uma instância criada e deseja configurar ou alterar a integração com o Chatwoot, utilize o endpoint `/chatwoot/set/{{instance}}` com o seguinte formato de requisição: #### Endpoint ```http theme={null} POST {{baseUrl}}/chatwoot/set/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de como deve ser o corpo da requisição para configurar a integração: ```json theme={null} { "enabled": true, "accountId": "1", "token": "TOKEN", "url": "https://chatwoot.com", "signMsg": true, "reopenConversation": true, "conversationPending": false, "nameInbox": "evolution", "mergeBrazilContacts": true, "importContacts": true, "importMessages": true, "daysLimitImportMessages": 2, "signDelimiter": "\n", "autoCreate": true, "organization": "BOT", "logo": "link_da_sua_logo" } ``` ### Explicação dos Parâmetros * **`enabled`**: Ativa (`true`) ou desativa (`false`) a integração do Chatwoot para a instância. * **`accountId`**: ID da conta do Chatwoot associada à integração. * **`token`**: Token de autenticação do usuário administrador da conta no Chatwoot. * **`url`**: URL base do Chatwoot. Importante: Não incluir a `/` no final da URL. * **`signMsg`**: Quando ativado (`true`), adiciona a assinatura com o nome do atendente nas mensagens enviadas. * **`reopenConversation`**: Define se a integração deve sempre reabrir a mesma conversa (`true`) ou criar uma nova. * **`conversationPending`**: Inicia as conversas como pendentes (`true`), aguardando ação de um atendente. * **`nameInbox`**: Nome customizado da inbox no Chatwoot. Se não fornecido, a instância usará o nome da instância. * **`mergeBrazilContacts`**: Faz merge de contatos brasileiros que possuem o dígito `9` adicional em seus números (`true`). * **`importContacts`**: Importa os contatos da agenda do WhatsApp para o Chatwoot (`true`). * **`importMessages`**: Importa as mensagens do WhatsApp para o Chatwoot (`true`). * **`daysLimitImportMessages`**: Define o número limite de dias para importação de mensagens antigas do WhatsApp. * **`signDelimiter`**: Delimitador usado para separar a assinatura do corpo da mensagem. * **`autoCreate`**: Se ativado (`true`), cria automaticamente a configuração da inbox no Chatwoot. * **`organization`**: Nome do contato do bot de comandos, usado para personalizar a interação. * **`logo`**: URL da imagem a ser usada como foto de perfil do contato do bot de comandos. ## Passos para Configurar a Integração 1. **Obtenha as Credenciais e URLs**: * Acesse o painel do Chatwoot e obtenha o `accountId` e o `token` do usuário administrador. * Verifique a URL base do seu Chatwoot e configure sem a `/` final. 2. **Crie ou Configure a Instância**: * Use o endpoint `/instance/create` para configurar o Chatwoot durante a criação da instância. * Use o endpoint `/chatwoot/set/{{instance}}` para configurar o Chatwoot em uma instância já existente. 3. **Verifique a Configuração**: * Acesse o Chatwoot para garantir que a inbox foi criada e que as configurações estão corretas. * Teste o envio e recebimento de mensagens para confirmar a integração. ## Considerações Finais A integração da Evolution API com o Chatwoot permite centralizar e automatizar a comunicação do WhatsApp diretamente na sua plataforma de atendimento ao cliente. Com opções de personalização, importação de contatos e mensagens, e a possibilidade de reabrir conversas existentes, esta integração oferece flexibilidade para atender às necessidades específicas do seu fluxo de trabalho. Para mais detalhes sobre outras integrações e configurações, consulte a [seção de variáveis de ambiente](/evolution-api/configuration/env). # WhatsApp Cloud API Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/cloudapi A Evolution API v2 permite integrar sua aplicação com a Cloud API oficial do WhatsApp para gerenciar mensagens, contatos, e outras funcionalidades diretamente através da API. A seguir, são detalhados os pré-requisitos e o processo de integração. ## Pré-requisitos Antes de iniciar a integração com a Cloud API do WhatsApp, você deve garantir que os seguintes passos foram concluídos: ### 1. Criação da Business Manager (BM) e Aprovação Para utilizar a Cloud API oficial do WhatsApp, você precisa de uma **Business Manager** (BM) aprovada. Este processo envolve: * Criar uma conta no Facebook Business Manager. * Seguir os passos para verificação da sua empresa. * Aguardar a aprovação da sua conta. ### 2. Criação do App no Facebook Developers Após a aprovação da sua BM, você precisa criar um aplicativo na plataforma Facebook Developers: * Acesse a sua conta do Facebook Developers e clique em **Meus Apps**. * Clique em **Criar App** e siga as instruções para configurar um novo aplicativo. * Certifique-se de adicionar a API do WhatsApp ao seu aplicativo. ### 3. Configuração do Número no Aplicativo Após criar o aplicativo, você precisa configurar o número do WhatsApp: * No painel do seu aplicativo no Facebook Developers, vá para a seção **WhatsApp**. * Adicione e verifique o número de telefone que deseja usar com a Cloud API. * Anote o **Number ID** fornecido. ### 4. Criar um Token Permanente Para evitar que o token de acesso expire, crie um **token permanente** para o usuário admin da sua BM: * Vá para a seção **Tokens de Acesso** no Facebook Developers. * Gere um token com as permissões necessárias para a API do WhatsApp. * Certifique-se de que este token é permanente, para não precisar ser renovado periodicamente. ## Configuração na Evolution API v2 Agora que você completou os pré-requisitos, siga os passos abaixo para configurar a integração com a Evolution API v2. ### 1. Criação da Instância Para criar uma instância que utiliza a Cloud API do WhatsApp, você precisará acessar a rota `/instance/create` da Evolution API v2 com o seguinte corpo de requisição: ```json theme={null} { "instanceName": "NOME DA INSTANCIA", "token": "TOKEN PERMANENTE DO USUARIO ADMIN DA BM", "number": "NUMBER ID DO WHATSAPP", "businessId": "BUSINESS ID DA CONTA DO WHATSAPP", "qrcode": false, "integration": "WHATSAPP-BUSINESS" } ``` ### Parâmetros do Corpo da Requisição: * **`instanceName`**: Nome da instância que você está criando. * **`token`**: Token permanente gerado para o usuário admin da sua BM. * **`number`**: Number ID do WhatsApp que você configurou no aplicativo do Facebook Developers. * **`businessId`**: ID da conta de negócios associada ao WhatsApp. * **`qrcode`**: Defina como `false` pois a integração é baseada em token, e não em QR Code. * **`integration`**: Use `"WHATSAPP-BUSINESS"` para especificar que esta integração é com a API oficial do WhatsApp Business. ### Exemplo de Requisição: ```bash theme={null} curl -X POST http://API_URL/instance/create \ -H "Content-Type: application/json" \ -d '{ "instanceName": "MinhaInstancia", "token": "EAAGm0PX4ZCpsBA...", "number": "1234567890", "businessId": "9876543210", "qrcode": false, "integration": "WHATSAPP-BUSINESS" }' ``` ### 2. Configuração do Webhook Depois de criar a instância, é necessário configurar o webhook no aplicativo da Meta para receber eventos e mensagens do WhatsApp. #### URL do Webhook No painel do seu aplicativo no Facebook Developers, configure o webhook com a seguinte URL: ```plaintext theme={null} API_URL/webhook/meta ``` #### Token do Webhook O token para validar o webhook deve ser configurado na variável `WA_BUSINESS_TOKEN_WEBHOOK` no seu arquivo `.env`: ```plaintext theme={null} WA_BUSINESS_TOKEN_WEBHOOK=seu_token_webhook ``` Este token será usado pela Meta para validar as requisições enviadas para o seu webhook. ### Conclusão Com a instância criada e o webhook configurado, a sua Evolution API v2 está pronta para operar com a Cloud API oficial do WhatsApp. Todas as mensagens e eventos relacionados ao número configurado serão gerenciados automaticamente pela Evolution API. Esta documentação fornece uma visão clara e detalhada de como integrar a Cloud API do WhatsApp com a Evolution API v2, desde a preparação necessária até a configuração final. Se você seguir todas as etapas, estará preparado para utilizar as funcionalidades do WhatsApp em sua aplicação através da Evolution API v2. # Dify Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/dify A Evolution API permite a criação e gerenciamento de bots utilizando a tecnologia Dify, proporcionando automação e interatividade avançada através de diferentes tipos de bots, como chatBots, textGenerators, agents, e workflows. A seguir, você encontrará as instruções detalhadas sobre como configurar bots, gerenciar sessões e definir configurações padrão. ## 1. Criação de Bots no Dify Você pode configurar diversos bots no Dify utilizando triggers para iniciar as interações. A configuração do bot pode ser feita através do endpoint `/dify/create/{{instance}}`. ### Endpoint para Criação de Bots #### Endpoint ```http theme={null} POST {{baseUrl}}/dify/create/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de corpo JSON para configurar um bot no Dify: ```json theme={null} { "enabled": true, "botType": "chatBot", /* chatBot, textGenerator, agent, workflow */ "apiUrl": "http://dify.site.com/v1", "apiKey": "app-123456", // opções "triggerType": "keyword", /* all ou keyword */ "triggerOperator": "equals", /* contains, equals, startsWith, endsWith, regex, none */ "triggerValue": "teste", "expire": 0, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 0, "ignoreJids": [] } ``` ### Explicação dos Parâmetros * **`enabled`**: Ativa (`true`) ou desativa (`false`) o bot. * **`botType`**: Tipo do bot Dify (`chatBot`, `textGenerator`, `agent`, `workflow`). * **`apiUrl`**: URL da API do Dify (sem a `/` no final). * **`apiKey`**: Chave da API fornecida pelo Dify. * **Opções**: * **`triggerType`**: Tipo de trigger para iniciar o bot (`all` ou `keyword`). * **`triggerOperator`**: Operador utilizado para avaliar o trigger (`contains`, `equals`, `startsWith`, `endsWith`, `regex`, `none`). * **`triggerValue`**: Valor utilizado no trigger (por exemplo, uma palavra-chave ou regex). * **`expire`**: Tempo em minutos após o qual o bot expira, reiniciando se a sessão expirou. * **`keywordFinish`**: Palavra-chave que encerra a sessão do bot. * **`delayMessage`**: Delay (em milissegundos) para simular a digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário (`true` ou `false`). * **`stopBotFromMe`**: Define se o bot deve parar quando o próprio usuário envia uma mensagem (`true` ou `false`). * **`keepOpen`**: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato. * **`debounceTime`**: Tempo (em segundos) para juntar várias mensagens em uma só. * **`ignoreJids`**: Lista de JIDs de contatos que não ativarão o bot. ## 2. Configurações Padrão do Dify Você pode definir configurações padrão que serão aplicadas caso os parâmetros não sejam passados durante a criação do bot. ### Endpoint para Configurações Padrão #### Endpoint ```http theme={null} POST {{baseUrl}}/dify/settings/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de configuração padrão: ```json theme={null} { "expire": 20, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 0, "ignoreJids": [], "difyIdFallback": "clyja4oys0a3uqpy7k3bd7swe" } ``` ### Explicação dos Parâmetros * **`expire`**: Tempo em minutos após o qual o bot expira. * **`keywordFinish`**: Palavra-chave que encerra a sessão do bot. * **`delayMessage`**: Delay para simular a digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário. * **`stopBotFromMe`**: Define se o bot deve parar quando o próprio usuário envia uma mensagem. * **`keepOpen`**: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato. * **`debounceTime`**: Tempo para juntar várias mensagens em uma só. * **`ignoreJids`**: Lista de JIDs de contatos que não ativarão o bot. * **`difyIdFallback`**: ID do bot de fallback que será utilizado caso nenhum trigger seja ativado. ## 3. Gerenciamento de Sessões do Dify Você pode gerenciar as sessões do bot, alterando o status entre aberta, pausada ou fechada para cada contato específico. ### Endpoint para Gerenciamento de Sessões #### Endpoint ```http theme={null} POST {{baseUrl}}/dify/changeStatus/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de como gerenciar o status da sessão: ```json theme={null} { "remoteJid": "5511912345678@s.whatsapp.net", "status": "closed" } ``` ### Explicação dos Parâmetros * **`remoteJid`**: JID (identificador) do contato no WhatsApp. * **`status`**: Status da sessão (`opened`, `paused`, `closed`). ## 4. Variáveis Automáticas e Especiais no Dify Quando uma sessão do Dify é iniciada, algumas variáveis predefinidas são automaticamente enviadas: ```json theme={null} inputs: { remoteJid: "JID do contato", pushName: "Nome do contato", instanceName: "Nome da instância", serverUrl: "URL do servidor da API", apiKey: "Chave de API da Evolution" }; ``` ### Explicação das Variáveis Automáticas * **`remoteJid`**: JID do contato com quem o bot está interagindo. * **`pushName`**: Nome do contato no WhatsApp. * **`instanceName`**: Nome da instância que está executando o bot. * **`serverUrl`**: URL do servidor onde a Evolution API está hospedada. * **`apiKey`**: Chave de API usada para autenticar as requisições. ### Variáveis Especiais para Workflows No caso de bots do tipo **workflow**, a mensagem recebida é enviada na variável `query` dentro dos inputs. Isso permite que o workflow processe a mensagem diretamente com base no conteúdo da variável `query`. ### Exemplo de Variáveis para Workflow ```json theme={null} inputs: { remoteJid: "JID do contato", pushName: "Nome do contato", instanceName: "Nome da instância", serverUrl: "URL do servidor da API", apiKey: "Chave de API da Evolution", query: "Conteúdo da mensagem recebida" } ``` ## Considerações Finais A integração da Evolution API com o Dify oferece uma maneira robusta de automatizar interações no WhatsApp, utilizando diferentes tipos de bots para atender às necessidades específicas do seu negócio. Com a capacidade de configurar triggers, gerenciar sessões e utilizar variáveis automáticas, você pode otimizar o fluxo de trabalho e melhorar a experiência do usuário final. # EvoAI Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/evoai Integração com a plataforma EvoAI para criação e gerenciamento de bots A Evolution API permite a criação e gerenciamento de bots usando a tecnologia EvoAI, fornecendo automação avançada e interatividade através de diferentes tipos de bots. A EvoAI é nossa própria tecnologia desenvolvida pela equipe da Evolution. Você pode saber mais em evo-ai.co. Abaixo, você encontrará instruções detalhadas sobre como configurar bots, gerenciar sessões e definir configurações padrão. ## 1. Criando Bots no EvoAI Você pode configurar vários bots no EvoAI usando gatilhos para iniciar interações. A configuração do bot pode ser feita através do endpoint `/evoai/create/{{instance}}`. ### Endpoint para Criação de Bot #### Endpoint ```http theme={null} POST {{baseUrl}}/evoai/create/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de um corpo JSON para configurar um bot no EvoAI: ```json theme={null} { "enabled": true, "agentUrl": "http://evoai.site.com/v1", "apiKey": "app-123456", // opções "triggerType": "keyword", /* all ou keyword */ "triggerOperator": "equals", /* contains, equals, startsWith, endsWith, regex, none */ "triggerValue": "test", "expire": 0, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 0, "ignoreJids": [] } ``` ### Explicação dos Parâmetros * **`enabled`**: Ativa (`true`) ou desativa (`false`) o bot. * **`agentUrl`**: URL da API EvoAI (sem uma barra `/` no final). * **`apiKey`**: Chave de API fornecida pelo EvoAI. * **Opções**: * **`triggerType`**: Tipo de gatilho para iniciar o bot (`all` ou `keyword`). * **`triggerOperator`**: Operador usado para avaliar o gatilho (`contains`, `equals`, `startsWith`, `endsWith`, `regex`, `none`). * **`triggerValue`**: Valor usado no gatilho (por exemplo, uma palavra-chave ou regex). * **`expire`**: Tempo em minutos após o qual o bot expira, reiniciando se a sessão expirou. * **`keywordFinish`**: Palavra-chave que encerra a sessão do bot. * **`delayMessage`**: Atraso (em milissegundos) para simular digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve ouvir mensagens enviadas pelo usuário (`true` ou `false`). * **`stopBotFromMe`**: Define se o bot deve parar quando o usuário enviar uma mensagem (`true` ou `false`). * **`keepOpen`**: Mantém a sessão aberta, impedindo que o bot reinicie para o mesmo contato. * **`debounceTime`**: Tempo (em segundos) para combinar várias mensagens em uma. * **`ignoreJids`**: Lista de JIDs de contatos que não ativarão o bot. ## 2. Configurações Padrão do EvoAI Você pode definir configurações padrão que serão aplicadas se os parâmetros não forem passados durante a criação do bot. ### Endpoint para Configurações Padrão #### Endpoint ```http theme={null} POST {{baseUrl}}/evoai/settings/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de configurações padrão: ```json theme={null} { "expire": 20, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 0, "ignoreJids": [], "evoaiIdFallback": "clyja4oys0a3uqpy7k3bd7swe" } ``` ### Explicação dos Parâmetros * **`expire`**: Tempo em minutos após o qual o bot expira. * **`keywordFinish`**: Palavra-chave que encerra a sessão do bot. * **`delayMessage`**: Atraso para simular digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve ouvir mensagens enviadas pelo usuário. * **`stopBotFromMe`**: Define se o bot deve parar quando o usuário enviar uma mensagem. * **`keepOpen`**: Mantém a sessão aberta, impedindo que o bot reinicie para o mesmo contato. * **`debounceTime`**: Tempo para combinar várias mensagens em uma. * **`ignoreJids`**: Lista de JIDs de contatos que não ativarão o bot. * **`evoaiIdFallback`**: ID do bot de fallback que será usado se nenhum gatilho for ativado. ## 3. Gerenciando Sessões do EvoAI Você pode gerenciar as sessões do bot alterando o status entre aberto, pausado ou fechado para cada contato específico. ### Endpoint para Gerenciamento de Sessão #### Endpoint ```http theme={null} POST {{baseUrl}}/evoai/changeStatus/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de como gerenciar o status da sessão: ```json theme={null} { "remoteJid": "5511912345678@s.whatsapp.net", "status": "closed" } ``` ### Explicação dos Parâmetros * **`remoteJid`**: JID (identificador) do contato no WhatsApp. * **`status`**: Status da sessão (`opened`, `paused`, `closed`). ## 4. Variáveis Automáticas no EvoAI Quando uma sessão do EvoAI é iniciada, algumas variáveis predefinidas são enviadas automaticamente: ```json theme={null} inputs: { remoteJid: "JID do contato", pushName: "Nome do contato", instanceName: "Nome da instância", serverUrl: "URL do servidor API", apiKey: "Chave da API Evolution" }; ``` ### Explicação das Variáveis Automáticas * **`remoteJid`**: JID do contato com o qual o bot está interagindo. * **`pushName`**: Nome do contato no WhatsApp. * **`instanceName`**: Nome da instância que está executando o bot. * **`serverUrl`**: URL do servidor onde a Evolution API está hospedada. * **`apiKey`**: Chave de API usada para autenticar solicitações. ## Considerações Finais A integração da Evolution API com o EvoAI oferece uma maneira robusta de automatizar interações no WhatsApp. Com a capacidade de configurar gatilhos, gerenciar sessões e usar variáveis automáticas, você pode otimizar o fluxo de trabalho e melhorar a experiência do usuário final. # Evolution Bot Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/evolution-bot O **Evolution Bot** é uma integração de chatbot universal que permite a utilização de qualquer URL de API ou automação para criar interações automatizadas. Ao utilizar o Evolution Bot, sua API deve retornar a resposta na forma de um JSON contendo o campo `message`, que será enviado de volta ao usuário. Este sistema oferece flexibilidade para construir chatbots que se integram perfeitamente com suas APIs personalizadas. ## 1. Criação de Bots no Evolution Bot Você pode configurar bots no Evolution Bot utilizando triggers para iniciar as interações. A configuração do bot pode ser feita através do endpoint `/evolutionBot/create/{{instance}}`. ### Endpoint para Criação de Bots #### Endpoint ```http theme={null} POST {{baseUrl}}/evolutionBot/create/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de corpo JSON para configurar um bot no Evolution Bot: ```json theme={null} { "enabled": true, "apiUrl": "http://api.site.com/v1", "apiKey": "app-123456", // optional // opções "triggerType": "keyword", /* all ou keyword */ "triggerOperator": "equals", /* contains, equals, startsWith, endsWith, regex, none */ "triggerValue": "teste", "expire": 0, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 0, "ignoreJids": [] } ``` ### Explicação dos Parâmetros * **`enabled`**: Ativa (`true`) ou desativa (`false`) o bot. * **`apiUrl`**: URL da API que será chamada pelo bot (sem a `/` no final). * **`apiKey`**: Chave da API fornecida pela sua aplicação (opcional). * **Opções**: * **`triggerType`**: Tipo de trigger para iniciar o bot (`all` ou `keyword`). * **`triggerOperator`**: Operador utilizado para avaliar o trigger (`contains`, `equals`, `startsWith`, `endsWith`, `regex`, `none`). * **`triggerValue`**: Valor utilizado no trigger (por exemplo, uma palavra-chave ou regex). * **`expire`**: Tempo em minutos após o qual o bot expira, reiniciando se a sessão expirou. * **`keywordFinish`**: Palavra-chave que encerra a sessão do bot. * **`delayMessage`**: Delay (em milissegundos) para simular a digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário (`true` ou `false`). * **`stopBotFromMe`**: Define se o bot deve parar quando o próprio usuário envia uma mensagem (`true` ou `false`). * **`keepOpen`**: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato. * **`debounceTime`**: Tempo (em segundos) para juntar várias mensagens em uma só. * **`ignoreJids`**: Lista de JIDs de contatos que não ativarão o bot. ### Exemplo de Retorno da API A resposta da sua API deve estar no formato JSON e conter a mensagem a ser enviada ao usuário no campo `message`: ```json theme={null} { "message": "Sua resposta aqui" } ``` ## 2. Configurações Padrão do Evolution Bot Você pode definir configurações padrão que serão aplicadas caso os parâmetros não sejam passados durante a criação do bot. ### Endpoint para Configurações Padrão #### Endpoint ```http theme={null} POST {{baseUrl}}/evolutionBot/settings/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de configuração padrão: ```json theme={null} { "expire": 20, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 0, "ignoreJids": [], "evolutionBotIdFallback": "clyja4oys0a3uqpy7k3bd7swe" } ``` ### Explicação dos Parâmetros * **`expire`**: Tempo em minutos após o qual o bot expira. * **`keywordFinish`**: Palavra-chave que encerra a sessão do bot. * **`delayMessage`**: Delay para simular a digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário. * **`stopBotFromMe`**: Define se o bot deve parar quando o próprio usuário envia uma mensagem. * **`keepOpen`**: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato. * **`debounceTime`**: Tempo para juntar várias mensagens em uma só. * **`ignoreJids`**: Lista de JIDs de contatos que não ativarão o bot. * **`evolutionBotIdFallback`**: ID do bot de fallback que será utilizado caso nenhum trigger seja ativado. ## 3. Gerenciamento de Sessões do Evolution Bot Você pode gerenciar as sessões do bot, alterando o status entre aberta, pausada ou fechada para cada contato específico. ### Endpoint para Gerenciamento de Sessões #### Endpoint ```http theme={null} POST {{baseUrl}}/evolutionBot/changeStatus/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de como gerenciar o status da sessão: ```json theme={null} { "remoteJid": "5511912345678@s.whatsapp.net", "status": "closed" } ``` ### Explicação dos Parâmetros * **`remoteJid`**: JID (identificador) do contato no WhatsApp. * **`status`**: Status da sessão (`opened`, `paused`, `closed`). ## 4. Variáveis Automáticas e Especiais no Evolution Bot Quando uma sessão do Evolution Bot é iniciada, algumas variáveis predefinidas são automaticamente enviadas: ```json theme={null} inputs: { remoteJid: "JID do contato", pushName: "Nome do contato", instanceName: "Nome da instância", serverUrl: "URL do servidor da API", apiKey: "Chave de API da Evolution" }; ``` ### Explicação das Variáveis Automáticas * **`remoteJid`**: JID do contato com quem o bot está interagindo. * **`pushName`**: Nome do contato no WhatsApp. * **`instanceName`**: Nome da instância que está executando o bot. * **`serverUrl`**: URL do servidor onde a Evolution API está hospedada. * **`apiKey`**: Chave de API usada para autenticar as requisições. ### Considerações Finais O Evolution Bot oferece uma plataforma flexível para integração de chatbots com suas APIs personalizadas, permitindo automação avançada e interações personalizadas no WhatsApp. Com o suporte para triggers, gerenciamento de sessões e configuração de variáveis automáticas, você pode construir uma experiência de chatbot robusta e eficaz para seus usuários. # Canal Evolution Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/evolution-channel O **Evolution Channel** é um canal universal de integração que permite a entrada de mensagens através de webhooks, proporcionando flexibilidade para conectar diversos sistemas e aplicativos com a Evolution API. Este canal facilita a automação e o gerenciamento de mensagens, suportando diversas integrações e fluxos de trabalho. *** ## 1. Configuração da Instância Evolution Para configurar uma instância no Evolution Channel, você precisará acessar a rota `/instance/create` da Evolution API com o seguinte corpo de requisição: ### Criação da Instância **Endpoint** ```http theme={null} POST {{baseUrl}}/instance/create ``` **Corpo da Requisição** Aqui está um exemplo de como criar uma instância no Evolution Channel: ```json theme={null} { "instanceName": "NOME DA INSTANCIA", "token": "TOKEN DA INSTANCIA (OPCIONAL)", "number": "NUMBER ID DA INSTANCIA", "qrcode": false, "integration": "EVOLUTION" } ``` ### Parâmetros do Corpo da Requisição * **`instanceName`**: Nome da instância que você está criando. * **`token`**: Token opcional para autenticar a instância. * **`number`**: Number ID da instância que será utilizado para receber e enviar mensagens. * **`qrcode`**: Defina como `false` pois a integração não requer QR Code. * **`integration`**: Use `"EVOLUTION"` para especificar que esta integração é com o canal universal Evolution. **Exemplo de Requisição** ```bash theme={null} curl -X POST http://API_URL/instance/create \ -H "Content-Type: application/json" \ -d '{ "instanceName": "MinhaInstancia", "token": "123456", "number": "9876543210", "qrcode": false, "integration": "EVOLUTION" }' ``` *** ## 2. Entrada de Mensagens no Evolution Channel Após a criação da instância, o Evolution Channel receberá as mensagens enviadas para a instância configurada. Essas mensagens são enviadas para a rota `{baseUrl}/webhook/evolution` como requisições POST. Este é o ponto de entrada para as mensagens que o Evolution Channel irá processar. **URL do Webhook para Entrada de Mensagens** ```http theme={null} POST {{baseUrl}}/webhook/evolution ``` ### Exemplo de Payload de Entrada de Mensagem Aqui está um exemplo do formato de payload enviado para o Evolution Channel quando uma mensagem é recebida: ```json theme={null} { "numberId": "1234567", "key": { "remoteJid": "557499879409", "fromMe": false, "id": "ABC1234" }, "pushName": "Davidson", "message": { "conversation": "Qual o seu nome?" }, "messageType": "conversation" } ``` ### Explicação dos Campos do Payload * **`numberId`**: ID do número cadastrado na criação da instância. * **`key.remoteJid`**: Número ou ID único do contato que enviou a mensagem. * **`key.fromMe`**: Indica se a mensagem foi enviada pelo contato (`false`) ou pelo próprio sistema (`true`). * **`key.id`**: ID único da mensagem. * **`pushName`**: Nome do contato que enviou a mensagem. * **`message.conversation`**: Conteúdo da mensagem recebida. * **`messageType`**: Tipo da mensagem (neste caso, `conversation`). *** ## 3. Feedback e Postbacks O Evolution Channel envia feedback e postbacks através dos canais de eventos configurados, como webhooks, RabbitMQ, ou SQS. Isso permite que você receba notificações em tempo real sobre o status das mensagens e interações, mantendo seu sistema atualizado. **Exemplos de Canais de Eventos** * **Webhook**: Notificações são enviadas para um endpoint HTTP especificado. * **RabbitMQ**: Mensagens são enviadas para uma fila RabbitMQ configurada. * **SQS**: Mensagens são enviadas para uma fila SQS da AWS. **Configuração de Canais de Eventos** Para configurar os canais de eventos, defina os parâmetros necessários no seu arquivo de configuração ou diretamente na instância, conforme as especificações da Evolution API. *** ## Conclusão Com a instância criada e a configuração do webhook de entrada de mensagens, a sua Evolution API está pronta para operar com o Evolution Channel. Todas as mensagens recebidas e os eventos associados serão gerenciados de forma centralizada, permitindo uma integração fluida e eficiente com seus sistemas de mensagens e automação. Esta documentação fornece uma visão clara e detalhada de como integrar o Evolution Channel com a Evolution API, desde a criação da instância até a configuração dos webhooks e canais de eventos. Seguindo estas etapas, você estará preparado para utilizar o canal universal Evolution em sua aplicação. # Flowise Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/flowise A Evolution API permite a criação e gerenciamento de bots utilizando a tecnologia Flowise, proporcionando automação e interatividade avançada através de diferentes tipos de interações. A seguir, você encontrará as instruções detalhadas sobre como configurar bots, gerenciar sessões e definir configurações padrão. ## 1. Criação de Bots no Flowise Você pode configurar diversos bots no Flowise utilizando triggers para iniciar as interações. A configuração do bot pode ser feita através do endpoint `/flowise/create/{{instance}}`. ### Endpoint para Criação de Bots #### Endpoint ```http theme={null} POST {{baseUrl}}/flowise/create/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de corpo JSON para configurar um bot no Flowise: ```json theme={null} { "enabled": true, "apiUrl": "http://flowise.site.com/v1", "apiKey": "app-123456", // optional // opções "triggerType": "keyword", /* all ou keyword */ "triggerOperator": "equals", /* contains, equals, startsWith, endsWith, regex, none */ "triggerValue": "teste", "expire": 0, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 0, "ignoreJids": [] } ``` ### Explicação dos Parâmetros * **`enabled`**: Ativa (`true`) ou desativa (`false`) o bot. * **`apiUrl`**: URL da API do Flowise (sem a `/` no final). * **`apiKey`**: Chave da API fornecida pelo Flowise (opcional). * **Opções**: * **`triggerType`**: Tipo de trigger para iniciar o bot (`all` ou `keyword`). * **`triggerOperator`**: Operador utilizado para avaliar o trigger (`contains`, `equals`, `startsWith`, `endsWith`, `regex`, `none`). * **`triggerValue`**: Valor utilizado no trigger (por exemplo, uma palavra-chave ou regex). * **`expire`**: Tempo em minutos após o qual o bot expira, reiniciando se a sessão expirou. * **`keywordFinish`**: Palavra-chave que encerra a sessão do bot. * **`delayMessage`**: Delay (em milissegundos) para simular a digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário (`true` ou `false`). * **`stopBotFromMe`**: Define se o bot deve parar quando o próprio usuário envia uma mensagem (`true` ou `false`). * **`keepOpen`**: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato. * **`debounceTime`**: Tempo (em segundos) para juntar várias mensagens em uma só. * **`ignoreJids`**: Lista de JIDs de contatos que não ativarão o bot. ## 2. Configurações Padrão do Flowise Você pode definir configurações padrão que serão aplicadas caso os parâmetros não sejam passados durante a criação do bot. ### Endpoint para Configurações Padrão #### Endpoint ```http theme={null} POST {{baseUrl}}/flowise/settings/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de configuração padrão: ```json theme={null} { "expire": 20, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 0, "ignoreJids": [], "flowiseIdFallback": "clyja4oys0a3uqpy7k3bd7swe" } ``` ### Explicação dos Parâmetros * **`expire`**: Tempo em minutos após o qual o bot expira. * **`keywordFinish`**: Palavra-chave que encerra a sessão do bot. * **`delayMessage`**: Delay para simular a digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário. * **`stopBotFromMe`**: Define se o bot deve parar quando o próprio usuário envia uma mensagem. * **`keepOpen`**: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato. * **`debounceTime`**: Tempo para juntar várias mensagens em uma só. * **`ignoreJids`**: Lista de JIDs de contatos que não ativarão o bot. * **`flowiseIdFallback`**: ID do bot de fallback que será utilizado caso nenhum trigger seja ativado. ## 3. Gerenciamento de Sessões do Flowise Você pode gerenciar as sessões do bot, alterando o status entre aberta, pausada ou fechada para cada contato específico. ### Endpoint para Gerenciamento de Sessões #### Endpoint ```http theme={null} POST {{baseUrl}}/flowise/changeStatus/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de como gerenciar o status da sessão: ```json theme={null} { "remoteJid": "5511912345678@s.whatsapp.net", "status": "closed" } ``` ### Explicação dos Parâmetros * **`remoteJid`**: JID (identificador) do contato no WhatsApp. * **`status`**: Status da sessão (`opened`, `paused`, `closed`). ## 4. Variáveis Automáticas e Especiais no Flowise Quando uma sessão do Flowise é iniciada, algumas variáveis predefinidas são automaticamente enviadas: ```json theme={null} inputs: { remoteJid: "JID do contato", pushName: "Nome do contato", instanceName: "Nome da instância", serverUrl: "URL do servidor da API", apiKey: "Chave de API da Evolution" }; ``` ### Explicação das Variáveis Automáticas * **`remoteJid`**: JID do contato com quem o bot está interagindo. * **`pushName`**: Nome do contato no WhatsApp. * **`instanceName`**: Nome da instância que está executando o bot. * **`serverUrl`**: URL do servidor onde a Evolution API está hospedada. * **`apiKey`**: Chave de API usada para autenticar as requisições. ### Variáveis Especiais para Workflows No caso de bots do tipo **workflow**, a mensagem recebida é enviada na variável `query` dentro dos inputs. Isso permite que o workflow processe a mensagem diretamente com base no conteúdo da variável `query`. ### Exemplo de Variáveis para Workflow ```json theme={null} inputs: { remoteJid: "JID do contato", pushName: "Nome do contato", instanceName: "Nome da instância", serverUrl: "URL do servidor da API", apiKey: "Chave de API da Evolution", query: "Conteúdo da mensagem recebida" } ``` ## Considerações Finais A integração da Evolution API com o Flowise oferece uma maneira robusta de automatizar interações no WhatsApp, utilizando diferentes tipos de bots para atender às necessidades específicas do seu negócio. Com a capacidade de configurar triggers, gerenciar sessões e utilizar variáveis automáticas, você pode otimizar o fluxo de trabalho e melhorar a experiência do usuário final. # Community Node N8N Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/n8n-community-node Como instalar o node comunitário do Evolution API no N8N Integre a **Evolution API** diretamente nos seus fluxos do N8N utilizando o node comunitário oficial. ## Pré-requisitos * Instância do **N8N** em funcionamento * **Evolution API** instalada e acessível *** ## Instalação No N8N, navegue até **Settings > Community Nodes** (`/settings/community-nodes`) Clique em **Install** No campo de instalação, digite: ``` n8n-nodes-evolution-api ``` Aceite o termo de uso e clique em **Install** ## Usando o node Após o processo de instalação, o node estará disponível nos seus fluxos. Para localizá-lo, pesquise por **"Evolution API"** na barra de busca de nodes do N8N. # OpenAI Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/openai A Evolution API permite a criação e gerenciamento de bots utilizando a tecnologia OpenAI, permitindo interações automatizadas e personalizadas através de assistentes virtuais ou modelos de chat completions. A seguir, você encontrará instruções detalhadas sobre como configurar credenciais, criar bots, gerenciar sessões e definir configurações padrão, incluindo o uso de reconhecimento de fala (speech-to-text). ## 1. Criação de Credenciais do OpenAI Antes de criar bots, é necessário configurar as credenciais da API do OpenAI. Isso é feito utilizando o endpoint `/openai/creds/{{instance}}`. ### Endpoint para Criação de Credenciais #### Endpoint ```http theme={null} POST {{baseUrl}}/openai/creds/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de como cadastrar uma nova credencial do OpenAI: ```json theme={null} { "name": "apikey", "apiKey": "sk-proj-..." } ``` ### Explicação dos Parâmetros * **`name`**: Nome identificador da credencial. * **`apiKey`**: Chave da API fornecida pelo OpenAI. ## 2. Criação de Bots com OpenAI Após configurar as credenciais, você pode criar vários bots que utilizam o sistema de triggers para iniciar as interações. Isso pode ser feito através do endpoint `/openai/create/{{instance}}`. ### Endpoint para Criação de Bots #### Endpoint ```http theme={null} POST {{baseUrl}}/openai/create/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de como criar um bot utilizando OpenAI: ```json theme={null} { "enabled": true, "openaiCredsId": "clyrx36wj0001119ucjjzxik1", "botType": "assistant", // para assistentes "assistantId": "asst_LRNyh6qC4qq8NTyPjHbcJjSp", "functionUrl": "https://n8n.site.com", // para chat completion "model": "gpt-4", "systemMessages": [ "You are a helpful assistant." ], "assistantMessages": [ "\n\nHello there, how may I assist you today?" ], "userMessages": [ "Hello!" ], "maxTokens": 300, // opções "triggerType": "keyword", "triggerOperator": "equals", "triggerValue": "teste", "expire": 20, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 10, "ignoreJids": [] } ``` ### Explicação dos Parâmetros * **`enabled`**: Ativa (`true`) ou desativa (`false`) o bot. * **`openaiCredsId`**: ID da credencial cadastrada anteriormente. * **`botType`**: Tipo do bot (`assistant` ou `chatCompletion`). * **Para Assistentes (`assistant`)**: * **`assistantId`**: ID do assistente OpenAI. * **`functionUrl`**: URL que será chamada caso o assistente necessite realizar uma ação. * **Para Chat Completion (`chatCompletion`)**: * **`model`**: Modelo do OpenAI a ser utilizado (ex.: `gpt-4`). * **`systemMessages`**: Mensagens que configuram o comportamento do bot. * **`assistantMessages`**: Mensagens iniciais do bot. * **`userMessages`**: Mensagens de exemplo do usuário. * **`maxTokens`**: Número máximo de tokens utilizados na resposta. * **Opções**: * **`triggerType`**: Tipo de trigger para iniciar o bot (`all` ou `keyword`). * **`triggerOperator`**: Operador utilizado para avaliar o trigger (`contains`, `equals`, `startsWith`, `endsWith`, `regex`, `none`). * **`triggerValue`**: Valor utilizado no trigger (por exemplo, uma palavra-chave ou regex). * **`expire`**: Tempo em minutos após o qual o bot expira, reiniciando se a sessão expirou. * **`keywordFinish`**: Palavra-chave que encerra a sessão do bot. * **`delayMessage`**: Delay (em milissegundos) para simular a digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário (`true` ou `false`). * **`stopBotFromMe`**: Define se o bot deve parar quando o próprio usuário envia uma mensagem (`true` ou `false`). * **`keepOpen`**: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato. * **`debounceTime`**: Tempo (em segundos) para juntar várias mensagens em uma só. * **`ignoreJids`**: Lista de JIDs de contatos que não ativarão o bot. ## 3. Gerenciamento de Sessões do OpenAI Você pode gerenciar as sessões do bot, alterando o status entre aberta, pausada ou fechada para cada contato específico. ### Endpoint para Gerenciamento de Sessões #### Endpoint ```http theme={null} POST {{baseUrl}}/openai/changeStatus/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de como gerenciar o status da sessão: ```json theme={null} { "remoteJid": "5511912345678@s.whatsapp.net", "status": "closed" } ``` ### Explicação dos Parâmetros * **`remoteJid`**: JID (identificador) do contato no WhatsApp. * **`status`**: Status da sessão (`opened`, `paused`, `closed`). ## 4. Configurações Padrão do OpenAI Você pode definir configurações padrão que serão aplicadas caso os parâmetros não sejam passados durante a criação do bot. Inclui também a opção de usar reconhecimento de fala (speech-to-text). ### Endpoint para Configurações Padrão #### Endpoint ```http theme={null} POST {{baseUrl}}/openai/settings/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de configuração padrão: ```json theme={null} { "openaiCredsId": "clyja4oys0a3uqpy7k3bd7swe", "expire": 20, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 0, "ignoreJids": [], "openaiIdFallback": "clyja4oys0a3uqpy7k3bd7swe", "speechToText": true } ``` ### Explicação dos Parâmetros * **`openaiCredsId`**: ID da credencial do OpenAI a ser usada como padrão. * **`expire`**: Tempo em minutos após o qual o bot expira. * **`keywordFinish`**: Palavra-chave que encerra a sessão do bot. * **`delayMessage`**: Delay para simular a digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário. * **`stopBotFromMe`**: Define se o bot deve parar quando o próprio usuário envia uma mensagem. * **`keepOpen`**: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato. * **`debounceTime`**: Tempo para juntar várias mensagens em uma só. * **`ignoreJids`**: Lista de JIDs de contatos que não ativarão o bot. * **`openaiIdFallback`**: ID do bot de fallback que será utilizado caso nenhum trigger seja ativado. * **`speechToText`**: Define se a funcionalidade de reconhecimento de fala (speech-to-text) deve ser ativada usando a credencial definida por padrão. ### Webhook com `speechToText` Quando o parâmetro `speechToText` está ativado, a Evolution API converte automaticamente os áudios recebidos em texto utilizando a credencial do OpenAI. A transcrição do áudio é então incluída no webhook enviado pela API. #### Exemplo de Webhook com `speechToText` ```json theme={null} { "event": "message", "data": { "message": { "id": "message-id", "from": "sender-number", "to": "receiver-number", "content": "Text message", "speech ToText": "This is the transcribed text from the audio." } } } ``` ## Considerações Finais A integração da Evolution API com o OpenAI oferece uma maneira poderosa de automatizar interações no WhatsApp, utilizando a inteligência artificial para fornecer respostas dinâmicas e personalizadas. Com as configurações corretas, você pode criar assistentes virtuais altamente eficientes, gerenciar sessões e definir configurações padrão, incluindo o uso de reconhecimento de fala para converter áudios em texto automaticamente. # RabbitMQ Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/rabbitmq A Evolution API permite a integração com o **RabbitMQ** para gerenciar eventos e filas de mensagens, facilitando a comunicação e processamento de tarefas de forma eficiente e escalável. A seguir, você encontrará informações sobre como configurar o RabbitMQ tanto em modo global quanto em instâncias individuais. ## Configuração Global do RabbitMQ Com a nova configuração global, é possível centralizar o processamento de eventos em filas unificadas, em vez de configurar filas separadas para cada instância. Isso simplifica a gestão de eventos, pois todos os eventos do sistema passam por filas específicas de acordo com o tipo de evento. ### Configuração de Variáveis de Ambiente Aqui estão as variáveis de ambiente necessárias para habilitar e configurar o RabbitMQ em modo global: ```plaintext theme={null} RABBITMQ_ENABLED=true RABBITMQ_URI=amqp://admin:admin@localhost:5672/default RABBITMQ_EXCHANGE_NAME=evolution_exchange RABBITMQ_GLOBAL_ENABLED=true ``` ### Eventos Configuráveis Com o modo global habilitado (`RABBITMQ_GLOBAL_ENABLED=true`), todos os eventos são enfileirados em filas específicas por tipo de evento, em vez de por instância. Aqui está a lista de eventos que você pode ativar globalmente: ```plaintext theme={null} RABBITMQ_EVENTS_APPLICATION_STARTUP=true RABBITMQ_EVENTS_INSTANCE_CREATE=true RABBITMQ_EVENTS_INSTANCE_DELETE=true RABBITMQ_EVENTS_QRCODE_UPDATED=true RABBITMQ_EVENTS_MESSAGES_SET=true RABBITMQ_EVENTS_MESSAGES_UPSERT=true RABBITMQ_EVENTS_MESSAGES_EDITED=true RABBITMQ_EVENTS_MESSAGES_UPDATE=true RABBITMQ_EVENTS_MESSAGES_DELETE=true RABBITMQ_EVENTS_SEND_MESSAGE=true RABBITMQ_EVENTS_CONTACTS_SET=true RABBITMQ_EVENTS_CONTACTS_UPSERT=true RABBITMQ_EVENTS_CONTACTS_UPDATE=true RABBITMQ_EVENTS_PRESENCE_UPDATE=true RABBITMQ_EVENTS_CHATS_SET=true RABBITMQ_EVENTS_CHATS_UPSERT=true RABBITMQ_EVENTS_CHATS_UPDATE=true RABBITMQ_EVENTS_CHATS_DELETE=true RABBITMQ_EVENTS_GROUPS_UPSERT=true RABBITMQ_EVENTS_GROUP_UPDATE=true RABBITMQ_EVENTS_GROUP_PARTICIPANTS_UPDATE=true RABBITMQ_EVENTS_CONNECTION_UPDATE=true RABBITMQ_EVENTS_CALL=true RABBITMQ_EVENTS_TYPEBOT_START=true RABBITMQ_EVENTS_TYPEBOT_CHANGE_STATUS=true ``` ### Funcionamento * **Fila por Evento**: No modo global, os eventos são enfileirados em filas específicas para cada tipo de evento. Por exemplo, todos os eventos de atualização de mensagens (`MESSAGES_UPDATE`) serão enfileirados na mesma fila, independentemente da instância de origem. * **Facilidade de Gerenciamento**: Essa abordagem facilita o gerenciamento e monitoramento dos eventos, permitindo uma centralização das operações e simplificando a lógica de consumo de mensagens no seu sistema. ## Configuração do RabbitMQ para Instâncias Individuais Embora a configuração global seja recomendada para centralizar o processamento de eventos, ainda é possível configurar o RabbitMQ para instâncias individuais, caso haja necessidade de segmentação por instância. ### Endpoint para Configuração Individual Para configurar o RabbitMQ para uma instância específica do WhatsApp na Evolution API, utilize o seguinte endpoint: ```http theme={null} POST [baseUrl]/rabbitmq/set/[instance_name] ``` ### Corpo da Requisição Aqui está um exemplo do corpo JSON para configurar eventos em uma instância específica: ```json theme={null} { "enabled": true, "events": [ "APPLICATION_STARTUP", "QRCODE_UPDATED", "MESSAGES_SET", "MESSAGES_UPSERT", "MESSAGES_UPDATE", "MESSAGES_DELETE", "SEND_MESSAGE", "CONTACTS_SET", "CONTACTS_UPSERT", "CONTACTS_UPDATE", "PRESENCE_UPDATE", "CHATS_SET", "CHATS_UPSERT", "CHATS_UPDATE", "CHATS_DELETE", "GROUPS_UPSERT", "GROUP_UPDATE", "GROUP_PARTICIPANTS_UPDATE", "CONNECTION_UPDATE", "CALL", "NEW_JWT_TOKEN" ] } ``` Remova eventos não utilizados para otimizar o uso de recursos do RabbitMQ. Ao configurar a integração com o RabbitMQ para instâncias individuais, ajuste o array de eventos no corpo JSON para incluir apenas os eventos relevantes para aquela instância. ## Considerações Finais A configuração do RabbitMQ na Evolution API oferece flexibilidade para gerenciar eventos de forma centralizada com a configuração global, ou de forma segmentada por instância, dependendo das necessidades do seu sistema. Utilize a configuração global para simplificar a gestão de eventos em ambientes complexos, ou configure individualmente para controle mais granular. Para mais detalhes sobre as variáveis de ambiente do RabbitMQ e outras configurações avançadas, consulte a [seção de variáveis de ambiente](/evolution-api/configuration/env#rabbitmq). # S3/Minio Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/s3minio A Evolution API suporta a integração com Amazon S3 ou Minio para armazenar arquivos de mídia do WhatsApp, como imagens, áudios e documentos. Essa integração permite que os arquivos sejam armazenados de forma segura e acessível, com links gerados automaticamente e incluídos nos webhooks enviados pela API. ## Configuração de Variáveis de Ambiente Para habilitar o armazenamento S3 ou Minio, você deve definir as variáveis de ambiente adequadas no arquivo `.env` da Evolution API. Abaixo estão as variáveis necessárias e suas funções: ### Variáveis de Configuração para S3 ```plaintext theme={null} S3_ENABLED=true S3_ACCESS_KEY=lJiKQSKlco6UfSUJSnZt S3_SECRET_KEY=gZXkzkXQwhME8XEmZVNF0ImSWxIpbXeJ5UoPy4s1 S3_BUCKET=evolution S3_PORT=443 S3_ENDPOINT=s3.eu-west-3.amazonaws.com S3_USE_SSL=true S3_REGION=eu-west-3 ``` ### Explicação das Variáveis * **`S3_ENABLED`**: Ativa (`true`) ou desativa (`false`) o uso do S3 ou Minio para armazenamento de arquivos. * **`S3_ACCESS_KEY`**: Chave de acesso fornecida pelo provedor do serviço (AWS ou Minio). * **`S3_SECRET_KEY`**: Chave secreta correspondente à chave de acesso, usada para autenticação. * **`S3_BUCKET`**: Nome do bucket onde os arquivos serão armazenados. * **`S3_PORT`**: Porta utilizada para a conexão. Normalmente `443` para conexões SSL. * **`S3_ENDPOINT`**: Endpoint do serviço S3 ou Minio. Para Amazon S3, é necessário incluir a região no formato `region: s3.[region].amazonaws.com`, por exemplo, `s3.eu-west-3.amazonaws.com`. * **`S3_USE_SSL`**: Define se a conexão deve usar SSL (`true` ou `false`). * **`S3_REGION`**: A região do bucket S3 (padrão é `us-east-1`). ### Exemplos de Configuração #### Amazon S3 Ao utilizar o Amazon S3, é essencial especificar o endpoint corretamente, incluindo a região. Aqui está um exemplo: ```plaintext theme={null} S3_ENABLED=true S3_ACCESS_KEY=your-aws-access-key S3_SECRET_KEY=your-aws-secret-key S3_BUCKET=my-s3-bucket S3_PORT=443 S3_ENDPOINT=s3.eu-west-3.amazonaws.com S3_USE_SSL=true S3_REGION=eu-west-3 ``` #### Minio Para Minio, o endpoint pode ser o domínio personalizado do serviço: ```plaintext theme={null} S3_ENABLED=true S3_ACCESS_KEY=your-minio-access-key S3_SECRET_KEY=your-minio-secret-key S3_BUCKET=my-minio-bucket S3_PORT=443 S3_ENDPOINT=minio.mycompany.com S3_USE_SSL=true ``` ## Como Funciona o Armazenamento de Mídia Quando o armazenamento S3 ou Minio é configurado corretamente, todos os arquivos de mídia recebidos do WhatsApp (como imagens, vídeos, áudios, etc.) são automaticamente enviados para o bucket configurado. A URL pública do arquivo armazenado é então gerada e incluída no webhook da Evolution API. ### Webhook com `mediaUrl` Quando um arquivo de mídia é recebido e armazenado, o webhook enviado pela Evolution API incluirá o `mediaUrl` no corpo da mensagem. Isso permite que sua aplicação acesse diretamente o arquivo armazenado no S3 ou Minio. ### Exemplo de Webhook Aqui está um exemplo de como o webhook com `mediaUrl` pode aparecer: ```json theme={null} { "event": "messages.upsert", "data": { "message": { ... "mediaUrl": "https://files.evolution-api-pro.com/bucket/path/to/media/file.jpg", ... } } } ``` ## Considerações Finais Integrar a Evolution API com Amazon S3 ou Minio para o armazenamento de arquivos de mídia oferece uma solução escalável e segura para gerenciar conteúdos de mídia do WhatsApp. Ao configurar as variáveis de ambiente corretamente, você garante que todos os arquivos de mídia sejam armazenados e acessíveis conforme necessário, proporcionando maior controle sobre os dados e a capacidade de integrá-los facilmente em suas aplicações. Para mais detalhes sobre as variáveis de ambiente e outras configurações avançadas, consulte a [seção de variáveis de ambiente](/evolution-api/configuration/env#s3). # Amazon SQS Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/sqs A Evolution API permite a integração com o **Amazon SQS (Simple Queue Service)** para gerenciar eventos e filas de mensagens de forma escalável e confiável. Assim como no RabbitMQ, o SQS na Evolution API pode ser configurado tanto de maneira global quanto para instâncias individuais. ## Configuração Global do SQS Para habilitar o SQS e configurar o processamento de eventos de forma centralizada, utilize as seguintes variáveis de ambiente: ### Configuração de Variáveis de Ambiente ```plaintext theme={null} SQS_ENABLED=true SQS_ACCESS_KEY_ID=your-access-key-id SQS_SECRET_ACCESS_KEY=your-secret-access-key SQS_ACCOUNT_ID=your-account-id SQS_REGION=your-region ``` ### Explicação das Variáveis * **`SQS_ENABLED`**: Ativa (`true`) ou desativa (`false`) a integração com o Amazon SQS. * **`SQS_ACCESS_KEY_ID`**: Chave de acesso da AWS para autenticação. * **`SQS_SECRET_ACCESS_KEY`**: Chave secreta correspondente à chave de acesso para autenticação. * **`SQS_ACCOUNT_ID`**: ID da conta AWS onde o SQS está configurado. * **`SQS_REGION`**: Região da AWS onde suas filas SQS estão localizadas (por exemplo, `us-east-1`). ### Funcionamento * **Fila por Evento**: No modo global, todos os eventos são enfileirados em filas específicas para cada tipo de evento. Isso significa que eventos de diferentes instâncias são centralizados em filas unificadas por evento, simplificando o processamento e o monitoramento. ## Configuração do SQS para Instâncias Individuais Embora a configuração global seja recomendada para centralizar o processamento de eventos, você pode configurar o SQS para instâncias individuais caso precise segmentar as filas por instância. ### Endpoint para Configuração Individual Para configurar o SQS para uma instância específica do WhatsApp na Evolution API, utilize o seguinte endpoint: ```http theme={null} POST [baseUrl]/sqs/set/[instance_name] ``` ### Corpo da Requisição Aqui está um exemplo do corpo JSON para configurar eventos em uma instância específica: ```json theme={null} { "enabled": true, "events": [ "APPLICATION_STARTUP", "QRCODE_UPDATED", "MESSAGES_SET", "MESSAGES_UPSERT", "MESSAGES_UPDATE", "MESSAGES_DELETE", "SEND_MESSAGE", "CONTACTS_SET", "CONTACTS_UPSERT", "CONTACTS_UPDATE", "PRESENCE_UPDATE", "CHATS_SET", "CHATS_UPSERT", "CHATS_UPDATE", "CHATS_DELETE", "GROUPS_UPSERT", "GROUP_UPDATE", "GROUP_PARTICIPANTS_UPDATE", "CONNECTION_UPDATE", "CALL", "NEW_JWT_TOKEN" ] } ``` Remova eventos não utilizados para otimizar o uso de recursos do SQS. ### Funcionamento * **Segmentação por Instância**: Ao configurar o SQS para instâncias individuais, cada instância pode ter suas próprias filas específicas para os eventos configurados. Isso permite maior controle e segmentação dos eventos, caso você precise separar o processamento por instância. ## Considerações Finais A integração com o Amazon SQS na Evolution API oferece uma solução poderosa para gerenciar eventos de forma escalável e confiável, tanto de maneira centralizada quanto segmentada por instância. Utilize a configuração global para simplificar o processamento em ambientes complexos, ou configure individualmente para um controle mais granular. Para mais detalhes sobre as variáveis de ambiente e outras configurações avançadas, consulte a [seção de variáveis de ambiente](/evolution-api/configuration/env#sqs). # Typebot Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/typebot A Evolution API permite integrar bots do **Typebot** para automatizar interações e responder a mensagens do WhatsApp com base em triggers configurados. A seguir, você encontrará as instruções detalhadas sobre como configurar, gerenciar sessões, inicializar bots manualmente e utilizar variáveis predefinidas. ## 1. Configuração de Bots no Typebot Você pode configurar diversos bots no Typebot utilizando triggers para iniciar as interações. A configuração do bot pode ser feita através do endpoint `/typebot/create/{{instance}}`. ### Endpoint para Configuração de Bots #### Endpoint ```http theme={null} POST {{baseUrl}}/typebot/create/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de corpo JSON para configurar um bot: ```json theme={null} { "enabled": true, "url": "https://bot.dgcode.com.br", "typebot": "my-typebot-uoz1rg9", "triggerType": "keyword", "triggerOperator": "regex", "triggerValue": "^atend.*", "expire": 20, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 10 } ``` ### Explicação dos Parâmetros * **`enabled`**: Ativa (`true`) ou desativa (`false`) o bot. * **`url`**: URL da API do Typebot (sem a `/` no final). * **`typebot`**: Nome público do bot no Typebot. * **`triggerType`**: Tipo de trigger para iniciar o bot (`keyword`, `all`, `none`). * **`triggerOperator`**: Operador utilizado para avaliar o trigger (`contains`, `equals`, `startsWith`, `endsWith`, `regex`). * **`triggerValue`**: Valor utilizado no trigger (por exemplo, uma palavra-chave ou regex). * **`expire`**: Tempo em minutos após o qual o bot expira, reiniciando se a sessão expirou. * **`keywordFinish`**: Palavra-chave que, quando recebida, encerra a sessão do bot. * **`delayMessage`**: Delay (em milissegundos) para simular a digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário (`true` ou `false`). * **`stopBotFromMe`**: Define se o bot deve parar quando o próprio usuário envia uma mensagem (`true` ou `false`). * **`keepOpen`**: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato. * **`debounceTime`**: Tempo (em segundos) para juntar várias mensagens em uma só. ## 2. Gerenciamento de Sessões do Typebot Você pode gerenciar as sessões do Typebot para cada contato específico, alterando o status da sessão entre aberta, pausada ou fechada. ### Endpoint para Gerenciamento de Sessões #### Endpoint ```http theme={null} POST {{baseUrl}}/typebot/changeStatus/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de como gerenciar o status da sessão: ```json theme={null} { "remoteJid": "5511912345678@s.whatsapp.net", "status": "closed" } ``` ### Explicação dos Parâmetros * **`remoteJid`**: JID (identificador) do contato no WhatsApp. * **`status`**: Status da sessão (`opened`, `paused`, `closed`). ## 3. Configuração Padrão do Typebot Você pode definir configurações padrão que serão aplicadas caso os parâmetros não sejam passados durante a criação do bot. ### Configuração Padrão Aqui está um exemplo de configuração padrão: ```json theme={null} { "expire": 20, "keywordFinish": "#SAIR", "delayMessage": 1000, "unknownMessage": "Mensagem não reconhecida", "listeningFromMe": false, "stopBotFromMe": false, "keepOpen": false, "debounceTime": 10, "ignoreJids": [], "typebotIdFallback": "clyja4oys0a3uqpy7k3bd7swe" } ``` ### Explicação dos Parâmetros * **`expire`**: Tempo em minutos após o qual o bot expira. * **`keywordFinish`**: Palavra-chave que encerra a sessão do bot. * **`delayMessage`**: Delay para simular a digitação antes de enviar uma mensagem. * **`unknownMessage`**: Mensagem enviada quando a entrada do usuário não é reconhecida. * **`listeningFromMe`**: Define se o bot deve escutar as mensagens enviadas pelo próprio usuário. * **`stopBotFromMe`**: Define se o bot deve parar quando o próprio usuário envia uma mensagem. * **`keepOpen`**: Mantém a sessão aberta, evitando que o bot seja reiniciado para o mesmo contato. * **`debounceTime`**: Tempo para juntar várias mensagens em uma só. * **`ignoreJids`**: Lista de JIDs de contatos que não ativarão o bot. * **`typebotIdFallback`**: ID do bot de fallback que será utilizado caso nenhum trigger seja ativado. ## 4. Inicialização Ativa de um Bot Além de usar triggers, você pode inicializar um bot de forma ativa para um contato específico usando o endpoint `/typebot/start/{{instance}}`. ### Endpoint para Inicialização Ativa #### Endpoint ```http theme={null} POST {{baseUrl}}/typebot/start/{{instance}} ``` #### Corpo da Requisição Aqui está um exemplo de como iniciar um bot de forma ativa: ```json theme={null} { "url": "https://bot.dgcode.com.br", "typebot": "fluxo-unico-3uuso28", "remoteJid": "557499879409@s.whatsapp.net", "startSession": false, "variables": [ { "name": "pushName", "value": "Davidson Gomes" } ] } ``` ### Explicação dos Parâmetros * **`url`**: URL da API do Typebot (sem a `/` no final). * **`typebot`**: Nome público do bot no Typebot. * **`remoteJid`**: JID (identificador) do contato no WhatsApp. * **`startSession`**: Define se a sessão deve ser iniciada com o bot (`true` ou `false`). * **`variables`**: Variáveis personalizadas que podem ser passadas ao bot (por exemplo, nome do usuário). ### Variáveis Predefinidas Quando uma sessão do Typebot é iniciada, algumas variáveis predefinidas são automaticamente enviadas: ```json theme={null} const prefilledVariables = { remoteJid: "JID do contato", pushName: "Nome do contato", instanceName: "Nome da instância", serverUrl: "URL do servidor da API", apiKey: "Chave de API da Evolution", ownerJid: "JID do número conectado à instância" }; ``` #### Explicação das Variáveis Predefinidas * **`remoteJid`**: JID do contato com quem o bot está interagindo. * **`pushName`**: Nome do contato no WhatsApp. * **`instanceName`**: Nome da instância que está executando o bot. * **`serverUrl`**: URL do servidor onde a Evolution API está hospedada. * **`apiKey`**: Chave de API usada para autenticar as requisições. * **`ownerJid`**: JID do número de telefone conectado à instância. ### Interação com Variáveis Passadas no `startTypebot` Quando você utiliza o endpoint `startTypebot`, as variáveis passadas no corpo da requisição são combinadas com as variáveis predefinidas. Isso permite que você adicione ou sobrescreva informações específicas para personalizar ainda mais a interação do bot. ### Considerações Finais A integração da Evolution API com o Typebot oferece uma maneira poderosa e flexível de automatizar interações no WhatsApp. Com variáveis predefinidas e a capacidade de iniciar bots de forma ativa, você pode personalizar a experiência do usuário final e otimizar o fluxo de atendimento. # WebSocket Source: https://docs.evolutionfoundation.com.br/evolution-api/integrations/websocket A Evolution API utiliza o `socket.io` para emitir eventos em tempo real, aproveitando a tecnologia WebSocket. Isso torna o desenvolvimento de integrações mais eficiente e direto para os desenvolvedores. O WebSocket fornece um canal de comunicação full-duplex sobre uma única conexão duradoura, permitindo o fluxo de dados em tempo real entre o cliente e o servidor. Para ativar os WebSockets, defina a variável de ambiente `WEBSOCKET_ENABLED` como `true`. Veja mais detalhes em [Variáveis de Ambiente](/evolution-api/configuration/env). ## Modos de Operação do WebSocket ### Modo Global No **modo global**, a variável de ambiente `WEBSOCKET_GLOBAL_EVENTS` deve ser definida como `true`. Nesse modo, o WebSocket é inicializado no start do serviço e envia eventos de todas as instâncias, independentemente dos canais. Isso significa que qualquer cliente conectado ao WebSocket receberá eventos globais, abrangendo todas as instâncias da Evolution API configuradas no sistema. * **Ativação**: Configure no arquivo `.env`: ```plaintext theme={null} WEBSOCKET_GLOBAL_EVENTS=true ``` * **Funcionamento**: Ideal para cenários onde você deseja monitorar ou processar eventos de todas as instâncias simultaneamente, sem precisar estabelecer uma conexão separada para cada instância. * **Conexão**: No modo global, a conexão ao WebSocket **não** requer o uso do `/nome_instancia` na URL. A URL de conexão será simplesmente: ```plaintext theme={null} wss://api.seusite.com ``` ### Modo Tradicional No **modo tradicional**, o WebSocket só pode ser conectado após a execução do comando `set` na instância. Isso permite que o WebSocket seja específico para cada instância, e a comunicação em tempo real é restrita àquela instância. * **Ativação**: Certifique-se de que `WEBSOCKET_GLOBAL_EVENTS` esteja definido como `false` ou não esteja configurado, e siga o fluxo tradicional de configuração da instância. * **Funcionamento**: Ideal para cenários onde você deseja uma comunicação em tempo real mais isolada, focada em uma única instância, permitindo maior controle e segmentação dos eventos. * **Conexão**: No modo tradicional, a conexão ao WebSocket requer o uso do `/nome_instancia` na URL: ```plaintext theme={null} wss://api.seusite.com/nome_instancia ``` ## Conexão ao WebSocket ### Modo Global No modo global, a URL de conexão é mais simples e não requer o nome da instância: ```plaintext theme={null} wss://api.seusite.com ``` ### Modo Tradicional No modo tradicional, utilize o seguinte formato de URL: ```plaintext theme={null} wss://api.seusite.com/nome_instancia ``` Substitua `api.seusite.com` pelo domínio real da sua API e `nome_instancia` pelo nome da sua instância específica. ### Exemplo de Estabelecimento de Conexão WebSocket Aqui está um exemplo básico de como estabelecer uma conexão WebSocket usando JavaScript: ```javascript theme={null} const socket = io('wss://api.seusite.com/nome_instancia', { transports: ['websocket'] }); socket.on('connect', () => { console.log('Conectado ao WebSocket da Evolution API'); }); // Escutando eventos socket.on('nome_evento', (data) => { console.log('Evento recebido:', data); }); // Lidando com desconexão socket.on('disconnect', () => { console.log('Desconectado do WebSocket da Evolution API'); }); ``` Neste exemplo, substitua `nome_evento` pelo evento específico que você deseja escutar. ## Manipulação de Eventos Uma vez conectado, você pode escutar vários eventos emitidos pelo servidor. Cada evento pode carregar dados relevantes para o contexto do evento. Por exemplo, se estiver ouvindo atualizações de mensagens, você pode receber dados contendo o conteúdo da mensagem atualizada e metadados. ## Fechamento da Conexão Para fechar a conexão WebSocket, utilize o método `disconnect`: ```javascript theme={null} socket.disconnect(); ``` Lembre-se de manipular a conexão de forma responsável, desconectando quando sua aplicação ou componente for desmontado para evitar vazamentos de memória e garantir o uso eficiente de recursos. ## Considerações Finais A Evolution API oferece uma forma poderosa de interação em tempo real através dos WebSockets, proporcionando uma experiência contínua tanto para desenvolvedores quanto para usuários finais. Seja no modo global, monitorando todas as instâncias simultaneamente, ou no modo tradicional, focado em uma única instância, a flexibilidade do sistema permite a adaptação às necessidades específicas do seu projeto. # Banco de Dados Source: https://docs.evolutionfoundation.com.br/evolution-api/requirements/database O banco de dados é uma parte fundamental da Evolution API v2, responsável por armazenar todas as informações críticas da aplicação. A API suporta tanto PostgreSQL quanto MySQL, utilizando o Prisma como ORM (Object-Relational Mapping) para facilitar a interação com esses bancos de dados. ## Escolha do Banco de Dados A Evolution API v2 permite a flexibilidade de escolher entre PostgreSQL e MySQL como provedor de banco de dados. A escolha pode ser configurada através da variável de ambiente `DATABASE_PROVIDER` e as conexões são gerenciadas pelo Prisma. ## Instalação e Configuração ### Utilizando Docker A maneira mais fácil e rápida de configurar um banco de dados para a Evolution API v2 é através do Docker. Abaixo estão as instruções para configurar tanto o PostgreSQL quanto o MySQL usando Docker Compose. #### PostgreSQL Para configurar o PostgreSQL via Docker, siga os passos abaixo: 1. Baixe o arquivo `docker-compose.yaml` para o PostgreSQL disponível aqui. 2. Navegue até o diretório onde o arquivo foi baixado e execute o comando: ```bash theme={null} docker-compose up -d ``` 3. A instância do PostgreSQL estará disponível no endereço `localhost` na porta `5432`. #### MySQL Para configurar o MySQL via Docker, siga os passos abaixo: 1. Baixe o arquivo `docker-compose.yaml` para o MySQL disponível aqui. 2. Navegue até o diretório onde o arquivo foi baixado e execute o comando: ```bash theme={null} docker-compose up -d ``` 3. A instância do MySQL estará disponível no endereço `localhost` na porta `3306`. ### Configuração das Variáveis de Ambiente Após configurar o banco de dados, defina as seguintes variáveis de ambiente no seu arquivo `.env`: ```env theme={null} # Habilitar o uso do banco de dados DATABASE_ENABLED=true # Escolher o provedor do banco de dados: postgresql ou mysql DATABASE_PROVIDER=postgresql # URI de conexão com o banco de dados DATABASE_CONNECTION_URI='postgresql://user:pass@localhost:5432/evolution?schema=public' # Nome do cliente para a conexão do banco de dados DATABASE_CONNECTION_CLIENT_NAME=evolution_exchange # Escolha os dados que você deseja salvar no banco de dados da aplicação DATABASE_SAVE_DATA_INSTANCE=true DATABASE_SAVE_DATA_NEW_MESSAGE=true DATABASE_SAVE_MESSAGE_UPDATE=true DATABASE_SAVE_DATA_CONTACTS=true DATABASE_SAVE_DATA_CHATS=true DATABASE_SAVE_DATA_LABELS=true DATABASE_SAVE_DATA_HISTORIC=true ``` ### Instalação Local Caso prefira configurar o banco de dados localmente sem utilizar Docker, siga as instruções abaixo: #### PostgreSQL 1. Instale o PostgreSQL na sua máquina. Em sistemas baseados em Ubuntu, por exemplo, você pode usar: ```bash theme={null} sudo apt-get update sudo apt-get install postgresql postgresql-contrib ``` 2. Inicie o serviço do PostgreSQL: ```bash theme={null} sudo service postgresql start ``` 3. Crie um banco de dados para a Evolution API v2: ```bash theme={null} sudo -u postgres createdb evolution ``` #### MySQL 1. Instale o MySQL na sua máquina. Em sistemas baseados em Ubuntu, você pode usar: ```bash theme={null} sudo apt-get update sudo apt-get install mysql-server ``` 2. Inicie o serviço do MySQL: ```bash theme={null} sudo service mysql start ``` 3. Crie um banco de dados para a Evolution API v2: ```bash theme={null} mysql -u root -p -e "CREATE DATABASE evolution;" ``` # Redis Source: https://docs.evolutionfoundation.com.br/evolution-api/requirements/redis O Redis é utilizado pela Evolution API v2 como um sistema de cache para otimizar o desempenho e a velocidade da aplicação. Ele pode ser configurado para armazenar informações temporárias e melhorar a eficiência das operações. ## Instalação e Configuração ### Utilizando Docker A maneira mais fácil e rápida de configurar o Redis para a Evolution API v2 é através do Docker. Abaixo estão as instruções para configurar o Redis usando Docker Compose. #### Redis Para configurar o Redis via Docker, siga os passos abaixo: 1. Baixe o arquivo `docker-compose.yaml` para o Redis disponível aqui. 2. Navegue até o diretório onde o arquivo foi baixado e execute o comando: ```bash theme={null} docker-compose up -d ``` 3. A instância do Redis estará disponível no endereço `localhost` na porta `6379`. ### Configuração das Variáveis de Ambiente Após configurar o Redis, defina as seguintes variáveis de ambiente no seu arquivo `.env`: ```env theme={null} # Habilitar o cache Redis CACHE_REDIS_ENABLED=true # URI de conexão com o Redis CACHE_REDIS_URI=redis://localhost:6379/6 # Prefixo para diferenciar os dados de diferentes instalações que utilizam o mesmo Redis CACHE_REDIS_PREFIX_KEY=evolution # Habilitar para salvar as informações de conexão no Redis ao invés do banco de dados CACHE_REDIS_SAVE_INSTANCES=false # Habilitar o cache local CACHE_LOCAL_ENABLED=false ``` ### Instalação Local Caso prefira configurar o Redis localmente sem utilizar Docker, siga as instruções abaixo: #### Redis 1. Instale o Redis na sua máquina. Em sistemas baseados em Ubuntu, por exemplo, você pode usar: ```bash theme={null} sudo apt-get update sudo apt-get install redis-server ``` 2. Inicie o serviço do Redis: ```bash theme={null} sudo service redis-server start ``` 3. Verifique se o Redis está rodando corretamente com o comando: ```bash theme={null} redis-cli ping ``` Se tudo estiver funcionando corretamente, você verá a resposta `PONG`. ### Configuração do Cache na Evolution API v2 Após a instalação e configuração do Redis, a próxima etapa é configurar o cache na Evolution API v2 utilizando as variáveis de ambiente. Isso permitirá que a API utilize o Redis para cachear dados importantes e melhorar a performance geral da aplicação. # Atualização Source: https://docs.evolutionfoundation.com.br/evolution-api/updates Manter sua instância da Evolution API atualizada é crucial para segurança, desempenho e acesso a novos recursos. O método de atualização depende de como você inicialmente instalou a API. Este guia cobre os passos para atualizar sua Evolution API usando Docker Compose e NPM. Antes de atualizar a Evolution, certifique-se de que todos os aplicativos integrados estão realmente funcionando com a Evolution. Atualize por sua conta e risco. ## Atualização com Docker Se você configurou inicialmente sua Evolution API usando Docker, siga estas etapas para atualizar: ### Atualização com Docker CLI Se sua Evolution API foi instalada inicialmente usando Docker Compose via interface de linha de comando (CLI), e não através do Portainer ou qualquer outra ferramenta de gerenciamento de contêiner, siga estas etapas para atualizá-la: 1. **Navegue até o Diretório do Docker Compose**: Abra um terminal e vá para o diretório onde seu arquivo Docker Compose (`docker-compose.yml`) está localizado. 2. **Puxe a Imagem Mais Recente**: Atualize a imagem da Evolution API para a versão mais recente executando o seguinte comando: ```shell theme={null} docker pull evoapicloud/evolution-api:v2.1.1 ``` 3. **Pare e Reinicie os Contêineres**: Após puxar a imagem mais recente, pare os contêineres atuais e reinicie-os. Isso pode ser feito usando o seguinte comando: ```shell theme={null} docker compose down && docker compose up -d ``` ## Atualização com Portainer Se você está usando o Portainer para gerenciamento de contêineres, siga estas etapas para atualizar sua Evolution API: 1. **Acesse o Painel do Portainer**: Abra o painel do Portainer em um navegador web. 2. **Navegue até Seus Contêineres**: Vá para a seção 'Stacks' onde seu contêiner da Evolution API está listado. 3. **Atualize o Compose**: * Localize o campo `image` na sua configuração do Docker Compose. ```yaml stack-file.yml theme={null} # ... (outros serviços e configurações) evolution_api: # Atualize a versão da imagem da Evolution API aqui # Use 'evoapicloud/evolution-api:latest' para a versão mais recente # Ou especifique uma versão específica como 'evoapicloud/evolution-api:2.1.1' image: evoapicloud/evolution-api:v2.x.x networks: - your_network ``` * Atualize o valor para `evoapicloud/evolution-api:v2.1.1` para a versão mais recente, ou use `evoapicloud/evolution-api:v2.x.x` para uma versão específica. * Após fazer as alterações, clique no botão 'Deploy' no final da janela de edição do compose. 4. **Verifique a Atualização**: Após recriar o contêiner, verifique se a Evolution API está executando a versão mais recente. Isso pode ser verificado tipicamente através do endpoint de versão da API ou dos logs. Para ambientes de produção, é recomendável especificar uma versão particular da Evolution API (ex.: evoapicloud/evolution-api:v1.x.x) em vez de usar latest. Esta prática garante estabilidade e previsibilidade, pois protege seu ambiente de produção de problemas potenciais decorrentes de mudanças inesperadas na versão mais recente. Seguindo esses passos, você pode garantir que sua Evolution API esteja sempre atualizada usando o Portainer. ## Atualização com NPM Atualizar sua instalação da Evolution API via NPM envolve várias etapas para garantir uma transição suave para a nova versão. Aqui está um guia passo a passo: 1. **Limpar e Parar**: Limpe todos os logs do PM2, útil para resolução de problemas após a atualização, e pare temporariamente a Evolution API para aplicar as atualizações com segurança. ```shell Terminal theme={null} # Limpar todos os logs do PM2 pm2 flush # Parar o processo atual da Evolution API pm2 stop ApiEvolution ``` 2. **Resetar o repositório local e puxar as atualizações mais recentes**: Garanta que seu código local esteja em sincronia com o commit mais recente e baixe as atualizações mais recentes do repositório. Opcionalmente, mude para uma versão específica se não estiver usando a mais recente. É recomendado para ambientes de produção. ```shell Terminal theme={null} # Resetar seu repositório local para o commit mais recente git reset --hard HEAD # Puxar as atualizações mais recentes do repositório git pull # Para uma versão específica, use 'git checkout main' para a mais recente, # ou 'git checkout 1.x.x' para uma versão específica. Exemplo: git checkout 1.x.x ``` 3. **Instalação Limpa**: Remova o `node_modules` existente para evitar possíveis conflitos com novas dependências e instale as dependências necessárias do Node.js para a versão atualizada. ```shell Terminal theme={null} # Remover o diretório node_modules atual para garantir uma instalação limpa rm -rf node_modules # Instalar dependências com NPM npm i # Reiniciar a Evolution API com a versão atualizada pm2 start ApiEvolution # Opcionalmente, visualizar os logs do PM2 para a Evolution API pm2 log ApiEvolution ``` # Configuração Inicial Source: https://docs.evolutionfoundation.com.br/evolution-go/getting-started Como ativar sua licença, fazer login e criar sua primeira instância no Evolution Go Após a [instalação](/evolution-go/installation), siga este guia para ativar sua licença, acessar o painel de gerenciamento e criar sua primeira instância WhatsApp no Evolution Go. *** ## Passo 1: Ativar a licença Evolution Antes de usar o Evolution Go, é necessário ativar sua licença. Ao acessar o sistema pela primeira vez, você será redirecionado para a tela de ativação. Tela de ativação da licença Evolution Go ### Como ativar 1. Acesse a URL do seu Evolution Go no navegador (ex: `http://localhost:8080` ou o domínio do seu servidor) 2. Na tela de ativação, você verá o formulário **"Ative sua licença Evolution"** 3. Preencha os campos: * **Nome Completo** — Seu nome completo para registro * **Email** — Seu email para receber o Magic Link de ativação 4. Clique em **"Enviar Magic Link"** 5. Verifique sua caixa de entrada e clique no link recebido para ativar Você também pode ativar usando uma conta social: **Continuar com Google** ou **Continuar com GitHub**. Isso agiliza o processo e vincula sua licença automaticamente. A licença é vinculada ao seu email. Guarde esse email, pois será necessário para futuras ativações ou migrações de servidor. *** ## Passo 2: Login no painel Após ativar a licença, você será direcionado para a tela de login do Evolution Go. Tela de login do Evolution Go ### Como fazer login 1. No campo **"URL da API Evolution GO"**, insira a URL da sua instância: * Para instalação local: `http://localhost:8080` * Para servidor remoto: `https://seu-dominio.com` (ou o IP do servidor com a porta) 2. No campo **"API Key (GLOBAL\_API\_KEY)"**, insira a chave de API que você configurou no arquivo `.env` durante a instalação A API Key é o valor da variável `GLOBAL_API_KEY` configurada no arquivo `.env` do Evolution Go. Se você não alterou, ela é a chave padrão definida no `.env.example` — **nunca use a chave padrão em produção**. ### Onde encontrar a API Key A API Key está no arquivo `.env` na raiz do seu projeto Evolution Go: ```env theme={null} # Chave de API global GLOBAL_API_KEY=sua-chave-segura-aqui ``` Se estiver usando Docker Compose, ela está no `docker-compose.yml`: ```yaml theme={null} environment: GLOBAL_API_KEY: sua-chave-segura-aqui ``` Após preencher os campos, clique em **"Entrar"** para acessar o painel. *** ## Passo 3: Dashboard Após o login, você será direcionado para o **Dashboard** do Evolution Go. Dashboard principal do Evolution Go O painel possui uma barra lateral com duas seções principais: * **Dashboard** — Visão geral do sistema (métricas e status serão implementados aqui) * **Instâncias** — Gerenciamento das suas instâncias WhatsApp No canto superior direito você encontra: * **Alternador de tema** (claro/escuro) * **Botão "Sair"** para fazer logout *** ## Passo 4: Criar sua primeira instância Navegue até a seção **Instâncias** na barra lateral para gerenciar suas conexões WhatsApp. Tela de instâncias sem nenhuma instância criada Na tela de instâncias você verá: * Um campo de **busca** para filtrar instâncias * O botão **"+ Nova Instância"** no canto superior direito * Uma mensagem indicando que nenhuma instância foi encontrada ### Criando a instância Clique em **"+ Nova Instância"** para abrir o formulário de criação: Modal de criação de nova instância WhatsApp Preencha os campos: | Campo | Obrigatório | Descrição | | ------------------------------------ | :---------: | ---------------------------------------------------------------------------------------------------------------- | | **Nome da Instância** | ✅ | Nome identificador da sua instância. Use apenas letras, números, hífen (`-`) e underscore (`_`) | | **Token (Opcional)** | ❌ | Token personalizado (UUID) para autenticação da instância. Se não informado, será gerado um UUID automaticamente | | **Configuração de Proxy (Opcional)** | ❌ | Configurações de proxy para a conexão WhatsApp, caso necessário | Clique em **"+ Criar Instância"** para finalizar. *** ## Passo 5: Conectar ao WhatsApp Após criar a instância, ela aparecerá na lista com o status **"Desconectado"** (em vermelho). Instância criada com status Desconectado Cada instância exibe: * **Nome** e identificador da instância * **Status** atual (`close` = desconectado) * Botões de ação: * **Conectar** (ícone de power, verde) — Inicia a conexão com o WhatsApp * **Configurações** (ícone de engrenagem) — Abre as configurações da instância * **Excluir** (ícone de lixeira, vermelho) — Remove a instância ### Configurar conexão Clique no botão **"Conectar"** ou no ícone de **engrenagem** para abrir o modal de configuração da conexão: Modal de configuração de conexão e webhook Neste modal você pode configurar: #### Webhook URL (opcional) Insira a URL que receberá os eventos da instância. Exemplo: ``` https://webhook.site/4d438e6a-7203-4102-8dbc-987addc73b53 ``` Use o webhook.site para testes rápidos. Em produção, aponte para o endpoint do seu servidor que processará os eventos. #### Eventos para Webhook Selecione quais eventos serão enviados para a URL do webhook: * **ALL** — Seleciona todos os eventos (recomendado para começar) * Ou escolha eventos individuais: | Evento | Descrição | | --------------- | --------------------------------------------------- | | `MESSAGE` | Mensagens enviadas e recebidas | | `PRESENCE` | Status de presença (online/offline) | | `CHAT_PRESENCE` | Presença em chats específicos (digitando, gravando) | | `CONNECTION` | Mudanças no status da conexão | | `READ_RECEIPT` | Confirmações de leitura | | `HISTORY_SYNC` | Sincronização do histórico de mensagens | | `CALL` | Chamadas recebidas | | `QRCODE` | Geração de QR Code para pareamento | | `LABEL` | Eventos de etiquetas | | `CONTACT` | Eventos de contatos | #### Telefone para Pairing Code (opcional) Se preferir conectar via **código de pareamento** ao invés de QR Code, insira o número de telefone no formato: ``` 5511999999999 ``` (código do país + DDD + número, sem espaços ou caracteres especiais) #### Configurações Avançadas Expanda para ver opções adicionais de configuração da instância. ### Finalizar conexão Após configurar, clique em **"Conectar"** para iniciar a conexão. Dependendo do método escolhido: * **QR Code**: Um QR Code será exibido na tela. Abra o WhatsApp no seu celular, vá em **Configurações > Dispositivos conectados > Conectar dispositivo** e escaneie o código. * **Pairing Code**: Um código de 8 dígitos será gerado. No WhatsApp do celular, vá em **Configurações > Dispositivos conectados > Conectar dispositivo > Conectar com número de telefone** e insira o código. Após a conexão bem-sucedida, o status da instância mudará de **"Desconectado"** para **"Conectado"** (em verde) e os eventos começarão a ser enviados para o webhook configurado. *** ## Próximos passos Precisa de um servidor? Confira os planos VPS otimizados para Evolution Go # Evolution Go Source: https://docs.evolutionfoundation.com.br/evolution-go/index API WhatsApp de alta performance escrita em Go O **Evolution Go** é uma implementação de alta performance da API WhatsApp, escrita em Go. Construído com a biblioteca padrão do Go e práticas modernas de desenvolvimento, oferece uma solução robusta e eficiente para integração com WhatsApp utilizando a biblioteca whatsmeow. ## Principais recursos * **Alta Performance** — Construído em Go para máxima performance e uso mínimo de recursos * **API RESTful** — Endpoints REST bem documentados e fáceis de usar * **Eventos em tempo real** — Suporte a WebSocket para recebimento de mensagens em tempo real * **Armazenamento de mensagens** — Integração opcional com PostgreSQL para persistência * **Suporte a mídia** — Envio e recebimento de imagens, vídeos, áudios e documentos * **QR Code** — Geração de QR Code para pareamento de dispositivos * **Docker** — Configuração Docker pronta para uso * **Documentação Swagger** — Documentação interativa auto-gerada * **Sistema de eventos** — Suporte a webhooks, AMQP (RabbitMQ), NATS e WebSocket ## Stack tecnológica | Tecnologia | Uso | | ---------------------------------------------------------- | ---------------------------------- | | Go 1.24+ | Linguagem principal | | `net/http` + ServeMux | Framework HTTP (biblioteca padrão) | | whatsmeow | Biblioteca WhatsApp Web | | PostgreSQL | Banco de dados (opcional) | | Swagger/OpenAPI | Documentação da API | | Docker | Containerização | | RabbitMQ/AMQP | Fila de mensagens | | MinIO/S3 | Armazenamento de mídia | ## Seções Guia passo a passo para instalar e configurar o Evolution Go Ative sua licença, faça login e crie sua primeira instância WhatsApp Configure webhooks para receber eventos em tempo real do WhatsApp Documentação técnica completa de todos os endpoints # Usando com Postman Source: https://docs.evolutionfoundation.com.br/evolution-go/install/postman Como importar a collection oficial e testar a API do Evolution Go usando o Postman O **Postman** é uma ferramenta para testar e explorar APIs REST de forma visual e intuitiva. Com a collection oficial do Evolution Go, você pode executar requisições, configurar ambientes e explorar todos os endpoints sem precisar escrever código. ## Pré-requisitos * **Evolution Go** instalado e rodando — veja o [guia de instalação](/evolution-go/installation) * **Postman** instalado — baixe aqui * Sua **API Key** (`GLOBAL_API_KEY` configurada no `.env`) *** ## Passo 1: Importar a Collection Oficial A collection oficial do Evolution Go está disponível publicamente no Postman e contém todos os endpoints da API prontos para uso. Abra o Postman no seu computador ou acesse o Postman Web. No canto superior esquerdo, clique em **Import**. Selecione a aba **Link** e cole a URL da collection oficial: ``` https://www.postman.com/agenciadgcode/evolution-api/collection/u95jxho/evolution-go ``` Clique em **Continue** e depois em **Import**. A collection **Evolution Go** aparecerá na sua barra lateral. *** ## Passo 2: Criar o Environment As variáveis de ambiente centralizam as configurações da sua instância, permitindo trocar entre ambientes (local, staging, produção) sem alterar cada requisição. No Postman, clique em **Environments** (ícone de olho no canto superior direito) e depois em **+** para criar um novo. Dê o nome **Evolution Go** (ou outro nome de sua preferência). Adicione as seguintes variáveis: | Variável | Valor inicial | Descrição | | ------------- | ---------------------------------- | ------------------------------------- | | `base_url` | `http://localhost:8080` | URL base do seu servidor Evolution Go | | `api_key` | `sua-chave-aqui` | Valor do `GLOBAL_API_KEY` no `.env` | | `instance_id` | *(preencher após criar instância)* | UUID da instância WhatsApp | Clique em **Save** e selecione o environment **Evolution Go** no seletor no canto superior direito do Postman. Nunca compartilhe ou exponha o valor da `api_key` publicamente. Ela dá acesso total à sua API. *** ## Passo 3: Configurar os Headers da Collection Para não precisar adicionar os headers em cada requisição individualmente, configure-os no nível da collection. Clique com o botão direito em **Evolution Go** na sidebar e selecione **Edit**. Confirme que as variáveis `base_url`, `api_key` e `instance_id` estão referenciadas. Se preferir, adicione os headers padrão em todas as requisições via **Pre-request Script**: ```javascript theme={null} pm.request.headers.add({ key: "apikey", value: pm.environment.get("api_key") }); pm.request.headers.add({ key: "instanceId", value: pm.environment.get("instance_id") }); pm.request.headers.add({ key: "Content-Type", value: "application/json" }); ``` Os headers necessários para autenticação são: * `apikey`: sua `GLOBAL_API_KEY` * `instanceId`: UUID da instância (necessário nas rotas que operam sobre uma instância específica) * `Content-Type`: `application/json` (para requisições com body) *** ## Passo 4: Testar a Conexão Antes de criar instâncias, verifique se o Evolution Go está acessível. **Requisição:** ``` GET {{base_url}}/ ``` Uma resposta de sucesso indica que o servidor está no ar. Se retornar erro de conexão, verifique se o Evolution Go está rodando e se o `base_url` está correto. *** ## Passo 5: Criar uma Instância WhatsApp Com a conexão verificada, crie sua primeira instância. **Requisição:** ``` POST {{base_url}}/instance/create ``` **Headers:** | Key | Value | | -------------- | ------------------ | | `Content-Type` | `application/json` | | `apikey` | `{{api_key}}` | **Body:** ```json theme={null} { "instanceName": "minha-instancia", "integration": "WHATSAPP-BAILEYS" } ``` **Resposta de sucesso:** ```json theme={null} { "instanceName": "minha-instancia", "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "token": "seu-token-aqui", "status": "created" } ``` Copie o `instanceId` da resposta e salve na variável `instance_id` do seu Environment para usar nas próximas requisições. *** ## Passo 6: Conectar ao WhatsApp Com a instância criada, inicie a conexão com o WhatsApp. Este endpoint também permite configurar o webhook para receber eventos. **Requisição:** ``` POST {{base_url}}/instance/connect ``` **Headers:** | Key | Value | | -------------- | ------------------ | | `Content-Type` | `application/json` | | `apikey` | `{{api_key}}` | | `instanceId` | `{{instance_id}}` | **Body:** ```json theme={null} { "webhookUrl": "https://webhook.site/seu-id-unico", "subscribe": ["ALL"], "immediate": true } ``` Após a requisição, você receberá um QR Code via webhook (campo `qrcode` em base64). Escaneie-o com o WhatsApp do seu celular em **Configurações > Dispositivos conectados > Conectar dispositivo**. Para conectar via **Pairing Code** ao invés de QR Code, adicione o campo `phone` no body com o número no formato `5511999999999`. *** ## Explorando Mais Endpoints Acesse a documentação interativa **Swagger** da sua instância para descobrir todos os endpoints disponíveis: ``` {{base_url}}/swagger/index.html ``` O Swagger permite visualizar parâmetros, testar endpoints diretamente no navegador e ver exemplos de response. *** ## Próximos passos Receba eventos em tempo real de mensagens, conexões e muito mais Gerencie instâncias pelo painel visual do Evolution Go # SetupOrion Source: https://docs.evolutionfoundation.com.br/evolution-go/install/setup-orion Instalação automatizada do Evolution Go com SetupOrion O SetupOrion é um instalador automatizado que configura toda a infraestrutura necessária para rodar o Evolution Go em uma VPS limpa, incluindo Docker, Traefik, Portainer e Docker Swarm. ## Pré-requisitos * VPS com **Debian 11** ou **Ubuntu 20.04** (sistema limpo) * Registro DNS (tipo A) apontando para o IP da VPS * Acesso root ao servidor *** ## Passo 1: Executar o SetupOrion Em uma VPS vazia, execute o comando abaixo e aguarde enquanto o SetupOrion instala todas as dependências necessárias. Ao finalizar, você será direcionado ao menu de ferramentas. ```bash theme={null} bash <(curl -sSL setup.oriondesign.art.br) ``` ## Passo 2: Instalar Traefik e Portainer No menu de ferramentas, selecione a **Opção 1** para instalar: * Docker * Docker Swarm (inicialização e criação de redes) * Traefik (proxy reverso com SSL automático) * Portainer (gerenciamento visual de containers) Responda as perguntas que aparecem na tela para que o Setup possa realizar as instalações corretamente. ## Passo 3: Instalar o Evolution Go Retorne ao menu de ferramentas e selecione a **Opção 3 (Evolution)**: 1. Escolha a versão: **EvoGO** 2. Informe o domínio configurado no DNS para a aplicação ## Passo 4: Verificar a instalação Após a instalação ser finalizada, você verá uma tela informando: * **Dados de acesso** da aplicação * **Links** para a documentação Anote as credenciais exibidas no terminal. Elas serão necessárias para acessar o Evolution Go. # Instalação do Evolution Go Source: https://docs.evolutionfoundation.com.br/evolution-go/installation Guia passo a passo para instalar e configurar o Evolution Go Este guia irá ajudá-lo a instalar e configurar o **Evolution Go**, nossa API WhatsApp de alta performance escrita em Go. ## Pré-requisitos Antes de iniciar, certifique-se de ter os seguintes requisitos atendidos: * Docker 20.10 ou superior * Docker Compose v2.x (opcional) * Mínimo de **512MB de RAM** disponível *** ## Instalação com Docker A forma mais rápida de começar a usar o Evolution Go. ### Passo 1: Clone o repositório ```bash theme={null} git clone https://git.evoai.app/Evolution/evolution-go.git cd evolution-go ``` ### Passo 2: Configure as variáveis de ambiente ```bash theme={null} cp .env.example .env ``` Edite o arquivo `.env` com suas configurações: ```env theme={null} # Porta do servidor SERVER_PORT=8080 # Nome do cliente CLIENT_NAME=evolution # Chave de API global (altere para uma chave segura!) GLOBAL_API_KEY=sua-chave-secura-aqui # Banco de dados (PostgreSQL) POSTGRES_AUTH_DB=postgresql://postgres:password@postgres:5432/evogo_auth?sslmode=disable POSTGRES_USERS_DB=postgresql://postgres:password@postgres:5432/evogo_users?sslmode=disable DATABASE_SAVE_MESSAGES=false # Logs WADEBUG=INFO LOGTYPE=console ``` Nunca utilize a chave de API padrão do `.env.example` em produção. Gere uma chave segura e única. ### Passo 3: Build e execução ```bash theme={null} # Build da imagem Docker make docker-build # Executar o container make docker-run ``` O serviço estará disponível em `http://localhost:8080`. ### Alternativa: Docker Compose Você também pode usar um `docker-compose.yml` para subir o Evolution Go junto com o PostgreSQL: ```yaml theme={null} services: postgres: image: postgres:15 environment: POSTGRES_USER: postgres POSTGRES_PASSWORD: password ports: - "5432:5432" volumes: - postgres_data:/var/lib/postgresql/data evolution-go: image: evoapicloud/evolution-go:latest ports: - "8080:8080" environment: SERVER_PORT: 8080 CLIENT_NAME: evolution GLOBAL_API_KEY: sua-chave-segura-aqui POSTGRES_AUTH_DB: postgresql://postgres:password@postgres:5432/evogo_auth?sslmode=disable POSTGRES_USERS_DB: postgresql://postgres:password@postgres:5432/evogo_users?sslmode=disable DATABASE_SAVE_MESSAGES: "false" WADEBUG: INFO LOGTYPE: console depends_on: - postgres restart: unless-stopped volumes: postgres_data: ``` Execute com: ```bash theme={null} docker compose up -d ``` *** ## Verificando a instalação Após iniciar o serviço, verifique se está funcionando corretamente: ### Teste de saúde ```bash theme={null} curl http://localhost:8080/ ``` ### Acesse a documentação Swagger Abra no navegador: ``` http://localhost:8080/swagger/index.html ``` ### Crie sua primeira instância WhatsApp ```bash theme={null} curl -X POST http://localhost:8080/instance/create \ -H "Content-Type: application/json" \ -H "apikey: sua-chave-segura-aqui" \ -d '{ "instanceName": "minha-instancia", "integration": "WHATSAPP-BAILEYS" }' ``` ### Obtenha o QR Code para conectar ```bash theme={null} curl http://localhost:8080/instance/minha-instancia/qrcode \ -H "apikey: sua-chave-segura-aqui" ``` Escaneie o QR Code com o WhatsApp do seu celular para conectar a instância. *** ## Variáveis de ambiente Tabela completa das variáveis de configuração disponíveis: | Variável | Descrição | Padrão | | ------------------------ | ----------------------------------------------------------- | ----------------- | | `SERVER_PORT` | Porta do servidor HTTP | `8080` | | `CLIENT_NAME` | Identificador do cliente | `evolution` | | `GLOBAL_API_KEY` | Chave de autenticação da API | **Obrigatório** | | `POSTGRES_AUTH_DB` | String de conexão do banco de autenticação | - | | `POSTGRES_USERS_DB` | String de conexão do banco de usuários | - | | `DATABASE_SAVE_MESSAGES` | Habilitar persistência de mensagens | `false` | | `WADEBUG` | Nível de log do WhatsApp (`DEBUG`, `INFO`, `WARN`, `ERROR`) | `INFO` | | `LOGTYPE` | Tipo de saída de log (`console`, `json`) | `console` | | `CONNECT_ON_STARTUP` | Reconectar instâncias ao iniciar | `true` | | `WEBHOOKFILES` | Incluir arquivos nos webhooks | `true` | | `WEBHOOK_URL` | URL para receber webhooks | - | | `AMQP_URL` | URL de conexão do RabbitMQ | - | | `AMQP_GLOBAL_ENABLED` | Habilitar RabbitMQ globalmente | `false` | | `MINIO_ENABLED` | Habilitar armazenamento MinIO/S3 | `false` | | `MINIO_ENDPOINT` | Endpoint do MinIO | - | | `MINIO_ACCESS_KEY` | Chave de acesso do MinIO | - | | `MINIO_SECRET_KEY` | Chave secreta do MinIO | - | | `MINIO_BUCKET` | Nome do bucket do MinIO | `evolution-media` | | `MINIO_USE_SSL` | Usar SSL na conexão MinIO | `false` | *** ## Comandos úteis (Docker) ```bash theme={null} # Build da imagem Docker make docker-build # Executar container Docker make docker-run ``` *** ## Próximos passos Após a instalação, você pode: * Consultar a [Referência API](/evolution-go/get-all-instances) para conhecer todos os endpoints disponíveis * Configurar [webhooks](/evolution-go/getting-started) para receber notificações em tempo real * Integrar com [RabbitMQ](/evolution-go/getting-started) para processamento assíncrono de mensagens # Community Node N8N Source: https://docs.evolutionfoundation.com.br/evolution-go/n8n-community-node Como instalar o node comunitário do Evolution Go no N8N Integre o **Evolution Go** diretamente nos seus fluxos do N8N utilizando o node comunitário oficial. ## Pré-requisitos * Instância do **N8N** em funcionamento * **Evolution Go** instalado e acessível *** ## Instalação No N8N, navegue até **Settings > Community Nodes** (`/settings/community-nodes`) Clique em **Install** No campo de instalação, digite: ``` n8n-nodes-evolution-go ``` Aceite o termo de uso e clique em **Install** ## Usando o node Após o processo de instalação, o node estará disponível nos seus fluxos. Para localizá-lo, pesquise por **"Evolution GO"** na barra de busca de nodes do N8N. # Webhooks Source: https://docs.evolutionfoundation.com.br/evolution-go/webhooks Os Webhooks permitem que o Evolution Go envie notificações em tempo real para sua aplicação quando eventos ocorrem no WhatsApp, como recebimento de mensagens, atualizações de conexão, chamadas e muito mais. ## Guia Rápido Siga estes passos para configurar e receber webhooks do Evolution Go. ### Pré-requisitos Antes de configurar webhooks, você precisa: 1. Ter o Evolution Go **instalado e rodando** — veja o [guia de instalação](/evolution-go/installation) 2. Ter uma **instância criada** — veja [Configuração Inicial](/evolution-go/getting-started) 3. Ter sua **API Key** (`GLOBAL_API_KEY` configurada no `.env`) 4. Ter uma **URL acessível** para receber os eventos Para testes rápidos, use o webhook.site para gerar uma URL temporária e visualizar os eventos recebidos em tempo real. Para desenvolvimento local, use o ngrok para expor seu servidor local à internet. ### Passo 1: Conectar a instância com webhook Configure o webhook ao conectar sua instância enviando uma requisição para o endpoint de conexão. #### Método ``` POST {BASE_URL}/instance/connect ``` #### Header | Key | Value | Descrição | | ------------ | -------------------------------------- | ----------------------------------------- | | Content-Type | `application/json` | Tipo do conteúdo | | apikey | `SUA_GLOBAL_API_KEY` | Chave de API global configurada no `.env` | | instanceId | `249aad2e-68f9-464f-bc84-aca560c38f0e` | UUID da instância que deseja conectar | A API Key é o valor da variável `GLOBAL_API_KEY` configurada no arquivo `.env` do Evolution Go. Nunca exponha essa chave publicamente. Veja mais detalhes em [Configuração Inicial](/evolution-go/getting-started#passo-2-login-no-painel). #### Body ```json theme={null} { "webhookUrl": "https://webhook.site/seu-id-unico", "subscribe": ["ALL"], "immediate": true } ``` #### Exemplo com cURL ```bash theme={null} curl -X POST 'http://localhost:8080/instance/connect' \ -H 'Content-Type: application/json' \ -H 'apikey: SUA_GLOBAL_API_KEY' \ -H 'instanceId: 249aad2e-68f9-464f-bc84-aca560c38f0e' \ -d '{ "webhookUrl": "https://webhook.site/seu-id-unico", "subscribe": ["ALL"], "immediate": true }' ``` #### Exemplo com JavaScript ```javascript theme={null} const response = await fetch('http://localhost:8080/instance/connect', { method: 'POST', headers: { 'Content-Type': 'application/json', 'apikey': 'SUA_GLOBAL_API_KEY', 'instanceId': '249aad2e-68f9-464f-bc84-aca560c38f0e' }, body: JSON.stringify({ webhookUrl: 'https://webhook.site/seu-id-unico', subscribe: ['ALL'], immediate: true }) }); const data = await response.json(); console.log(data); ``` #### Exemplo com Python ```python theme={null} import requests response = requests.post( 'http://localhost:8080/instance/connect', headers={ 'Content-Type': 'application/json', 'apikey': 'SUA_GLOBAL_API_KEY', 'instanceId': '249aad2e-68f9-464f-bc84-aca560c38f0e' }, json={ 'webhookUrl': 'https://webhook.site/seu-id-unico', 'subscribe': ['ALL'], 'immediate': True } ) print(response.json()) ``` ### Passo 2: Parear com o WhatsApp Após a conexão, você receberá um evento `QRCode` no seu webhook com a imagem do QR Code em base64: 1. Abra o **WhatsApp** no celular 2. Vá em **Configurações > Dispositivos conectados > Conectar dispositivo** 3. Escaneie o QR Code recebido no webhook (decodifique o campo `qrcode` base64 para exibir a imagem) Se preferir usar **Pairing Code** ao invés de QR Code, envie o campo `phone` no body: ```json theme={null} { "webhookUrl": "https://webhook.site/seu-id-unico", "subscribe": ["ALL"], "phone": "5511999999999" } ``` ### Passo 3: Confirmar a conexão Após o pareamento bem-sucedido, você receberá uma sequência de eventos: `PairSuccess` → `Connected` → `OfflineSyncCompleted`. Se recebeu esses 3 eventos, seu webhook está configurado corretamente. ### Passo 4: Receber mensagens A partir de agora, toda mensagem recebida no WhatsApp será enviada como evento `Message` para sua URL. ``` Usuário envia mensagem → WhatsApp → Evolution Go → HTTP POST → Seu Webhook ``` #### Processando no seu servidor ```javascript Node.js (Express) theme={null} const express = require('express'); const app = express(); app.use(express.json()); app.post('/webhook', (req, res) => { const { event, data, instanceId } = req.body; switch (event) { case 'Message': const sender = data.Info.PushName || data.Info.Sender; const text = data.Message.conversation; console.log(`[${instanceId}] ${sender}: ${text}`); break; case 'Connected': console.log(`Instância ${instanceId} conectada!`); break; case 'QRCode': console.log(`QR Code recebido para ${instanceId}`); break; default: console.log(`Evento: ${event}`); } res.status(200).json({ received: true }); }); app.listen(3000, () => console.log('Webhook rodando na porta 3000')); ``` ```python Python (Flask) theme={null} from flask import Flask, request, jsonify app = Flask(__name__) @app.route('/webhook', methods=['POST']) def webhook(): payload = request.json event = payload.get('event') data = payload.get('data', {}) instance_id = payload.get('instanceId') if event == 'Message': sender = data.get('Info', {}).get('PushName', data.get('Info', {}).get('Sender')) text = data.get('Message', {}).get('conversation', '') print(f'[{instance_id}] {sender}: {text}') elif event == 'Connected': print(f'Instância {instance_id} conectada!') elif event == 'QRCode': print(f'QR Code recebido para {instance_id}') else: print(f'Evento: {event}') return jsonify({'received': True}), 200 if __name__ == '__main__': app.run(port=3000) ``` Seu endpoint **deve** responder com status HTTP `2xx` (200-299) em até 30 segundos. Caso contrário, o Evolution Go fará até **5 retentativas** com intervalo de **30 segundos** entre cada uma. *** ## Configuração Detalhada A configuração de webhooks é feita no momento da conexão da instância, através do endpoint `POST /instance/connect`. ### Webhook por Instância Ao conectar uma instância, você pode definir a URL do webhook e os eventos que deseja receber: ```json POST /instance/connect theme={null} { "webhookUrl": "https://seu-dominio.com/webhook", "subscribe": [ "MESSAGE", "SEND_MESSAGE", "CONNECTION", "QRCODE" ], "immediate": true, "phone": "5511999999999" } ``` ### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | --------------- | --------- | ----------- | ------------------------------------------------------------------------- | | webhookUrl | string | Não | URL que receberá os eventos via HTTP POST | | subscribe | string\[] | Não | Lista de tipos de eventos para receber. Se vazio, recebe apenas `MESSAGE` | | immediate | boolean | Não | Conectar imediatamente sem aguardar QR Code | | phone | string | Não | Número de telefone para pareamento | | rabbitmqEnable | string | Não | `"enabled"` para ativar envio via RabbitMQ | | websocketEnable | string | Não | `"enabled"` para ativar envio via WebSocket | | natsEnable | string | Não | `"enabled"` para ativar envio via NATS | ### Webhook Global Você pode definir um webhook global via variável de ambiente. Ele receberá eventos de **todas** as instâncias, além dos webhooks individuais de cada instância. ```bash .env theme={null} # URL do webhook global (recebe eventos de todas as instâncias) WEBHOOK_URL=https://seu-dominio.com/webhook/global # Incluir arquivos de mídia no payload do webhook (padrão: true) WEBHOOK_FILES=true ``` Quando configurados, **ambos** os webhooks são acionados: o global (definido por `WEBHOOK_URL`) e o da instância (definido em `webhookUrl`). Isso permite ter um sistema centralizado de monitoramento junto com integrações específicas por instância. ## Tipos de Eventos Ao configurar o webhook, você pode se inscrever nos seguintes tipos de eventos: | Tipo de Evento | Descrição | Eventos Incluídos | | --------------- | --------------------------------------- | --------------------------------------------------------------- | | `ALL` | Recebe todos os eventos disponíveis | Todos abaixo | | `MESSAGE` | Mensagens recebidas | `Message` | | `SEND_MESSAGE` | Mensagens enviadas | `SendMessage` | | `READ_RECEIPT` | Confirmações de leitura | `Receipt` (Read, ReadSelf, Delivered) | | `PRESENCE` | Status de presença online/offline | `Presence` | | `HISTORY_SYNC` | Sincronização de histórico | `HistorySync` | | `CHAT_PRESENCE` | Presença em chats (digitando, gravando) | `ChatPresence`, `Archive` | | `CALL` | Eventos de chamada | `CallOffer`, `CallRelayLatency`, `CallTerminate` | | `CONNECTION` | Status de conexão | `Connected`, `PairSuccess`, `LoggedOut`, `OfflineSyncCompleted` | | `LABEL` | Gerenciamento de etiquetas | `LabelEdit`, `LabelAssociationChat`, `LabelAssociationMessage` | | `CONTACT` | Atualizações de contatos | `Contact`, `PushName` | | `GROUP` | Eventos de grupos | `GroupInfo`, `JoinedGroup` | | `NEWSLETTER` | Eventos de canais/newsletters | `NewsletterJoin`, `NewsletterLeave` | | `QRCODE` | Eventos de QR Code | `QRCode`, `QRTimeout`, `QRSuccess` | Use `"ALL"` na lista de `subscribe` para receber todos os eventos sem precisar listar cada um individualmente. ## Estrutura do Payload Todos os webhooks são enviados como requisições `HTTP POST` com `Content-Type: application/json`. A estrutura base do payload é: ```json theme={null} { "event": "NomeDoEvento", "data": { ... }, "instanceId": "uuid-da-instancia", "instanceToken": "token_da_instancia" } ``` | Campo | Tipo | Descrição | | ------------- | ------ | ---------------------------------------------- | | event | string | Nome do evento que ocorreu | | data | object | Dados específicos do evento (varia por evento) | | instanceId | string | UUID da instância | | instanceToken | string | Token de autenticação da instância | *** ## Payloads por Evento ### QRCode Emitido quando um novo QR Code é gerado para pareamento. ```json theme={null} { "event": "QRCode", "data": { "code": "2@DoOPPlssTlSoDDdtPFXDXNp24ImY0bxwSivPLNbNLtCgXOYGFnsCN1Y64QYQB/r5tAmNqt0zhaf3TyOydXGZYGnKqB3UNTPDx1M=,...", "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEA..." }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` | Campo | Tipo | Descrição | | ----------- | ------ | --------------------------------- | | data.code | string | Código do QR Code para pareamento | | data.qrcode | string | Imagem do QR Code em base64 (PNG) | *** ### PairSuccess Emitido quando o pareamento do dispositivo é concluído com sucesso. ```json theme={null} { "event": "PairSuccess", "data": { "BusinessName": "", "ID": "5511918798714:5@s.whatsapp.net", "Platform": "android", "jid": "5511918798714:5@s.whatsapp.net", "pushName": "", "status": "open" }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` | Campo | Tipo | Descrição | | ----------------- | ------ | -------------------------------------------- | | data.BusinessName | string | Nome da empresa (para contas Business) | | data.ID | string | JID completo do dispositivo pareado | | data.Platform | string | Plataforma do dispositivo (`android`, `ios`) | | data.jid | string | JID do WhatsApp | | data.pushName | string | Nome de exibição do perfil | | data.status | string | Status da conexão (`open`) | *** ### Message Emitido quando uma mensagem é recebida. O payload varia conforme o tipo de mensagem. Todos os eventos de mensagem compartilham a mesma estrutura base em `data`, com o objeto `Info` contendo metadados e `Message` contendo o conteúdo. #### Campos comuns do objeto `Info` | Campo | Tipo | Descrição | | ----------------- | ------- | ------------------------------------------------------- | | Info.Chat | string | JID do chat (individual ou grupo) | | Info.Sender | string | JID do remetente | | Info.SenderAlt | string | JID alternativo do remetente (LID) | | Info.IsFromMe | boolean | `true` se a mensagem foi enviada pela própria instância | | Info.IsGroup | boolean | `true` se a mensagem é de um grupo | | Info.ID | string | ID único da mensagem | | Info.Type | string | Tipo da mensagem (`text`, `media`, etc.) | | Info.PushName | string | Nome de exibição do remetente | | Info.Timestamp | string | Data/hora da mensagem (ISO 8601) | | Info.MediaType | string | Tipo de mídia (`image`, `video`, `audio`, `document`) | | Info.VerifiedName | object | Informações do nome verificado (contas Business) | #### Campos comuns adicionais | Campo | Tipo | Descrição | | --------------------- | ------- | ------------------------------------------ | | IsEphemeral | boolean | Mensagem temporária | | IsViewOnce | boolean | Mensagem que pode ser vista apenas uma vez | | IsViewOnceV2 | boolean | Mensagem view once v2 | | IsViewOnceV2Extension | boolean | Extensão view once v2 | | IsDocumentWithCaption | boolean | Documento com legenda | | IsLottieSticker | boolean | Sticker animado Lottie | | IsEdit | boolean | Mensagem editada | #### Text ```json theme={null} { "event": "Message", "data": { "Info": { "Chat": "557499879409@s.whatsapp.net", "Sender": "557499879409:38@s.whatsapp.net", "SenderAlt": "123234343434@lid", "IsFromMe": false, "IsGroup": false, "ID": "3EB0C05FF2D3A0068B2A2D", "Type": "text", "PushName": "Davidson Gomes", "Timestamp": "2024-10-10T17:17:44-03:00", "MediaType": "", "VerifiedName": { "Certificate": { "details": "CJOzjf3Oh/LGQBIGc21iOndhIg5EYXZpZHNvbiBHb21lcw==", "signature": "KjXTl5LfeToLO6bFflbHyiBQe7a1zly4Wdhhf2XPU1Lq8tj9p03hvYUjbs+M0ChWBQhjy/NBq7+nYCKQlLP3Bw==" }, "Details": { "serial": 4651594154187643283, "issuer": "smb:wa", "verifiedName": "Davidson Gomes" } } }, "Message": { "conversation": "oi", "messageContextInfo": { "deviceListMetadata": { "senderKeyHash": "jS2BFebH+KJxzA==", "senderTimestamp": 1728407293 }, "deviceListMetadataVersion": 2 } }, "IsEphemeral": false, "IsViewOnce": false, "IsEdit": false }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` #### Image Quando `WEBHOOK_FILES=true` (padrão), o campo `base64` contém a imagem codificada. Caso contrário, `mediaUrl` apontará para o armazenamento MinIO/S3. ```json theme={null} { "event": "Message", "data": { "Info": { "Chat": "557499879409@s.whatsapp.net", "Sender": "557499879409:45@s.whatsapp.net", "IsFromMe": false, "IsGroup": false, "ID": "3EB0546D154AB4C90A11E1", "Type": "media", "PushName": "Davidson Gomes", "Timestamp": "2024-10-23T09:15:41-03:00", "MediaType": "image" }, "Message": { "imageMessage": { "url": "https://mmg.whatsapp.net/v/...", "mimetype": "image/jpeg", "fileSha256": "...", "fileLength": 82247, "height": 1600, "width": 1200, "mediaKey": "...", "fileEncSha256": "...", "directPath": "/v/...", "mediaKeyTimestamp": 1729685741, "scansSidecar": "...", "scanLengths": [20898], "midQualityFileSha256": "..." }, "base64": "/9j/4AAQSkZJRgABAQAAAQABAAD/..." }, "IsEphemeral": false, "IsViewOnce": false, "IsEdit": false }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` #### Video ```json theme={null} { "event": "Message", "data": { "Info": { "Chat": "557499879409@s.whatsapp.net", "Sender": "557499879409:45@s.whatsapp.net", "IsFromMe": false, "IsGroup": false, "ID": "3EB0A1B2C3D4E5F6071234", "Type": "media", "PushName": "Davidson Gomes", "Timestamp": "2024-10-23T09:20:00-03:00", "MediaType": "video" }, "Message": { "videoMessage": { "url": "https://mmg.whatsapp.net/v/...", "mimetype": "video/mp4", "fileSha256": "...", "fileLength": 1048576, "seconds": 15, "mediaKey": "...", "fileEncSha256": "...", "directPath": "/v/...", "mediaKeyTimestamp": 1729685741 }, "base64": "AAAAIGZ0eXBpc29tAAACAGlzb21pc28y..." }, "IsEphemeral": false, "IsViewOnce": false, "IsEdit": false }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` #### Audio ```json theme={null} { "event": "Message", "data": { "Info": { "Chat": "557499879409@s.whatsapp.net", "Sender": "557499879409:45@s.whatsapp.net", "IsFromMe": false, "IsGroup": false, "ID": "3EB0F1E2D3C4B5A6091234", "Type": "media", "PushName": "Davidson Gomes", "Timestamp": "2024-10-23T09:25:00-03:00", "MediaType": "audio" }, "Message": { "audioMessage": { "url": "https://mmg.whatsapp.net/v/...", "mimetype": "audio/ogg; codecs=opus", "fileSha256": "...", "fileLength": 25600, "seconds": 5, "ptt": true, "mediaKey": "...", "fileEncSha256": "...", "directPath": "/v/...", "mediaKeyTimestamp": 1729685741, "waveform": "AAAAAAAAAAAAAAAA..." }, "base64": "T2dnUwACAAAAAAAAAAA..." }, "IsEphemeral": false, "IsViewOnce": false, "IsEdit": false }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` #### Document ```json theme={null} { "event": "Message", "data": { "Info": { "Chat": "557499879409@s.whatsapp.net", "Sender": "557499879409:45@s.whatsapp.net", "IsFromMe": false, "IsGroup": false, "ID": "3EB0D1C2B3A4E5F6071234", "Type": "media", "PushName": "Davidson Gomes", "Timestamp": "2024-10-23T09:30:00-03:00", "MediaType": "document" }, "Message": { "documentMessage": { "url": "https://mmg.whatsapp.net/v/...", "mimetype": "application/pdf", "title": "documento.pdf", "fileSha256": "...", "fileLength": 512000, "fileName": "documento.pdf", "mediaKey": "...", "fileEncSha256": "...", "directPath": "/v/...", "mediaKeyTimestamp": 1729685741 }, "base64": "JVBERi0xLjQKJeLj..." }, "IsDocumentWithCaption": false, "IsEphemeral": false, "IsViewOnce": false, "IsEdit": false }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` Quando `WEBHOOK_FILES=true` (padrão), mensagens com mídia incluem o conteúdo do arquivo como `base64` dentro do objeto `Message`. Se o MinIO/S3 estiver configurado, o campo `mediaUrl` será adicionado em vez do `base64`. *** ### Receipt Emitido para confirmações de leitura e entrega. O campo `state` no nível raiz indica o tipo: `Read`, `ReadSelf` ou `Delivered`. ```json theme={null} { "event": "Receipt", "state": "Read", "data": { "Chat": "557499879409@s.whatsapp.net", "Sender": "5511918798714:5@s.whatsapp.net", "IsFromMe": false, "IsGroup": false, "MessageIDs": ["3EB0C05FF2D3A0068B2A2D"], "Timestamp": "2024-10-10T17:18:00-03:00", "Type": "read" }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` | Campo | Tipo | Descrição | | --------------- | --------- | ---------------------------------------------------- | | state | string | Tipo de confirmação: `Read`, `ReadSelf`, `Delivered` | | data.Chat | string | JID do chat | | data.Sender | string | JID do remetente | | data.MessageIDs | string\[] | Lista de IDs das mensagens confirmadas | | data.Timestamp | string | Data/hora da confirmação (ISO 8601) | *** ### Connected Emitido quando a instância se conecta ao WhatsApp com sucesso. ```json theme={null} { "event": "Connected", "data": { "status": "open", "jid": "5511918798714:5@s.whatsapp.net", "pushName": "Davidson Gomes" }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` *** ### LoggedOut Emitido quando a instância é desconectada do WhatsApp. ```json theme={null} { "event": "LoggedOut", "data": { "Reason": "logged_out" }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` *** ### OfflineSyncCompleted Emitido quando a sincronização offline de mensagens é concluída após a reconexão. ```json theme={null} { "event": "OfflineSyncCompleted", "data": { "Count": 42 }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` | Campo | Tipo | Descrição | | ---------- | ---- | ----------------------------------------- | | data.Count | int | Número de mensagens sincronizadas offline | *** ### CallOffer Emitido quando uma chamada é recebida. ```json theme={null} { "event": "CallOffer", "data": { "From": "557499879409@s.whatsapp.net", "Timestamp": "2024-10-10T17:20:00-03:00", "CallCreator": "557499879409@s.whatsapp.net", "CallID": "A1B2C3D4E5F6", "RemotePlatform": "android", "RemoteVersion": "2.24.10.12" }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` | Campo | Tipo | Descrição | | ------------------- | ------ | ----------------------------------------- | | data.From | string | JID de quem está ligando | | data.Timestamp | string | Data/hora da chamada (ISO 8601) | | data.CallCreator | string | JID do criador da chamada | | data.CallID | string | ID único da chamada | | data.RemotePlatform | string | Plataforma do chamador (`android`, `ios`) | | data.RemoteVersion | string | Versão do WhatsApp do chamador | *** ### CallRelayLatency Emitido com informações de latência durante uma chamada em andamento. ```json theme={null} { "event": "CallRelayLatency", "data": { "From": "557499879409@s.whatsapp.net", "Timestamp": "2024-10-10T17:20:05-03:00", "CallCreator": "557499879409@s.whatsapp.net", "CallID": "A1B2C3D4E5F6" }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` *** ### CallTerminate Emitido quando uma chamada é encerrada. ```json theme={null} { "event": "CallTerminate", "data": { "From": "557499879409@s.whatsapp.net", "Timestamp": "2024-10-10T17:21:00-03:00", "CallCreator": "557499879409@s.whatsapp.net", "CallID": "A1B2C3D4E5F6", "Reason": "busy" }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` | Campo | Tipo | Descrição | | ----------- | ------ | ------------------------------------------------ | | data.Reason | string | Motivo do encerramento (`busy`, `timeout`, etc.) | *** ### JoinedGroup Emitido quando a instância entra em um grupo. ```json theme={null} { "event": "JoinedGroup", "data": { "Reason": "invite", "JID": "120363012345678901@g.us", "GroupName": { "Name": "Equipe Evolution", "NameSetAt": "2024-10-01T10:00:00-03:00" }, "GroupCreated": "2024-10-01T10:00:00-03:00", "Participants": [ { "JID": "5511918798714@s.whatsapp.net", "IsAdmin": true, "IsSuperAdmin": true } ] }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` | Campo | Tipo | Descrição | | ----------------- | ------ | ---------------------------------- | | data.Reason | string | Motivo da entrada (`invite`, etc.) | | data.JID | string | JID do grupo | | data.GroupName | object | Informações do nome do grupo | | data.Participants | array | Lista de participantes com roles | *** ### GroupInfo Emitido quando informações de um grupo são atualizadas (nome, descrição, participantes, etc.). ```json theme={null} { "event": "GroupInfo", "data": { "JID": "120363012345678901@g.us", "Sender": "557499879409@s.whatsapp.net", "Timestamp": "2024-10-10T17:25:00-03:00", "Name": { "Name": "Equipe Evolution - Novo Nome", "NameSetAt": "2024-10-10T17:25:00-03:00", "NameSetBy": "557499879409@s.whatsapp.net" }, "Join": [], "Leave": [], "Promote": [], "Demote": [] }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } ``` | Campo | Tipo | Descrição | | -------------- | ------ | -------------------------------------- | | data.JID | string | JID do grupo | | data.Sender | string | JID de quem fez a alteração | | data.Timestamp | string | Data/hora da alteração (ISO 8601) | | data.Name | object | Novo nome do grupo (se alterado) | | data.Topic | object | Nova descrição do grupo (se alterada) | | data.Join | array | JIDs de usuários que entraram no grupo | | data.Leave | array | JIDs de usuários que saíram do grupo | | data.Promote | array | JIDs de usuários promovidos a admin | | data.Demote | array | JIDs de usuários rebaixados de admin | *** ### NewsletterJoin Emitido quando a instância entra em um canal/newsletter. ```json theme={null} { "event": "NewsletterJoin", "data": { "id": "120363123456789012@newsletter", "state": { "type": "ACTIVE" }, "thread_metadata": { "creation_time": "1696118400", "invite": "ABC123DEF456", "name": { "text": "Evolution Go News", "id": "1234567890" }, "description": { "text": "Canal oficial do Evolution Go" }, "subscribers_count": 1500, "verification": "VERIFIED", "picture": { "url": "https://pps.whatsapp.net/v/..." } }, "viewer_metadata": { "mute": "OFF", "role": "SUBSCRIBER" } }, "instanceId": "249aad2e-68f9-464f-bc84-aca560c38f0e", "instanceToken": "2ef79c34-b6e1-4969-9e37-12b3d3a9d1062" } --- ## Política de Retentativas O Evolution Go possui um sistema automático de retentativas para garantir a entrega dos webhooks: | Configuração | Valor | | -------------------------- | ------------------ | | Máximo de tentativas | **5** | | Intervalo entre tentativas | **30 segundos** | | Método HTTP | `POST` | | Content-Type | `application/json` | | Resposta esperada | Status HTTP `2xx` | Se todas as 5 tentativas falharem, o evento é descartado e um log de erro é registrado. Certifique-se de que seu endpoint de webhook responda com status HTTP `2xx` (200-299) para confirmar o recebimento. Qualquer resposta fora dessa faixa será tratada como falha e acionará uma nova tentativa. ## Canais de Entrega Alternativos Além de webhooks HTTP, o Evolution Go suporta outros canais de entrega de eventos: Envio via filas AMQP. Configure com `rabbitmqEnable: "enabled"` na conexão da instância e as variáveis `AMQP_URL`, `AMQP_GLOBAL_ENABLED` e `AMQP_GLOBAL_EVENTS`. Envio via NATS messaging. Configure com `natsEnable: "enabled"` na conexão e as variáveis `NATS_URL`, `NATS_GLOBAL_ENABLED` e `NATS_GLOBAL_EVENTS`. Receba eventos em tempo real via WebSocket. Configure com `websocketEnable: "enabled"` na conexão da instância. Múltiplos canais podem ser ativados simultaneamente. Por exemplo, você pode receber eventos via webhook HTTP **e** RabbitMQ ao mesmo tempo. ## Variáveis de Ambiente Todas as variáveis de ambiente relacionadas a eventos e webhooks: | Variável | Descrição | Padrão | | ----------------------- | ------------------------------------------------------ | ------- | | `WEBHOOK_URL` | URL do webhook global | - | | `WEBHOOK_FILES` | Incluir arquivos de mídia nos payloads | `true` | | `AMQP_URL` | URL de conexão do RabbitMQ | - | | `AMQP_GLOBAL_ENABLED` | Ativar filas globais RabbitMQ | `false` | | `AMQP_GLOBAL_EVENTS` | Eventos para filas globais (separados por vírgula) | - | | `AMQP_SPECIFIC_EVENTS` | Eventos para filas específicas (separados por vírgula) | - | | `NATS_URL` | URL de conexão do NATS | - | | `NATS_GLOBAL_ENABLED` | Ativar NATS global | `false` | | `NATS_GLOBAL_EVENTS` | Eventos para NATS global (separados por vírgula) | - | | `EVENT_IGNORE_GROUP` | Ignorar eventos de grupos | `false` | | `EVENT_IGNORE_STATUS` | Ignorar eventos de status/stories | `false` | ``` # Documentação Evolution Foundation Source: https://docs.evolutionfoundation.com.br/index Bem-vindo(a) à documentação oficial da Evolution Foundation — Ecossistema para Growth com IA. Aqui você encontra guias práticos, detalhes dos produtos e a referência completa das APIs. ## Sobre a Evolution Foundation A **Evolution Foundation** desenvolve infraestrutura open-source para **engajamento de clientes e growth com IA**. Construímos as ferramentas que empresas usam para gerenciar conversas, automatizar marketing, executar agentes inteligentes e orquestrar operações em múltiplos canais — com controle total dos dados e infraestrutura. Todo o nosso software é open-source sob a licença Apache 2.0. ## Principais Seções Plataforma completa de CRM, automação de campanhas e agentes de IA — multi-canal e self-hosted. APIs e serviços para WhatsApp e mensageria multi-canal — Node.js e Go. Camada multi-agente para operação e desenvolvimento — 38 agentes especializados orquestrados via Claude Code. Documentação técnica completa de todas as APIs REST disponíveis. ## Recursos | Recurso | Link | | ------------ | ------------------------------------------------------------------------------------ | | Site oficial | [evolutionfoundation.com.br](https://evolutionfoundation.com.br) | | Comunidade | [evolutionfoundation.com.br/community](https://evolutionfoundation.com.br/community) | | GitHub | [github.com/evolution-foundation](https://github.com/evolution-foundation) | | Suporte | [suporte@evofoundation.com.br](mailto:suporte@evofoundation.com.br) | # VPS HostGator + Evo CRM Source: https://docs.evolutionfoundation.com.br/infraestrutura/hostgator-evo-crm O futuro do atendimento com IA — Servidor VPS HostGator com Evo CRM pré-instalado ## O futuro do atendimento com IA já chegou Crie agentes inteligentes, automatize seu atendimento no WhatsApp com a API oficial e escale seus resultados nos seus principais canais de venda — com o **Evo CRM pré-instalado** no seu servidor VPS HostGator. **A partir de R\$ 45,49/mês** — Evo CRM pré-instalado, provisionamento instantâneo e 30 dias para reembolso. ## Por que escolher VPS HostGator com Evo CRM? ### Automação com IA que vende de verdade Agentes inteligentes respondem continuamente nos seus canais de venda, sem parar. Configure uma vez e deixe a IA trabalhar por você. ### Atendimento multicanal unificado Centralize WhatsApp, Instagram, Telegram e outros canais em uma única plataforma, com histórico completo e contexto para cada conversa. ### Sem conhecimento técnico necessário Interface simples e intuitiva, sem necessidade de programação. O Evo CRM já vem pré-instalado e pronto para usar logo após a contratação. ## Planos disponíveis Os planos do Evo CRM começam no **VPS NVMe 8** para garantir a performance adequada para a plataforma. Você pode parcelar em até **12x no cartão**. | Plano | vCPU | RAM | Armazenamento | Preço inicial | | -------------- | ---- | ---------- | ------------- | ------------- | | VPS NVMe 8 ⭐ | 4 | 8 GB DDR5 | 200 GB NVMe | R\$ 45,49/mês | | VPS NVMe 12 | 4 | 12 GB DDR5 | 300 GB NVMe | Consultar | | VPS NVMe 16 | 6 | 16 GB DDR5 | 400 GB NVMe | Consultar | | VPS NVMe 32 🏆 | 8 | 32 GB DDR5 | 500 GB NVMe | Consultar | ⭐ **VPS NVMe 8** é o plano recomendado para começar. 🏆 **VPS NVMe 32** é ideal para operações de alto volume com múltiplas equipes. ## O que está incluso em todos os planos Pronto para usar imediatamente após a contratação. Sem necessidade de configuração manual da aplicação ou instalação de dependências. Processadores **AMD Epyc**, memória **RAM DDR5** e discos **NVMe** de alta performance. Servidores Cloud localizados no **Brasil**. **Transferência de dados ilimitada**, **1 IP dedicado** por plano, **acesso root** completo e **segurança reforçada**. **Suporte especializado com fila prioritária** para clientes Evolution. **Migração grátis** do seu projeto atual. **Provisionamento instantâneo**. ## Principais funcionalidades do Evo CRM Crie agentes inteligentes que respondem automaticamente 24 horas nos seus canais de venda Acompanhe e gerencie leads em um funil de vendas visual com automações integradas WhatsApp, Instagram, Telegram e mais — tudo em uma única caixa de entrada Respostas em áudio natural geradas por IA para interações mais humanas Conecte com mais de 20 plataformas e ferramentas do seu ecossistema IA responde automaticamente; humanos assumem quando necessário com contexto completo ## Perguntas frequentes É uma plataforma de atendimento com IA que automatiza conversas no WhatsApp e outros canais. Permite criar agentes inteligentes, gerenciar leads e centralizar toda a comunicação com clientes em um único lugar. Não. O Evo CRM tem uma interface simples e intuitiva, sem necessidade de programação. O servidor já vem com tudo pré-instalado. Não. O Evo CRM integra WhatsApp, Instagram, Telegram e outros canais em uma plataforma unificada. Sim. O Evo CRM suporta atendimento híbrido: a IA responde automaticamente e, quando necessário, um humano pode assumir a conversa com contexto completo do histórico. O Evo CRM é uma plataforma completa com múltiplos serviços rodando simultaneamente (CRM, Auth, Frontend, Processor e Core). O VPS NVMe 8 garante recursos suficientes para uma operação estável e performática. ## Comece agora Aproveite — servidores VPS com até 73% OFF por tempo limitado. Evo CRM pré-instalado, provisionamento instantâneo e 30 dias para reembolso. # Comprar e ativar o Evolution Go Source: https://docs.evolutionfoundation.com.br/infraestrutura/hostgator-evogo-ativacao Passo a passo completo para contratar o VPS HostGator com Evolution Go pré-instalado e ativar suas credenciais de acesso ## Passo a passo completo Este guia cobre todo o processo: desde a escolha do plano na HostGator até a ativação das credenciais do Evolution Go no seu servidor. Clique no botão abaixo para ser direcionado à página de planos da HostGator com o Evolution Go pré-instalado. Aproveite — servidores VPS com até 73% OFF por tempo limitado. Provisionamento instantâneo e 30 dias para reembolso. Na página de planos, selecione a configuração ideal para o seu projeto. O Evolution Go já vem **pré-instalado e incluso gratuitamente** em todos os planos. | Plano | vCPU | RAM | Armazenamento | Instâncias WhatsApp | Preço | | ------------- | ---- | --------- | ------------- | ------------------- | ------------- | | VPS NVMe 2 | 1 | 2 GB DDR5 | 50 GB NVMe | Até 150 | R\$ 19,99/mês | | VPS NVMe 4 ⭐ | 2 | 4 GB DDR5 | 100 GB NVMe | Até 350 | R\$ 28,49/mês | | VPS NVMe 8 🏆 | 4 | 8 GB DDR5 | 200 GB NVMe | Até 700 | R\$ 45,49/mês | ⭐ **VPS NVMe 4** é o plano mais popular. 🏆 **VPS NVMe 8** é o recomendado para a maioria dos projetos. Você pode parcelar em até **12x no cartão**. Página de seleção de planos VPS com Evolution Go pré-instalado e preços Clique em **Escolher plano** para continuar. Após escolher o plano, confira o resumo do pedido. Verifique que o item **Evolution GO** aparece como **Grátis** — isso confirma que ele está corretamente incluído. Você também pode ajustar o **ciclo de pagamento** (mensal, anual ou 3 anos) para obter o maior desconto disponível. Carrinho com VPS NVMe selecionado e Evolution GO incluído gratuitamente Quando estiver pronto, clique em **Continuar para identificação**. Na etapa de **Identificação**, crie uma conta HostGator ou faça login se já for cliente. Para criar sua conta, preencha: * **E-mail pessoal** — será usado para acessar o portal do cliente * **Celular** — para notificações e suporte * **Senha** — escolha uma senha forte Você também pode usar o **Continue com Google** para agilizar o cadastro. Formulário de criação de conta HostGator com campos de e-mail, celular e senha Clique em **Criar conta** para avançar para o pagamento. Escolha a forma de pagamento: * **Cartão de crédito** — parcelamento em até 12x * **Pix** — pagamento instantâneo * **Boleto** — compensação em até 3 dias úteis Após o pagamento ser aprovado, você verá a tela de confirmação com a mensagem **"Compra finalizada com sucesso!"**. Tela de confirmação de compra com mensagem de sucesso e botão para acessar o portal Clique em **Acessar o portal do cliente** para continuar. Em instantes, a HostGator enviará um e-mail com o assunto **"Dados de acesso ao seu VPS"** contendo: * Link para o **Portal do Cliente** * Seu **Token de acesso** ao Evolution Go O **Token** exibido no e-mail é a sua **Global API Key** do Evolution Go. Ele será necessário para autenticar todas as requisições à API. Não compartilhe este token. E-mail da HostGator com dados de acesso ao VPS e token do Evolution Go em destaque No **Portal do Cliente**, clique em **Hospedagens e Servidores** no menu lateral esquerdo. Menu lateral do portal HostGator com 'Hospedagens e Servidores' destacado Seu VPS aparecerá inicialmente com o status **Em Configuração** — isso é normal e leva alguns minutos. VPS OCI NVMe 2 com status 'Em Configuração' e aviso de aguardar Quando o servidor estiver pronto, o status mudará para **Ativo** (indicador verde). Clique em **GERENCIAR** para acessar o painel do seu servidor. VPS OCI NVMe 2 com status 'Ativo' e botão Gerenciar disponível No painel de gerenciamento você encontrará tudo o que precisa para acessar o servidor. **Informações da VPS:** * **IP atribuído** — endereço do seu servidor * **Localização** — São Paulo, Brasil * Processador, Memória RAM e Armazenamento **Acesso SSH** (painel lateral direito): * **IP** — mesmo IP atribuído * **Porta** — `22022` * **Usuário** — `root` * **Senha** — clique em **Alterar senha** para definir a sua **Gerenciamento:** * **SO e aplicações** — AlmaLinux 9 * **Evolution Go** — clique para ver detalhes da aplicação Painel VPS com IP, porta SSH 22022 e usuário root exibidos Anote o **IP**, a **Porta SSH** (`22022`) e o **Token** recebido por e-mail. Esses três dados são necessários para configurar qualquer integração com o Evolution Go. No painel do VPS, clique no card **Evolution Go** dentro da seção **Gerenciamento**. Você será redirecionado para a tela de login do Evolution GO Manager. Preencha os campos com as informações do seu servidor: * **URL da API Evolution GO** — `http://SEU_IP:8080` (substitua pelo IP exibido no painel) * **API Key (GLOBAL\_API\_KEY)** — o Token recebido no e-mail da HostGator Tela de login do Evolution GO Manager com campos de URL da API e API Key Clique em **Entrar** para acessar o painel do Evolution Go. Siga o guia de Configuração Inicial para criar sua primeira instância e conectar seu número de WhatsApp. ## Resumo das credenciais Após concluir o processo, você terá em mãos: | Informação | Onde encontrar | | ------------------- | --------------------------------------------------------------- | | **IP do servidor** | Painel HostGator → Gerenciar VPS → IP atribuído | | **Porta SSH** | Painel HostGator → Gerenciar VPS → Acesso SSH → Porta (`22022`) | | **Usuário SSH** | `root` | | **Token / API Key** | E-mail "Dados de acesso ao seu VPS" → campo Token | ## Próximos passos Com o servidor ativo e as credenciais em mãos, você está pronto para conectar seus números de WhatsApp. Aprenda a criar instâncias, conectar números e configurar webhooks. Veja os planos disponíveis e compare com o Evolution API. # VPS HostGator + Evolution API Source: https://docs.evolutionfoundation.com.br/infraestrutura/hostgator-evolution-api Automatize, integre e escale seu WhatsApp — Servidor VPS HostGator com Evolution API pré-instalada ## Automatize, integre e escale seu WhatsApp com Evolution API Integre seus sistemas ao WhatsApp Business, automatize interações e crie fluxos inteligentes para ganhar escala e eficiência — com a **Evolution API pré-instalada** no seu servidor VPS HostGator. **A partir de R\$ 19,99/mês** — Evolution API pré-instalada, provisionamento instantâneo e 30 dias para reembolso. ## Por que escolher VPS HostGator com Evolution API? ### Implantação rápida Crie automações e integrações com mais agilidade, **sem precisar configurar a infraestrutura do zero**. Seu servidor já vem com a Evolution API pronta para usar. ### Integrações nativas Integre automações, IA, chatbots e sistemas de atendimento criando **fluxos inteligentes no WhatsApp**. Compatível com Typebot, Chatwoot, OpenAI, Dify, N8N e Flowise. ### Automação 24 horas Mantenha atendimentos e notificações funcionando **sem intervenção manual**. Transforme o WhatsApp em um canal automatizado de comunicação. ## Planos disponíveis ### Desempenho padrão | Plano | vCPU | RAM | Armazenamento | Instâncias WhatsApp | Preço inicial | | ------------- | ---- | --------- | ------------- | ------------------- | ------------- | | VPS NVMe 2 | 1 | 2 GB DDR5 | 50 GB NVMe | Até 20 | R\$ 19,99/mês | | VPS NVMe 4 ⭐ | 2 | 4 GB DDR5 | 100 GB NVMe | Até 50 | Consultar | | VPS NVMe 8 🏆 | 4 | 8 GB DDR5 | 200 GB NVMe | Até 100 | Consultar | ### Alto desempenho | Plano | vCPU | RAM | Armazenamento | Instâncias WhatsApp | Preço inicial | | ----------- | ---- | ---------- | ------------- | ------------------- | ------------- | | VPS NVMe 12 | 4 | 12 GB DDR5 | 300 GB NVMe | Consultar | Consultar | | VPS NVMe 16 | 6 | 16 GB DDR5 | 400 GB NVMe | Consultar | Consultar | ⭐ **VPS NVMe 4** é o plano mais popular. 🏆 **VPS NVMe 8** é o recomendado para a maioria dos projetos. Você pode parcelar em até **12x no cartão**. ## O que está incluso em todos os planos Pronta para usar imediatamente após a contratação. Sem necessidade de configuração manual. Suporte a Baileys (WhatsApp Web) e API oficial Meta (WhatsApp Cloud API). Processadores **AMD Epyc**, memória **RAM DDR5** e discos **NVMe** de alta performance. Servidores Cloud localizados no **Brasil**. **Transferência de dados ilimitada**, **1 IP dedicado** por plano, **acesso root** completo e **segurança reforçada**. **Suporte especializado com fila prioritária** para clientes Evolution. **Migração grátis** do seu projeto atual. **Provisionamento instantâneo**. ## Evolution API vs Evolution Go | Critério | Evolution API ✅ | Evolution Go | | -------------------- | ------------------------------------------- | ----------------------------------- | | **Conexão WhatsApp** | WhatsApp Web + API oficial Meta | Apenas WhatsApp Web | | **Integrações** | Nativas (Typebot, Chatwoot, OpenAI, N8N) | Via Webhooks e APIs externas | | **Implementação** | Rápida, com integrações prontas | Requer configuração de integrações | | **Ideal para** | Automações, chatbots, fluxos personalizados | Alta escala e operações SaaS | | **Arquitetura** | Completa e pronta para uso | Foco em performance e baixo consumo | **Precisa de alta escala?** Se seu projeto demanda mais de 50 instâncias ou alto volume de eventos simultâneos, considere o [VPS HostGator + Evolution Go](/infraestrutura/hostgator-evolution-go). ## Casos de uso * **Chatbots e IA** — Conecte bots, IA e assistentes virtuais com facilidade * **Fluxos de atendimento** — Crie fluxos inteligentes com Typebot e Chatwoot * **Notificações automáticas** — Dispare alertas e comunicações em escala * **Integração com CRM/ERP** — Centralize comunicação em uma única plataforma * **Automação de processos** — Transforme o WhatsApp em canal automatizado * **Workflows entre sistemas** — Conecte N8N, Flowise e outros orquestradores ## Perguntas frequentes É uma solução que permite conectar ferramentas e aplicações ao WhatsApp Business para enviar, receber e automatizar mensagens. Com ela é possível desenvolver integrações, criar fluxos e transformar o WhatsApp em um canal automatizado de comunicação. Para automatizar interações no WhatsApp, integrar com sistemas e criar chatbots, notificações automáticas, fluxos de atendimento e processos de comunicação em escala. Sim. A Evolution API é voltada para desenvolvedores ou equipes técnicas, sendo necessário conhecimento básico de APIs e integrações. Evolution API integra-se com a API oficial do WhatsApp e oferece integrações nativas com ferramentas como Typebot e Chatwoot, sendo ideal para automações e chatbots. Evolution Go oferece alta performance e menor consumo de recursos, ideal para alta escala e SaaS. ## Comece agora Aproveite — servidores VPS com até 73% OFF por tempo limitado. Provisionamento instantâneo e 30 dias para reembolso. # VPS HostGator + Evolution Go Source: https://docs.evolutionfoundation.com.br/infraestrutura/hostgator-evolution-go API de WhatsApp 10x mais potente e 90% menos custo — Servidor VPS HostGator com Evolution Go pré-instalado ## API de WhatsApp 10x mais potente e 90% menos custo Rode até **500 instâncias de WhatsApp em um único container** com o servidor VPS HostGator + Evolution Go pré-instalado e pronto para usar. **A partir de R\$ 21,69/mês** — Evolution Go pré-instalado, provisionamento instantâneo e 30 dias para reembolso. ## Por que escolher VPS HostGator com Evolution Go? ### API de WhatsApp de alta performance Envie e receba mensagens automaticamente com uma API rápida e estável, construída em Golang para máxima performance e uso mínimo de recursos. ### Escalável para múltiplas instâncias Gerencie vários números de WhatsApp e aumente conforme seu projeto cresce. Até **500 instâncias por container**, ideal para operações SaaS e alto volume. ### Automação 24 horas Mantenha atendimentos, notificações e automações funcionando continuamente, sem intervenção manual. ## Planos disponíveis ### Desempenho padrão | Plano | vCPU | RAM | Armazenamento | Instâncias WhatsApp | Preço inicial | | ------------- | ---- | --------- | ------------- | ------------------- | ------------- | | VPS NVMe 2 | 1 | 2 GB DDR5 | 50 GB NVMe | Até 150 | R\$ 21,69/mês | | VPS NVMe 4 ⭐ | 2 | 4 GB DDR5 | 100 GB NVMe | Até 350 | Consultar | | VPS NVMe 8 🏆 | 4 | 8 GB DDR5 | 200 GB NVMe | Até 700 | Consultar | ### Alto desempenho | Plano | vCPU | RAM | Armazenamento | Instâncias WhatsApp | Preço inicial | | ----------- | ---- | ---------- | ------------- | ------------------- | ------------- | | VPS NVMe 12 | 4 | 12 GB DDR5 | 300 GB NVMe | Até 1.000 | Consultar | | VPS NVMe 16 | 6 | 16 GB DDR5 | 400 GB NVMe | Até 1.400 | Consultar | | VPS NVMe 32 | 8 | 32 GB DDR5 | 500 GB NVMe | Até 2.800 | Consultar | ⭐ **VPS NVMe 4** é o plano mais popular. 🏆 **VPS NVMe 8** é o recomendado para a maioria dos projetos. Você pode parcelar em até **12x no cartão**. ## O que está incluso em todos os planos Pronto para usar imediatamente após a contratação. Sem necessidade de configuração manual da aplicação. Processadores **AMD Epyc**, memória **RAM DDR5** e discos **NVMe** de alta performance. Servidores Cloud localizados no **Brasil**. **Transferência de dados ilimitada**, **1 IP dedicado** por plano, **acesso root** completo e **segurança reforçada**. **Suporte especializado com fila prioritária** para clientes Evolution. **Migração grátis** do seu projeto atual. **Provisionamento instantâneo**. ## Evolution Go vs Evolution API | Critério | Evolution Go ✅ | Evolution API | | --------------------------- | ----------------- | ---------------------------------- | | **Custo de infraestrutura** | Até 10x menor | Maior consumo de recursos | | **Instâncias por servidor** | Até 500 números | Até 50 números | | **Performance** | Alta (Golang) | Moderada (Node.js) | | **Ideal para** | Alto volume, SaaS | Automações com integrações nativas | | **Eventos simultâneos** | Processa milhares | Centenas | ## Casos de uso * **Automação de mensagens** — Envio e recebimento automatizado 24h * **Chatbots e IA** — Integração com assistentes virtuais * **Notificações e alertas** — Disparos automáticos para clientes * **Workflows entre sistemas** — Conexão via Webhooks e APIs * **Integração com CRMs/ERPs** — Centralização de comunicação * **Monitoramento em tempo real** — Acompanhamento de eventos via WebSocket ## Perguntas frequentes É uma API desenvolvida em Golang para integrar WhatsApp via requisições HTTP. Oferece alta performance e baixo consumo de recursos, sendo ideal para projetos que precisam gerenciar múltiplas instâncias. Sim. Um servidor VPS é necessário para manter a conexão ativa e as automações funcionando continuamente, 24 horas por dia. Sim. Você pode conectar múltiplos números de WhatsApp independentes no mesmo servidor, com até 500 instâncias por container. Evolution Go oferece alta performance e menor consumo de recursos, ideal para alta escala e SaaS. Evolution API integra-se com a API oficial do WhatsApp e oferece integrações nativas, sendo adequada para ambientes empresariais e automações com chatbots. ## Comece agora Aproveite — servidores VPS com até 73% OFF por tempo limitado. Provisionamento instantâneo e 30 dias para reembolso. # Hospedagem HostGator Source: https://docs.evolutionfoundation.com.br/infraestrutura/index Servidores VPS HostGator com Evolution API e Evolution Go pré-instalados — potência máxima com preço mínimo ## Potência máxima com preço mínimo A **HostGator** é a parceira oficial de hospedagem do ecossistema Evolution, oferecendo servidores VPS com **Evolution API** e **Evolution Go pré-instalados e prontos para usar** — sem precisar configurar infraestrutura do zero. Junte-se a mais de **7 milhões de clientes no mundo**. Conte com uma plataforma comprometida com o sucesso do seu projeto. ## Por que HostGator? * **Provisionamento instantâneo** — Seu servidor fica pronto em minutos, não em horas * **Servidores Cloud no Brasil** — Baixa latência para seus clientes * **Processadores AMD Epyc + RAM DDR5 + Discos NVMe** — Hardware de última geração * **Suporte especializado com fila prioritária** — Atendimento diferenciado para Evolution * **Migração grátis** — Traga seu projeto sem custo adicional * **30 dias para reembolso** — Garantia total de satisfação ## Escolha a solução ideal para seu projeto **Atendimento com IA pré-configurado.** Agentes inteligentes, funil de vendas e multicanal prontos para usar. A partir de R\$ 45,49/mês. **API 10x mais potente, 90% menos custo.** Rode até 500 instâncias por container. Ideal para alto volume e SaaS. A partir de R\$ 21,69/mês. **Automatize, integre e escale seu WhatsApp.** Integrações nativas com Typebot, Chatwoot, OpenAI e mais. Ideal para automações e chatbots. A partir de R\$ 19,99/mês. ## Evolution Go vs Evolution API — Qual escolher? | Critério | Evolution Go | Evolution API | | --------------------------- | ------------------------------ | ------------------------------------------- | | **Linguagem** | Golang (alta performance) | Node.js + TypeScript | | **Instâncias por servidor** | Até 500 números | Até 50 números | | **Conexão WhatsApp** | WhatsApp Web | WhatsApp Web + API oficial Meta | | **Integrações** | Via Webhooks e APIs externas | Nativas (Typebot, Chatwoot, OpenAI, N8N) | | **Consumo de recursos** | Baixo | Moderado | | **Ideal para** | Alta escala, SaaS, alto volume | Automações, chatbots, fluxos personalizados | ## Casos de uso Envie e receba mensagens automaticamente 24 horas por dia Integre bots, IA e assistentes virtuais ao WhatsApp Dispare notificações automáticas para seus clientes Conecte WhatsApp ao seu CRM, ERP e outros sistemas Centralize comunicação com clientes em uma única plataforma Acompanhe eventos e métricas em tempo real via WebSocket # Fluxo de Ativação Source: https://docs.evolutionfoundation.com.br/licensing/activation Como sua instância da Evolution registra uma licença gratuita — endpoints, polling, autenticação HMAC e ciclo de vida. Para deploys após o primeiro registro do mesmo e-mail, você pode pular o navegador e usar a [ativação automática por e-mail](/licensing/auto-activation) — uma única chamada de API. O fluxo abaixo continua sendo necessário no **primeiro** registro de um e-mail. ## Visão geral do fluxo Diagrama do fluxo de ativação manual: instância chama register/init, exibe URL, operador autentica no navegador, instância faz polling, recebe api_key, ativa via HMAC e segue com heartbeats. A URL base do servidor é definida na variável `LICENSE_BASE_URL` do `.env` do produto (padrão: `https://license.evolutionfoundation.com.br`). *** ## Passo 1 — Iniciar registro Quando a instância detecta que não há `api_key` salva localmente, ela chama: ```http theme={null} POST /v1/register/init Content-Type: application/json { "tier": "community", "version": "2.4.0", "instance_id": "550e8400-e29b-41d4-a716-446655440000" } ``` **Campos:** | Campo | Tipo | Descrição | | ------------- | ------- | -------------------------------------------------------------- | | `tier` | string | `community` ou `beta` | | `version` | string | Versão do produto Evolution (ex.: `2.4.0`) | | `instance_id` | UUID v4 | Identificador local da instância — gerado uma vez e persistido | **Resposta (200):** ```json theme={null} { "register_url": "https://license.evolutionfoundation.com.br/register?token=abc123def456...", "token": "abc123def456..." } ``` O `token` expira em **30 minutos**. Há rate limit de **10 inits por hora por IP**. Se o operador não concluir a ativação no prazo, basta repetir o passo 1. **Erros possíveis:** | HTTP | Code | Significado | | ---- | -------------- | --------------------------------- | | 400 | `INVALID_TIER` | tier não é `community` nem `beta` | | 400 | `INVALID_BODY` | JSON malformado | | 429 | `RATE_LIMIT` | excedeu 10 inits/hora | *** ## Passo 2 — Exibir a URL ao operador A instância exibe o `register_url` ao operador. Padrões aceitos: * **Web UI / Manager** — botão "Ativar Licença" abre o link no navegador * **Terminal / CLI** — imprime a URL e fica aguardando * **QR Code** — em deployments headless, gera um QR para escanear Exemplo de output em CLI: ``` ───────────────────────────────────────────────────────────────── Ativação de licença Evolution API ───────────────────────────────────────────────────────────────── Para ativar, abra no navegador: https://license.evolutionfoundation.com.br/register?token=abc123def... Aguardando confirmação... (expira em 30 minutos) ───────────────────────────────────────────────────────────────── ``` *** ## Passo 3 — O que acontece no navegador O servidor de licença renderiza a página de registro com a identidade visual da Evolution. O operador escolhe entre: * **Magic Link** — informa nome e e-mail, recebe link de confirmação por e-mail * **Google OAuth** — login com conta Google * **GitHub OAuth** — login com conta GitHub Após autenticar, o servidor cria (ou recupera) o customer e gera um `authorization_code` interno. Esse fluxo é transparente para a instância — ela só precisa fazer polling. *** ## Passo 4 — Polling do status Enquanto o operador resolve o login, a instância faz polling: ```http theme={null} GET /v1/register/status?token=abc123def456... ``` **Resposta enquanto pendente:** ```json theme={null} { "status": "pending" } ``` **Resposta quando concluído:** ```json theme={null} { "status": "completed", "api_key": "64chars_hex_key...", "customer_id": 8, "tier": "community" } ``` **Resposta após expiração:** ```json theme={null} { "status": "expired" } ``` **Recomendações de implementação:** * Intervalo de polling entre **3 e 5 segundos** (não mais rápido) * Timeout total de 30 minutos * Quando receber `completed`, persistir `api_key` em local seguro (config criptografada, secret manager, etc.) *** ## Passo 5 — Ativar a instância Com a `api_key` em mãos, a instância chama o endpoint de ativação: ```http theme={null} POST /v1/activate Content-Type: application/json X-API-Key: 64chars_hex_key... X-Signature: { "instance_id": "550e8400-e29b-41d4-a716-446655440000", "version": "2.4.0" } ``` **Resposta:** ```json theme={null} { "status": "active", "tier": "community", "instance_id": "550e8400-e29b-41d4-a716-446655440000" } ``` A geolocalização (`operator_country`, `operator_city`) é **detectada automaticamente** pelo IP da request. A instância não precisa enviar essa informação. *** ## Passo 6 — Heartbeat periódico Após ativação, a instância envia heartbeats a cada **5 minutos**: ```http theme={null} POST /v1/heartbeat Content-Type: application/json X-API-Key: 64chars_hex_key... X-Signature: { "instance_id": "550e8400-e29b-41d4-a716-446655440000", "telemetry_bundle": { "messages_sent": 1500, "features": ["chatbot", "broadcast", "webhook"] } } ``` O campo `telemetry_bundle` é JSON livre. Os campos extraídos automaticamente pelo servidor são detalhados em [Telemetria](/licensing/telemetry). *** ## Passo 7 — Desativação (opcional) Em shutdown gracioso (uninstall, container stop intencional), recomenda-se: ```http theme={null} POST /v1/deactivate Content-Type: application/json X-API-Key: 64chars_hex_key... X-Signature: { "instance_id": "550e8400-e29b-41d4-a716-446655440000" } ``` Isso libera a contagem da instância no licenciamento. Não é obrigatório — o servidor expira instâncias inativas automaticamente após 7 dias sem heartbeat. *** ## Autenticação HMAC Todas as chamadas para `/v1/activate`, `/v1/heartbeat` e `/v1/deactivate` exigem o header `X-Signature` com HMAC-SHA256 do body. **Algoritmo:** 1. Serializar o body em JSON 2. Calcular `HMAC-SHA256(body, api_key)` 3. Converter para hexadecimal 4. Enviar no header `X-Signature` O body usado no HMAC deve ser **byte-a-byte idêntico** ao enviado. Não reformate o JSON entre o cálculo da assinatura e o envio. ### Exemplo Python ```python theme={null} import hmac, hashlib, json, requests api_key = "64chars_hex..." payload = { "instance_id": "550e8400-e29b-41d4-a716-446655440000", "version": "2.4.0", } body = json.dumps(payload, separators=(",", ":")) sig = hmac.new(api_key.encode(), body.encode(), hashlib.sha256).hexdigest() requests.post( "https://license.evolutionfoundation.com.br/v1/activate", data=body, headers={ "Content-Type": "application/json", "X-API-Key": api_key, "X-Signature": sig, }, ) ``` ### Exemplo Node.js ```javascript theme={null} const crypto = require('crypto'); const apiKey = '64chars_hex...'; const payload = { instance_id: '550e8400-e29b-41d4-a716-446655440000', version: '2.4.0', }; const body = JSON.stringify(payload); const sig = crypto.createHmac('sha256', apiKey).update(body).digest('hex'); await fetch('https://license.evolutionfoundation.com.br/v1/activate', { method: 'POST', body, headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey, 'X-Signature': sig, }, }); ``` ### Exemplo Go ```go theme={null} package main import ( "crypto/hmac" "crypto/sha256" "encoding/hex" ) func sign(body []byte, apiKey string) string { mac := hmac.New(sha256.New, []byte(apiKey)) mac.Write(body) return hex.EncodeToString(mac.Sum(nil)) } ``` *** ## Códigos de erro | HTTP | Code | Causa | Ação recomendada | | ---- | -------------------- | ----------------------------- | -------------------------------- | | 401 | `HMAC_INVALID` | Assinatura incorreta | Verificar serialização do body | | 401 | `INVALID_API_KEY` | Key mal formatada | Confirmar uso da hex de 64 chars | | 403 | `KEY_SUSPENDED` | Key suspensa por abuso | Contatar suporte | | 403 | `INSTANCE_LIMIT` | Limite de instâncias atingido | Solicitar aumento | | 404 | `INSTANCE_NOT_FOUND` | Heartbeat sem ativação prévia | Rodar `/v1/activate` primeiro | | 410 | `TOKEN_EXPIRED` | Token de 30min expirou | Repetir `/v1/register/init` | | 429 | `RATE_LIMIT` | Excedeu rate limit | Backoff exponencial | *** ## Checklist de integração Para quem está implementando a ativação em um fork ou produto derivado: * [ ] Gerar e persistir `instance_id` (UUID v4) na primeira execução * [ ] Implementar `POST /v1/register/init` quando não houver `api_key` * [ ] Exibir `register_url` ao operador (UI, terminal ou QR) * [ ] Polling `GET /v1/register/status` a cada 3–5s * [ ] Persistir `api_key` em local seguro (não em texto plano) * [ ] Implementar cálculo HMAC-SHA256 para todas as chamadas assinadas * [ ] `POST /v1/activate` na inicialização do serviço * [ ] `POST /v1/heartbeat` a cada 5min com `messages_sent` + `features` * [ ] `POST /v1/deactivate` em shutdown gracioso * [ ] Tratar erros (token expirado, key suspensa, limite de instâncias) * [ ] Backoff exponencial em falhas transitórias de rede *** ## Modo offline e degradação Se o servidor de licença estiver inacessível: * A instância **continua funcionando normalmente** * Heartbeats falham silenciosamente (sem quebrar a aplicação) * Após reconexão, o próximo heartbeat retoma o ciclo A ativação inicial (passo 1–5) é a única etapa que **exige conectividade**. Depois disso, a instância tolera períodos offline. Veja [FAQ — modo offline](/licensing/faq#modo-offline) para mais detalhes. # Ativação Automática por E-mail Source: https://docs.evolutionfoundation.com.br/licensing/auto-activation Ative novas instâncias da Evolution sem abrir navegador — uma única chamada de API com o e-mail já cadastrado. ## Quando usar O fluxo padrão de [ativação](/licensing/activation) exige que o operador abra o navegador, faça login (Magic Link ou OAuth) e aguarde o registro completar. Para o **primeiro** registro de um e-mail, isso é necessário. Para **toda instalação subsequente** do mesmo operador (mesmo e-mail), você pode pular o navegador inteiro e ativar a licença em uma única chamada HTTP. Ideal para: * Deploy automatizado (CI/CD, Terraform, Ansible) * Múltiplas instâncias do mesmo produto em servidores diferentes * Containers efêmeros que sobem e morrem com frequência * Provisionamento programático (multi-tenant, multi-região) A primeira ativação ainda precisa ser feita pelo fluxo manual (navegador + Magic Link/OAuth). Só depois disso o e-mail fica "conhecido" pelo servidor de licenciamento e a ativação automática passa a funcionar. *** ## Endpoint ```http theme={null} POST /v1/register/auto Content-Type: application/json { "email": "operator@example.com", "tier": "community", "version": "2.4.0", "instance_id": "550e8400-e29b-41d4-a716-446655440000" } ``` **Campos:** | Campo | Tipo | Obrigatório | Descrição | | ------------- | ------- | ----------- | ----------------------------------------------------------- | | `email` | string | sim | E-mail de um customer **já registrado** anteriormente | | `tier` | string | sim | Slug do produto (`community`, `beta`, etc.) | | `version` | string | sim | Versão do produto sendo ativado | | `instance_id` | UUID v4 | sim | UUID gerado localmente, mesmo padrão do `/v1/register/init` | | `country` | string | não | Override de país (padrão: GeoIP do servidor) | | `city` | string | não | Override de cidade (padrão: GeoIP do servidor) | **Resposta de sucesso (200):** ```json theme={null} { "status": "active", "api_key": "64chars_hex_key...", "customer_id": 8, "tier": "community", "instance_id": "550e8400-e29b-41d4-a716-446655440000" } ``` A `api_key` retornada está **pronta para uso imediato** — não é necessário chamar `/v1/activate` em seguida. A instância já entra como `active` no servidor. Se a chamada for repetida com o mesmo `(email, instance_id)`, a resposta inclui `"reused": true` e devolve a **mesma** `api_key` da chamada anterior. Isso torna a chamada **idempotente** — seguro para retry em scripts de boot. *** ## Modelo de confiança O servidor de licenciamento aceita a chamada usando **apenas o e-mail** como prova de identidade. Não há segundo fator, não há captcha, não há rate limit. **Por quê:** * O e-mail já foi verificado uma vez (no registro manual inicial, via Magic Link ou OAuth) * Emitir uma licença para um customer **não é uma ação destrutiva** — todas as instâncias ficam visíveis no portal do customer * O customer pode revogar `api_key`s a qualquer momento se detectar uso não autorizado * O customer pode desabilitar a ativação automática (`auto_activation_enabled = false`) no portal caso suspeite que o e-mail vazou Implicação: quem souber o e-mail de um customer pode emitir licenças nesse nome. Se isso for um problema para seu cenário (multi-tenant comercial, e-mail compartilhado, suspeita de vazamento), **desabilite a ativação automática no portal** e force todos os deploys a usarem o fluxo manual. *** ## Códigos de erro | HTTP | Code | Quando | Como tratar | | ---- | -------------------------- | ------------------------------------------ | ------------------------------------------------ | | 400 | `INVALID_BODY` | JSON malformado | Verificar corpo da request | | 400 | `MISSING_FIELD` | Campo `email` ausente | Incluir o campo | | 400 | `INVALID_EMAIL` | E-mail malformado | Validar antes de enviar | | 400 | `INVALID_TIER` | `tier` não corresponde a nenhum produto | Verificar o slug | | 400 | `INVALID_INSTANCE_ID` | `instance_id` não é UUID | Gerar UUID v4 | | 404 | `CUSTOMER_NOT_FOUND` | E-mail não tem registro prévio | **Caia para o fluxo manual** `/v1/register/init` | | 403 | `CUSTOMER_BLOCKED` | Customer bloqueado ou key suspensa | Contatar suporte | | 403 | `AUTO_ACTIVATION_DISABLED` | Customer desabilitou auto-ativação | Usar fluxo manual | | 403 | `INSTANCE_LIMIT` | Limite de instâncias do customer atingido | Solicitar aumento de cap | | 409 | `INSTANCE_EXISTS` | `instance_id` já existe sob outro customer | Gerar novo UUID | A resposta `CUSTOMER_NOT_FOUND` é o sinal canônico para o cliente cair para o fluxo manual. **Sempre implemente esse fallback** — primeiro deploy de um e-mail novo precisa passar pelo manual. *** ## Fluxo recomendado no client ```python theme={null} import os, uuid, requests LICENSE_URL = "https://license.evolutionfoundation.com.br" def ensure_api_key(): if local_api_key_exists(): return load_api_key() instance_id = read_or_create_instance_uuid() email = os.environ.get("EVOLUTION_OPERATOR_EMAIL") # 1. Tente ativação automática se temos o e-mail if email: resp = requests.post(f"{LICENSE_URL}/v1/register/auto", json={ "email": email, "tier": "community", "version": PRODUCT_VERSION, "instance_id": instance_id, }) if resp.status_code == 200: data = resp.json() save_api_key(data["api_key"]) return data["api_key"] if resp.json().get("code") == "CUSTOMER_NOT_FOUND": pass # cai para o fluxo manual abaixo elif resp.status_code in (403, 409): raise RuntimeError(f"Auto-activation rejected: {resp.json()}") # 2. Fallback: fluxo manual com navegador init_resp = requests.post(f"{LICENSE_URL}/v1/register/init", json={ "tier": "community", "version": PRODUCT_VERSION, "instance_id": instance_id, }).json() print(f"Abra no navegador: {init_resp['register_url']}") api_key = poll_until_completed(init_resp["token"]) save_api_key(api_key) return api_key ``` ### Variável de ambiente padrão Os produtos Evolution leem o e-mail do operador da variável **`EVOLUTION_OPERATOR_EMAIL`**: ```bash theme={null} # .env EVOLUTION_OPERATOR_EMAIL=operator@example.com ``` Se a variável não estiver definida, o produto cai diretamente no fluxo manual (sem tentar auto-ativação). *** ## Idempotência detalhada A chamada é idempotente em `(email, instance_id)`: | Cenário | Comportamento | | ---------------------------------------- | ------------------------------------------------------ | | Primeira chamada | Cria APIKey nova + Instance, retorna `api_key` | | Mesma `(email, instance_id)` de novo | Retorna a **mesma** `api_key`, `"reused": true` | | Mesmo `instance_id`, e-mail diferente | Erro `409 INSTANCE_EXISTS` | | Mesma `(email)`, `instance_id` diferente | Cria nova APIKey + Instance (deploy de instância nova) | Isso é o que torna seguro chamar a rota no startup do container — se o container já registrou antes, recebe a mesma key; se é nova, recebe key nova. Containers que **sempre geram UUID novo a cada boot** acumulam APIKeys (uma por boot) sob o mesmo customer. Se quiser comportamento idempotente real, persista o `instance_id` em volume montado (`/data/instance-id`) entre reinicializações. *** ## Como desabilitar para meu customer No portal do customer (`https://license.evolutionfoundation.com.br/portal`), há um toggle **"Ativação Automática por E-mail"**. Quando desabilitado: * Todas as chamadas a `/v1/register/auto` com seu e-mail retornam `403 AUTO_ACTIVATION_DISABLED` * Novos deploys obrigatoriamente passam pelo fluxo manual (navegador + Magic Link/OAuth) * Suas `api_key`s existentes continuam funcionando normalmente Recomendado para customers que: * Operam em ambiente regulado e querem trilha de auditoria em cada ativação * Têm o e-mail conhecido publicamente e querem reduzir superfície de ataque * Suspeitam de uso indevido do e-mail *** ## Auditoria Cada chamada a `/v1/register/auto` gera uma linha em `activation_logs` com `alert_type = 'auto_activation'`. O portal do customer mostra: * Data/hora de cada auto-ativação * IP do servidor que solicitou * Localização aproximada (país/cidade via GeoIP) * Resultado (`created` ou `reused`) Se você ver auto-ativações que não reconhece, **suspenda a key correspondente** no portal imediatamente — isso revoga acesso da instância sem afetar as outras. *** ## Próximos passos Fluxo completo do `/v1/register/init` — necessário no primeiro registro O que é enviado em cada chamada de licença Perguntas frequentes Resumo do sistema de licenciamento # FAQ — Licenciamento Source: https://docs.evolutionfoundation.com.br/licensing/faq Perguntas frequentes sobre ativação, telemetria, fork, uso comercial e modo offline. ## Cobrança e modelo ### Preciso pagar pela Evolution? Não. A licença `community` é **gratuita**. Não há cobrança em nenhum momento — nem na ativação, nem no uso continuado. ### A Evolution vai cobrar no futuro? O modelo atual é gratuito para self-hosted e permanece assim. O modelo comercial da Evolution Foundation é focado em: * **Cloud hospedado** — para quem prefere não fazer instalação própria * **Suporte profissional** — SLA e prioridade * **Serviços gerenciados** — infraestrutura e compliance Se o modelo mudar, mudanças relevantes serão anunciadas com antecedência e documentadas publicamente. O código já entregue sob Apache 2.0 continua sob Apache 2.0. ### Posso usar a Evolution comercialmente? Sim. A Apache 2.0 permite uso comercial, redistribuição, modificação e uso em produtos pagos. A única ressalva é o uso da **marca Evolution** (nome, logo, identidade visual), que é protegida separadamente — veja [Posso fazer fork?](#posso-fazer-fork). ### Existe alguma feature paga dentro do produto open source? Não. Tudo que está no repositório público é gratuito e sem restrição de uso. Não há feature flag bloqueando funcionalidade por tier. *** ## Privacidade e dados ### A Evolution monitora minhas mensagens? Não. Nenhum conteúdo de mensagem, número de contato ou mídia é enviado ao servidor de licenciamento. Veja [Telemetria](/licensing/telemetry) para o payload exato. ### O que acontece com meu e-mail e telefone? São armazenados no servidor de licenciamento para: * Identificar o operador da instância * Contato em caso de incidente de segurança ou abuso * Suporte comunitário Não são vendidos a terceiros, não são usados para marketing fora do escopo da Evolution e podem ser excluídos a pedido (`suporte@evofoundation.com.br`). ### Posso desabilitar a telemetria de licenciamento? A coleta do heartbeat é parte do fluxo de ativação e não tem uma flag de "desabilitar" no produto oficial — desabilitá-la equivale a operar uma instância **sem registro**, o que está fora do uso suportado pela marca Evolution. Forks podem remover o cliente de licenciamento (a Apache 2.0 permite), com a ressalva sobre marca abaixo. ### Como sei o que está sendo enviado de fato? Você pode interceptar o tráfego com `mitmproxy` ou usar o endpoint de debug local. Procedimentos em [Telemetria — Como auditar localmente](/licensing/telemetry#como-auditar-localmente). *** ## Open source e fork ### A Evolution está virando closed source? Não. O código permanece sob **Apache License 2.0**, sem cláusulas adicionais. ### Posso auditar o código? Sim. Todo o código-fonte da Evolution API, CRM e Go está disponível publicamente: * [evolution-foundation/evolution-api](https://github.com/evolution-foundation/evolution-api) * [evolution-foundation/evo-ai](https://github.com/evolution-foundation/evo-ai) * [evolution-foundation/evolution-go](https://github.com/evolution-foundation/evolution-go) * [evolution-foundation/evo-crm-community](https://github.com/evolution-foundation/evo-crm-community) * [evolution-foundation/evo-nexus](https://github.com/evolution-foundation/evo-nexus) ### Posso fazer fork? Sim, a Apache 2.0 permite fork. Restrições: * **Marca**: o nome "Evolution", logo e identidade visual são protegidos. Forks redistribuídos devem usar nome próprio. * **Aviso**: forks devem manter o `NOTICE` da Apache 2.0. * **Atribuição**: créditos da Evolution Foundation devem ser preservados conforme exigido pela licença. ### Posso remover o cliente de licenciamento no meu fork? Tecnicamente sim — a Apache 2.0 permite modificação. Implicações: * Seu fork não é mais a **Evolution oficial** — não pode usar a marca * Você fica responsável por toda a manutenção do fork * Atualizações futuras da Evolution oficial não serão diretamente compatíveis sem merge manual A Evolution Foundation não persegue forks por remoção do cliente de licenciamento, desde que respeitem a marca. ### A Evolution Foundation pode mudar a licença para closed source no futuro? Apenas para código **futuro**. Tudo que foi entregue sob Apache 2.0 permanece sob Apache 2.0 para sempre — essa é uma garantia da própria licença. Se houver mudança de licenciamento para versões futuras, o último commit Apache 2.0 continuará disponível e fork-ável. *** ## Modo offline ### Funciona em rede isolada (air-gap)? A **ativação inicial** exige conectividade ao servidor de licenciamento (uma vez). Após a ativação, a instância tolera longos períodos offline — heartbeats falham silenciosamente e retomam quando a conectividade volta. Para ambientes 100% air-gap, entre em contato com a equipe Evolution para discutir licenciamento offline. ### O que acontece se o servidor de licença cair? Sua instância **continua funcionando normalmente**. O cliente de licenciamento: * Faz retry com backoff exponencial * Não bloqueia nenhuma operação do produto * Loga falhas como warnings, não como erros fatais Não há kill switch remoto — o servidor de licença não tem capacidade de desligar instâncias em produção. ### E se eu suspender minha key por engano? Contate `suporte@evofoundation.com.br` com o `customer_id` retornado na ativação. Suspensão é reversível. *** ## Operação ### Posso ter múltiplas instâncias com a mesma key? Sim. O tier `community` **não tem limite de instâncias** — você pode rodar quantas precisar, em quantos servidores quiser, gratuitamente. Isso vale tanto para deploys self-hosted simples quanto para plataformas multi-tenant que criam instâncias programaticamente. Não há cap, não há throttle e não há cobrança por instância. ### O que é `instance_id`? Um UUID v4 gerado **localmente** na primeira execução e persistido. Identifica unicamente uma instalação. Trocar de servidor mantendo o mesmo banco preserva o `instance_id` — recriar do zero gera outro. ### O que é `api_key`? Uma string hex de 64 caracteres gerada pelo servidor de licenciamento na conclusão do registro. Funciona como credencial da instância nas chamadas seguintes (HMAC). Deve ser tratada como **segredo** — não commit em repositório, não exponha em logs. ### Posso transferir uma `api_key` entre servidores? Sim, dentro da mesma operação. Em migrações de host, basta copiar a `api_key` + `instance_id` para o novo servidor. O heartbeat seguinte aparece com IP novo, e o servidor atualiza a geolocalização. ### Como faço backup da licença? Inclua no backup: * O arquivo de config onde a `api_key` está armazenada (ex.: `.env`, secret manager) * O `instance_id` persistido * O banco de dados do produto (que pode também armazenar esses valores) *** ## Versões antigas ### Tenho Evolution API 2.3.x. Preciso atualizar? Não. Versões anteriores a `2.4.0` **não exigem ativação** e continuam funcionando normalmente. A exigência vale apenas a partir de `2.4.0+`. ### Posso fazer downgrade para evitar a ativação? Você pode manter qualquer versão que esteja rodando. Mas downgrades perdem features, correções e ganhos de performance — não recomendamos. ### A 2.4.0 é estável? A `2.4.0` foi lançada como **Release Candidate (RC)** — versão de validação antes da release estável. Use com isso em mente em produção crítica. *** ## Contato | Assunto | Canal | | ------------------------------------------------------- | ----------------------------------------------------------------------------- | | Bugs no licenciamento | [GitHub Issues](https://github.com/evolution-foundation/evolution-api/issues) | | Suporte, segurança, privacidade (LGPD/GDPR) e comercial | `suporte@evofoundation.com.br` | | Comunidade | [Discord](https://discord.gg/evolution-api) | # Licenciamento e Ativação Source: https://docs.evolutionfoundation.com.br/licensing/index Como funciona a ativação de licença gratuita da Evolution API, CRM e Go — o que é coletado, o que não é, e por que existe. ## Resumo A partir das versões mais recentes, os produtos da Evolution (API, CRM, Go e Evo Nexus) passaram a exigir uma **ativação de licença gratuita** no primeiro acesso. Isso **não muda** a natureza open source do projeto. A Evolution continua: * 100% gratuita * Open source sob **Apache License 2.0** * Self-hosted * Sem limites de uso * Sem bloqueio de funcionalidades * Sem cobrança em nenhum momento A ativação existe para que possamos entender o alcance real do ecossistema, medir métricas de adoção e proteger a marca Evolution. Se você instalou uma versão sem ativação obrigatória, continua funcionando normalmente. O requisito de ativação vale apenas para as versões a partir das releases indicadas em cada produto (ex.: Evolution API `2.4.0+`). *** ## Quais produtos exigem ativação | Produto | Versão a partir de | Tier padrão | | ------------- | ------------------ | ----------- | | Evolution API | `2.4.0` | `community` | | Evolution CRM | release atual | `community` | | Evolution Go | release atual | `community` | | Evo Nexus | release atual | `community` | Todos os tiers `community` são **gratuitos**, sem limite de instâncias, sem limite de mensagens e sem feature flag bloqueando funcionalidades. *** ## O que é coletado Durante a ativação, coletamos apenas: * **E-mail** — para identificar o operador da instância * **Telefone** — para contato em caso de incidentes de segurança ou abuso * **Versão** da Evolution em uso * **Identificador único da instância** (UUID gerado localmente) Depois da ativação, a instância envia *heartbeats* periódicos contendo: * Versão atual * Contadores agregados de uso (ex.: total de mensagens enviadas no período) * Lista de features habilitadas (ex.: `chatbot`, `webhook`, `broadcast`) * IP do servidor (extraído automaticamente do request, usado para geolocalização aproximada) Payload exato do heartbeat: ```json theme={null} { "instance_id": "550e8400-e29b-41d4-a716-446655440000", "telemetry_bundle": { "messages_sent": 1500, "features": ["chatbot", "broadcast", "webhook"] } } ``` *** ## O que NÃO é coletado A Evolution **não** coleta, em nenhuma circunstância: * Mensagens * Conversas * Conteúdo trafegado * Contatos * Mídia * Números de WhatsApp dos usuários finais * Tokens, credenciais ou API keys de terceiros * Dados privados da instância * Configurações sensíveis A coleta é **agregada e técnica** — não há acesso ao conteúdo das comunicações que passam pela sua instância. *** ## Por que existe a ativação A ativação da licença permite à Evolution Foundation: 1. **Medir o ecossistema** — saber quantas instâncias existem, em quais países, em quais versões 2. **Planejar infraestrutura** — dimensionar serviços públicos (registry, telemetry, docs) 3. **Detectar abuso** — identificar uso indevido da marca Evolution e usos fora dos termos da Apache 2.0 4. **Priorizar roadmap** — saber quais features são realmente usadas em produção 5. **Sustentar o projeto** — fundamentar decisões comerciais (Cloud, suporte) com dados reais A Evolution sempre teve telemetria básica de versão. A partir das releases atuais, esse processo passou a ser **formalizado** através da ativação. *** ## A Evolution continua Apache 2.0? Sim. A licença do código-fonte continua sendo **Apache License 2.0**, sem cláusulas adicionais. Isso significa que você pode: * Auditar todo o código-fonte * Modificar, recompilar e redistribuir * Fazer fork do projeto * Usar comercialmente * Self-hostar sem cobrança A ativação da licença é um requisito de **funcionalidade do Manager**, não da licença de software. Ela existe como mecanismo operacional (registro de instância), não como restrição de uso do código. Forks que removem a ativação são permitidos pela Apache 2.0, mas perdem o direito de usar a marca **Evolution** e os assets associados (logo, nome, identidade visual). A marca é protegida separadamente da licença do código. *** ## Continua tudo grátis? Sim. No modelo atual: * A licença `community` é gratuita * Não há feature paga dentro do Evolution API, CRM ou Go open source * Não há limite de uso, mensagens ou instâncias para o tier community O modelo comercial da Evolution sempre foi e continua sendo: * **Cloud hospedado** — para quem prefere não fazer instalação própria * **Suporte profissional** — SLA, prioridade, integração assistida * **Serviços gerenciados** — infraestrutura, observabilidade, compliance *** ## Próximos passos Como funciona o registro de licença — endpoints, polling, autenticação Pule o navegador em instalações subsequentes com `EVOLUTION_OPERATOR_EMAIL` Payloads exatos, heartbeat e o que é enviado em cada chamada Perguntas frequentes sobre cobrança, privacidade, fork, offline e marca *** ## Compromisso de transparência Acreditamos que open source se constrói com transparência. Se houver qualquer mudança em telemetria, licenciamento ou coleta de dados no futuro, ela será: * Documentada publicamente nesta página * Anunciada no changelog do produto * Comunicada na comunidade antes de virar release estável A documentação atual reflete o comportamento dos produtos nas versões listadas acima. Para acompanhar mudanças, veja o [changelog do Evolution API](https://github.com/evolution-foundation/evolution-api/releases). # Telemetria de Licenciamento Source: https://docs.evolutionfoundation.com.br/licensing/telemetry Payloads exatos enviados pela ativação e pelo heartbeat — o que sai da sua instância, o que fica do lado do servidor, e como inspecionar. ## O que esta página cobre Esta página descreve a telemetria do sistema de licenciamento (ativação + heartbeat) — o que sustenta a contagem de instâncias da Evolution Foundation. *** ## Payload exato — ativação Enviado uma vez, no `POST /v1/activate`: ```json theme={null} { "instance_id": "550e8400-e29b-41d4-a716-446655440000", "version": "2.4.0" } ``` Headers: ``` Content-Type: application/json X-API-Key: X-Signature: ``` **Campos extraídos automaticamente pelo servidor (sem envio explícito):** | Campo | Origem | Uso | | ------------------ | --------------------------------- | -------------------------------- | | `operator_country` | GeoIP do IP da request | Métricas agregadas por país | | `operator_city` | GeoIP do IP da request | Métricas agregadas por região | | `server_ip` | `X-Forwarded-For` ou `RemoteAddr` | Detecção de ativações duplicadas | | `activated_at` | Timestamp do servidor | Log imutável | *** ## Payload exato — heartbeat Enviado a cada 5 minutos, no `POST /v1/heartbeat`: ```json theme={null} { "instance_id": "550e8400-e29b-41d4-a716-446655440000", "telemetry_bundle": { "messages_sent": 1500, "features": ["chatbot", "broadcast", "webhook"] } } ``` ### Campos do `telemetry_bundle` O `telemetry_bundle` é um objeto JSON livre. O servidor extrai automaticamente: | Campo | Tipo | Significado | | --------------- | --------- | ---------------------------------------------------------------------------------------------- | | `messages_sent` | number | Total de mensagens enviadas **desde o último heartbeat**. O servidor soma ao acumulado global. | | `features` | string\[] | Lista de features ativas na instância. Ex.: `["chatbot", "broadcast", "webhook", "api-rest"]` | Qualquer campo adicional incluído no bundle é **armazenado** na tabela `telemetry_bundles` para consulta futura, mas não há processamento padrão sobre ele. ### O que `features` pode conter Valores comuns observados em produção: * `chatbot` — integração com Chatwoot, Typebot, Dify, n8n, etc. * `broadcast` — envio em massa * `webhook` — webhooks configurados * `api-rest` — uso da REST API * `s3` / `minio` — armazenamento de mídia em object storage * `rabbitmq` / `sqs` / `websocket` — eventos * `cloudapi` — Cloud API oficial do WhatsApp * `crm` — integração com Evo CRM A lista exata depende da versão do produto. *** ## O que NÃO está no payload Estes campos **nunca** são enviados, em nenhuma versão: * Conteúdo de mensagens * Identificadores de conversas * Números de WhatsApp dos contatos * Mídia (imagens, áudios, vídeos) * Tokens de webhook ou API keys de terceiros * Variáveis de ambiente da instância * Configurações de chatbots * Credenciais de banco de dados * Logs da aplicação * Stack traces ou erros internos A presença desses dados em qualquer payload seria uma **violação grave** da política de telemetria e seria tratada como bug crítico. *** ## Como auditar localmente Você pode interceptar o tráfego para confirmar o que está sendo enviado. ### Com `mitmproxy` ```bash theme={null} # Em uma janela mitmproxy -p 8888 # Em outra, redirecionar a instância export HTTPS_PROXY=http://localhost:8888 export LICENSE_BASE_URL=https://license.evolutionfoundation.com.br # reiniciar a instância ``` Cada `POST /v1/heartbeat` aparece no mitmproxy com body completo, pronto para inspeção. ### Com tcpdump + jq ```bash theme={null} # Capturar tráfego para o licensing server sudo tcpdump -i any -A -s 0 'host license.evolutionfoundation.com.br and port 443' ``` (TLS encripta o conteúdo — para inspecionar o JSON, use mitmproxy com CA local instalado.) ### Inspecionando localmente no código A Evolution API expõe um endpoint de debug que retorna o último heartbeat enviado: ```http theme={null} GET /telemetry/last-heartbeat Authorization: Bearer ``` Resposta: ```json theme={null} { "sent_at": "2026-05-12T10:34:00Z", "body": { "instance_id": "...", "telemetry_bundle": { "messages_sent": 42, "features": ["chatbot"] } }, "signature": "abc123..." } ``` O endpoint exato pode variar por versão. Veja o changelog do produto para detalhes. *** ## Frequência e custo | Operação | Frequência | Payload típico | | ------------------------- | ---------------------------------- | -------------- | | `POST /v1/register/init` | 1x na vida da instância | \~150 bytes | | `GET /v1/register/status` | polling de \~3–5s durante registro | \~50 bytes | | `POST /v1/activate` | 1x por inicialização do serviço | \~150 bytes | | `POST /v1/heartbeat` | a cada 5 min (≈ 288/dia) | \~250 bytes | | `POST /v1/deactivate` | shutdown gracioso (opcional) | \~80 bytes | Custo total mensal estimado em tráfego: **\< 3 MB por instância**. *** ## Retenção dos dados | Tipo de dado | Retenção | | -------------------------------------- | ------------------------------------------------------------------- | | `register/init` tokens | 30 minutos (expira automaticamente) | | `instance_id` + `api_key` | Indefinida enquanto a instância estiver ativa | | Heartbeats | Últimos 90 dias em tabela quente, agregados retidos indefinidamente | | Logs de ativação | 12 meses | | Métricas agregadas (sem identificação) | Indefinidamente | *** ## Conformidade ### LGPD (Brasil) * E-mail e telefone coletados são tratados sob base legal de **legítimo interesse** para operação do projeto open source * Operadores podem solicitar exclusão de dados via `suporte@evofoundation.com.br` * Não há perfilhamento de pessoa física * A `instance_id` é um UUID aleatório, não derivada de PII ### GDPR (Europa) * A coleta é proporcional e necessária ao funcionamento do registro * Direito de exclusão preservado * DPO via `suporte@evofoundation.com.br` *** ## Mudanças futuras Qualquer mudança em telemetria será: 1. Anunciada no [changelog do produto](https://github.com/evolution-foundation/evolution-api/releases) 2. Documentada nesta página 3. Disponibilizada em release candidate antes da release estável Se for adicionada coleta de novo campo, ele aparecerá explicitamente na seção "Payload exato" acima. *** ## Reportar inconsistência Se você observar **qualquer campo** sendo enviado fora do documentado nesta página, reporte como bug de segurança: * E-mail: `suporte@evofoundation.com.br` * GitHub Security Advisory: [evolution-api/security/advisories](https://github.com/evolution-foundation/evolution-api/security/advisories) Issues de telemetria não documentada são tratadas como **prioridade alta**. # Bem-vindo ao Evo CRM Source: https://docs.evolutionfoundation.com.br/introduction Plataforma completa de CRM, automação de campanhas e agentes de IA com suporte multi-canal para WhatsApp, Email, Redes Sociais e mais. ## O que é o Evo CRM? O **Evo CRM** é uma plataforma completa e self-hosted para gerenciar relacionamento com clientes, automação de marketing e agentes de inteligência artificial. Com ele, você pode: * **Gerenciar conversas** em múltiplos canais (WhatsApp, Email, Facebook, Instagram, Telegram e mais) * **Automatizar campanhas** de marketing com segmentação avançada e jornadas personalizadas * **Criar agentes de IA** que atendem clientes, processam informações e executam tarefas automaticamente * **Analisar performance** com métricas em tempo real e relatórios detalhados * **Manter controle total** dos seus dados e infraestrutura Tudo isso em uma única plataforma que você instala e gerencia na sua própria infraestrutura. ## Como Começar Escolha o caminho que melhor se adapta ao que você precisa fazer: Guia completo para instalar o Evo CRM na sua infraestrutura Documentação completa das APIs REST para integrações ## Suporte e Comunidade * **Site oficial**: [evolutionfoundation.com.br](https://evolutionfoundation.com.br) * **GitHub**: [github.com/evolution-foundation](https://github.com/evolution-foundation) * **Comunidade**: [evolutionfoundation.com.br/community](https://evolutionfoundation.com.br/community) * **Suporte**: [suporte@evofoundation.com.br](mailto:suporte@evofoundation.com.br) * **Issues**: reporte problemas e sugira melhorias no repositório correspondente *** Pronto para começar? Escolha seu caminho acima. # v1.0.0-rc3 — Estabilização e novas features Source: https://docs.evolutionfoundation.com.br/release-notes/v1.0.0-rc3 > **Release date:** 17 de maio de 2026 > **Tipo:** Release Candidate > **Foco:** estabilização (muitas correções de bugs) + três features cross-stack O `v1.0.0-rc3` chega cerca de **12 dias após o `v1.0.0-rc2`** e concentra \~165 commits entre os submódulos da família CRM Community. O foco predominante é **correção de bugs** identificados em produção depois do rc2, combinado com três features cross-stack que vínhamos preparando: **products catalog**, **template bundles** e **integração com Knowledge Nexus**. *** ## Highlights ### Estabilização Frentes principais de hardening: * **Mensageria Evolution Go / Evolution API** — paridade de payload em mensagens interativas (botões e listas) corrigida (EVO-1115). Entrega de mídia outbound em ambos os providers funcionando consistentemente (EVO-1151). Deduplicação de mensagens duplicadas no incoming handler. * **Hardening do endpoint Notificame verify** (EVO-986) — auth obrigatório, validação fechada, sem error leakage. Detalhes em [Webhooks](/user-guides/settings/integrations). * **2FA backup codes** (EVO-991) — códigos agora armazenados com hash BCrypt no banco. Correção do erro 500 ao listar codes. Ver [Autenticação em Duas Etapas](/user-guides/security/two-factor-authentication). * **Filtragem de secrets nos logs Rails** (EVO-1111) — campos sensíveis (password, token, api\_key) são filtrados antes de chegar ao log. * **IDOR no `BulkActionsJob`** (EVO-1084) — escopo de account aplicado; antes era possível manipular recursos cross-tenant com um ID válido. ### Três features cross-stack #### 📦 Catálogo de Produtos Cadastre seu portfólio de produtos com variantes (preço, SKU), vincule a agentes de IA e a itens de pipeline. O agente passa a conhecer seu catálogo automaticamente, sem precisar colar tabela no prompt. Inclui tool nativa `link_product_to_pipeline_item` para o agente registrar oportunidades de venda durante a conversa. Ver [Catálogo de Produtos](/user-guides/products/overview). #### 📤 Template Bundles export/import (EVO-1116) Exporte a configuração da sua instalação (inboxes, agentes, automation rules, canned responses, templates) como um arquivo ZIP portável. Importe em outra instalação para replicar setups, migrar entre staging/produção ou criar templates de instalação reutilizáveis. Ver [Bundles de Configuração](/user-guides/settings/template-bundles). #### 🔌 Integração com Knowledge Nexus Agentes de IA podem consultar **Knowledge Nexus spaces** diretamente do prompt, usando a tool nativa `knowledge_nexus_search`. Útil quando sua organização já mantém uma base de conhecimento separada do CRM. Ver [Knowledge Nexus](/user-guides/agents/knowledge-nexus). *** ## Outras Adições Relevantes ### UI * **Roles & Permissions admin UI** (EVO-1061) — tela completa de gestão de papéis customizados, com CRUD pleno e guard contra privilege escalation via delegation. Ver [Funções Personalizadas](/user-guides/settings/custom-roles). * **Bulk resolve de conversas** (EVO-1011) — resolver várias conversas em lote via checkbox na lista. Ver [Ações de Conversa](/user-guides/conversations/conversation-actions). * **Pipeline actions no menu 3 pontos + context menu** (EVO-990) — ações de pipeline acessíveis sem precisar abrir o detalhe do card. * **Telefone do contato visível na lista e no header** (EVO-988). * **Reconexão ativa de WebSocket** (EVO-1085) — toast de sucesso ao restabelecer + backoff em background. * **Upload de arquivos elevado para 100MB** (EVO-1131). ### Automation Rules * **Operador `attribute_changed` com pickers From/To** (EVO-1058) — dispare regra apenas em transições específicas. * **Triggers `conversation_resolved` e `conversation_status_changed`** (EVO-1057). * **Action `move_to_pipeline`** — move item para pipeline diferente preservando id. * **Painel de Logs** — visualize execuções, conditions avaliadas e erros. * **Dedup em janela de 5s** para `pipeline_stage_updated` por `(rule, pipeline_item, stage)`. Ver [Visão Geral de Automation](/user-guides/automation/overview) e [Regras](/user-guides/automation/rules). ### Auth Service * **CRUD completo de roles com escopo `account_owner`** (EVO-1061). * **Permissões `products.*` e `template_bundles`** no RBAC. * **SMTP/BMS/Resend aplicados em runtime** (EVO-1049) — sem precisar restart do container ao mudar configuração via UI. * **Password validation 422 estruturada** (EVO-1063) — frontend mostra checklist inline. ### Processor * **Tools nativas** para LLM agent: `knowledge_nexus_search`, `manage_conversation_labels`, `link_product_to_pipeline_item`. * **Catálogo de produtos injetado no contexto** do agente. * **Merge de integrações em runtime** — mudanças em `agent_integrations` refletem na próxima conversa sem reconfigurar. *** ## Notas de Upgrade ### ✅ Aplicação automática * **RBAC do role `agent`** — `pipelines.read` é backfilled via migration; `pipelines.update` é removido (teria desbloqueado endpoints destrutivos por erro). Sem ação manual. * **SMTP/BMS/Resend runtime** — funciona automaticamente após upgrade do auth-service. Operador pode trocar configs sem restart. * **Filtragem de secrets** — ativa após upgrade do CRM. Logs anteriores ao upgrade não são afetados. * **Hash dos backup codes 2FA** — codes gerados a partir do rc3 são hashed automaticamente. ### ⚠️ Atenção * **Backup codes 2FA gerados antes do rc3** — ficavam em plaintext no banco. Se o histórico do banco esteve acessível a alguém fora do operador da instalação, recomenda-se regenerar via `Perfil → Segurança`. A operação leva 30 segundos. * **Pipelines stage automation** — se você usava regras `move_to_stage` em produção, valide o comportamento após upgrade. A janela de dedup de 5s pode mudar o timing de regras em rajada (antes podia disparar múltiplas vezes; agora dispara uma vez). ### 📝 Configuração nova Variável de ambiente nova no `.env.example`: ```bash theme={null} EVOLUTION_OPERATOR_EMAIL=ops@seudominio.com ``` Usada para licensing/telemetria. Não bloqueia o boot se ausente, mas recomenda-se preencher em produção. *** ## Compatibilidade * **Banco de dados:** migrations rodam automaticamente em `db:migrate`. Tudo idempotente e reversível. * **Container:** rebuild necessário para todos os 5 serviços. Imagens publicadas no Docker Hub com tag `1.0.0-rc3`. * **Frontend:** hard refresh do browser necessário para invalidar o bundle antigo. * **Submódulos:** se você usa a estrutura umbrella, atualize os pointers com `git submodule update --remote`. *** ## Histórico de Releases * [`v1.0.0-rc2`](/release-notes/v1.0.0-rc2) — Estabilização e mídia WhatsApp Cloud (2026-05-05) * [`v1.0.0-rc1`](/release-notes/v1.0.0-rc1) — Primeiro release candidate público (2026-04-24) ## Detalhamento técnico Para o changelog técnico completo com IDs de PRs e commits, consulte: * [`CHANGELOG.md` do umbrella](https://github.com/evolution-foundation/evo-crm-community/blob/main/CHANGELOG.md) * `CHANGELOG.md` de cada submódulo no respectivo repositório # v1.0.0-rc4 — Evo Hub + mensagens interativas Source: https://docs.evolutionfoundation.com.br/release-notes/v1.0.0-rc4 > **Data de publicação:** 25 de maio de 2026 > **Tipo:** Release Candidate > **Foco:** Integração com Evo Hub + botões interativos do Typebot + hardening de MFA A `v1.0.0-rc4` chega cerca de **8 dias após a `v1.0.0-rc3`** e se concentra em duas funcionalidades ponta a ponta e uma rodada de hardening de segurança: **Evo Hub** como proxy opcional para canais Meta, **botões interativos do Typebot** atravessando processor / CRM / frontend / widget, e **hardening de MFA** no auth-service (remediação de backup codes pós-EVO-991, invalidação do cache de sessão, fail-open de licensing). *** ## Destaques ### 🔌 Evo Hub como proxy opcional para canais Meta Agora é possível conectar canais de WhatsApp / Instagram / Facebook através do **Evo Hub** como proxy, em vez de passar pela integração direta com a Meta. A funcionalidade é opt-in — quando o Evo Hub não está configurado, o fluxo direto da Meta continua funcionando como antes. Integração ponta a ponta: * **Frontend** — nova página administrativa (URL, API key, webhook secret com gerador embutido `crypto.getRandomValues`) e um `HubConnectButton` para conectar canais via o proxy do Hub. * **CRM** — webhook receiver dedicado, `InboxBuilder` para inboxes do proxy, ciclo de vida `hub_pending?` / `hub_active?` no model `Channel`, validação reforçada e limpeza que propaga a remoção do webhook para o Hub remoto. ### 💬 Botões interativos do Typebot Blocos `choice` do Typebot agora são renderizados como **mensagens com botões interativos** em vez de texto puro, tanto no chat principal quanto no widget embutível. A mudança toca três submódulos em conjunto: `evo-ai-processor-community` (#12), `evo-ai-crm-community` e `evo-ai-frontend-community`. ### 🔐 Hardening de MFA (auth-service) * **Backup codes em texto puro de deploys pré-correção foram invalidados** (EVO-991) — uma migração one-shot zera `otp_backup_codes` e limpa `mfa_confirmed_at` para qualquer usuário cujo array ainda contenha entradas legadas não-BCrypt. Usuários afetados são marcados com `mfa_setup_incomplete: true` e contornam o desafio de MFA no próximo login até concluírem a reconfiguração. * **Cache de sessão invalidado após reconfiguração de MFA** (EVO-1104) — `complete_mfa_setup` agora invalida o cache imediatamente, em vez de esperar até 5 minutos pelo TTL. * **Fail-open de licensing** — quando o servidor de licensing está inacessível, o auth-service opera em uma janela curta de fail-open em vez de bloquear logins. *** ## Outras mudanças notáveis ### CRM * **EVO-1088 — Persistência do status de execução de macros + exposição de falhas via webhook** — execuções de macro agora persistem o status (sucesso/falha/mensagem de erro) e expõem falhas no payload do webhook para que automações externas possam reagir. * **EVO-1372 — Hardening de mensagens interativas** — validação de payload, truncamento para os limites da Meta/WhatsApp, tratamento de casos extremos. * **Correções de premissas legadas de conta única** — caminhos internos ainda referenciavam o model `Account` removido; pontos de chamada remanescentes foram corrigidos. * **Listeners de label/conversation reforçados** — caminhos de mutação de `label_list` agora emitem consistentemente via setter. ### Frontend * **EVO-1088 — Resultado real da execução de macro na UI** (#89) — a UI mostra a mensagem real de sucesso/falha/erro vinda do backend. * **EVO-1274 — Cadência adaptativa de `useRelativeTime`** (30s / 60s / 10min) — reduz re-renders em conversas com muitas mensagens. * **EVO-1254 — Indicador de `lastSaved` em linguagem natural** — substitui o HH:MM:SS bruto por "2 minutos atrás" / "agora mesmo". * **Correções no chat** — contagem total de conversas vinda da API, race condition de `loadMore` em redes lentas, scroll da sidebar / colapso de layout. * **EVO-1405 — Sidebar de contato busca os dados completos do contato ao abrir**. * **EVO-1406 / EVO-1407 — Desempacotamento do envelope do `SessionsViewer` + guards defensivos de stats**. ### Auth Service * **EVO-1104 — Push do questionário de onboarding** — implementação do push de respostas mais um endpoint de retomada para usuários que abandonaram o fluxo. * **Provider de storage em runtime** (EVO-1050) — mudanças na UI Admin entre S3 / GCS / storage local passam a valer no processo em execução sem restart. Log de warn emitido em caso de fallback para o default. * **Downgrade da versão da migração do ActiveRecord 7.2 → 7.1** — alinha com a versão do Rails efetivamente em uso; evita erros de boot durante `db:migrate`. ### Processor * **Renderização de botões interativos do Typebot** (#12) — em conjunto com as mudanças correspondentes em CRM e frontend. ### Core Service * **Sem mudanças funcionais** — tag emitida para manter a família CRM Community alinhada em uma única versão de release-candidate. *** ## Notas de atualização * ✅ **Automático** — a maioria das mudanças se aplica no restart do container. Nenhuma nova variável de ambiente foi introduzida para usuários finais. * ⚠️ **Migração de auth com lock por linha** — a migração de invalidação de backup codes do EVO-991 executa um `UPDATE` com lock por linha na tabela `users`. Para bancos com mais de 100k usuários, agende uma janela curta de manutenção. * ⚠️ **Prompt de reconfiguração de MFA** — usuários que tinham MFA habilitado antes da v1.0.0-rc4 serão solicitados a configurar o TOTP novamente no próximo login. Trata-se de medida preventiva pós-EVO-991, não de resposta a um vazamento confirmado. * ⚠️ **Migração de limpeza de schema legado no CRM** — remove tabelas descontinuadas. Sem impacto em dados de produção (as tabelas não estavam em uso). Rode `db:migrate` na atualização. * 📝 **Nenhuma nova env var** é exigida pela funcionalidade do Evo Hub, a menos que você opte por habilitá-la (configure via UI Admin). *** ## Compatibilidade * Compatível com deploys da `v1.0.0-rc3` — caminho de upgrade direto. * Nenhuma breaking change na API pública. * Imagens Docker publicadas sob a org `evoapicloud` no Docker Hub. A tag Docker remove o `v` inicial (git `v1.0.0-rc4` → Docker `1.0.0-rc4`). *** ## Referência técnica * [CHANGELOG — evo-crm-community (umbrella)](https://github.com/evolution-foundation/evo-crm-community/blob/main/CHANGELOG.md) * [CHANGELOG — evo-ai-crm-community](https://github.com/evolution-foundation/evo-ai-crm-community/blob/main/CHANGELOG.md) * [CHANGELOG — evo-ai-frontend-community](https://github.com/evolution-foundation/evo-ai-frontend-community/blob/main/CHANGELOG.md) * [CHANGELOG — evo-auth-service-community](https://github.com/evolution-foundation/evo-auth-service-community/blob/main/CHANGELOG.md) * [CHANGELOG — evo-ai-processor-community](https://github.com/evolution-foundation/evo-ai-processor-community/blob/main/CHANGELOG.md) * [CHANGELOG — evo-ai-core-service-community](https://github.com/evolution-foundation/evo-ai-core-service-community/blob/main/CHANGELOG.md) # v1.0.0-rc5 — Hardening de instalação fresh + Expansão EvoFlow Source: https://docs.evolutionfoundation.com.br/release-notes/v1.0.0-rc5 > **Data de publicação:** 27 de maio de 2026 > **Tipo:** Release Candidate > **Foco:** Confiabilidade de instalações fresh (correção da race condition no banco compartilhado) + expansão da superfície EvoFlow A `v1.0.0-rc5` chega **dois dias após a `v1.0.0-rc4`** e concentra dois temas: **eliminar a race condition de primeira inicialização** que travava autenticação em instalações novas (quando todos os serviços subiam em paralelo contra o mesmo Postgres) e **expandir a superfície de EvoFlow** ponta a ponta — worker de backfill de eventos de contato, mirror do schema de eventos em Ruby com validador, cinco novos tipos de nó de fluxo e um `EventSelector` compartilhado no frontend que consome o manifest de eventos. *** ## Destaques ### 🛠️ Confiabilidade de instalação fresh A imagem da `rc4`, quando subia contra um Postgres vazio com todos os serviços iniciando em paralelo, caía em uma race condition: o `evo-ai-processor-community` (Python/SQLAlchemy) criava um stub `users(id integer)` para suas foreign keys **antes** do `evo-auth-service-community` (Rails) rodar sua migração `InitSchema`. O Rails então pulava silenciosamente seu próprio `create_table :users` (via `if_not_exists: true`), e o schema canônico (PK `uuid`, `mfa_method`, `encrypted_password`, `oauth_access_tokens`) nunca era materializado. Todo login terminava em `PG::UndefinedTable: relation "oauth_access_tokens" does not exist`, cascateando para 503 no CRM. A correção atua nos dois lados: * **Processor** — `Base.metadata.create_all()` agora exclui tabelas que pertencem a outros serviços. O processor só materializa as tabelas que ele mesmo possui; o stub `users` simplesmente não é mais emitido. * **Auth-service** — antes de rodar `InitSchema`, a migração detecta a presença de um `users(id integer)` sem colunas de autenticação (heurística do stub) e dropa a tabela. O schema canônico é então recriado intacto. A operação é idempotente — não faz nada em instalações cuja tabela `users` já está no formato correto. O incidente que disparou a correção (multimport, 2026-05-27) está documentado em runbook interno; instalações novas em ambientes de serviços compartilhados agora sobem limpas, sem intervenção manual. ### 🔓 Licensing nunca bloqueia uma requisição O middleware `Licensing::SetupGate` no auth-service foi rebaixado de **gate de enforcement** para **hook puro de observabilidade**. Antes da `rc5`, qualquer indisponibilidade do servidor de licensing (timeout, DNS, 5xx) virava `503 SETUP_REQUIRED` em toda rota fora da bypass list — derrubando o CRM inteiro mesmo após as correções de auth. A nova implementação: * Tenta reidratar o contexto de licença se ele estiver inativo. * Emite o sinal de observabilidade independentemente do resultado. * **Sempre encaminha a requisição.** O estado da licença vira telemetria; nenhuma requisição é bloqueada por ele. Complementarmente, a queue `licensing` foi adicionada ao `config/sidekiq.yml`. Antes ela estava ausente, então `SetupJob` e `HeartbeatJob` ficavam silenciosamente enfileirados e nunca executados — resultado: `api_key` não era persistido após o setup e o heartbeat de licenciamento nunca rodava. ### 🌊 Expansão EvoFlow A `rc5` traz três avanços coordenados na superfície EvoFlow: * **Mirror Ruby do schema de eventos + `SchemaValidator`** (EVO-1261) — o `EVENT_SCHEMA` canônico do EvoFlow é espelhado no CRM e congelado profundamente. O validador exige UUID estrito, rejeita strings vazias, faz checagem eager de schema e levanta exceção em nomes de evento não registrados. Inclui cast de `inbox_id` / `assigned_by_id` para `:uuid` no fork de leitura. * **Cinco novos tipos de nó de fluxo** (EVO-1262) — `ActionService` foi consolidado sobre handlers compartilhados de pipeline e mensagem, e cinco novos node types passam por esses handlers. Acompanha harness de paridade, cobertura de specs e README descrevendo o contrato dos handlers compartilhados. * **`BackfillContactEventsWorker`** — worker Sidekiq que portar eventos históricos de `Message` e `ReportingEvent` para o dataset `contact_events` via `/events/batch` do EvoFlow. Roda em **dry-run por padrão**, na queue `:integrations` com `retry: 2`. Não é disparado automaticamente — operador invoca via `bundle exec rake evo_flow:backfill[]`. No frontend, o `EventSelector` + `EventPropertiesForm` compartilhados consomem o manifest de eventos em runtime — adicionar ou remover eventos no backend não exige mais editar o código dos nós do flow editor. *** ## Outras mudanças notáveis ### CRM * **EVO-1243 — Endpoint proxy `/contacts/:id/events` com enrich** — expõe o stream de eventos do contato vindo do EvoFlow através do CRM, enriquecendo cada evento com o contexto que a UI precisa. Inclui guard de STI adicionado durante o hardening de revisão. * **Evolution Hub — vincular inbox a canal existente** (EVO-1455) — operadores agora podem anexar uma inbox do CRM a um canal preexistente no Evolution Hub, em vez de sempre provisionar um canal novo via o proxy. Inclui nova migração `AddEvolutionHubMetaToChannels`. * **Evolution Hub — gate legado `EVOLUTION_HUB_URL` removido** — instalações não precisam mais setar a variável de ambiente legada para ativar os fluxos do Hub; a configuração é lida da fonte canônica (UI Admin). * **Notificações — payload enriquecido** — nome do remetente, avatar, preview da mensagem e `last_activity_at` passam a viajar no payload, permitindo render rich na lista sem round-trip extra. * **EVO-1419 — Escopo de notificações apertado** — fan-out de inbox saiu do escopo da EVO-1419; o enriquecimento de payload acima é o entregável remanescente. Tipos `pipeline_task_*` declarados explicitamente fora do escopo desta iteração. * **WhatsApp Cloud — erros de envio passam por `StatusUpdateService`** — erros em tempo de envio no provider Cloud agora seguem o mesmo funil de status-update dos demais providers, mantendo o pipeline de status de mensagem consistente. * **EvoFlow — entradas faltantes para 5 eventos de conversation** — gap no schema de eventos espelhado, que travava o boot da branch `develop` da rc4, foi fechado. Sem ação de upgrade necessária. * **Notificações — sender nil em assignment + lookup defensivo de `avatar_url`** — notificações de atribuição não quebram mais quando o usuário que atribuiu é nil; `avatar_url` é buscado defensivamente. ### Frontend * **Evolution Hub — vincular inbox a canal existente** — fluxo de conexão agora permite anexar inbox a um canal Hub preexistente, não apenas criar um novo a cada vez. * **Notificações — `NotificationItem` redesenhado** — linha de notificação passa a mostrar nome do remetente, avatar, preview da mensagem e timestamp relativo, substituindo o layout mínimo anterior. * **Notificações — tempo relativo locale-aware** — `NotificationItem` migrado para helpers de tempo relativo do `date-fns` (com suporte a locale). * **Notificações — guard no merge de update via WebSocket + testes de reducer** — caminho de merge de updates concorrentes protegido contra estado inconsistente; testes cobrindo o comportamento de remoção ao marcar como lida. * **Notificações — usar `notification.sender` para nome e avatar** — campo estava sendo lido da fonte errada, causando avatares ausentes ou incorretos. * **EVO-1421 — Remoção do wrapper inert de floating-panel + aposentadoria do `BaseFlowPanel`** — wrapper era renderizado mas inert (nenhum click ou teclado chegava ao painel); removido junto com o componente legado, agora que os consumidores migraram. * **EVO-1454 — Contraste WCAG AA no hint de empty-state do `ConditionalNode`** — tonalidade subiu para `text-yellow-700` para atingir contraste AA contra o fundo do nó. * **i18n — acento espanhol em `channel_message` + limpeza de double blank line** — corrigida tradução espanhola e removida linha em branco dupla no mesmo arquivo de locale. ### Auth Service * **AuthBridge 1.1.0 — `find_user_by_email` + `sign_in_request`** — dois novos extension points estritos expostos pelo `AuthBridge`. `find_user_by_email` permite que uma implementação Enterprise resolva o usuário a partir de um identity store alternativo (ex.: diretório SSO) antes do lookup local; `sign_in_request` permite injetar lógica custom no sign-in em tempo de request (auditoria, elevação de MFA, provisionamento JIT). Ambos seguem o contrato duck-typed existente com erro explícito em retornos com shape inválido. Documentado em `EXTENSION_POINTS.md`. * **`add_fk_if_missing` type-aware** (#36) — helper de FK agora inspeciona o tipo da PK referenciada e casa o tipo da coluna, evitando erros de type-mismatch em instalações que migram de uma `users` histórica com PK integer. * **Downgrade da versão da migração ActiveRecord para 7.1** (#37) — alinha com a versão do Rails efetivamente em uso, evitando erros de boot em `db:migrate` contra ambientes em 7.1. ### Processor * **Renomeação org `EvolutionAPI` → `evolution-foundation` na documentação** — URLs do GitHub e referências atualizadas. Sem impacto em código. ### Core Service * **Sem mudanças funcionais** — tag emitida para manter a família CRM Community alinhada em uma única versão de release-candidate. ### Bot Runtime * **Release de catch-up** — o serviço pulou a `v1.0.0-rc4` (não havia mudança funcional que justificasse tag na época). A `v1.0.0-rc5` realinha a imagem do bot-runtime com o restante da família. O binário Go é **idêntico ao da `v1.0.0-rc3`** — só a tag é nova. Faça pull de `evoapicloud/evo-bot-runtime:1.0.0-rc5` para manter o `docker-compose` consistente. *** ## Notas de atualização * ✅ **Instalações fresh** — a race condition do `users` table stub está resolvida. Sem intervenção manual em deploys novos: o processor não cria mais o stub, e o auth-service dropa qualquer stub preexistente antes de recriar o schema canônico. * ⚠️ **Upgrade de instalação quebrada pela race condition da rc4** — se sua instalação caiu no sintoma típico (`relation "oauth_access_tokens" does not exist` em todo login; tabela `users` existe mas com PK `integer` e sem as colunas de auth), execute `DROP TABLE users CASCADE` no Postgres compartilhado **antes** de fazer pull da `rc5` e redeploy. Faça backup antes. O auto-detect da migração cobre o shape comum, mas se seu stub divergir pode ser necessário dropar explicitamente. * ⚠️ **Licensing não bloqueia mais nenhum endpoint** — se seus runbooks operacionais dependiam do auth-service retornar `503 SETUP_REQUIRED` enquanto o licensing estava inacessível, atualize-os. O sinal agora é um evento de observabilidade, não uma resposta que bloqueia requisições. O estado da licença continua aparecendo em logs e métricas para monitoramento. * ⚠️ **Sidekiq — queue `licensing` ativa** — a queue `licensing` foi adicionada ao `config/sidekiq.yml`. Se seu deploy usa um `sidekiq.yml` customizado (montado via volume), inclua `- licensing` na lista de queues, senão `SetupJob` e `HeartbeatJob` continuarão silenciosos. * ⚠️ **CRM — `db:migrate` na atualização** — a migração `AddEvolutionHubMetaToChannels` adiciona colunas Meta do Evolution Hub na tabela `channels`. Idempotente. * ✅ **EvoFlow — backfill de contact events** — o `BackfillContactEventsWorker` é seguro de rodar em instalações existentes (idempotente). Operadores fazendo upgrade da rc4 devem deixá-lo concluir antes de depender do novo endpoint `/contacts/:id/events`. **Roda em dry-run por padrão**; só executa quando invocado via `bundle exec rake evo_flow:backfill[]`. * ✅ **EvoFlow — schema sanity** — entradas faltantes para 5 eventos de conversation foram registradas. Sem ação de upgrade. * 📝 **Bot Runtime — pulou rc4** — a tag salta de `v1.0.0-rc3` direto para `v1.0.0-rc5`. Conteúdo da imagem é o mesmo da `rc3`. Faça pull da tag nova só para manter o compose alinhado. * 📝 **`EVOLUTION_HUB_URL` não é mais consultada** — se ainda estiver setada no seu `.env`, pode remover. A configuração do Hub é lida da UI Admin. * 📝 **AuthBridge 1.1.0** — extensão opt-in para Enterprise; consumidores 1.0.x continuam funcionando. *** ## Compatibilidade * Compatível com deploys da `v1.0.0-rc4` — caminho de upgrade direto (com as ressalvas acima sobre limpeza manual do stub em instalações quebradas). * Compatível com deploys da `v1.0.0-rc3` — upgrade direto. * Nenhuma breaking change na API pública. * Imagens Docker publicadas sob a org `evoapicloud` no Docker Hub. A tag Docker remove o `v` inicial (git `v1.0.0-rc5` → Docker `1.0.0-rc5`). *** ## Referência técnica * [CHANGELOG — evo-crm-community (umbrella)](https://github.com/evolution-foundation/evo-crm-community/blob/main/CHANGELOG.md) * [CHANGELOG — evo-ai-crm-community](https://github.com/evolution-foundation/evo-ai-crm-community/blob/main/CHANGELOG.md) * [CHANGELOG — evo-ai-frontend-community](https://github.com/evolution-foundation/evo-ai-frontend-community/blob/main/CHANGELOG.md) * [CHANGELOG — evo-auth-service-community](https://github.com/evolution-foundation/evo-auth-service-community/blob/main/CHANGELOG.md) * [CHANGELOG — evo-ai-processor-community](https://github.com/evolution-foundation/evo-ai-processor-community/blob/main/CHANGELOG.md) * [CHANGELOG — evo-ai-core-service-community](https://github.com/evolution-foundation/evo-ai-core-service-community/blob/main/CHANGELOG.md) # Variáveis de Ambiente Source: https://docs.evolutionfoundation.com.br/self-hosted/configuration/environment-variables O arquivo `.env` é onde você diz para a plataforma como ela deve se comportar: onde está o banco de dados, qual senha usar, quais serviços se comunicam entre si. Sem ele configurado corretamente, nada funciona. A boa notícia: para a maioria das instalações com Docker, você **não precisa mudar quase nada**. *** ## Como funciona Toda a configuração fica em **um único arquivo `.env`** na raiz do projeto. Ele é criado a partir de um modelo pronto: ```bash theme={null} cp .env.example .env ``` O `.env.example` já vem com valores padrão que funcionam imediatamente para rodar a plataforma localmente com Docker. Abra o `.env` com qualquer editor de texto e ajuste apenas o que for necessário para o seu ambiente. O arquivo `.env.example` é o arquivo com a lista completa de todas as variáveis disponíveis. Consulte-o sempre que precisar de uma referência completa. *** ## Banco de dados (PostgreSQL) Todos os serviços compartilham o mesmo banco de dados. Com Docker, essas variáveis já estão configuradas e funcionam sem alteração. ```bash theme={null} # Servidor e porta POSTGRES_HOST=postgres POSTGRES_PORT=5432 # Credenciais POSTGRES_USERNAME=postgres POSTGRES_PASSWORD=sua_senha_segura # Nome do banco POSTGRES_DATABASE=evo_community ``` O serviço **Core** (`evo-ai-core-service-community`) usa um conjunto separado de variáveis com o mesmo banco: ```bash theme={null} DB_HOST=postgres DB_PORT=5432 DB_USER=postgres DB_PASSWORD=sua_senha_segura DB_NAME=evo_community DB_SSLMODE=disable ``` O serviço **Processor** usa o formato de string de conexão: ```bash theme={null} POSTGRES_CONNECTION_STRING=postgresql://postgres:sua_senha_segura@postgres:5432/evo_community ``` O Evo CRM Community **não é compatível** com MySQL, MariaDB ou SQLite. Use sempre PostgreSQL 16 ou superior com a extensão pgVector habilitada. *** ## Redis (cache e filas) O Redis é usado para manter sessões ativas e processar tarefas em segundo plano. Com Docker, ele já sobe automaticamente. ```bash theme={null} # Auth e CRM usam URL completa REDIS_URL=redis://:sua_senha_redis@redis:6379 REDIS_PASSWORD=sua_senha_redis # Processor usa variáveis separadas REDIS_HOST=redis REDIS_PORT=6379 REDIS_DB=0 REDIS_SSL=false ``` *** ## Secrets compartilhados Essas são as variáveis mais importantes para a segurança da plataforma. Elas devem ter o **mesmo valor** em todos os serviços que as utilizam. ```bash theme={null} # Usado por: auth, crm, core-service (assinatura de tokens JWT) SECRET_KEY_BASE=gere-uma-chave-longa-e-aleatoria-com-rails-secret JWT_SECRET_KEY=gere-uma-chave-longa-e-aleatoria-com-rails-secret # Usado por: core-service, processor (criptografia de chaves de API) ENCRYPTION_KEY=gere-uma-chave-base64-de-32-bytes # Usado por: auth, crm, processor (autenticação entre serviços) EVOAI_CRM_API_TOKEN=gere-um-uuid-unico-aqui ``` **Como gerar os valores:** ```bash theme={null} # Para SECRET_KEY_BASE e JWT_SECRET_KEY make shell-auth # dentro do container: rails secret # Para ENCRYPTION_KEY (base64 de 32 bytes) openssl rand -base64 32 # Para EVOAI_CRM_API_TOKEN (UUID) uuidgen ``` Em produção, **nunca use os valores do `.env.example`**. Gere valores únicos para cada instalação. Todos os serviços que compartilham uma chave devem usar exatamente o mesmo valor. *** ## Frontend As variáveis do frontend começam com `VITE_` e são incorporadas ao código no momento do build. Elas usam `localhost` porque o navegador as acessa diretamente — não pelo Docker. ```bash theme={null} VITE_APP_ENV=development # Endereços dos serviços (acessados pelo navegador) VITE_API_URL=http://localhost:3000 VITE_AUTH_API_URL=http://localhost:3001 VITE_EVOAI_API_URL=http://localhost:5555 VITE_AGENT_PROCESSOR_URL=http://localhost:8000 ``` Em produção, substitua `localhost` pelos domínios reais da sua instalação: ```bash theme={null} VITE_APP_ENV=production VITE_API_URL=https://api.seudominio.com VITE_AUTH_API_URL=https://auth.seudominio.com VITE_EVOAI_API_URL=https://core.seudominio.com VITE_AGENT_PROCESSOR_URL=https://processor.seudominio.com ``` *** ## E-mail (SMTP) Em desenvolvimento, a plataforma usa o **Mailhog** — um servidor de e-mail local que captura as mensagens sem enviá-las de verdade. Acesse `http://localhost:8025` para ver os e-mails capturados. ```bash theme={null} # Desenvolvimento com Mailhog (padrão — não precisa alterar) SMTP_ADDRESS=mailhog SMTP_PORT=1025 SMTP_DOMAIN=evoai-community.local SMTP_AUTHENTICATION=plain SMTP_ENABLE_STARTTLS_AUTO=false SMTP_USERNAME= SMTP_PASSWORD= MAILER_SENDER_EMAIL=noreply@evoai-community.local ``` Para produção, substitua pelos dados do seu provedor de e-mail: ```bash theme={null} SMTP_ADDRESS=smtp.seudominio.com SMTP_PORT=587 SMTP_DOMAIN=seudominio.com SMTP_AUTHENTICATION=plain SMTP_ENABLE_STARTTLS_AUTO=true SMTP_USERNAME=noreply@seudominio.com SMTP_PASSWORD=sua_senha_smtp MAILER_SENDER_EMAIL=noreply@seudominio.com ``` ### Configuração via UI em runtime (a partir do v1.0.0-rc3) A partir do `v1.0.0-rc3` (EVO-1049), as configurações de SMTP, **BMS** e **Resend** podem ser alteradas via UI no painel `/settings/admin` e são aplicadas **em runtime**, sem reiniciar o container. Antes era necessário restart para que mudanças refletissem. Isso significa que você pode: * Manter `.env` apenas com defaults (ou nem configurar SMTP no `.env`, deixando vazio). * Configurar credenciais de produção pela UI após o boot. * Trocar provedor (de SMTP para Resend, por exemplo) sem downtime. > O acesso ao painel `/settings/admin` é exclusivo do papel `super_admin` — o operador da instalação, separado do `account_owner`. *** ## Licensing e Operador A partir do `v1.0.0-rc3`, o `.env.example` documenta a variável de operador: ```bash theme={null} # E-mail do operador da instalação (usado em eventos de licensing) EVOLUTION_OPERATOR_EMAIL=ops@seudominio.com ``` Este e-mail é referência para auto-ativação e telemetria. Para detalhes, ver [Licensing](/licensing). *** ## Canais opcionais Essas variáveis ficam comentadas no `.env.example` e só precisam ser configuradas se você for usar os respectivos canais. ```bash theme={null} # WhatsApp Cloud API WP_APP_ID=seu_app_id WP_VERIFY_TOKEN=seu_token_de_verificacao WP_APP_SECRET=seu_app_secret # Facebook Messenger FB_APP_SECRET=seu_app_secret FB_APP_ID=seu_app_id # Google OAuth (integração com Gmail) GOOGLE_OAUTH_CLIENT_ID=seu_client_id GOOGLE_OAUTH_CLIENT_SECRET=seu_client_secret # Slack SLACK_CLIENT_ID=seu_client_id SLACK_CLIENT_SECRET=seu_client_secret ``` *** ## Dicas de segurança * **Nunca envie o arquivo `.env` para o GitHub ou GitLab.** Ele já está no `.gitignore` por padrão. * O arquivo `.env.example` é seguro para versionar — ele contém apenas exemplos sem dados reais. * Em produção, gere valores únicos para `SECRET_KEY_BASE`, `JWT_SECRET_KEY`, `ENCRYPTION_KEY` e `EVOAI_CRM_API_TOKEN`. * Use senhas fortes e únicas para `POSTGRES_PASSWORD` e `REDIS_PASSWORD`. *** ## Solução de problemas ### Banco de dados não conecta Se após o `make setup` você vir erros de conexão: 1. Verifique se os containers estão rodando: `make status` 2. Confira os valores de `POSTGRES_HOST`, `POSTGRES_USERNAME` e `POSTGRES_PASSWORD` no `.env` 3. Para banco em nuvem, verifique se o acesso externo está liberado no painel do provedor ### E-mail não está sendo enviado Em desenvolvimento, os e-mails não são enviados de verdade — ficam retidos no Mailhog. Acesse `http://localhost:8025` para visualizá-los. ### Serviço não sobe após o setup ```bash theme={null} # Ver logs de um serviço específico make logs SERVICE=evo-crm # Ver todos os logs de uma vez make logs ``` Os logs mostram exatamente qual variável está faltando ou com valor incorreto. # VPS HostGator + Evo CRM Source: https://docs.evolutionfoundation.com.br/self-hosted/hostgator-evo-crm O futuro do atendimento com IA — Servidor VPS HostGator com Evo CRM pré-instalado ## O futuro do atendimento com IA já chegou Crie agentes inteligentes, automatize seu atendimento no WhatsApp com a API oficial e escale seus resultados nos seus principais canais de venda — com o **Evo CRM pré-instalado** no seu servidor VPS HostGator. **A partir de R\$ 45,49/mês** — Evo CRM pré-instalado, provisionamento instantâneo e 30 dias para reembolso. ## Por que escolher VPS HostGator com Evo CRM? ### Automação com IA que vende de verdade Agentes inteligentes respondem continuamente nos seus canais de venda, sem parar. Configure uma vez e deixe a IA trabalhar por você. ### Atendimento multicanal unificado Centralize WhatsApp, Instagram, Telegram e outros canais em uma única plataforma, com histórico completo e contexto para cada conversa. ### Sem conhecimento técnico necessário Interface simples e intuitiva, sem necessidade de programação. O Evo CRM já vem pré-instalado e pronto para usar logo após a contratação. ## Planos disponíveis Os planos do Evo CRM começam no **VPS NVMe 8** para garantir a performance adequada para a plataforma. Você pode parcelar em até **12x no cartão**. | Plano | vCPU | RAM | Armazenamento | Preço inicial | | -------------- | ---- | ---------- | ------------- | ------------- | | VPS NVMe 8 ⭐ | 4 | 8 GB DDR5 | 200 GB NVMe | R\$ 45,49/mês | | VPS NVMe 12 | 4 | 12 GB DDR5 | 300 GB NVMe | Consultar | | VPS NVMe 16 | 6 | 16 GB DDR5 | 400 GB NVMe | Consultar | | VPS NVMe 32 🏆 | 8 | 32 GB DDR5 | 500 GB NVMe | Consultar | ⭐ **VPS NVMe 8** é o plano recomendado para começar. 🏆 **VPS NVMe 32** é ideal para operações de alto volume com múltiplas equipes. ## O que está incluso em todos os planos Pronto para usar imediatamente após a contratação. Sem necessidade de configuração manual da aplicação ou instalação de dependências. Processadores **AMD Epyc**, memória **RAM DDR5** e discos **NVMe** de alta performance. Servidores Cloud localizados no **Brasil**. **Transferência de dados ilimitada**, **1 IP dedicado** por plano, **acesso root** completo e **segurança reforçada**. **Suporte especializado com fila prioritária** para clientes Evolution. **Migração grátis** do seu projeto atual. **Provisionamento instantâneo**. ## Principais funcionalidades do Evo CRM Crie agentes inteligentes que respondem automaticamente 24 horas nos seus canais de venda Acompanhe e gerencie leads em um funil de vendas visual com automações integradas WhatsApp, Instagram, Telegram e mais — tudo em uma única caixa de entrada Respostas em áudio natural geradas por IA para interações mais humanas Conecte com mais de 20 plataformas e ferramentas do seu ecossistema IA responde automaticamente; humanos assumem quando necessário com contexto completo ## Perguntas frequentes É uma plataforma de atendimento com IA que automatiza conversas no WhatsApp e outros canais. Permite criar agentes inteligentes, gerenciar leads e centralizar toda a comunicação com clientes em um único lugar. Não. O Evo CRM tem uma interface simples e intuitiva, sem necessidade de programação. O servidor já vem com tudo pré-instalado. Não. O Evo CRM integra WhatsApp, Instagram, Telegram e outros canais em uma plataforma unificada. Sim. O Evo CRM suporta atendimento híbrido: a IA responde automaticamente e, quando necessário, um humano pode assumir a conversa com contexto completo do histórico. O Evo CRM é uma plataforma completa com múltiplos serviços rodando simultaneamente (CRM, Auth, Frontend, Processor e Core). O VPS NVMe 8 garante recursos suficientes para uma operação estável e performática. ## Comece agora Aproveite — servidores VPS com até 73% OFF por tempo limitado. Evo CRM pré-instalado, provisionamento instantâneo e 30 dias para reembolso. # Bem-vindo ao Guia de Instalação do Evo CRM Community Source: https://docs.evolutionfoundation.com.br/self-hosted/index O **Evo CRM Community** é a versão gratuita e open-source do Evo CRM. Você instala tudo no seu próprio servidor — os dados ficam com você, sem mensalidades e sem limites de uso. **Prefere não se preocupar com servidor?** Contrate um VPS com o Evo CRM já pré-instalado e pronto para usar em minutos. [Ver planos HostGator + Evo CRM →](/infraestrutura/hostgator-evo-crm) A plataforma é formada por 5 serviços que trabalham juntos: | Serviço | O que faz | Porta | | ------------------------------- | ------------------------------------------------ | ----- | | `evo-auth-service-community` | Cuida do login e das permissões de acesso | 3001 | | `evo-ai-crm-community` | Gerencia conversas, contatos e caixas de entrada | 3000 | | `evo-ai-frontend-community` | A interface visual que você usa no navegador | 5173 | | `evo-ai-processor-community` | Executa os agentes de IA | 8000 | | `evo-ai-core-service-community` | Gerencia agentes, pastas e chaves de API | 5555 | Esta edição não tem painel de administração global, planos de cobrança ou suporte a múltiplas contas. É simples por design. *** ## Antes de Começar Você vai precisar de três ferramentas instaladas na sua máquina: * **Docker** e **Docker Compose** — criam e gerenciam os containers onde cada serviço roda. [Clique aqui para instalar](https://docs.docker.com/get-docker/) * **Git** — baixa o código do projeto. [Clique aqui para instalar](https://git-scm.com/) * **make** — simplifica a execução de comandos. Geralmente já vem instalado no Linux e macOS. [Clique aqui para instalar](https://www.gnu.org/software/make/) *** ## Passo a Passo ### Passo 1 — Baixe o projeto Abra o terminal e execute: ```bash theme={null} git clone --recurse-submodules git@github.com:evolution-foundation/evo-crm-community.git cd evo-crm-community ``` Esse comando baixa o repositório principal **e** todos os serviços que compõem a plataforma de uma só vez. Se você já clonou o repositório antes sem a flag `--recurse-submodules`, rode este comando para baixar os serviços que faltaram: ```bash theme={null} git submodule update --init --recursive ``` ### Passo 2 — Atualize os serviços para a versão mais recente ```bash theme={null} git submodule update --remote --merge ``` Isso garante que cada serviço está na versão mais atual. Faça isso sempre que quiser atualizar a plataforma. ### Passo 3 — Escolha onde o banco de dados vai rodar Antes de configurar o `.env`, decida onde o banco de dados ficará hospedado. Há três opções: #### Opção A — Docker (padrão, recomendado para começar) Não precisa fazer nada. O Docker Compose já sobe um PostgreSQL automaticamente. Pule direto para o **Passo 4**. #### Opção B — PostgreSQL instalado localmente Prefere instalar o PostgreSQL direto na sua máquina? Use a versão **16 ou superior** com a extensão **pgVector** habilitada. | Sistema | Como instalar | | ----------- | --------------------------------------------------------------------- | | **Linux** | [Guia oficial para Linux](https://www.postgresql.org/download/linux/) | | **macOS** | [Postgres.app](https://postgresapp.com/) — a forma mais simples | | **Windows** | [Instalador oficial](https://www.postgresql.org/download/windows/) | Depois de instalar, habilite o pgVector no banco: ```sql theme={null} CREATE EXTENSION IF NOT EXISTS vector; ``` #### Opção C — Banco de dados na nuvem Você também pode usar um serviço gerenciado. Veja as opções compatíveis: | Provedor | pgVector nativo | Documentação oficial | | -------------------- | :-------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Supabase** | ✅ | [supabase.com/docs/…/pgvector](https://supabase.com/docs/guides/database/extensions/pgvector) | | **Neon** | ✅ | [neon.tech/docs/…/pgvector](https://neon.tech/docs/extensions/pgvector) | | **AWS RDS** | ✅ | [docs.aws.amazon.com/…/PostgreSQL.ExtensionsAndModules](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/PostgreSQL.ExtensionsAndModules.html) | | **Google Cloud SQL** | ✅ | [cloud.google.com/sql/docs/…/extensions](https://cloud.google.com/sql/docs/postgres/extensions) | | **Azure PostgreSQL** | ✅ | [learn.microsoft.com/…/how-to-use-pgvector](https://learn.microsoft.com/azure/postgresql/flexible-server/how-to-use-pgvector) | | **Railway** | ✅ | [docs.railway.app/databases/postgresql](https://docs.railway.app/databases/postgresql) | **Se você escolheu a Opção B ou C**, após criar o banco ajuste estas 5 variáveis no `.env` (Passo 4): ```env theme={null} DB_HOST=localhost # Endereço do servidor de banco de dados DB_PORT=5432 # Porta padrão do PostgreSQL DB_NAME=evo_crm # Nome do banco que você criou DB_USER=seu_usuario # Usuário do banco DB_PASSWORD=sua_senha # Senha do banco ``` O Evo CRM Community **não é compatível** com MySQL, MariaDB ou SQLite. Use sempre PostgreSQL 16 ou superior com a extensão pgVector habilitada. ### Passo 4 — Configure as variáveis de ambiente ```bash theme={null} cp .env.example .env ``` Esse comando cria o arquivo `.env` a partir de um modelo pronto. Abra-o com qualquer editor de texto e ajuste as configurações para o seu ambiente. Se você ficou com a **Opção A (Docker)**, os valores padrão já funcionam. Não precisa alterar nada por enquanto. ### Passo 5 — Execute o setup ```bash theme={null} make setup ``` Esse único comando cuida de tudo, na ordem certa: 1. Constrói as imagens Docker de todos os serviços 2. Sobe o banco de dados e aguarda ele estar pronto 3. Cria as tabelas e popula os dados iniciais 4. Inicia todos os serviços Na primeira execução, o processo pode levar **de 15 a 20 minutos**. O Docker precisa baixar e compilar todas as imagens. Nas próximas vezes será muito mais rápido. ### Passo 6 — Acesse a plataforma Quando o setup terminar, abra o navegador e acesse: ``` http://localhost:5173 ``` A plataforma está pronta para uso. *** ## Serviços disponíveis | Interface | Endereço | | ---------------- | ----------------------- | | Frontend | `http://localhost:5173` | | CRM API | `http://localhost:3000` | | Auth API | `http://localhost:3001` | | Processor API | `http://localhost:8000` | | Core API | `http://localhost:5555` | | Mailhog (e-mail) | `http://localhost:8025` | *** ## Comandos do dia a dia Após o setup, use estes comandos para gerenciar a plataforma: | Comando | O que faz | | ------------------------ | --------------------------------------------------------------- | | `make start` | Liga todos os serviços | | `make stop` | Desliga todos os serviços | | `make restart` | Reinicia todos os serviços | | `make status` | Mostra quais containers estão rodando | | `make logs` | Exibe os logs de todos os serviços em tempo real | | `make logs SERVICE=nome` | Filtra os logs de um serviço específico (ex: `SERVICE=evo-crm`) | | `make build` | Reconstrói todas as imagens do zero (sem cache) | | `make seed` | Repopula os dados iniciais do banco | | `make shell-auth` | Abre um terminal dentro do container do Auth | | `make shell-crm` | Abre um terminal dentro do container do CRM | | `make shell-core` | Abre um terminal dentro do container do Core | | `make shell-processor` | Abre um terminal dentro do container do Processor | | `make clean` | Para tudo e **apaga todos os dados permanentemente** | `make clean` não tem volta. Ele remove o banco de dados, o cache e todos os arquivos gerados. Use somente se quiser começar do zero. *** ## Próximos passos Acesse pela primeira vez e configure sua conta Conecte WhatsApp, e-mail, Telegram e outros canais Crie e configure seus agentes de atendimento com IA Referência completa de todas as variáveis disponíveis *** ## Precisa de ajuda? * **GitHub**: [evolution-foundation/evo-crm-community](https://github.com/evolution-foundation/evo-crm-community) * **Comunidade**: [evolutionfoundation.com.br/community](https://evolutionfoundation.com.br/community) * **Issues**: Encontrou um problema? Abra uma issue no repositório do serviço correspondente # Configuração do Agente Source: https://docs.evolutionfoundation.com.br/user-guides/agents/agent-configuration Após criar um agente, é possível ajustar seu comportamento, conectar recursos externos e configurar capacidades avançadas.\ Este guia descreve todas as opções disponíveis na tela de **Configuração do Agente**, acessível ao editar um agente existente. *** ## Acessando a Configuração do Agente Na tela de Agents, você visualiza todos os agentes criados no workspace. **Elementos principais:** * **Lista de Agents**: cards contendo nome do agente, tipo (LLM), modelo e status * **Menu de ações (⋯ Actions)**: aparece ao passar o mouse sobre o card do agente * **Edit**: abre a tela de configuração do agente selecionado * **Delete**: remove permanentemente o agente **Passo a passo:** 1. Localize o agente desejado 2. Clique em **⋯ Actions** 3. Clique em **Edit** para configurar Visão geral da tela de Agents *** ## Profile – Informações Básicas do Agente A seção **Profile** é responsável por definir quem é o agente e como ele se comporta. Perfil do agente **Campos disponíveis:** * **Agent name**: Nome interno do agente (ex.: assistente\_de\_vendas) * **Description**: Descrição curta do propósito do agente * **Role**: Papel do agente na conversa (ex.: Assistente de suporte ao cliente) * **Goal**: Objetivo principal do agente (ex.: Resolver dúvidas dos clientes) * **Behavior**: Define o tom e a personalidade do agente (ex.: Você é um assistente especialista em vendas) **Botões:** * **Review Prompt**: permite revisar o prompt final gerado * **Generate with AI**: gera automaticamente o comportamento * **Test your agent**: abre um chat de teste * **Save**: salva todas as alterações *** ## Sub Agents – Composição de Agentes A seção **Sub Agents** permite que um agente execute outros agentes como parte do fluxo. Adicionando sub-agents **Componentes:** * **No sub-agent selected**: indica que nenhum subagente foi adicionado * **Available Agents**: lista de agentes disponíveis * **Search Agents**: campo de busca * **Add**: adiciona o agente selecionado como subagente **Passo a passo:** 1. Clique em **Sub Agents** no menu lateral 2. Busque o agente desejado 3. Clique em **Add** 4. Salve as alterações *** ## Knowledge – Base de Conhecimento e Memória A seção **Knowledge** permite que o agente acesse informações armazenadas em bases de conhecimento e utilize memória de conversas anteriores. Essa funcionalidade é essencial para que o agente forneça respostas contextualizadas e personalizadas. Visão geral da seção Knowledge ### Load Knowledge – Carregando Base de Conhecimento Configuração de Load Knowledge A funcionalidade **Load Knowledge** permite que o agente acesse documentos, arquivos e informações previamente carregadas em uma base de conhecimento vetorial. **Configurações disponíveis:** * **Toggle Load Knowledge**: Ativa ou desativa o uso da base de conhecimento pelo agente * **Knowledge Base**: Seleciona qual base de conhecimento será utilizada (ex.: evoai via Pinecone) * **Preload Knowledge**: Opção de otimização que carrega o conhecimento antes da consulta * **Maximum Results**: Define a quantidade máxima de resultados retornados da base de conhecimento * **Knowledge Tags**: Permite filtrar o conhecimento por tags específicas (ex.: Vendas, Suporte, Produto) **Como funciona:** Quando ativado, o agente busca automaticamente informações relevantes na base de conhecimento antes de responder ao usuário. Isso permite que ele acesse documentos técnicos, manuais, políticas da empresa e outros conteúdos relevantes sem precisar ter essas informações diretamente em suas instruções. ### Load Memory – Gerenciando Memória de Conversas Configuração de Load Memory A funcionalidade **Load Memory** permite que o agente mantenha o contexto de conversas anteriores, tornando as interações mais naturais e contextualizadas. **Configurações disponíveis:** * **Toggle Load Memory**: Ativa ou desativa o uso de memória pelo agente * **Memory Base**: Seleciona onde a memória será armazenada (ex.: evoai via Pinecone) * **Maximum Messages in Short-Term Memory**: Define quantas mensagens recentes o agente mantém em memória de curto prazo * **Compression Interval for Medium-Term Memory**: Define após quantas mensagens ocorre a compactação para memória de médio prazo **Como funciona:** O sistema de memória funciona em níveis: * **Memória de Curto Prazo**: Mantém as mensagens mais recentes completas para contexto imediato * **Memória de Médio Prazo**: Compacta mensagens antigas em resumos, mantendo informações importantes sem ocupar muito espaço * **Memória de Longo Prazo**: Armazena informações relevantes que podem ser recuperadas em conversas futuras **Limpeza de Memória:** * **Clear All Memory**: Remove toda a memória armazenada do agente. Use com cuidado, pois essa ação é irreversível. *** ## Tools – Ferramentas do Agente A seção **Tools** define quais ferramentas o agente pode utilizar durante as conversas. Visão geral da seção Tools ### Agent Tools Configuração de Agent Tools Permite selecionar outros agentes como ferramentas que podem ser chamadas durante a execução. **Como adicionar:** 1. Clique em **Add** na seção Agent Tools 2. Selecione os agentes desejados da lista **Opções:** * Lista de agentes disponíveis com checkbox para seleção * **Confirm**: confirma a escolha dos agentes * **Cancel**: fecha sem salvar ### Custom Tools Custom Tools Permite criar ferramentas HTTP customizadas para integrar com APIs externas. **Opções:** * **Add Tool**: Cria ferramentas HTTP customizadas * **Create**: Inicia o processo de criação de uma nova ferramenta ### Native Tools (a partir do v1.0.0-rc3) Tools nativas embarcadas no processor que ficam disponíveis sem precisar configurar HTTP custom. Aparecem automaticamente quando o pré-requisito está satisfeito: | Tool | Pré-requisito | O que faz | | ------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `knowledge_nexus_search` | Pelo menos um space Nexus vinculado ao agente | Busca semântica em spaces do Evo Nexus. Ver [Knowledge Nexus](/user-guides/agents/knowledge-nexus). | | `manage_conversation_labels` | Toggle "Permitir gerenciar labels" ativo no agente | Permite ao agente listar, adicionar e remover labels da conversa em andamento. | | `link_product_to_pipeline_item` | Pelo menos um produto vinculado ao agente | Permite ao agente vincular um produto do catálogo ao item de pipeline ativo. Ver [Produtos](/user-guides/products/overview). | Hints de uso de pipeline manipulation e label management são automaticamente injetados no system prompt quando essas tools estão ativas, orientando o LLM sobre quando chamá-las. ### Toggle "Permitir gerenciar labels" A partir do `v1.0.0-rc3`, a configuração do agente expõe o toggle **Permitir gerenciar labels** (`allow_manage_labels`). Quando ativo: * O agente recebe a tool `manage_conversation_labels`. * O agente pode adicionar/remover labels durante a conversa. Quando inativo, a tool não é exposta — o agente não tem como tagear conversas. *** ## Produtos – Catálogo Vinculado (a partir do v1.0.0-rc3) Na aba **Produtos** do agente, selecione quais itens do catálogo o agente deve conhecer. Os produtos vinculados são injetados no contexto do agente em runtime — mudanças no catálogo refletem na próxima conversa sem reconfigurar o prompt. Apenas produtos com status `ativo` ficam disponíveis para vinculação. Ver [Catálogo de Produtos](/user-guides/products/overview). *** ## Integrations – Integrações Externas A seção **Integrations** permite conectar o agente a serviços externos. Integrações disponíveis **Integrações disponíveis:** * **ElevenLabs**: Permite que o agente gere respostas em áudio usando síntese de voz. Botão: **ACTIVATE** * **Google Calendar**: Permite criar, visualizar e gerenciar eventos no calendário. Botão: **ACTIVATE** * **Google Sheets**: Permite criar, ler e atualizar planilhas do Google. Botão: **ACTIVATE** Configuração de integração **Configuração de Integrações:** Ao ativar uma integração, será necessário fornecer: * **API Key**: Chave de autenticação do serviço externo * **Apply Settings**: Salva a configuração da integração *** ## MCP Servers – Servidores MCP A seção **MCP Servers** permite conectar servidores MCP (Model Context Protocol), que expandem as capacidades do agente. Lista de integrações MCP **Integrações MCP disponíveis:** GitHub, Notion, Stripe, HubSpot, Linear, Monday.com, PayPal, Canva.\ **Status atual**: Todas exibidas como **Coming soon**. Custom MCPs **Custom MCPs:** * **Add Custom MCP**: Adiciona um servidor MCP criado previamente * **Add MCP Server**: Cria um novo servidor MCP personalizado Adicionar MCP Server **Select Custom MCPs:** * Campo de busca para filtrar MCPs * Mensagem **No MCP server configured** quando não há MCPs configurados * Botão **Add MCP Server** para adicionar novo servidor *** ## Configuration – Configurações Avançadas do Agente A seção **Configuration** é onde você define os ajustes técnicos e comportamentais do agente. Esta seção está dividida em quatro abas principais: **General**, **System**, **Message Handling** e **Inactivity Actions**. Visão geral da tela de Configuration *** ## Aba General – Configurações Gerais A aba **General** contém as configurações fundamentais que definem como o agente processa e responde às solicitações. ### Model and API – Modelo de IA e Chave de API Configuração de Model and API Esta seção define qual modelo de inteligência artificial será utilizado pelo agente e qual chave de autenticação será usada para acessar esse modelo. **Campos disponíveis:** * **API Key**: Selecione a chave de API que o agente utilizará para se conectar ao provedor de IA. A chave selecionada determina quais modelos estarão disponíveis para escolha * **Language Model**: Escolha o modelo de linguagem específico (exemplos: GPT-4.1 Nano, GPT-4, Claude 3.5 Sonnet, etc.). Cada modelo possui características diferentes de velocidade, custo e capacidade * **Manage**: Botão que abre o gerenciador de chaves de API, permitindo adicionar, editar ou remover chaves **Por que isso é importante:** A escolha do modelo afeta diretamente a qualidade das respostas, o tempo de processamento e o custo de operação do agente. Modelos mais avançados tendem a fornecer respostas mais precisas, mas podem ter custos mais elevados. *** ### Agent Capabilities – Capacidades Avançadas Agent Capabilities Esta seção ativa funcionalidades especiais que expandem as capacidades do agente. **Opções disponíveis:** * **Planner** (toggle): Quando ativado, o agente executa um processo de planejamento antes de responder. Isso significa que ele primeiro analisa a solicitação, cria um plano de ação e depois executa esse plano passo a passo. Essa capacidade melhora significativamente a qualidade das respostas em tarefas complexas que exigem múltiplas etapas ou raciocínio estruturado. **Quando usar o Planner:** * Tarefas que exigem múltiplos passos * Análises complexas que precisam de estruturação * Situações onde é importante o agente "pensar" antes de agir *** ### Output Format – Formato de Saída Estruturado Output Format O **Output Format** permite definir um esquema estruturado para as respostas do agente, garantindo que ele sempre retorne dados em um formato consistente e previsível. **Configurações básicas:** * **Output Key**: Identificador único que será usado para referenciar a saída deste agente. Útil quando você tem múltiplos agentes e precisa identificar qual está retornando os dados * **Output Schema**: Define a estrutura de dados que o agente deve retornar **Structured Schema – Criando o Esquema de Saída:** Configuração detalhada do Output Schema O esquema estruturado permite definir exatamente quais campos o agente deve retornar e em que formato. **Como configurar:** 1. Clique em **First Field** ou **Add Field** para adicionar um novo campo ao esquema 2. Para cada campo, defina: * **Field Name**: Nome do campo (ex.: "nome\_cliente", "valor\_total", "status") * **Type**: Tipo de dado do campo: * **String**: Texto (ex.: "João Silva", "Aprovado") * **Number**: Número (ex.: 150.50, 42) * **Boolean**: Verdadeiro ou falso (ex.: true, false) * **Array**: Lista de valores (ex.: \["item1", "item2", "item3"]) * **Object**: Estrutura complexa com múltiplos campos * **Description**: Descreva o propósito do campo para que o agente entenda o que deve incluir ali 3. Use os botões **Edit**, **Remove** ou **Save** para gerenciar os campos criados **Exemplo de uso:** Se você está criando um agente de vendas, pode definir um esquema como: * **nome\_cliente** (String): Nome completo do cliente * **email** (String): E-mail de contato * **valor\_orcamento** (Number): Valor total do orçamento * **produtos\_interesse** (Array): Lista de produtos que o cliente demonstrou interesse * **status\_negociacao** (String): Status atual da negociação **Por que usar Output Format:** * **Integração com sistemas**: Facilita a integração do agente com CRMs, ERPs e outros sistemas * **Consistência**: Garante que os dados sempre virão no mesmo formato * **Automação**: Permite automatizar processos baseados nas respostas estruturadas do agente * **Análise de dados**: Facilita a análise e relatórios sobre as interações *** ## Aba System – Comportamento e Permissões A aba **System** controla as permissões e o comportamento do agente dentro do sistema durante as conversas. Configurações da aba System ### Conversation Behavior – Comportamento em Conversas Define o que o agente pode ou não fazer durante as interações com os usuários. **Permissões disponíveis:** * **Transfer to human**: Quando ativado, permite que o agente identifique situações onde é necessário transferir a conversa para um atendente humano. O agente pode fazer isso automaticamente quando detecta frustração do cliente, solicitações complexas que não consegue resolver, ou quando o usuário pede explicitamente para falar com uma pessoa. * **Allow registering reminders**: Permite que o agente crie lembretes e agendamentos. Por exemplo, se um cliente pede para ser lembrado sobre uma promoção no próximo mês, o agente pode registrar esse lembrete automaticamente. * **Allow editing contacts**: Concede ao agente a permissão para modificar informações de contatos, como atualizar números de telefone, e-mails, endereços ou outras informações cadastrais quando o usuário fornece novos dados. * **Allow pipeline manipulation**: Permite que o agente mova contatos entre diferentes etapas do pipeline de vendas ou atendimento. Por exemplo, mover um lead de "Primeiro Contato" para "Negociação" ou de "Qualificação" para "Proposta Enviada". **Dica de segurança:** Ative apenas as permissões que o agente realmente precisa. Se o agente é apenas informativo, não é necessário permitir edição de contatos ou manipulação de pipeline. ### Agent Timezone – Fuso Horário do Agente Define o fuso horário que o agente utilizará para todos os cálculos de data e hora. **Configuração:** * Selecione o fuso horário apropriado para sua operação * Exemplo: **America/Sao\_Paulo (GMT-3)** para o horário de Brasília **Por que isso é importante:** O fuso horário correto garante que: * Lembretes sejam enviados no horário certo * Relatórios mostrem os horários corretamente * Agendamentos sejam feitos considerando o horário local do negócio *** ## Aba Message Handling – Tratamento de Mensagens A aba **Message Handling** define como o agente processa, formata e envia suas mensagens. Configurações de Message Handling ### Configurações de Processamento e Envio **Message Wait Time (seconds) – Tempo de Espera:** Define quantos segundos o agente deve aguardar antes de processar e responder a uma mensagem. * **Quando usar**: Útil quando os usuários costumam enviar múltiplas mensagens seguidas. Em vez de responder a cada mensagem individualmente, o agente aguarda o tempo configurado e responde considerando todas as mensagens enviadas no período. * **Exemplo**: Se configurado para 3 segundos e o usuário envia "Quero", "comprar", "um notebook", o agente aguarda 3 segundos e processa as três mensagens juntas, entendendo a solicitação completa. **Message Signature – Assinatura de Mensagem:** Texto que será automaticamente adicionado ao final de cada mensagem enviada pelo agente. * **Uso comum**: Adicionar informações de contato, horário de atendimento ou disclaimers * **Exemplo**: "Esta é uma mensagem automática. Para falar com um atendente, digite 'falar com humano'." **Enable text segmentation – Segmentação de Texto:** Quando ativado, o agente divide mensagens longas em múltiplas mensagens menores. * **Vantagem**: Melhora a legibilidade, especialmente em dispositivos móveis * **Comportamento**: Uma resposta longa é dividida em parágrafos ou tópicos separados **Use Emojis in Responses – Uso de Emojis:** Permite que o agente inclua emojis em suas respostas para torná-las mais amigáveis e expressivas. * **Quando ativar**: Canais informais como WhatsApp, Instagram * **Quando desativar**: Comunicações corporativas formais, e-mails profissionais **Send message as reply in conversation – Responder Mensagens Específicas:** Quando ativado, o agente responde diretamente a mensagens específicas usando o recurso de "responder" ou "quote" disponível na maioria das plataformas de mensagem. * **Vantagem**: Mantém o contexto claro, especialmente em conversas com múltiplas perguntas * **Exemplo**: Se o usuário faz três perguntas diferentes, o agente pode responder cada uma citando a pergunta específica *** ## Aba Inactivity Actions – Ações de Inatividade A aba **Inactivity Actions** permite configurar ações automáticas que o agente executará quando um usuário ficar inativo (não responder) por um determinado período. Configuração de Inactivity Actions ### Como Funciona Esta funcionalidade é essencial para manter o engajamento com os usuários e evitar que conversas importantes sejam esquecidas. **Estrutura da tela:** * Visualização de todas as regras de inatividade configuradas * Botão **+ Add previous action** para criar novas regras ### Criando uma Ação de Inatividade **Passo a passo:** 1. Clique em **+ Add previous action** 2. Configure os seguintes campos: **If not respond in – Se não responder em:** Define o tempo de inatividade que acionará a ação. * **Opções**: Minutos, horas ou dias * **Exemplo**: 2 minutes, 1 hour, 1 day, 3 days **the agent should – o agente deve:** Define qual ação será executada após o período de inatividade. * **Interact with client**: Enviar uma mensagem de reengajamento * **Send reminder**: Enviar um lembrete sobre algo pendente * **Close conversation**: Encerrar a conversa automaticamente * **Transfer to human**: Transferir para atendente humano * **Move in pipeline**: Mover para outra etapa do funil **What should the agent say? – O que o agente deve dizer:** Campo de texto livre onde você escreve a mensagem que será enviada. **Exemplos de mensagens:** * Para reengajamento: "Olá! Vi que você estava interessado em nossos produtos. Posso ajudar com algo mais?" * Para lembretes: "Oi! Lembre-se que nossa promoção termina amanhã. Deseja continuar com sua compra?" * Para qualificação: "Notei que você não respondeu. Ainda tem interesse em conhecer nossa solução?" 3. Clique em **Save** para salvar a regra ### Criando Múltiplas Regras em Cascata Você pode criar várias regras de inatividade com diferentes tempos para criar uma sequência de reengajamento. **Exemplo de estratégia:** 1. **2 minutos de inatividade**: "Você ainda está por aí? Posso esclarecer alguma dúvida?" 2. **1 hora de inatividade**: "Oi! Vi que conversamos mais cedo. Se precisar de ajuda, estou aqui!" 3. **1 dia de inatividade**: "Olá! Notei que você demonstrou interesse em \[produto]. Gostaria de retomar nossa conversa?" 4. **3 dias de inatividade**: "Esta é minha última tentativa de contato. Se desejar, podemos conversar futuramente. Até breve!" ### Boas Práticas * **Não seja invasivo**: Evite enviar muitas mensagens em curtos períodos * **Seja relevante**: Faça referência ao contexto da conversa anterior * **Ofereça valor**: Cada mensagem deve oferecer algo útil ao usuário * **Respeite limites**: Se o usuário não responde após várias tentativas, pare de enviar mensagens *** ## Considerações Finais A tela de **Configuração do Agente** é o centro de controle completo para personalizar o comportamento, conectar recursos externos e definir como o agente opera em diferentes cenários. **Recomendações importantes:** * Sempre clique em **Save** no canto superior direito após fazer alterações * Use **Test your agent** para validar o comportamento antes de colocar o agente em produção * Configure a base de conhecimento e memória para conversas mais contextualizadas * Ajuste as permissões do sistema de acordo com o nível de autonomia desejado para o agente * Defina ações de inatividade para manter o engajamento com os usuários Após configurar todas as seções, o agente estará pronto para uso em fluxos complexos, integrações e automações avançadas. # Criando um Agente Source: https://docs.evolutionfoundation.com.br/user-guides/agents/creating-agent Este guia descreve o processo completo para criar um novo agente de IA utilizando o assistente de criação (wizard). O fluxo é dividido em etapas sequenciais, permitindo configurar o nome, tipo, função, comportamento e modelo de IA que será utilizado pelo agente. *** ## Criando um Novo Agente Você pode criar um novo agente usando um dos botões **Novo Agente** disponíveis. Botão Novo Agente O botão **Novo Agente** está disponível em dois locais: * No canto superior direito da tela * No centro do estado vazio quando nenhum agente existe Clicar neste botão inicia o assistente de criação de agente. *** ## Iniciando a Criação de um Novo Agente Para iniciar a criação de um agente, acesse a seção **Agentes** e clique em **Novo Agente**. Isso abrirá o assistente de criação, que guia o processo em etapas. Início do assistente de criação de agente Nesta primeira etapa, você deve definir o nome do agente. ### Nome do agente O campo **What is your agent's name?** define o nome que será utilizado para identificar o agente dentro do workspace. * O nome é obrigatório * Ele será exibido na lista de agentes * Pode ser alterado posteriormente nas configurações avançadas Após preencher o nome, clique em **Continue** para avançar. *** ## Selecionando o Tipo de Agente Na etapa seguinte, você deve escolher o tipo de agente que melhor se adapta ao seu caso de uso. Seleção do tipo de agente Os tipos disponíveis determinam como o agente irá operar: * **LLM (Language Model)**: Agente conversacional baseado em modelos de linguagem (mais comum) * **Task**: Agente focado em automação de tarefas específicas * **Sequential**: Executa agentes em sequência * **Parallel**: Executa agentes em paralelo * **Loop**: Executa agentes em loop contínuo *** ## Tipo de Agente LLM Para agentes conversacionais, selecione a opção **LLM (Modelo de Linguagem)**. Tipo de agente LLM selecionado Esse tipo é o mais utilizado e indicado para assistentes virtuais, atendimento ao cliente, suporte técnico e agentes de vendas. Após selecionar o tipo, clique em **Continuar**. *** ## Definindo Função e Objetivo do Agente Nesta etapa, você define o papel do agente e seu principal objetivo. Definição de função e objetivo do agente ### Agent Role O campo **Agent Role** descreve a função do agente, ou seja, qual papel ele exerce (por exemplo: assistente de suporte, vendedor, analista). ### Main Goal O campo **Main Goal** define o objetivo principal do agente, descrevendo o que ele deve alcançar durante as interações. Esses campos ajudam a orientar o comportamento do agente, mas podem ser ajustados posteriormente. Esta etapa é opcional e pode ser ignorada clicando em **Skip**. *** ## Definindo Instruções do Agente A etapa de instruções define como o agente deve se comportar e responder. Instruções de comportamento do agente No campo **What does your agent do?**, descreva: * O comportamento esperado do agente * O tom de resposta (formal, amigável, técnico, etc.) * Limites e responsabilidades * Boas práticas de atendimento ou execução Quanto mais detalhadas forem as instruções, mais consistente será o comportamento do agente.\ Você pode usar os botões **Review Prompt** ou **Generate with AI** para revisar ou gerar sugestões automaticamente. *** ## Selecionando o Modelo de IA Nesta etapa, você define qual modelo de IA será utilizado pelo agente. Seleção de modelo de IA e gerenciamento de API Keys Antes de selecionar um modelo, é necessário configurar uma **API Key**. ### Gerenciando Chaves de API Clique em **Manage** para abrir o gerenciador de chaves de API. Gerenciar chaves de API Caso não exista nenhuma chave configurada, você pode clicar em **Add First Key** ou **New Key**. Adicionar nova chave de API Preencha os campos: * **Name**: Nome identificador da chave * **Provider**: Provedor do modelo (ex: OpenAI) * **Key**: Chave de API fornecida pelo provedor Clique em **Add** para salvar a chave. *** ## Escolhendo o Modelo de IA Após configurar a API Key, você poderá selecionar o modelo de IA. Seleção do modelo de IA No campo **Search or select a model**, escolha o modelo desejado (por exemplo: GPT-4.1, GPT-4.5 Preview, GPT-4o, entre outros). A lista exibida depende do provedor e da chave de API configurada. Clique em **Continue** para finalizar a criação. *** ## Agente Criado com Sucesso Após concluir todas as etapas, o agente será criado e estará pronto para uso. Agente criado com sucesso Nesta tela, você pode: * Ajustar configurações avançadas * Testar o agente em um chat * Adicionar ferramentas (Tools) * Retornar à lista de agentes A partir daqui, você pode avançar para configurações mais avançadas, como servidores MCP, ferramentas customizadas e bases de conhecimento. *** ## Considerações Finais O processo de criação de agentes foi projetado para ser rápido e intuitivo. Após a criação inicial, você pode refinar as configurações, adicionar ferramentas e bases de conhecimento para expandir as capacidades do agente. # Base de Conhecimento Source: https://docs.evolutionfoundation.com.br/user-guides/agents/knowledge-base A seção **Base de Conhecimento** permite gerenciar documentos e dados que serão usados para treinar e enriquecer seus agentes de IA. Nesta seção, você pode fazer upload de arquivos, adicionar conteúdo manualmente, indexar URLs, configurar provedores e testar buscas semânticas. *** ## Acessando a Seção Knowledge Use o menu de navegação principal para acessar a área Knowledge. Na barra lateral, clique em **Knowledge** para abrir a tela de gerenciamento de conhecimento. ## Tela Principal do Knowledge Após acessar a seção Knowledge, você verá a tela principal listando todos os documentos e fontes de dados disponíveis. Acessando a seção Knowledge Cada card representa um documento ou entrada de conteúdo indexado na base de conhecimento, incluindo seu status e tags. *** ## Editando uma Entrada de Conhecimento Existente Você pode editar um documento existente para atualizar seu título, descrição ou conteúdo. Clique no menu de três pontos no card do documento e selecione a opção de edição para abrir o modal de edição. Editando entrada de conhecimento *** ## Adicionando Novo Conteúdo à Base de Conhecimento Para adicionar novo conteúdo, use o botão **Add Content** disponível na tela do Knowledge. Clique em **Add Content** para abrir o modal de criação de conteúdo. O modal oferece três métodos diferentes para adicionar conhecimento: **Manual**, **Upload** e **URL**. Botão Add Content *** ## Adicionando Conteúdo Manualmente Você pode criar entradas de conhecimento digitando o conteúdo diretamente no editor. **Passo a passo:** 1. Clique em **Add Content** na tela do Knowledge 2. No modal que abrir, selecione a aba **Manual** 3. Preencha os campos disponíveis: Adicionando conteúdo manualmente **Campos disponíveis:** * **Knowledge Base**: Selecione qual base de conhecimento será usada. Se nenhuma for selecionada, será usada a configuração padrão da conta * **Title**: Título da entrada de conhecimento (ex.: "Como configurar o sistema") * **Description**: Descrição breve do conteúdo * **Content**: Conteúdo completo em formato de texto. Você pode usar Markdown para formatação * **Tags**: Tags para categorização e filtragem. Digite uma tag e pressione Enter para adicionar * **Active**: Toggle para ativar ou desativar a entrada 4. Após preencher todos os campos, clique em **Create** para salvar a entrada *** ## Adicionando Conteúdo via Upload de Arquivo Você pode fazer upload de documentos diretamente do seu computador. **Passo a passo:** 1. Clique em **Add Content** na tela do Knowledge 2. No modal que abrir, selecione a aba **Upload** 3. Arraste e solte um arquivo na área indicada ou clique em **Choose File** para selecionar um arquivo 4. O arquivo será processado e indexado automaticamente Upload de documento **Formatos suportados:** * **Documentos**: PDF, DOCX, XLSX, PPTX, HTML * **Texto**: TXT, MD, MDX * **Imagens**: PNG, JPG, JPEG, TIFF, BMP **Tamanho máximo**: 50MB *** ## Adicionando Conteúdo via URL Você também pode indexar conteúdo de uma URL pública. **Passo a passo:** 1. Clique em **Add Content** na tela do Knowledge 2. No modal que abrir, selecione a aba **URL** 3. Cole a URL da página ou documento online no campo indicado 4. Configure as opções disponíveis: Adicionando conhecimento via URL **Opções disponíveis:** * **Include Sub-pages**: Quando ativado, processa automaticamente páginas vinculadas * **Max Pages**: Limite de páginas para processar (1-50). Útil para controlar quantas páginas serão indexadas 5. Clique em **Process URL** para iniciar o processamento e adicionar o conteúdo à base de conhecimento *** ## Testando a Busca de Conhecimento Após adicionar conteúdo, você pode testar como o agente recuperará informações. Use esta funcionalidade para validar resultados de busca semântica com base em consultas e tags. **Configurações de teste:** * **Search Query**: Consulta de busca para testar * **Knowledge Base**: Seleciona qual base de conhecimento usar * **Tags**: Filtro opcional por tags * **Maximum Results**: Número máximo de resultados retornados Teste de busca de conhecimento *** ## Configurações da Base de Conhecimento Você pode configurar provedores e configurações de indexação para a base de conhecimento. Nesta tela, você pode gerenciar provedores como Pinecone ou Qdrant e controlar a ativação. Configurações do Knowledge *** ## Criando uma Nova Configuração de Conhecimento Você pode criar uma nova configuração de provedor para a base de conhecimento. **Configurações disponíveis:** * **Provider**: Seleciona o provedor (Pinecone, Qdrant, etc.) * **Name**: Nome da configuração * **Active**: Toggle para ativar/desativar * **Default**: Define como configuração padrão **Configurações do Pinecone:** * **API Key**: Chave de API do Pinecone * **Environment**: Ambiente do Pinecone (ex.: us-east-1-aws) * **Index Name (Knowledge)**: Nome do índice usado para conhecimento * **Index Name (Memory)**: Nome do índice usado para memória do agente * **Dimension**: Dimensão dos vetores (ex.: 1536) * **Metric**: Métrica de busca (Cosine, Euclidean, DotProduct) **Configurações de Busca:** * **Default Search Type**: Tipo de busca padrão (Hybrid, Vector, Text) * **Hybrid Alpha**: Controle do equilíbrio entre busca textual e semântica (0.0 = apenas texto, 1.0 = apenas semântica) **Configurações de Conexão:** * **Pool Threads**: Número de threads do pool * **Connection Pool Max Size**: Tamanho máximo do pool de conexões Preencha os detalhes do provedor, chaves de API, nomes de índices e configurações de busca, depois salve a configuração. Nova configuração de conhecimento *** ## Considerações Finais A Base de Conhecimento é essencial para permitir que os agentes respondam perguntas com base em seus documentos e dados. Sempre certifique-se de que o conteúdo está adequadamente indexado e testado antes de usá-lo em agentes de produção. **Dicas importantes:** * Teste sempre a busca semântica após adicionar novo conteúdo * Use tags para organizar e filtrar o conhecimento * Configure adequadamente os provedores para melhor performance * Mantenha o conteúdo atualizado e relevante * Use a funcionalidade de teste antes de ativar agentes em produção *** ## Alternativa: Knowledge Nexus (a partir do v1.0.0-rc3) Para times que mantêm uma base de conhecimento separada do CRM (wiki, docs vivos, conteúdo evoluindo continuamente), a partir do `v1.0.0-rc3` é possível vincular **Knowledge Nexus spaces** ao agente. A integração é complementar à Base de Conhecimento embutida — você pode usar os dois ao mesmo tempo no mesmo agente. Quando usar Nexus em vez (ou junto) da KB do CRM: * Sua organização já mantém base centralizada. * Conteúdo evolui frequentemente. * Múltiplos times consomem a mesma base. Para o passo a passo, ver [Integração com Knowledge Nexus](/user-guides/agents/knowledge-nexus). # Integração com Knowledge Nexus Source: https://docs.evolutionfoundation.com.br/user-guides/agents/knowledge-nexus A partir do `v1.0.0-rc3`, agentes de IA podem consultar **Knowledge Nexus spaces** diretamente do prompt, usando a tool nativa `knowledge_nexus_search`. Isso permite responder com base em documentação interna, FAQs e bases de conhecimento mantidas no Nexus, sem configurar tool customizada. > Para a base de conhecimento embutida do CRM (PDFs, arquivos colados manualmente), continue usando o módulo [Base de Conhecimento](/user-guides/agents/knowledge-base). Nexus é complementar — útil quando sua organização já mantém uma base de conhecimento separada e quer reaproveitá-la no agente. *** ## Pré-requisitos * Instalação do **Evo Nexus** acessível pela rede do CRM. * Pelo menos um **space** criado no Nexus com documentos indexados. * Permissão no seu papel para editar agentes (`agents.manage`). A conexão entre CRM e Nexus é configurada pelo operador da instalação (ver documentação do Evo Nexus). Como usuário do CRM, você consome a integração sem configurar credencial. *** ## Vinculando um Space ao Agente 1. Abra o detalhe de um agente em `Agentes → [nome do agente]`. 2. Vá até a seção **Integrações** → **Knowledge Nexus**. 3. Clique no seletor de spaces. O CRM consulta a API do Nexus (via proxy do core-service) e lista os spaces disponíveis. 4. Marque os spaces que esse agente deve poder consultar. 5. Salve. Você pode vincular múltiplos spaces a um mesmo agente — o agente decide qual consultar em cada momento, com base no contexto da pergunta. *** ## Como o agente usa o Nexus O agente recebe automaticamente uma tool chamada `knowledge_nexus_search` no seu vocabulário. Quando o usuário faz uma pergunta cuja resposta plausivelmente está na base, o LLM chama essa tool: ``` knowledge_nexus_search(query="política de troca após 30 dias", space="suporte") ``` A tool retorna os trechos mais relevantes indexados no space. O agente usa esses trechos para compor a resposta, citando o contexto quando apropriado. ### Comportamento esperado * **Resposta com base na fonte:** se o trecho encontrado responde diretamente, o agente cita a informação textualmente. * **Resposta com lacuna:** se a base não cobre o caso, o agente informa que não encontrou informação específica e pede mais contexto, em vez de inventar (com prompt bem calibrado). * **Resposta de retorno vazio:** se a busca não retorna nada, o agente continua a conversa sem citar a base. *** ## Quando usar Nexus vs Base de Conhecimento do CRM | Use **Nexus** quando | Use **KB do CRM** quando | | ------------------------------------------------- | --------------------------------------------- | | Sua organização já mantém base centralizada | Você quer uma KB exclusiva por agente | | Conteúdo evolui frequentemente (wiki, docs vivos) | Conteúdo estático (PDFs, manuais fixos) | | Múltiplos times consomem a mesma base | Conteúdo é específico de um único caso de uso | | Você quer separar gestão de conhecimento do CRM | Você quer manter tudo dentro do CRM | Não é exclusivo — você pode usar os dois ao mesmo tempo no mesmo agente. *** ## Diagnóstico Se o agente não está usando o Nexus apesar de estar vinculado: 1. **Confirme a vinculação.** Reabra o detalhe do agente; o space deve aparecer marcado. 2. **Cheque permissões.** O agente precisa ter `agents.read` sobre os recursos vinculados. 3. **Veja se o space tem documentos indexados.** Se o space está vazio ou ainda processando documentos, a tool retorna vazio. 4. **Reveja o prompt.** Se o system prompt do agente é muito rígido (ex.: "responda apenas com base no que sabe"), ele pode não chamar a tool. Ajuste o prompt para deixar explícito quando consultar a base externa. 5. **Logs do processor.** O serviço `evo-ai-processor-community` registra as chamadas a tools — útil quando você precisa confirmar se a tool foi de fato invocada. *** ## Considerações Finais A integração com Knowledge Nexus desacopla a gestão de conhecimento da gestão do CRM. Mantenha as bases atualizadas no lugar onde elas naturalmente vivem, e deixe o agente fazer a ponte na hora da conversa. # Servidores MCP Source: https://docs.evolutionfoundation.com.br/user-guides/agents/mcp-servers *Conteúdo em desenvolvimento* # Visão Geral dos Agentes Source: https://docs.evolutionfoundation.com.br/user-guides/agents/overview A seção **Agentes** permite gerenciar todos os agentes de IA disponíveis em seu workspace. Nesta tela, você pode visualizar agentes existentes, criar novos, exportar configurações e gerenciar chaves de API usadas pelos agentes para interagir com serviços externos. *** ## Acessando a Seção de Agentes Para acessar a área de Agentes, use o menu de navegação principal. Acessando a seção de agentes Na barra lateral, clique em **Agentes** para abrir a tela de gerenciamento de agentes. *** ## Tela Principal de Agentes Após acessar a seção, você verá a tela principal de Agentes. Tela principal de agentes Esta tela é responsável por listar todos os agentes criados e fornecer ações globais relacionadas ao gerenciamento de agentes. ### Elementos disponíveis nesta tela: * **Pesquisar agentes**: Permite pesquisar agentes por nome. * **Filtros**: Aplique filtros para refinar a lista de agentes. * **Área de lista de agentes**: Exibe todos os agentes existentes (ou um estado vazio se nenhum existir). * **Ações principais**: Criar agentes, gerenciar chaves de API ou exportar agentes. Se nenhum agente foi criado ainda, uma mensagem de estado vazio será exibida com um atalho para criar um novo agente. *** ## Gerenciando Chaves de API Os agentes podem exigir chaves de API para interagir com modelos ou serviços externos. Essas chaves podem ser gerenciadas diretamente na tela de Agentes. Gerenciar chaves de API Clique em **Gerenciar Chaves de API** para: * Criar novas chaves de API * Visualizar chaves existentes * Revogar ou rotacionar chaves quando necessário Essas chaves são usadas pelos agentes durante a execução e integrações. *** ## Exportando Agentes Você pode exportar todas as configurações dos agentes para fins de backup ou migração. Exportar agentes Clique em **Exportar Todos** para baixar os dados dos agentes. Esta ação exporta a configuração de todos os agentes existentes no workspace. *** ## Lista e Status dos Agentes Quando os agentes estão disponíveis, eles serão exibidos na área principal da lista. Lista de agentes com status Cada entrada de agente pode incluir: * **Nome do agente** * **Status** (ativo, inativo ou rascunho) * **Informações de criação ou última atualização** * **Ações de acesso rápido** (dependendo da configuração) Esta lista ajuda você a identificar rapidamente quais agentes estão disponíveis e prontos para uso. *** ## Considerações Finais A **Visão Geral dos Agentes** é o hub central para gerenciar agentes de IA. A partir daqui, você pode criar novos agentes, gerenciar chaves de acesso, exportar configurações e monitorar o estado geral de seus agentes antes de avançar para configurações avançadas como ferramentas, servidores MCP e bases de conhecimento. # Ferramentas Source: https://docs.evolutionfoundation.com.br/user-guides/agents/tools *Conteúdo em desenvolvimento* # Visão Geral de Automation Rules Source: https://docs.evolutionfoundation.com.br/user-guides/automation/overview O módulo **Automation Rules** permite definir regras `trigger → condition → action` que executam automaticamente em resposta a eventos do CRM. É a forma declarativa de codificar workflows operacionais — sem código, sem job customizado, sem precisar de scheduler externo. ### O modelo Toda regra de automação segue o mesmo formato: ``` QUANDO SE ENTÃO ``` ### Triggers suportados | Trigger | Quando dispara | | ----------------------------- | ------------------------------------------------------ | | `message_created` | Nova mensagem entra na conversa | | `conversation_created` | Conversa nova aberta | | `conversation_updated` | Atributos da conversa mudam | | `conversation_status_changed` | Status muda (`open`, `resolved`, `pending`, `snoozed`) | | `conversation_resolved` | Conversa marcada como resolvida (atalho do anterior) | | `pipeline_stage_updated` | Item de pipeline muda de estágio | | `label_added` | Label adicionada à conversa ou contato | | `attribute_changed` | Atributo customizado muda (com pickers From/To) | > Os triggers `conversation_resolved` e `conversation_status_changed` foram adicionados no `v1.0.0-rc3` (EVO-1057). O operador `attribute_changed` com pickers explícitos foi adicionado no mesmo release (EVO-1058). ### Conditions Conditions filtram o trigger antes de disparar a action. Suportam: * **Campos da conversa:** status, assignee, inbox, team, prioridade. * **Campos do contato:** atributos customizados, telefone, email, labels. * **Labels:** operadores `has` / `has-not` (em conversa OU contato). * **Atributo customizado mudou:** `attribute_changed` com seletores de valor **antes** e **depois**. * **Tipo de mensagem:** aceita keys (`incoming`, `outgoing`) ou valores numéricos. ### Actions disponíveis | Action | O que faz | | ---------------------------- | ---------------------------------------------------------------- | | `assign_agent` | Atribui a conversa a um agente humano | | `assign_team` | Atribui a um time | | `add_label` / `remove_label` | Manipula labels (resolve UUIDs para titles automaticamente) | | `set_priority` | Define prioridade | | `change_status` | Move para `open`, `resolved`, `pending`, `snoozed` | | `move_to_stage` | Move item de pipeline para outro estágio do mesmo pipeline | | `move_to_pipeline` | **(rc3)** Move item para um pipeline diferente, preservando o id | | `send_message` | Envia mensagem (texto livre) | | `send_canned_response` | Envia uma resposta pronta | | `send_template` | Envia um template de mensagem com variáveis | | `trigger_webhook` | Dispara webhook customizado | | `apply_macro` | Roda um macro existente | ### Garantias * **Dedup em janela de 5s** para `pipeline_stage_updated` por `(rule, pipeline_item, stage)` — evita disparo em rajada quando múltiplos eventos chegam quase simultâneos (rc3). * **Loop prevention** em stage automation — uma regra acionada por `move_to_stage` não dispara outra do mesmo tipo recursivamente. * **Macro webhook failures** são surfaceadas (não silenciosas) — você vê o erro na aba de logs. *** ## Permissões | Permissão | O que permite | | ------------------------- | -------------------------------------- | | `automation_rules.read` | Ver regras existentes e seus logs | | `automation_rules.manage` | Criar, editar, ativar/desativar regras | *** ## Próximos passos * Para criar e gerenciar regras, ver [Regras de Automação](/user-guides/automation/rules). * Para regras vinculadas a estágios de pipeline, ver [Gerenciando Pipelines](/user-guides/pipelines/managing-pipelines). # Regras de Automação Source: https://docs.evolutionfoundation.com.br/user-guides/automation/rules Este guia mostra como criar, gerenciar e diagnosticar regras de automação. Para o modelo conceitual (triggers, conditions, actions), ver [Visão Geral](/user-guides/automation/overview). *** ## Criando uma regra 1. Acesse `Configurações → Automação`. 2. Clique em **Nova Regra**. 3. Dê um **nome** descritivo (ex.: "Atribuir leads do WhatsApp ao time comercial"). 4. Escolha um **trigger** da lista. 5. (Opcional) Adicione **conditions** para filtrar quando a regra deve disparar. 6. Adicione uma ou mais **actions**. 7. Ative a regra. ### Dicas para nomes * Comece com o verbo da ação principal (`Atribuir...`, `Mover...`, `Etiquetar...`). * Inclua o contexto (canal, time, estágio) para que outros operadores entendam sem abrir o detalhe. * Evite nomes genéricos como "Regra 1" ou "Auto" — você vai acumular dezenas e precisa achá-las pela busca. *** ## Conditions e templates de mensagem Conditions usam o sistema de **variáveis de template** quando você precisa fazer comparações dinâmicas. A partir do `v1.0.0-rc3` (EVO-1146), as variáveis ganharam campos adicionais: * `label`, `source`, `example`, `position`, `component` Use esses campos nas conditions para expressões mais precisas. Por exemplo: filtrar por uma label específica usando o `label.title` resolvido em vez do UUID cru. ### Operador `attribute_changed` com From/To Quando você quer disparar regra apenas em uma transição específica de atributo (ex.: "status mudou de `aguardando` para `qualificado`"), use o operador `attribute_changed` com os pickers explícitos de valor **antes** e valor **depois**. *** ## Actions com payload dinâmico ### `send_template` Permite enviar um template de mensagem com variáveis preenchidas dinamicamente. O sistema usa `deep_stringify_keys` no payload para que a chamada funcione independente do shape das keys (string ou symbol). ### `send_canned_response` Atalho para enviar uma resposta pronta cadastrada em `Configurações → Respostas Prontas`. O payload aceita variáveis substituídas com dados da conversa. ### `move_to_pipeline` (rc3) Move o item de pipeline para outro pipeline preservando o `id` do item. Útil para regras tipo "se label `qualificado` foi adicionada no pipeline Leads, move para o pipeline Vendas". > A action faz bypass da validação de `same-pipeline` automaticamente. Não confunda com `move_to_stage`, que move dentro do mesmo pipeline. ### `apply_label` A partir do `v1.0.0-rc3`, a action exibe um **picker de labels** em vez de campo de texto livre. UUIDs são resolvidos para titles antes de tagear, com fallback caso a label tenha sido renomeada. *** ## Painel de Logs (rc3) Cada execução de regra agora gera um registro no painel `Automação → Logs`. Você vê: * **Quando** a regra disparou. * **Qual conversa / item** acionou. * **Conditions avaliadas** — quais passaram e quais não. * **Actions executadas** — sucesso ou erro. * **Erros surfaceados** — incluindo falhas em macro webhooks (que antes ficavam silenciosas, ver EVO-1041). ### Limpeza automática Logs antigos são removidos por um **cleanup job** que roda periodicamente. Você não precisa apagar manualmente. ### Endpoint de API Para consumir logs programaticamente (dashboards externos, alertas), use o endpoint de listagem de `automation_rule_runs`. Ver a [API Reference](/api-reference/openapi/EvoAI-CRM-Service) para o schema completo. *** ## Diagnóstico de regras que não disparam Roteiro rápido quando uma regra parece não estar funcionando: 1. **Verifique se está ativa.** Regras desativadas não aparecem como erro — simplesmente não rodam. 2. **Confirme o trigger.** `conversation_updated` cobre vários casos, mas `attribute_changed` é específico. 3. **Veja o log da execução.** No painel de logs, filtre pela regra. Se aparece com "no match", suas conditions estão filtrando ele. 4. **Conditions com label.** A condition `labels` usa subquery `EXISTS` (independente e NULL-safe) e casa label em **conversation OU contact**. Se você esperava casamento só na conversa, restrinja com outra condition. 5. **Dedup.** Para `pipeline_stage_updated`, há janela de 5s — dois eventos no mesmo `(rule, pipeline_item, stage)` em janela curta executam só uma vez. *** ## Loop prevention Quando uma regra `move_to_stage` aciona um evento `pipeline_stage_updated` que poderia disparar a mesma regra recursivamente, o sistema marca a execução com `Current.executed_by = :stage_automation` e ignora reentrâncias. Isso evita loops infinitos por design. *** ## Considerações Finais Automation rules são a forma declarativa de codificar comportamento operacional do CRM. Para fluxos mais complexos que envolvam IA conversacional, considere combinar uma automation rule com um agente — a regra cuida do roteamento e o agente cuida do diálogo. # Configuração de API Source: https://docs.evolutionfoundation.com.br/user-guides/channels/api-setup O canal **API** permite criar uma integração personalizada usando a API do Evo CRM para conectar sistemas externos e aplicações customizadas. Este canal oferece flexibilidade para integrações personalizadas através de endpoints REST. *** ## Iniciando um Novo Canal Para começar a criar um canal de API, use a ação destacada na tela de Canais. Botão New Channel O botão **New Channel** (destacado) é usado para iniciar a criação de um novo canal de comunicação. *** ## Selecionando API Na tela **Select a channel type**, clique no card **API**. Selecionando API como tipo de canal O card destacado representa a **integração de API personalizada**. *** ## Configurando o Canal API Após selecionar API, a tela **Configure Channel** é exibida. Tela de configuração do Canal API Dentro da área destacada, a tela mostra: ### Identificação do Canal * **API** * Descrição: **"Custom API integration"** ### Informações do Canal * **Display Name** \* * Nome amigável para identificação * Exemplo: "API Support" * **Channel Name** \* * Nome do canal (gerado automaticamente) * Exemplo: "api-support" ### Configuração de Webhook * **Webhook URL** * URL onde os eventos serão enviados * Exemplo: "[https://your-api.com/webhook](https://your-api.com/webhook)" * Campo opcional ### Informações sobre Canal API A tela exibe uma caixa informativa com: * **API Channel:** Integração personalizada via API REST * **Webhook URL:** Opcional - URL para receber eventos em tempo real * **Documentação:** Consulte a documentação da API para implementação ### Botões de Ação * **Cancel** * Descarta a configuração * **Create Channel** * Salva e ativa o Canal API Após preencher os campos necessários, clique em **Create Channel** para finalizar a configuração. *** ## Considerações Finais * O canal API requer conhecimento técnico para configuração * O Webhook URL é opcional, mas recomendado para receber eventos em tempo real * As credenciais de API devem ser mantidas seguras * Consulte a documentação da API para detalhes de implementação * Uma vez configurado, o canal permite integração com sistemas externos através de endpoints REST # Configurações de Canal Source: https://docs.evolutionfoundation.com.br/user-guides/channels/channel-settings As **Configurações de Canal** permitem personalizar o comportamento e as funcionalidades de cada canal de comunicação no Evo CRM. Através desta seção, você pode gerenciar agentes, horários comerciais, pesquisas de satisfação, modelos de mensagem e muito mais. *** ## Acessando as Configurações do Canal Para acessar as configurações de um canal, vá até a lista de canais e clique no botão **Configure** do canal desejado. Lista de canais com botão Configure destacado O botão **Configure** (destacado) abre a tela de configurações do canal selecionado. *** ## Estrutura da Tela de Configurações A tela de configurações é dividida em várias abas, cada uma focada em um aspecto específico do canal: * **Channel Settings** - Configurações gerais do canal * **Collaborators** - Gerenciamento de agentes * **Business Hours** - Horário comercial * **Satisfaction Survey** - Pesquisa de satisfação * **Message Templates** - Modelos de mensagem * **Configuration** - Configurações avançadas * **Bot Configuration** - Configuração de bots * **Moderation** - Moderação de comentários *** ## Channel Settings (Configurações Gerais) A aba **Channel Settings** contém as configurações principais do canal. Esta aba possui múltiplas seções de configuração. ### Configurações Básicas Configurações básicas do canal #### Mensagem de Boas-vindas (Greeting Message) * **Enable greeting message** * Envia mensagem automática ao iniciar uma nova conversa * Toggle para habilitar/desabilitar * Descrição: "Send automatic message when starting a new conversation." #### Bloqueio para Conversa Única (Lock to Single Conversation) * **Enable single conversation lock** * Limita o cliente a uma conversa ativa por vez * Quando habilitado, novas mensagens reabrem a mesma conversa ao invés de criar novas * Descrição: "When enabled, customers can only have one active conversation. New messages reopen the same conversation instead of creating new ones." * **Quando Habilitado:** Clientes sempre reutilizam a mesma conversa. Ideal para suporte contínuo. * **Quando Desabilitado:** Novas conversas podem ser criadas livremente. Ideal para suporte transacional ou multi-departamento. * **Recomendado:** Habilitar para canais de suporte contínuo. Desabilitar para canais transacionais ou multi-departamento. #### Status Padrão da Conversa (Default Conversation Status) * **Initial Status** * Define o status inicial para novas conversas neste canal * Dropdown para selecionar o status padrão * Descrição: "Choose the default status that new conversations will have when created." * Se nenhum status for selecionado, o sistema usa o comportamento padrão: 'pending' para canais com bots ativos, 'open' para outros * Esta configuração sobrescreve o comportamento padrão ### Configurações do WhatsApp Configurações específicas do WhatsApp #### Atualizar API Key * **Update API Key** * Permite atualizar a chave de API do WhatsApp * Descrição: "Paste your new WhatsApp API Key here." * Campo para colar a nova API Key * Botão **Update** para salvar #### Marcar como Lido * **Mark messages as read** * Marca automaticamente as mensagens como lidas no WhatsApp * Descrição: "Automatically mark messages as read on WhatsApp." * Toggle para habilitar/desabilitar *** ## Collaborators (Colaboradores) A aba **Collaborators** permite gerenciar quais agentes podem lidar com conversas neste canal. ### Seleção de Agentes Seleção de agentes colaboradores #### Lista de Agentes * Exibe todos os agentes disponíveis no sistema * Permite selecionar quais agentes terão acesso ao canal através de checkboxes * Mostra informações de cada agente: * Avatar com inicial do nome * Nome completo * Email * Status (ex: "Unknown") * Tipo (Agent) * Exibe resumo: "X agents selected (Y total)" * Botão **Update** para salvar as alterações após selecionar os agentes ### Atribuição Automática Configuração de atribuição automática #### Enable Auto Assignment * **Enable auto assignment** * Configura como as conversas são automaticamente atribuídas aos agentes * Quando habilitado, novas conversas são automaticamente atribuídas a agentes disponíveis * Descrição: "New conversations will be automatically assigned to available agents" * Toggle para habilitar/desabilitar #### Informações Importantes * A atribuição automática distribui conversas entre agentes disponíveis * Considera a carga de trabalho atual de cada agente * Agentes offline não recebem novas conversas automaticamente * Você pode definir limite máximo de conversas por agente *** ## Business Hours (Horário Comercial) A aba **Business Hours** permite configurar os horários em que sua equipe está disponível. ### Horário Comercial Desabilitado Horário comercial desabilitado Quando o horário comercial está desabilitado: * Exibe mensagem: "Business Hours Disabled" * Descrição: "Business hours are disabled. All messages will be processed normally." * Todas as mensagens são processadas normalmente, sem restrições de horário ### Configuração de Horário Comercial Configuração completa de horário comercial #### Habilitar Horário Comercial * **Enable business hours** * Toggle para ativar/desativar horário comercial * Quando ativado, mensagens automáticas são enviadas fora do horário comercial * Descrição: "Auto-reply will be sent outside business hours." #### Mensagem de Indisponibilidade * **Unavailability Message** * Mensagem personalizada enviada quando a equipe está fora do horário comercial * Campo de texto para personalizar a mensagem * Exemplo: "Sorry, we're outside business hours..." * Descrição: "This message will be sent when outside business hours" #### Fuso Horário * **Timezone** * Seletor de fuso horário para os horários comerciais * Exemplo: UTC #### Agenda Semanal * **Weekly Schedule** * Configure horários específicos para cada dia da semana * Para cada dia: * Checkbox para habilitar/desabilitar o dia * Horário de início e fim (formato AM/PM) * Opção "24 hours" para disponibilidade completa * Exibição da duração do dia útil (ex: "8h") * Exemplo de configuração: * Domingo: Indisponível (checkbox desmarcado) * Segunda-feira: 09:00 AM - 05:00 PM (8h) * Terça-feira: 09:00 AM - 05:00 PM (8h) * E assim por diante para os demais dias *** ## Satisfaction Survey (Pesquisa de Satisfação) A aba **Satisfaction Survey** permite configurar pesquisas de satisfação do cliente (CSAT). ### CSAT Desabilitado Quando a pesquisa CSAT está desabilitada: * Exibe ícone de estrela e mensagem: "CSAT Disabled" * Descrição: "Customer satisfaction survey is disabled for this channel." * A pesquisa não é enviada aos clientes ### Configuração Completa do CSAT Configuração completa da pesquisa de satisfação #### Habilitar Pesquisa CSAT * **Customer Satisfaction (CSAT) Survey** * Toggle para ativar/desativar pesquisas de satisfação * Descrição: "Configure satisfaction surveys to collect customer feedback" * Quando habilitado, todas as opções de configuração ficam disponíveis #### Tipo de Exibição (Display Type) * **Display Type** * Define como a pesquisa será apresentada ao cliente * Descrição: "How the survey will be presented to the customer" * Opções: * **Emojis de expressões faciais** (muito triste, triste, neutro, feliz, muito feliz) - opção selecionada * **Ícones de estrelas** (1 a 5 estrelas) #### Mensagem da Pesquisa * **Survey Message** * Mensagem que será exibida junto com a pesquisa * Campo de texto multilinhas * Exemplo: "How would you rate our service?" * Descrição: "Message that will be displayed along with the survey" * Limite de 200 caracteres (exibido como "0/200") #### Regras da Pesquisa * **Survey Rules** * **Condição:** A pesquisa será enviada automaticamente quando: * Dropdown para selecionar condição (ex: "contains") * **Labels:** Apenas conversas com estas etiquetas receberão a pesquisa * Se nenhuma etiqueta for selecionada, a pesquisa será enviada para todas as conversas * Mensagem: "No labels selected - survey will be sent for all conversations" #### Como Funciona * A pesquisa é enviada automaticamente após a resolução da conversa * Clientes podem avaliar de 1 a 5 estrelas * Respostas são armazenadas para análise posterior * Relatórios CSAT estão disponíveis na seção de relatórios Após configurar, clique em **Save Settings** para salvar. *** ## Message Templates (Modelos de Mensagem) A aba **Message Templates** permite gerenciar modelos de mensagem para o canal. Gerenciamento de modelos de mensagem ### Funcionalidades * **Buscar modelos:** Campo de pesquisa com placeholder "Search templates..." para encontrar modelos específicos * **Sincronizar:** Botão **Sync** com ícone de atualização para sincronizar modelos com o provedor * **Criar novo modelo:** Botão verde **+ New Message Template** para criar novos modelos ### Lista de Modelos A tabela exibe os modelos existentes com as seguintes colunas: * **Name:** Nome do modelo (ex: "sample\_template", "teste") * **Category:** Categoria do modelo com badge colorido (ex: "Utility" em verde, "Marketing" em azul) * **Status:** Status do modelo com badge (ex: "Active" em verde) * **Language:** Idioma do modelo (ex: "en\_US", "pt\_BR") * **Created At:** Data de criação (ex: "20/01/2026") * **Actions:** Coluna com ações para cada modelo: * **Visualizar:** Ícone de olho * **Editar:** Ícone de lápis * **Excluir:** Ícone de lixeira ### Criar Novo Modelo de Mensagem Ao clicar em **+ New Message Template**, uma tela de criação é exibida. Criando novo modelo de mensagem Nesta tela, você pode preencher todas as informações necessárias para criar um novo modelo de mensagem. *** ## Configuration (Configuração) A aba **Configuration** contém configurações avançadas do canal. Configurações avançadas Esta seção permite ajustar configurações específicas do tipo de canal configurado. As opções disponíveis podem variar dependendo do provedor e tipo de canal. *** ## Bot Configuration (Configuração de Bot) A aba **Bot Configuration** permite configurar bots de suporte para automatizar respostas. Configuração de bot ### Título e Descrição * **Bot Configuration** * Descrição: "Configure support bots to automate responses" * Status: Exibe o status atual da conexão do bot (ex: "Disconnected" com ícone de alerta) ### Selecionar Bot * **Select Bot** * Dropdown com placeholder "Select a bot" para selecionar um bot existente * Botão verde **Configure Bot** para configurar o bot selecionado ### Como Funciona Caixa informativa explicando as funcionalidades dos bots: * Bots podem responder automaticamente a mensagens de clientes * Configure palavras-chave e respostas automáticas * Bots podem transferir conversas para agentes humanos * Estatísticas de desempenho do bot estão disponíveis *** ## Moderation (Moderação) A aba **Moderation** permite revisar e moderar comentários do Facebook que requerem aprovação. Moderação de comentários ### Moderação de Comentários * **Comment Moderation** * Título: "Comment Moderation" * Descrição: "Review and moderate Facebook comments that require approval" ### Filtros Barra de filtros com: * **Status:** Filtro por status com ícone de funil (ex: "Pending") * **Type:** Filtro por tipo (ex: "All Types") * **Total:** Contador de comentários pendentes (ex: "Total: 0") ### Área de Comentários * Exibe comentários do Facebook aguardando moderação * Quando não há comentários pendentes, mostra áreas vazias indicando que não há itens para moderar * Permite aprovar ou rejeitar comentários quando disponíveis *** ## Considerações Finais * Todas as alterações nas configurações devem ser salvas usando o botão **Save** no topo da tela * As configurações são específicas para cada canal * Algumas configurações podem variar dependendo do tipo de canal (WhatsApp, Email, etc.) * Recomenda-se revisar todas as abas de configuração para otimizar o funcionamento do canal * O botão **Save** está sempre disponível no canto superior direito para salvar todas as alterações de uma vez # Configuração de Email Source: https://docs.evolutionfoundation.com.br/user-guides/channels/email-setup O canal **Email** permite conectar um provedor de email ao Evo CRM para que você possa gerenciar suporte por email dentro da plataforma. No momento, a interface mostra dois provedores (**Gmail** e **Outlook**), mas apenas **Gmail** está disponível para conexão. *** ## Iniciando um Novo Canal de Email Para começar a criar um canal de Email, use a ação destacada na tela de Canais. Botão New Channel O botão **New Channel** (destacado) é a ação que inicia o fluxo de criação de canal. *** ## Selecionando Email Após clicar em **New Channel**, o sistema abre o seletor de tipo de canal. Selecionando Email Clique no card **Email** (destacado) para continuar com a configuração de Email. *** ## Escolhendo o Provedor de Email Após selecionar Email, o sistema mostra os provedores disponíveis. Provedores de Email: Gmail e Outlook Dentro da área destacada, você verá: * **Gmail** *(Recomendado)*\ Texto exibido: **"Integração com Gmail via OAuth"** * **Outlook** *(Popular)*\ Texto exibido: **"OAuth da Microsoft não configurado"** Isso significa que a opção Outlook está visível, mas ainda não está pronta para ser usada. *** ## Conectando Gmail (OAuth) Clique em **Gmail** para abrir a tela de configuração. Tela Connect Gmail Dentro da área destacada, a tela mostra: * **Connect Gmail** * Subtítulo: **"Conecte sua conta Gmail via OAuth"** * Um card intitulado **"Email from Google"** com o texto de instrução: * **"Clique no botão do Google para começar. Você será solicitado a aceitar as permissões solicitadas e será redirecionado de volta ao painel."** * Campo: **"Enter the email address"** * Botão: **"Sign in with Google"** Para prosseguir, insira o endereço de email e clique em **Sign in with Google** para iniciar a conexão OAuth. *** ## Aviso de Segurança do Google Após clicar em **Sign in with Google**, você será redirecionado para uma tela de autenticação do Google. Se o aplicativo ainda não foi verificado pelo Google, você verá um aviso de segurança. Aviso do Google sobre app não verificado Esta tela exibe: * **Ícone de aviso**: Um triângulo vermelho com ponto de exclamação no topo * **Título**: "O Google não verificou este app" * **Mensagem explicativa**: Informa que o app está solicitando acesso a informações confidenciais na sua Conta do Google e que não é recomendado usá-lo até que o desenvolvedor faça a verificação com o Google * **Link "Avançado"**: Localizado no canto inferior esquerdo (destacado com seta vermelha) Este aviso aparece porque o aplicativo ainda não passou pelo processo de verificação do Google. É seguro prosseguir se você confia no desenvolvedor e no serviço evo-ai.co. Clique em **Avançado** para continuar com o processo de autorização. *** ## Acessando o Aplicativo Não Verificado Após clicar em **Avançado**, uma nova tela será exibida com mais opções. Tela de acesso ao aplicativo não verificado Esta tela contém: * **Mensagem de aviso**: "O Google não verificou este app" * **Explicação adicional**: Informa que o app está solicitando acesso a informações confidenciais e mostra o e-mail do desenvolvedor ([agenciadgcode@gmail.com](mailto:agenciadgcode@gmail.com)) * **Link "Ocultar avançado"**: Permite voltar à tela anterior * **Botão "VOLTAR À SEGURANÇA"**: Cancela o processo de autorização * **Texto de aviso**: "Continue apenas se você entender os riscos e confiar no desenvolvedor" * **Link principal**: **"Acessar evo-ai.co (não seguro)"** (destacado com seta vermelha) O aviso "não seguro" refere-se ao fato de que o aplicativo ainda não foi verificado pelo Google, não significa que há um problema de segurança real. Se você confia no serviço evo-ai.co, pode prosseguir com segurança. Clique no link **"Acessar evo-ai.co (não seguro)"** para continuar com o processo de autorização. *** ## Concedendo Permissões ao Aplicativo Após clicar em **"Acessar evo-ai.co (não seguro)"**, você será direcionado para a tela de consentimento do Google. Tela de consentimento e permissões do Google Esta tela exibe: ### Informações do Aplicativo * **Título**: "O app evo-ai.co quer acessar sua Conta do Google" * **Conta**: Mostra o endereço de email da sua conta Google que será usada (exemplo: [davidsongviolao@gmail.com](mailto:davidsongviolao@gmail.com)) ### Permissões Solicitadas Na seção **"Selecione o que o app evo-ai.co pode acessar"**, você verá as seguintes permissões: #### Permissão Principal de Email * **Permissão de Gmail**: "Ler, escrever, enviar e excluir permanentemente todos os seus e-mails do Gmail" * **Status**: Esta permissão estará marcada (com check azul e contorno laranja) * **Importante**: Esta é a permissão essencial para que o Evo CRM possa gerenciar seus emails #### Outras Permissões Concedidas Como você está usando o recurso "Fazer login com o Google", o app também terá acesso a: * Ver suas informações pessoais, inclusive aquelas que você disponibilizou publicamente * Ver o endereço de e-mail principal da sua Conta do Google * Associar suas informações pessoais a você no Google ### Informações Adicionais Na parte inferior da tela, há uma barra informativa azul explicando por que você não está vendo links para a Política de Privacidade ou os Termos de Serviço do evo-ai.co. ### Finalizando a Autorização Após revisar as permissões solicitadas, você pode: 1. Verificar que a permissão de Gmail está marcada (necessária para o funcionamento) 2. Clicar em **Continuar** ou no botão de autorização para conceder as permissões As permissões solicitadas são necessárias para que o Evo CRM possa gerenciar seus emails do Gmail. Você pode revogar essas permissões a qualquer momento nas configurações da sua conta Google. Após autorizar, você será redirecionado de volta ao painel do Evo CRM e a conexão com o Gmail será estabelecida. *** ## Considerações Finais * A tela de configuração de Email atualmente oferece **Gmail (OAuth)** como a opção disponível * A opção **Outlook** aparece como **"OAuth da Microsoft não configurado"**, então só poderá ser usada quando esta integração for habilitada no sistema * O processo de autorização do Google pode exibir avisos de segurança se o aplicativo ainda não foi verificado pelo Google * É seguro prosseguir com a autorização se você confia no serviço evo-ai.co * As permissões solicitadas são necessárias para que o Evo CRM possa gerenciar seus emails do Gmail * Você pode revogar as permissões a qualquer momento nas configurações da sua conta Google * Após a autorização bem-sucedida, você será redirecionado automaticamente de volta ao painel do Evo CRM * O canal de email ficará disponível para receber e gerenciar mensagens assim que a conexão for estabelecida # Configuração do Facebook e Instagram Source: https://docs.evolutionfoundation.com.br/user-guides/channels/facebook-instagram-setup Este documento explica como configurar os canais **Instagram** e **Facebook Messenger** no Evo CRM. Ambos os canais usam um fluxo de autenticação que conecta sua **conta comercial/página** à plataforma para que as mensagens possam ser recebidas e gerenciadas. *** ## Iniciando um Novo Canal Para começar, use a ação destacada na tela de Canais. Botão New Channel O botão **New Channel** (destacado) é usado para iniciar a criação de um novo canal de comunicação. *** ## Selecionando Instagram Na tela **Select a channel type**, clique no card **Instagram**. Tipo de canal Instagram O card destacado representa o canal de **mensagens diretas do Instagram**. *** ## Conectando Instagram Após selecionar Instagram, o sistema abre a tela de configuração. Conectar com Instagram Dentro da área destacada, a tela mostra: * **Connect with Instagram** * Descrição indicando que uma **conta comercial do Instagram** é necessária * Botão: **Connect with Instagram** * Opção para **Cancelar** a operação Clicar em **Connect with Instagram** redireciona você para o Instagram para autorizar a conexão. *** ## Selecionando Facebook Messenger Para configurar o Facebook Messenger, retorne à tela de seleção de tipo de canal e clique em **Facebook Messenger**. Tipo de canal Facebook Messenger O card destacado representa o canal de **chat do Facebook Messenger**. *** ## Conectando Facebook Messenger Após selecionar Facebook Messenger, a tela de configuração é exibida. Conectar com Facebook Dentro da área destacada, a tela mostra: * **Connect with Facebook** * Botão: **Sign in with Facebook** * Mensagem informando que você será redirecionado para autorizar a aplicação * Nota indicando que você deve ser um **administrador da página do Facebook** Clicar em **Sign in with Facebook** redireciona você para o Facebook para autenticar e conceder acesso à página selecionada. *** ## Considerações Finais * **Instagram** requer uma **conta comercial do Instagram** * **Facebook Messenger** requer **acesso de administrador** à página do Facebook * Ambos os canais usam um fluxo de autorização externa * Após a autorização, o canal fica disponível no Evo CRM # Visão Geral Source: https://docs.evolutionfoundation.com.br/user-guides/channels/overview A seção **Canais** é responsável por gerenciar todos os canais de comunicação disponíveis no seu workspace. A partir desta área, você pode visualizar canais existentes, pesquisar por canais específicos, criar novos e acessar opções de configuração para cada canal. Esta tela funciona como o centro de controle para todos os métodos de comunicação de entrada e saída conectados ao Evo CRM. *** ## Acessando a Seção de Canais Para acessar a área de Canais, use o menu de navegação principal no lado esquerdo da tela. Acessando a seção de Canais Clique em **Channels** para abrir a tela de gerenciamento de canais. Uma vez selecionado, o sistema carregará todos os canais configurados no workspace atual. *** ## Pesquisando Canais No topo da tela de Canais, há um campo de busca que ajuda você a encontrar rapidamente um canal específico. Utilizando o campo de busca Este campo de busca permite: * Pesquisar canais por **nome de exibição** * Localizar rapidamente um canal quando muitos canais estão configurados * Reduzir a lista visível em tempo real conforme você digita Isso é útil para ambientes com múltiplos canais de comunicação configurados. *** ## Criando um Novo Canal Para adicionar um novo canal de comunicação, use o botão **New Channel** localizado no canto superior direito da tela. Criando um novo canal Clicar em **New Channel** inicia o fluxo de criação de canal e redireciona você para a tela de seleção de tipo de canal. *** ## Selecionando um Tipo de Canal Após clicar em **New Channel**, o sistema exibe uma tela onde você pode escolher o tipo de canal que deseja criar. Tela de seleção de tipo de canal Nesta tela, cada card representa um canal de comunicação suportado: * **Web Widget**: Widget de chat incorporado ao seu website * **WhatsApp**: Canal WhatsApp para comunicação com clientes * **Instagram**: Mensagens diretas do Instagram * **Facebook Messenger**: Conversas do Facebook Messenger * **Telegram**: Bot do Telegram para suporte automatizado ou humano * **SMS**: Comunicação por mensagens de texto SMS * **Email**: Canal de suporte baseado em email * **API**: Integração de API personalizada para sistemas externos Selecionar uma dessas opções inicia o processo de configuração para o tipo de canal escolhido. *** ## Lista e Detalhes dos Canais Quando os canais já estão configurados, eles são exibidos como cards na tela principal de Canais. Lista e detalhes dos canais Cada card de canal exibe informações importantes: * **Ícone do canal**: Indica o tipo de canal (Email, Telegram, WhatsApp, etc.) * **Nome do canal**: O nome interno usado para identificar o canal * **Nome de exibição**: O nome visível para usuários ou clientes * **Channel ID**: Identificador único usado internamente pelo sistema * **Tipo**: A categoria do canal (Email – Gmail, Telegram, etc.) ### Ações disponíveis em cada canal: * **Configure**: Abre as configurações e opções de configuração do canal * **Ícone de deletar**: Remove o canal do workspace Esses cards fornecem uma visão geral rápida de todos os canais de comunicação ativos e permitem acesso rápido a ações de gerenciamento. *** ## Considerações Finais A tela de **Visão Geral de Canais** é o ponto de partida para gerenciar todos os métodos de comunicação no Evo CRM. A partir desta seção, você pode criar novos canais, pesquisar canais existentes, revisar seu status e detalhes, e acessar configurações individuais de cada canal antes de prosseguir para guias de configuração mais específicos para cada tipo de canal. # Configuração de SMS Source: https://docs.evolutionfoundation.com.br/user-guides/channels/sms-setup O canal **SMS** permite conectar um provedor de SMS ao Evo CRM para que mensagens de texto possam ser enviadas e recebidas diretamente pela plataforma. Este canal permite comunicação via mensagens de texto SMS com seus clientes. *** ## Iniciando um Novo Canal Para começar a criar um canal de SMS, use a ação destacada na tela de Canais. Botão New Channel O botão **New Channel** (destacado) é usado para iniciar a criação de um novo canal de comunicação. *** ## Selecionando SMS Na tela **Select a channel type**, clique no card **SMS**. Selecionando SMS como tipo de canal O card destacado representa o canal de **mensagens de texto SMS**. *** ## Escolhendo o Provedor de SMS Após selecionar SMS, o sistema exibe a tela **SMS Channel** com os provedores disponíveis. Provedores de SMS: Twilio e Bandwidth Dentro da área destacada, você verá duas opções de provedor: * **Twilio SMS** *(Recomendado)*\ Descrição: **"SMS sending via Twilio"** * **Bandwidth**\ Descrição: **"SMS sending via Bandwidth"** No momento, ambas as opções estão disponíveis para configuração. *** ## Configurando SMS com Twilio Selecione **Twilio SMS** para prosseguir com a configuração. Tela de configuração do Twilio SMS A tela **Configure Channel** exibe os seguintes campos: ### Informações Básicas * **Display Name** \* * Nome amigável para identificação * Exemplo: "SMS Support" * **Channel Name** \* * Nome para identificar o canal SMS * Exemplo: "SMS Twilio" ### Autenticação * **Account SID** \* * Seu Twilio Account SID * Formato: ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX * **Auth Token** \* * Auth Token do Twilio * API Key gerada no Twilio ### Autenticação Avançada * **Use API Key (instead of Auth Token)** * Opção para configurar API Key como alternativa ao Auth Token ### Configuração de Telefone * **Use Messaging Service** * Opção para usar um serviço de mensagens ao invés de um número único * **Phone Number** \* * Número de telefone no formato internacional * Seletor de código do país disponível Após preencher os campos necessários, clique em **Create Channel** para finalizar a configuração. *** ## Configurando SMS com Bandwidth Selecione **Bandwidth** para prosseguir com a configuração. Tela de configuração do Bandwidth SMS A tela **Configure Channel** exibe os seguintes campos: ### Informações Básicas * **Display Name** \* * Nome amigável para identificação * Exemplo: "SMS Bandwidth" * **Channel Name** \* * Nome gerado automaticamente a partir do display name * Exemplo: "SMS Twilio" ### Configuração de Telefone * **Phone Number** \* * Número de telefone no formato internacional * Seletor de código do país (ex: BR +55) ### Credenciais da API * **API Token** \* * Token da API do Bandwidth * **API Secret** \* * Secret da API do Bandwidth (campo mascarado) * **Application ID** \* * Application ID configurado no Bandwidth * **Account ID** \* * Account ID no Bandwidth ### Ajuda - Bandwidth * **API Key & Secret:** Encontre no seu dashboard do Bandwidth * **Application ID:** Application ID configurado no Bandwidth * **Account ID:** Account ID no Bandwidth Após preencher os campos necessários, clique em **Create Channel** para finalizar a configuração. *** ## Considerações Finais * O canal SMS requer um provedor de SMS configurado (Twilio ou Bandwidth) * As credenciais de API devem ser válidas e ativas * O número de telefone deve estar no formato internacional * Uma vez configurado, o canal permite envio e recebimento de mensagens SMS # Configuração do Telegram Source: https://docs.evolutionfoundation.com.br/user-guides/channels/telegram-setup O canal **Telegram** permite conectar um bot do Telegram ao Evo CRM para que as mensagens possam ser recebidas e gerenciadas automaticamente. Esta configuração usa um **Bot Token**, gerado diretamente no Telegram. *** ## Iniciando um Novo Canal Para começar a criar um canal do Telegram, use a ação destacada. Botão New Channel O botão **New Channel** (destacado) inicia o processo de criação de canal. *** ## Selecionando Telegram Na tela **Select a channel type**, clique no card **Telegram**. Tipo de canal Telegram O card destacado representa o **bot do Telegram para suporte automatizado**. *** ## Configurando o Canal do Telegram Após selecionar Telegram, a tela de configuração é exibida. Tela de configuração do Telegram Dentro das áreas destacadas, a tela mostra: ### Campo Bot Token * **Bot Token** * Campo onde o token do bot do Telegram deve ser colado * Texto de ajuda explicando que o token é obtido do **@BotFather** no Telegram ### Painel de Instruções Um guia passo a passo explicando como criar um bot do Telegram: 1. Abra o Telegram e procure por **@BotFather** 2. Digite **/newbot** 3. Defina um nome para o bot 4. Defina um nome de usuário terminando com **bot** 5. Copie o token gerado ### Botões de Ação * **Cancel** * Descarta a configuração * **Create Channel** * Salva o canal do Telegram e o ativa Para finalizar a configuração, cole o Bot Token e clique em **Create Channel**. *** ## Considerações Finais * O canal do Telegram requer um **Bot Token** válido * O token deve ser gerado usando **@BotFather** * Uma vez criado, o bot fica disponível no Evo CRM # Configuração do Widget do Website Source: https://docs.evolutionfoundation.com.br/user-guides/channels/website-widget-setup O canal **Website Widget** permite adicionar um widget de chat ao seu website para que os visitantes possam iniciar conversas diretamente da página. Este canal é configurado definindo informações básicas do website e a aparência do widget. *** ## Iniciando um Novo Canal Para começar a criar um canal Website Widget, use a ação destacada. O botão **New Channel** (destacado) inicia o fluxo de criação de canal. Botão New Channel *** ## Selecionando Website Widget Na tela **Select a channel type**, clique no card **Web Widget**. Tipo de canal Web Widget O card destacado representa o **widget de chat para seu website**. *** ## Configurando o Website Widget Após selecionar Web Widget, a tela de configuração é exibida. Configuração do Website Widget A área destacada contém todos os campos de configuração necessários. ### Informações Básicas * **Display Name** * Nome exibido internamente para identificar o canal * **Channel Name** * Identificador interno do widget * **Website URL** * URL onde o widget será incorporado ### Aparência do Widget * **Widget Color** * Define a cor principal do widget * **Welcome Title** * Mensagem principal exibida no topo do widget * **Welcome Tagline** * Mensagem curta exibida abaixo do título ### Mensagem de Boas-vindas * **Enable automatic greeting message** * Quando habilitado, envia uma mensagem de boas-vindas automaticamente quando um visitante abre o chat ### Resumo da Configuração * Exibe um resumo de: * Nome do website * URL * Cor selecionada * Status da mensagem de boas-vindas ### Botões de Ação * **Cancel** * Descarta a configuração * **Create Channel** * Salva e ativa o Website Widget Após preencher os campos necessários, clique em **Create Channel** para finalizar a configuração. *** ## Considerações Finais * O Website Widget requer uma **Website URL** válida * A personalização visual afeta como o widget aparece para os visitantes * Uma vez criado, o widget fica disponível para incorporação no seu site # Configuração do WhatsApp Source: https://docs.evolutionfoundation.com.br/user-guides/channels/whatsapp-setup O canal **WhatsApp** permite conectar sua conta do WhatsApp Business ao Evo CRM para receber e gerenciar mensagens automaticamente. Esta configuração utiliza a **WhatsApp Business API (Cloud)**, a solução oficial do WhatsApp com integração direta. *** ## Iniciando um Novo Canal Para começar a criar um canal do WhatsApp, navegue até a seção de **Channels** e clique no botão **New Channel** localizado no canto superior direito da tela. Botão New Channel na tela de canais O botão **New Channel** (destacado) inicia o processo de criação de canal e redireciona você para a tela de seleção de tipo de canal. *** ## Selecionando o Tipo de Canal WhatsApp Na tela **Select a channel type**, localize e clique no card **WhatsApp**. Selecionando o tipo de canal WhatsApp O card destacado representa o **canal WhatsApp para atendimento ao cliente**. Após selecionar, você será redirecionado para a próxima etapa de configuração. *** ## Escolhendo o Provedor de API Na tela **WhatsApp Channel**, você verá a seção **API Provider** com várias opções de provedores disponíveis. Selecionando o provedor WhatsApp Business API Cloud Selecione o provedor **WhatsApp Business API (Cloud)**, que é a opção recomendada (marcada com o rótulo verde "Recommended"). Esta é a API oficial do WhatsApp com integração direta e oferece a melhor experiência de configuração. ### Outros Provedores Disponíveis Embora a opção recomendada seja a WhatsApp Business API (Cloud), você também pode escolher entre outros provedores: * **Evolution API**: Solução robusta do WhatsApp Evolution API * **Evolution Go**: WhatsApp Evolution Go API com performance otimizada * **Notificame**: Provedor brasileiro de WhatsApp * **Z-API**: WhatsApp Z-API * **Twilio**: Twilio WhatsApp Business API *** ## Configurando o Canal Após selecionar o provedor, a tela **Configure Channel** será exibida. Esta tela permite configurar os detalhes do seu novo canal para começar a receber mensagens. Tela de configuração do canal WhatsApp ### Integração com Facebook Na seção **Facebook Integration**, você encontrará um botão **Connect with Facebook**. Esta integração permite conectar sua conta do Facebook para preencher automaticamente as informações do WhatsApp Business. Clique em **Connect with Facebook** para iniciar o processo de autenticação e integração. ### Detalhes do Canal Na seção de detalhes do canal, preencha os seguintes campos obrigatórios: * **Display Name**: Nome de exibição do canal (exemplo: "WhatsApp Support") * **Channel Name**: Nome interno do canal (exemplo: "WhatsApp Cloud") * **Phone Number**: Número de telefone completo com código do país (exemplo: +55 para Brasil) ### Botões de Ação Na parte inferior da tela, você encontrará dois botões: * **Cancel**: Cancela a criação do canal e retorna à tela anterior * **Create Channel**: Cria o canal com as configurações informadas *** ## Conectando com o Facebook Ao clicar em **Connect with Facebook**, uma janela pop-up será aberta solicitando o login com o Facebook. Nesta tela, você precisará selecionar sua configuração inicial. *** ## Selecionando o Tipo de Configuração Na janela **Log In With Facebook**, você verá a pergunta **"Select your setup"** com duas opções disponíveis: Selecionando tipo de configuração do WhatsApp ### Opção 1: Conectar seu aplicativo existente do WhatsApp Business Esta é a opção recomendada se você já possui uma conta do WhatsApp Business configurada. Ao selecionar esta opção: * Você compartilhará sua conta do WhatsApp Business com o Evo CRM * Você ainda terá acesso total ao seu aplicativo WhatsApp Business * Poderá continuar usando o aplicativo normalmente ### Opção 2: Começar com um novo número de telefone do WhatsApp Escolha esta opção se deseja adicionar um novo número de telefone. Você precisará verificar seu novo número para continuar. Selecione a opção **"Connect your existing WhatsApp Business App"** e clique em **Next** para prosseguir. *** ## Compartilhando Contatos e Conversas Após selecionar a configuração e clicar em **Next**, uma nova tela será exibida no navegador solicitando o compartilhamento de contatos e histórico de conversas. Esta tela explica que você pode: * Importar contatos e até 6 meses de histórico de conversas do aplicativo WhatsApp Business para o Evo CRM * Antes de prosseguir, atualizar o aplicativo para a versão mais recente * Procurar uma mensagem da conta oficial do Facebook Business no WhatsApp e tocar em **Scan QR code** Um código QR será exibido no centro da tela. Este código precisa ser escaneado pelo aplicativo WhatsApp Business no seu dispositivo móvel. *** ## Escaneando o Código QR no Aplicativo No seu dispositivo móvel, abra o aplicativo **WhatsApp Business** e procure por uma mensagem da conta oficial **"Facebook Business"** (identificada com um selo de verificação azul). Mensagem do Facebook Business no WhatsApp Na conversa com o Facebook Business, você verá: 1. **Código de confirmação**: Uma mensagem contendo um código numérico (exemplo: 64570) que é seu código de confirmação do Facebook 2. **Mensagem de conexão**: Uma mensagem com o título **"Connect to Business Platform"** instruindo você a escanear o código QR para continuar o processo Toque no botão **"Scan QR code"** dentro da mensagem do Facebook Business. *** ## Conectando à Plataforma de Negócios Ao tocar em **"Scan QR code"**, o aplicativo WhatsApp Business abrirá a tela **"Business platform"**. Tela Business platform no aplicativo WhatsApp Esta tela exibe: * Uma ilustração representando a conexão à plataforma de negócios * O título **"Connect to the Business Platform"** * A instrução: **"Scan the QR code to connect to the Business Platform"** * Informações importantes sobre o uso conjunto do aplicativo e da plataforma * Um botão grande **"Scan QR code"** na parte inferior Toque no botão **"Scan QR code"** para abrir o scanner de QR code. *** ## Decidindo sobre o Compartilhamento de Histórico Após escanear o código QR, um pop-up será exibido no aplicativo solicitando sua decisão sobre o compartilhamento do histórico de conversas. O pop-up **"Share chat history"** apresenta três opções: ### Opção 1: Share chats (Compartilhar conversas) * Permite compartilhar até 6 meses de histórico de conversas * Mensagens anteriores poderão ser visualizadas na Business Platform * **Importante**: Esta decisão não pode ser alterada posteriormente ### Opção 2: Don't share chats (Não compartilhar conversas) * Não compartilha o histórico de conversas * Mensagens anteriores não poderão ser visualizadas na Business Platform * **Importante**: Esta decisão não pode ser alterada posteriormente ### Opção 3: Cancel (Cancelar) * Cancela o processo de conexão Escolha a opção desejada e confirme. Lembre-se de que esta escolha é permanente e não pode ser alterada depois. *** ## Finalizando a Configuração Após completar o processo de escaneamento do QR code e decidir sobre o compartilhamento do histórico, você será redirecionado de volta para a tela de configuração do canal no navegador. Finalizando configuração do canal Preencha os campos restantes: * **Display Name**: Nome de exibição do canal * **Channel Name**: Nome interno do canal * **Phone Number**: Número de telefone completo Clique em **Create Channel** para finalizar a criação do canal WhatsApp. *** ## Considerações Finais * O canal WhatsApp requer uma conta do **WhatsApp Business** válida * A integração com o Facebook é necessária para usar a WhatsApp Business API (Cloud) * O processo de escaneamento do QR code deve ser feito no aplicativo WhatsApp Business no dispositivo móvel * A decisão sobre compartilhamento de histórico de conversas é permanente e não pode ser alterada posteriormente * Após a configuração, o canal ficará disponível no Evo CRM para receber e gerenciar mensagens * Você pode continuar usando o aplicativo WhatsApp Business normalmente após a conexão # Perfil do Contato Source: https://docs.evolutionfoundation.com.br/user-guides/contacts/contact-profile A página de Perfil do Contato centraliza todas as informações e ações relacionadas a um contato específico. Nesta tela, você pode visualizar detalhes do contato, iniciar conversas, editar informações, mesclar contatos duplicados e gerenciar atributos e histórico. *** ## Acessando um Perfil de Contato Na lista de **Contatos**, cada card de contato fornece ações rápidas e acesso a informações detalhadas. Ações ao passar o mouse sobre o contato Ao passar o mouse sobre um card de contato, as seguintes ações ficam disponíveis: * **Iniciar Conversa**: Inicia uma nova conversa com o contato selecionado. * **Ver Detalhes**: Abre o perfil completo do contato. * **Atividade / Eventos**: Exibe indicadores relacionados às interações (se disponível). * **Editar Contato**: Abre o formulário de edição do contato. * **Excluir Contato**: Remove permanentemente o contato do sistema. *** ## Iniciando uma Conversa Para iniciar uma conversa com um contato, clique no ícone **Chat** disponível no card do contato. ### As configurações de conversa incluem: * **Canal de Comunicação**: Selecione o canal (ex: Telegram). * **Seletor de Template**: Opcionalmente, use um template de mensagem predefinido. * **Campo de Mensagem**: Digite a mensagem inicial para começar a conversa. Clique em **Iniciar Conversa** para começar a interagir com o contato. Modal para iniciar conversa *** ## Visualizando Detalhes do Contato Clicar em **Ver Detalhes** abre o perfil completo do contato. ### Ações do cabeçalho: * **Iniciar Conversa**: Inicie rapidamente um novo chat. * **Editar**: Modifique as informações do contato. * **Mesclar Contatos**: Combine contatos duplicados em um único perfil. ### Seções do perfil: * **Pipeline**: Mostra se o contato está associado a algum pipeline. * **Histórico**: Exibe interações e atividades passadas. * **Notas**: Permite adicionar anotações internas sobre o contato. * **Atributos**: Mostra atributos personalizados vinculados ao contato. Visualização dos detalhes do contato *** ## Editando um Contato Para atualizar as informações do contato, clique em **Editar** no perfil do contato. ### As seções editáveis incluem: #### Informações Básicas * Nome * Sobrenome * CPF * E-mail * Telefone * Foto de perfil #### Status do Contato * Habilite ou desabilite o contato para controlar a disponibilidade de comunicação. #### Informações da Empresa * Vincule o contato a empresas existentes. Formulário de edição do contato *** ## Detalhes Avançados do Contato Rolando mais para baixo na tela de edição, você encontra opções adicionais de customização. ### Campos disponíveis: #### Links Sociais * LinkedIn * Facebook * Instagram * Twitter * GitHub #### Etiquetas * Adicione tags para organizar e categorizar contatos. #### Atributos Personalizados * Adicione campos customizados para armazenar dados adicionais específicos do contato. * Os atributos podem ser configurados globalmente ou adicionados diretamente ao editar o contato. Clique em **Salvar alterações** para aplicar todas as atualizações. Detalhes avançados do contato *** ## Mesclando Contatos A opção **Mesclar Contatos** permite combinar registros de contatos duplicados em um único perfil, preservando dados relevantes e evitando redundância. Isso é útil quando o mesmo contato é criado várias vezes em diferentes canais. *** ## Considerações Finais O Perfil do Contato é o hub principal para gerenciar contatos individuais, oferecendo visibilidade completa sobre dados do contato, interações e opções de customização. # Visão Geral Source: https://docs.evolutionfoundation.com.br/user-guides/contacts/overview A seção **Contatos** permite gerenciar todos os contatos cadastrados no Evo CRM em um único local. Nesta tela, é possível visualizar, pesquisar, criar e filtrar contatos de forma rápida e organizada. ## Acessando Contatos Para acessar a área de contatos: 1. No menu lateral esquerdo, clique em **Contatos** 2. Em seguida, selecione a opção **Contatos** 3. A tela principal será exibida com a lista de todos os contatos cadastrados. Cada contato é apresentado em formato de card, contendo informações básicas como nome, identificador e telefone. Tela principal de Contatos ## Pesquisando Contatos (Busca Rápida) A barra de pesquisa permite localizar contatos rapidamente pelo nome. ### Como pesquisar 1. Na parte superior da tela, utilize o campo **Pesquisar contatos** 2. Digite o nome ou parte do nome do contato desejado 3. A lista de contatos será atualizada automaticamente conforme o termo digitado Buscando contatos por nome Esse recurso é ideal para encontrar contatos específicos sem a necessidade de aplicar filtros avançados. ## Criando um Novo Contato É possível criar novos contatos diretamente pela tela de Contatos. Botão para criar novo contato ### Passo 1: Abrir o modal de criação 1. Clique no botão **+ Novo Contato**, localizado no canto superior direito da tela 2. Um modal de criação de contato será exibido ### Passo 2: Preencher os detalhes do contato No modal de criação: 1. Selecione o **Tipo de Contato** (ex: Pessoa) 2. Preencha as informações básicas: * Nome * Sobrenome * CPF (opcional) * E-mail * Telefone 3. Caso necessário, vincule o contato a uma empresa existente na seção **Informações da Empresa** 4. Após preencher os dados, finalize o cadastro conforme as opções disponíveis no modal Modal de criação de novo contato Campos obrigatórios são indicados visualmente no formulário. ## Filtrando Contatos Os filtros permitem refinar a lista de contatos com base em critérios específicos. " ### Passo 1: Abrir filtros Clique no botão **Filtros**, localizado ao lado da barra de pesquisa Botão de filtros de contatos ### Passo 2: Configurar filtros No modal **Filtrar Contatos**, selecione: 1. O campo a ser filtrado (ex: Nome) 2. O operador (ex: Igual a) 3. O valor desejado 4. Para adicionar mais critérios, clique em **Adicionar Filtro** 5. Após configurar os filtros, clique em **Aplicar Filtros** Modal de filtros de contatos ### Opções adicionais * **Limpar Filtros**: remove todos os filtros aplicados * **Cancelar**: fecha o modal sem aplicar alterações ## Considerações Finais * A tela de Contatos foi projetada para facilitar o gerenciamento de grandes volumes de contatos * O uso combinado da busca rápida e dos filtros avançados otimiza a navegação e a organização dos dados *** ## Contatos de Grupo WhatsApp (a partir do v1.0.0-rc3) A partir do `v1.0.0-rc3` (EVO-1018), o CRM distingue **contatos de grupo WhatsApp** de **contatos reais de cliente**: * Grupos WhatsApp deixam de aparecer misturados na lista principal de contatos. A entidade "grupo" não é uma pessoa — ela representa a sala, não um interlocutor individual. * Mensagens enviadas dentro de um grupo continuam sendo associadas ao **autor individual** da mensagem, que aparece como contato real. * Reports e filtros que rodam sobre a base de contatos passam a refletir apenas pessoas — sem inflar métricas com IDs de sala. Se você precisa visualizar grupos como entidade (raro), o filtro avançado expõe a opção de incluir grupos explicitamente. # Ações Agendadas Source: https://docs.evolutionfoundation.com.br/user-guides/contacts/scheduled-actions A funcionalidade de **Ações Agendadas** (Scheduled Actions) permite agendar ações automáticas para contatos específicos. Essas ações são executadas em uma data e hora definidas e atualmente suportam o envio de mensagens por canais configurados. Essa funcionalidade é útil para: * Lembretes automáticos * Follow-ups programados * Mensagens agendadas para contatos específicos *** ## Acessando Ações Agendadas Para acessar a tela de **Ações Agendadas**, siga os passos abaixo: 1. No menu lateral, clique em **Contatos** 2. Em seguida, selecione **Ações Agendadas** Acessando Ações Agendadas *** ## Tela Inicial de Ações Agendadas Ao acessar a tela, você verá uma visão geral com todas as ações agendadas existentes. Quando não houver nenhuma ação criada, a interface exibirá uma mensagem indicando que não existem ações agendadas. ### Componentes da tela: * **Campo de busca**: permite pesquisar ações agendadas pelo nome do contato. * **Botão "Nova Ação"**: disponível no canto superior direito e também no centro da tela quando não há registros. *** ## Criando uma Nova Ação Agendada Para criar uma nova ação agendada, clique no botão **Nova Ação** (New Action). Botão Nova Ação Ao clicar, um modal será aberto para configuração da ação. *** ## Selecionando o Contato No modal **Nova Ação Agendada**, o primeiro campo é o de **Contato** (Contact). Selecionando o contato ### Detalhes do campo: * Digite o nome do contato no campo de busca * A lista exibirá os contatos correspondentes * Selecione o contato desejado para associá-lo à ação > Apenas um contato pode ser selecionado por Ação Agendada. *** ## Configurando Data, Hora e Recorrência Após selecionar o contato, preencha as informações de agendamento. ### Campos disponíveis: #### Data e Hora (Date and Time) * Define a data e o horário em que a ação será executada * O formato segue o padrão `dd/mm/aaaa hh:mm` #### Recorrência (Recurrence) * Define a frequência da ação * Atualmente disponível: * **Uma vez (Once)**: executa a ação apenas uma vez ### Definindo o Tipo de Ação No campo **Tipo de Ação** (Action Type), selecione o tipo de ação que será executada. ### Opção disponível: * **Enviar Mensagem (Send Message)**: envia uma mensagem automática para o contato selecionado *** ## Selecionando o Canal No campo **Canal** (Channel), escolha por qual canal a mensagem será enviada. ### Exemplos de canais: * Telegram * WhatsApp (se configurado) * Outros canais integrados à plataforma > Apenas canais previamente configurados estarão disponíveis para seleção. ## Escrevendo a Mensagem No campo **Mensagem** (Message), escreva o conteúdo que será enviado ao contato no momento agendado. ### Dicas: * A mensagem será enviada exatamente como foi escrita * Verifique o texto antes de salvar a ação *** ## Salvando a Ação Agendada Após preencher todos os campos corretamente, clique em **Salvar** (Save) para finalizar a criação da ação. Finalizando a criação da ação Se desejar cancelar o processo, clique em **Cancelar** (Cancel). *** ## Considerações Finais * Cada Ação Agendada está vinculada a um único contato * A ação será executada automaticamente na data e hora configuradas * É possível visualizar e gerenciar todas as ações pela tela principal de Ações Agendadas Essa funcionalidade oferece mais controle e automação no relacionamento com contatos, garantindo que mensagens importantes sejam enviadas no momento certo. # Interface de Chat Source: https://docs.evolutionfoundation.com.br/user-guides/conversations/chat-interface A **Interface de Chat** é onde você visualiza e interage diretamente com as conversas, visualiza o histórico de mensagens, envia respostas e realiza ações específicas para cada interação com o cliente. Esta seção detalha os componentes da interface de chat, incluindo o cabeçalho da conversa, o histórico de mensagens, a área de composição de mensagens e as ferramentas de assistência de IA disponíveis. *** ## Acessando a Interface de Chat Para abrir a interface de chat: 1. Na lista de conversas, clique na conversa desejada 2. A interface de chat será aberta no painel direito ou central, dependendo do layout *** ## Estrutura da Interface de Chat A interface de chat ocupa a área central e direita da tela, exibindo os detalhes da conversa selecionada na lista lateral. Interface completa de chat A interface principal de conversas apresenta uma estrutura dividida em três colunas principais: ### Barra de Navegação Superior No topo da tela, há uma barra de navegação com: * **Seletor de Contexto:** No canto superior esquerdo, um seletor exibindo "Evolution" com ícone de prédio e uma seta para baixo, indicando o contexto ou ambiente atual * **Ícones de Controle:** No canto superior direito: * Ícone de sol/lua para alternar tema (claro/escuro) * Ícone de sino para notificações * Avatar do usuário (ex: "MS") ### Lista de Conversas (Coluna da Esquerda) A coluna da esquerda exibe todas as conversas disponíveis: #### Barra de Pesquisa * **Campo de Busca:** No topo da coluna, um campo com placeholder "Search conversations..." e ícone de lupa * **Funcionalidade:** Permite buscar conversas por nome do contato ou palavras-chave #### Contador e Filtros Abaixo da barra de pesquisa: * **Contador de Conversas:** Exibe o número total de conversas encontradas (ex: "1 conversation") * **Indicador de Filtros:** Mostra quantos filtros estão ativos (ex: "1 filter") * **Botão Filters:** Com ícone de funil, permite abrir o modal de configuração de filtros #### Conversa Selecionada A conversa atualmente selecionada é destacada em um bloco verde-escuro: * **Avatar:** Foto de perfil do contato (ex: "Davidson Gomes") * **Ícone do Canal:** Pequeno ícone sobreposto ao avatar indicando o canal (ex: ícone azul de avião de papel para Telegram) * **Nome e Horário:** Nome do contato seguido de "Evolu..." e indicação de tempo (ex: "Agora") * **Preview da Mensagem:** Última mensagem trocada na conversa (ex: "Ola") * **Indicador de Status:** Pequeno ícone de relógio amarelo, sugerindo status específico da conversa ou horário comercial ### Interface de Chat Ativa (Coluna Principal à Direita) A coluna principal à direita mostra a conversa selecionada: #### Cabeçalho da Conversa * **Informações do Contato:** * Nome do cliente e canal (ex: "Davidson Gomes - Evolution API") * Identificador interno (ex: "evoai-davidson") * Status da conversa (ex: "Status: Pendente") * **Botões de Ação:** No canto superior direito: * Botão "Open Conversation" (verde com ícone de cadeado aberto) * Ícone de três pontos verticais (menu de opções) * Ícone "X" (fechar conversa) #### Histórico de Mensagens A área central exibe o fluxo cronológico das mensagens: * **Marcador de Início:** Uma linha horizontal centralizada com o texto "Start of conversation" * **Mensagem Recebida:** * Bolha de chat preta/cinza à esquerda * Texto da mensagem (ex: "ola") * Timestamp abaixo (ex: "19 jan às 12:57") * **Mensagem Enviada:** * Bolha de chat verde-água à direita * Identificação do agente acima (ex: "Agent Davidson Gomes") * Texto da mensagem dentro da bolha (ex: "Ola") * Timestamp com checkmark (ex: "19 jan às 12:57 ✓") indicando que a mensagem foi enviada/lida #### Área de Composição de Mensagens (Inferior) Na parte inferior da interface: * **Abas de Modo:** * **Reply:** Aba desativada (cinza claro) para respostas públicas ao cliente * **Private Note:** Aba ativada (verde) com ícone de cadeado para notas internas * Texto informativo: "Visible only to agents" ao lado da aba Private Note * **Campo de Texto:** Grande caixa de texto retangular com placeholder dinâmico baseado na aba selecionada * **Ícones de Ação (Inferior Esquerdo):** * Clipe de papel (anexar arquivos) * Rosto sorridente (emojis) * "@" (menções) * Documento/estrela (modelos de resposta rápida) * **Botões de Envio e Ferramentas (Inferior Direito):** * Microfone (gravação de áudio) * Estrela/diamante brilhante (AI Assistance) * Avião de papel (enviar mensagem) *** ## Área de Composição de Mensagens A área de composição permite aos agentes responderem e adicionarem notas internas. Esta seção é fundamental para a interação com os clientes. Área de composição de mensagens ### Abas de Modo de Composição Na parte superior da área de composição, há duas abas que determinam o tipo de mensagem: #### Reply (Responder) * **Função:** Enviar mensagens públicas que serão visíveis ao cliente * **Quando usar:** Para responder diretamente ao cliente * **Estilo:** Aba destacada em verde quando ativa * **Placeholder:** "Type your message... (type / for canned responses)" #### Private Note (Nota Privada) * **Função:** Adicionar notas internas visíveis apenas para outros agentes * **Quando usar:** Para discussões internas sobre a conversa, repassar informações ou solicitar ajuda * **Visibilidade:** Apenas visível para agentes e colaboradores da plataforma * **Estilo:** Aba destacada em verde com ícone de cadeado quando ativa * **Placeholder:** "Type your private note (pending conversation)..." * **Texto informativo:** "Visible only to agents" ao lado da aba ### Campo de Texto A área principal para digitar mensagens: * **Tamanho:** Grande caixa de texto retangular * **Placeholder dinâmico:** * "Type your message... (type / for canned responses)" quando a aba Reply está ativa * "Type your private note (pending conversation)..." quando a aba Private Note está ativa * **Atalho:** Digite "/" para acessar respostas prontas (canned responses) ### Ícones de Ação e Formatação No canto inferior esquerdo do campo de texto, há vários ícones: * **Anexo (Clipe de Papel):** * Permite anexar arquivos, imagens ou documentos * Clique para selecionar arquivos do seu dispositivo * **Emojis (Smiley Face):** * Abre o seletor de emojis * Adiciona expressividade às mensagens * **Menções (@):** * Permite mencionar outros agentes em notas privadas * Útil para chamar atenção de membros específicos da equipe * **Modelos de Resposta Rápida (Documento/Estrela):** * Acessa respostas prontas ou templates de mensagem * Digite "/" no campo de texto para atalho rápido ### Botões de Envio e Ferramentas Adicionais No canto inferior direito da área de composição: * **Microfone:** * Possível entrada de voz (se disponível) * Permite gravar mensagens de áudio * **AI Assistance (Estrela/Diamante):** * Ícone de diamante brilhante ou estrela estilizada * Abre o modal de assistência de inteligência artificial * Veja a seção "Assistência de IA" abaixo para mais detalhes * **Enviar (Avião de Papel):** * Envia a mensagem digitada * Também pode ser acionado pressionando Enter *** ## Ação "Open Conversation" O botão **Open Conversation** é crucial para o fluxo de trabalho da plataforma. Botão Open Conversation destacado O cabeçalho da interface de chat exibe o botão **Open Conversation** no canto superior direito, destacado em verde com ícone de cadeado aberto. ### Informações da Conversa No cabeçalho, você pode visualizar: * **Nome do Contato e Canal:** "Davidson Gomes - Evolution API" (nome do cliente e canal de comunicação) * **Identificador Interno:** "evoai-davidson" (identificador único da conversa) * **Status da Conversa:** "Status: Pendente" (estado atual da conversa) ### Botão "Open Conversation" O botão está localizado no canto superior direito do cabeçalho: * **Aparência:** Botão verde com texto "Open Conversation" e ícone de cadeado aberto * **Função:** Altera o status da conversa de "Pendente" para "Aberta" * **Quando usar:** Quando você está pronto para iniciar o atendimento ativo * **Importante:** Este botão é crucial para o fluxo de trabalho, sinalizando que um agente está ativamente engajado na resolução ### Outros Botões no Cabeçalho À direita do botão "Open Conversation", você encontra: * **Menu de Opções:** Ícone de três pontos verticais para opções adicionais relacionadas à conversa * **Fechar Conversa:** Ícone "X" para fechar a visualização da conversa ### Quando Usar * Quando uma conversa está no status **"Pendente"** * Quando você está pronto para iniciar o atendimento ativo * Para sinalizar que um agente está engajado na resolução ### Como Funciona 1. Clique no botão **Open Conversation** no cabeçalho da conversa 2. O status da conversa muda de **"Pendente"** para **"Aberta"** 3. Isso indica que o atendimento foi iniciado e um agente está ativamente trabalhando na conversa ### Importância * **Organização:** Ajuda a rastrear quais conversas estão sendo atendidas * **Colaboração:** Evita que múltiplos agentes trabalhem na mesma conversa simultaneamente * **Métricas:** Contribui para relatórios e análises de desempenho *** ## Notas Privadas A funcionalidade de **Private Note** permite que a equipe se comunique internamente dentro do contexto de uma conversa específica. Modal de Assistência de IA ### Características * **Visibilidade:** Apenas visível para outros agentes e colaboradores * **Cliente não vê:** As notas privadas não aparecem para o cliente * **Contexto:** Mantém o contexto da conversa específica ### Quando Usar * **Discussões internas:** Para discutir estratégias de atendimento * **Repasse de informações:** Para deixar informações importantes para outros agentes * **Solicitar ajuda:** Para pedir assistência de outros membros da equipe * **Anotações:** Para registrar observações importantes sobre o cliente ou situação ### Como Usar 1. Clique na aba **Private Note** na área de composição 2. Digite sua nota no campo de texto 3. Opcionalmente, use "@" para mencionar outros agentes 4. Clique no botão de envio ou pressione Enter *** ## Assistência de IA (AI Assistance) O Evo CRM oferece ferramentas de inteligência artificial integradas para otimizar as interações com os clientes. Modal de Assistência de IA ### Acessando a Assistência de IA Para abrir o modal de AI Assistance: 1. Na área de composição de mensagens, localize o ícone de **AI Assistance** (diamante brilhante ou estrela) 2. Clique no ícone 3. O modal **AI Assistance** será exibido no lado esquerdo da interface ### Estrutura do Modal O modal apresenta: * **Título:** "AI Assistance" com ícone de diamante brilhante verde ao lado * **Subtítulo:** "Select an action to get started" (Selecione uma ação para começar) * **Botão de Fechar:** Ícone "X" no canto superior direito ### Ações Disponíveis O modal apresenta uma série de cards clicáveis, cada um representando uma funcionalidade de IA: #### Reply suggestion (Sugestão de Resposta) * **Ícone:** Diamante brilhante * **Descrição:** "Generate reply suggestion" (Gerar sugestão de resposta) * **Uso:** Gera sugestões de resposta baseadas no contexto da conversa #### Summarize conversation (Resumir Conversa) * **Ícone:** Letra 'T' * **Descrição:** "Create conversation summary" (Criar resumo da conversa) * **Uso:** Cria um resumo automático de toda a conversa #### Rephrase (Reescrever) * **Ícone:** Diamante brilhante com setas duplas * **Descrição:** "Rewrite the message in a different way" (Reescrever a mensagem de uma forma diferente) * **Uso:** Reescreve uma mensagem mantendo o significado mas alterando a forma #### Fix spelling (Corrigir Ortografia) * **Ícone:** Documento com marca de verificação * **Descrição:** "Correct grammatical and spelling errors" (Corrigir erros gramaticais e de ortografia) * **Uso:** Corrige automaticamente erros de gramática e ortografia #### Expand (Expandir) * **Ícone:** Setas opostas se expandindo * **Descrição:** "Make the message more detailed" (Tornar a mensagem mais detalhada) * **Uso:** Expande uma mensagem curta em uma versão mais detalhada #### Shorten (Resumir) * **Ícone:** Setas opostas se contraindo * **Descrição:** "Summarize the message" (Resumir a mensagem) * **Uso:** Reduz uma mensagem longa em uma versão mais concisa #### Make friendly (Tornar Amigável) * **Ícone:** Rosto sorrindo * **Descrição:** "Use a more casual and friendly tone" (Usar um tom mais casual e amigável) * **Uso:** Adapta o tom da mensagem para ser mais casual e amigável #### Make formal (Tornar Formal) * **Ícone:** Chapéu de formatura/gravata * **Descrição:** "Use a more professional tone" (Usar um tom mais profissional) * **Uso:** Adapta o tom da mensagem para ser mais formal e profissional #### Simplify (Simplificar) * **Ícone:** Lâmpada * **Descrição:** "Make it easier to understand" (Tornar mais fácil de entender) * **Uso:** Simplifica a linguagem da mensagem para facilitar a compreensão #### Analyze sentiment (Analisar Sentimento) * **Ícone:** Escudo ou anel protetor * **Descrição:** "Check if the message contains offensive or inappropriate content" (Verificar se a mensagem contém conteúdo ofensivo ou inapropriado) * **Uso:** Analisa o sentimento e detecta conteúdo potencialmente problemático ### Como Usar as Ações de IA 1. Digite ou selecione a mensagem que deseja processar 2. Clique no ícone de **AI Assistance** 3. Selecione a ação desejada no modal 4. A IA processará a mensagem conforme a ação selecionada 5. Revise o resultado e use conforme necessário *** ## Considerações Finais * A interface de chat é projetada para uma interação eficiente e contextualizada * O status da conversa pode ser facilmente gerenciado através do cabeçalho usando o botão "Open Conversation" * A distinção entre **Reply** e **Private Note** é fundamental para comunicação eficaz com clientes e colaboração interna da equipe * As informações do contato e o identificador único ajudam a manter o contexto da conversa * As mensagens são sincronizadas em tempo real entre todos os agentes * Você pode ver quando outros agentes estão digitando * O histórico completo da conversa é mantido permanentemente * As ferramentas de IA ajudam a otimizar a qualidade e eficiência das respostas * Algumas funcionalidades podem variar dependendo do canal de comunicação * Use as notas privadas para manter a comunicação interna organizada e contextualizada *** ## Novidades do v1.0.0-rc3 * **Telefone do contato visível na lista e no header.** Antes era necessário abrir o detalhe do contato para ver o número. Agora o número aparece tanto no card de cada conversa na lista quanto no cabeçalho do chat (EVO-988). * **Reconexão ativa de WebSocket.** Quando a conexão cai (rede instável, reinício do servidor), o frontend tenta reconectar em background com backoff exponencial. Ao restabelecer, exibe toast de sucesso. Antes a conexão caída ficava silenciosa e era preciso atualizar a página (EVO-1085). * **Upload de arquivos grandes.** Limite elevado para 100MB. Arquivos grandes pulam o fluxo de fetch+blob e usam upload direto (EVO-1131). * **Scroll preservado na paginação.** Ao paginar o histórico, o scroll fica fixo na posição em que você estava — não pula mais para o topo (EVO-1106). # Ações de Conversa Source: https://docs.evolutionfoundation.com.br/user-guides/conversations/conversation-actions As **Ações de Conversa** são funcionalidades que permitem gerenciar e organizar conversas de forma eficiente. Através dessas ações, você pode atribuir agentes, alterar status, adicionar etiquetas, criar notas, definir prioridades e muito mais. Esta seção detalha todas as ações disponíveis para gerenciar conversas, incluindo o menu de ações principal e o painel lateral de contexto e informações. *** ## Acessando Ações de Conversa As ações de conversa estão disponíveis através de: * **Menu de ações (três pontos):** Localizado no canto superior direito do cabeçalho da conversa * **Menu de contexto:** Clique com o botão direito na conversa na lista * **Painel lateral direito:** Clique no avatar do contato no cabeçalho da conversa *** ## Menu de Ações de Conversa O menu de ações é acessado através do ícone de três pontos verticais no cabeçalho da conversa. Menu de ações de conversa ### Acessando o Menu Para abrir o menu de ações: 1. No cabeçalho da conversa, localize o ícone de três pontos verticais (`:`) no canto superior direito 2. Clique no ícone 3. O menu suspenso será exibido com todas as ações disponíveis ### Estrutura do Menu O menu apresenta as ações organizadas em categorias: #### Gerenciamento de Status Estas ações permitem alterar o status da conversa: * **Mark as unread (Marcar como não lida):** * Ícone: Envelope * Função: Marca a conversa como não lida * Quando usar: Quando você precisa revisar a conversa posteriormente * **Mark as resolved (Marcar como resolvida):** * Ícone: Checkmark dentro de um círculo * Função: Marca a conversa como resolvida * Quando usar: Quando o problema ou questão foi completamente resolvido * **Mark as pending (Marcar como pendente):** * Ícone: Relógio * Função: Marca a conversa como pendente * Quando usar: Quando a conversa precisa aguardar uma resposta ou ação * **Pause conversation (Pausar conversação):** * Ícone: Duas barras verticais * Função: Pausa temporariamente a conversa * Quando usar: Quando você precisa interromper temporariamente o atendimento #### Gerenciamento de Prioridade Estas ações permitem definir a prioridade da conversa: * **Urgent Priority (Prioridade Urgente):** * Estilo: Texto vermelho com ícone de triângulo de exclamação vermelho * Função: Marca a conversa como urgente * Quando usar: Para questões críticas que requerem atenção imediata * **High Priority (Alta Prioridade):** * Ícone: Seta para cima laranja * Função: Define prioridade alta * Quando usar: Para questões importantes que precisam ser tratadas rapidamente * **Medium Priority (Prioridade Média):** * Ícone: Linha horizontal azul * Função: Define prioridade média * Quando usar: Para questões normais que seguem o fluxo padrão * **Low Priority (Baixa Prioridade):** * Ícone: Seta para baixo azul * Função: Define prioridade baixa * Quando usar: Para questões que podem ser tratadas quando houver disponibilidade #### Atribuição e Organização Estas ações permitem atribuir responsabilidades e organizar conversas: * **Assign Agent (Atribuir Agente):** * Ícone: Pessoa * Função: Atribui a conversa a um agente específico * Quando usar: Para direcionar a conversa para um agente específico * **Assign Team (Atribuir Equipe):** * Ícone: Duas pessoas * Função: Atribui a conversa a uma equipe * Quando usar: Para distribuir a conversa entre membros de uma equipe * **Assign Label (Atribuir Etiqueta):** * Ícone: Tag * Função: Adiciona etiquetas à conversa * Quando usar: Para categorizar e organizar conversas por temas ou tipos #### Outras Ações * **Delete conversation (Excluir conversação):** * Estilo: Texto vermelho com ícone de lixeira * Função: Remove permanentemente a conversa * Quando usar: Apenas quando necessário remover conversas irrelevantes ou duplicadas * **Atenção:** Esta ação é permanente e não pode ser desfeita *** ## Painel Lateral de Contexto e Ações O painel lateral direito fornece acesso a informações detalhadas do contato e ações relacionadas à conversa. Painel lateral de contexto e ações ### Acessando o Painel Lateral Para abrir o painel lateral: 1. No cabeçalho da conversa, clique no avatar do contato 2. O painel lateral será exibido no lado direito da interface ### Estrutura do Painel Lateral O painel apresenta seções expansíveis organizadas em cards: #### Cabeçalho do Painel * **Avatar do Contato:** Foto de perfil maior do contato * **Nome e Canal:** Nome do contato seguido do canal (ex: "Davidson Gomes - Evolution API") * **Status Online:** Indicador "• Online" mostrando se o contato está online #### Seções Disponíveis Cada seção é um card expansível com título, descrição, ícone e seta indicando que pode ser expandida: ##### Contact Information (Informações do Contato) * **Ícone:** Pessoa * **Descrição:** "Personal data and attributes" * **Conteúdo:** Exibe dados pessoais e atributos do contato * **Uso:** Visualizar e editar informações do contato ##### Pipeline * **Ícone:** Chave inglesa/tubo * **Descrição:** "Manage sales funnel" * **Conteúdo:** Gerencia o funil de vendas ou processo * **Uso:** Mover o contato através de diferentes estágios do processo de vendas ou suporte ##### Macros * **Ícone:** Raio * **Descrição:** "Execute automations" * **Conteúdo:** Executa ações automatizadas * **Uso:** Aplicar automações pré-configuradas à conversa ou contato ##### Contact Notes (Notas do Contato) * **Ícone:** Documento/bloco de notas * **Descrição:** "Important notes" * **Conteúdo:** Permite adicionar ou revisar notas importantes sobre o contato * **Uso:** Registrar informações relevantes sobre o contato que podem ser úteis em futuras interações ##### Previous Conversations (Conversas Anteriores) * **Ícone:** Bolha de chat * **Descrição:** "Conversation history" * **Conteúdo:** Exibe o histórico de conversas anteriores * **Uso:** Revisar interações passadas com o contato ##### Conversation Information (Informações da Conversa) * **Ícone:** Relógio * **Descrição:** "Technical details" * **Conteúdo:** Exibe detalhes técnicos da conversa * **Uso:** Visualizar informações técnicas como timestamps, IDs, metadados ##### Conversation Attributes (Atributos da Conversa) * **Ícone:** 'i' em um círculo * **Descrição:** "Editable custom attributes" * **Conteúdo:** Permite editar atributos personalizados da conversa * **Uso:** Adicionar ou modificar atributos customizados específicos da conversa ##### Contact Attributes (Atributos do Contato) * **Ícone:** Tag * **Descrição:** "Editable custom attributes" * **Conteúdo:** Permite editar atributos personalizados do contato * **Uso:** Adicionar ou modificar atributos customizados do contato ### Como Usar as Seções 1. Clique no avatar do contato no cabeçalho da conversa 2. O painel lateral será aberto no lado direito 3. Clique em qualquer seção para expandir e visualizar mais detalhes 4. Use as ações disponíveis em cada seção conforme necessário *** ## Ações Disponíveis (Resumo Detalhado) ### Alterar Status da Conversa Gerencia o estado atual da conversa: * **Aberto (Open):** Conversa ativa e em andamento * **Pendente (Pending):** Aguardando resposta ou ação * **Resolvido (Resolved):** Conversa finalizada com sucesso * **Fechado (Closed):** Conversa arquivada * **Não Lida (Unread):** Conversa marcada para revisão posterior * **Pausada (Paused):** Conversa temporariamente interrompida **Como alterar:** 1. Abra o menu de ações (três pontos) 2. Selecione a ação de status desejada 3. O status será atualizado imediatamente ### Definir Prioridade Organize conversas por nível de urgência: * **Urgente:** Requer atenção imediata (vermelho) * **Alta:** Importante e deve ser tratada rapidamente (laranja) * **Média:** Segue o fluxo padrão (azul) * **Baixa:** Pode ser tratada quando houver disponibilidade (azul) **Como definir:** 1. Abra o menu de ações 2. Selecione a prioridade desejada na seção "Priority" 3. A conversa será marcada com a prioridade selecionada ### Atribuir Agente ou Equipe Direcione conversas para agentes ou equipes específicas: **Atribuir Agente:** 1. Abra o menu de ações 2. Selecione "Assign Agent" 3. Escolha o agente desejado da lista 4. A conversa será atribuída ao agente selecionado **Atribuir Equipe:** 1. Abra o menu de ações 2. Selecione "Assign Team" 3. Escolha a equipe desejada 4. A conversa será distribuída entre os membros da equipe ### Adicionar Etiquetas (Labels) Organize conversas usando etiquetas: 1. Abra o menu de ações 2. Selecione "Assign Label" 3. Escolha etiquetas existentes ou crie novas 4. As etiquetas ajudam a categorizar e filtrar conversas ### Gerenciar Informações do Contato Através do painel lateral: 1. Clique no avatar do contato 2. Expanda a seção "Contact Information" 3. Visualize ou edite dados pessoais e atributos 4. Use "Contact Attributes" para adicionar atributos customizados ### Gerenciar Notas Adicione notas importantes sobre o contato: 1. Abra o painel lateral clicando no avatar 2. Expanda a seção "Contact Notes" 3. Adicione ou revise notas importantes 4. As notas ficam disponíveis para todos os agentes ### Visualizar Histórico Revise conversas anteriores: 1. Abra o painel lateral 2. Expanda a seção "Previous Conversations" 3. Navegue pelo histórico de interações 4. Use o histórico para entender o contexto completo ### Executar Macros Aplique automações pré-configuradas: 1. Abra o painel lateral 2. Expanda a seção "Macros" 3. Selecione a automação desejada 4. A macro será executada automaticamente ### Gerenciar Pipeline Mova o contato através do funil: 1. Abra o painel lateral 2. Expanda a seção "Pipeline" 3. Selecione o estágio desejado 4. O contato será movido para o novo estágio *** ## Ações em Lote Algumas ações podem ser aplicadas a múltiplas conversas simultaneamente: ### Como Usar Ações em Lote 1. Na lista de conversas, selecione as conversas desejadas usando checkboxes 2. Um menu de ações em lote aparecerá no topo da lista 3. Escolha a ação desejada 4. Confirme a ação em lote ### Ações Disponíveis em Lote * **Atribuir a agente:** Atribui múltiplas conversas a um agente * **Alterar status:** Altera o status de várias conversas de uma vez * **Adicionar/remover etiquetas:** Aplica etiquetas a múltiplas conversas * **Definir prioridade:** Define a mesma prioridade para várias conversas * **Arquivar:** Move múltiplas conversas para o arquivo * **Resolver em lote** *(a partir do v1.0.0-rc3)***:** Marca as conversas selecionadas como `resolvidas` em uma única operação (EVO-1011). ### Resultado por item (rc3) A partir do `v1.0.0-rc3`, ações em lote retornam o resultado de cada item separadamente — `success_ids` com as conversas processadas com sucesso e `failed_ids` com as que falharam (e o motivo). Antes a resposta era binária (tudo ou nada), o que mascarava falhas parciais. Na UI, conversas que falharam ficam destacadas e o operador pode tentar a ação novamente apenas nelas. *** ## Considerações Finais * Todas as ações são registradas no histórico da conversa * Algumas ações podem exigir permissões específicas * As ações em lote são úteis para gerenciar múltiplas conversas rapidamente * O painel lateral fornece acesso rápido a informações e ações relacionadas * As prioridades ajudam a organizar o fluxo de trabalho e garantir que questões urgentes sejam tratadas primeiro * Use etiquetas para categorizar conversas e facilitar a busca e filtragem * O histórico de conversas ajuda a manter o contexto em interações futuras * Macros podem automatizar tarefas repetitivas e aumentar a eficiência * Consulte as permissões da sua conta para ver quais ações estão disponíveis * A ação de excluir conversa é permanente e deve ser usada com cuidado # Visão Geral de Conversas Source: https://docs.evolutionfoundation.com.br/user-guides/conversations/overview A seção **Conversas** é o centro de comunicação do Evo CRM, onde você pode gerenciar todas as interações com seus clientes através dos diferentes canais de comunicação. Nesta área, você pode visualizar, responder e gerenciar conversas de forma centralizada, independente do canal utilizado (WhatsApp, Email, Facebook, Instagram, Telegram, SMS, Website Widget ou API). *** ## Acessando Conversas Para acessar a área de conversas: 1. No menu lateral esquerdo, clique em **Conversas** 2. A tela principal será exibida com a lista de todas as conversas ativas *** ## Interface Principal de Conversas A tela de conversas é dividida em duas áreas principais: a lista de conversas à esquerda e a área de visualização da conversa selecionada à direita. Tela inicial de conversas ### Estrutura da Interface A interface principal apresenta: #### Área de Lista de Conversas A coluna da esquerda exibe todas as conversas disponíveis: * **Barra de Pesquisa:** Campo no topo para buscar conversas específicas * **Contador de Conversas:** Exibe o total de conversas encontradas (ex: "3 conversations") * **Indicador de Filtros:** Mostra quantos filtros estão ativos (ex: "1 filter") * **Botão Filters:** Permite aplicar e gerenciar filtros Cada item da lista de conversas exibe: * **Avatar do Contato:** Foto de perfil ou inicial do nome * **Nome do Contato:** Nome completo do cliente * **Canal de Comunicação:** Ícone indicando o canal (Telegram, WhatsApp, Email, etc.) * **Timestamp:** Data e hora da última mensagem (ex: "Agora", "21 jan 1970") * **Preview da Mensagem:** Última mensagem trocada na conversa * **Indicadores de Status:** Ícones que indicam status da conversa ou canal #### Área de Visualização da Conversa A coluna da direita mostra a conversa selecionada: * **Cabeçalho da Conversa:** * Nome do contato e canal (ex: "Davidson Gomes - Evolution API") * Identificador único (ex: "evoai-davidson") * Status da conversa (ex: "Status: Aberta" ou "Status: Pendente") * Botões de ação (menu de três pontos, fechar) * **Histórico de Mensagens:** * Mensagens recebidas aparecem à esquerda * Mensagens enviadas aparecem à direita com nome do agente * Timestamps para cada mensagem * Indicadores de leitura/entrega * **Área de Composição:** * Abas para **Reply** (Responder) e **Private Note** (Nota Privada) * Campo de texto para digitar mensagens * Ícones para anexos, emojis, menções e modelos de resposta rápida * Botão de envio *** ## Busca e Filtros A barra de busca e os filtros são ferramentas essenciais para localizar conversas específicas rapidamente. Barra de pesquisa e filtros ### Barra de Pesquisa No topo da lista de conversas, você encontra: * **Campo de Busca:** Com placeholder "Search conversations..." * **Ícone de Lupa:** Indica a funcionalidade de busca * **Funcionalidade:** Permite buscar conversas por nome do contato, palavras-chave ou conteúdo das mensagens **Como usar:** 1. Clique no campo de busca 2. Digite o nome do contato ou palavra-chave (ex: "Davidson Gomes") 3. A lista será filtrada automaticamente mostrando apenas conversas correspondentes 4. O contador será atualizado (ex: "1 conversation") ### Contador e Filtros Abaixo da barra de busca: * **Contador de Conversas:** Exibe o número total de conversas encontradas após aplicar busca e filtros * Exemplo: "1 conversation" ou "3 conversations" * **Indicador de Filtros Ativos:** Mostra quantos filtros estão aplicados * Exemplo: "1 filter" indica que há um filtro ativo * **Botão Filters:** Com ícone de funil, permite abrir o modal de configuração de filtros ### Lista de Conversas Filtrada Quando busca ou filtros são aplicados, a lista exibe apenas as conversas correspondentes: * **Avatar e Nome:** Foto de perfil e nome do contato * **Ícone do Canal:** Pequeno ícone sobreposto ao avatar indicando o canal (ex: ícone azul de avião de papel para Telegram) * **Timestamp:** "Agora" para conversas recentes ou data/hora específica * **Preview da Mensagem:** Última mensagem trocada * **Indicadores de Status:** Ícones que podem indicar: * Status da conversa (pendente, aberta, resolvida) * Horário comercial (ícone de relógio amarelo) * Prioridade ou outros estados *** ## Configurando Filtros de Conversas O sistema permite aplicar múltiplos filtros para refinar a visualização das conversas. Modal de filtros de conversas ### Acessando o Modal de Filtros Para abrir o modal de filtros: 1. Clique no botão **Filters** na parte superior da lista de conversas 2. O modal **Filter Conversations** será exibido ### Estrutura do Modal de Filtros O modal apresenta: #### Título e Descrição * **Título:** "Filter Conversations" * **Descrição:** "Configure filters to find the conversations you're looking for" * **Botão de Fechar:** Ícone "X" no canto superior direito #### Filtros Configurados A área principal exibe os filtros já aplicados: **Exemplo de Filtro Ativo:** * **Campo 1 - Tipo de Filtro:** Dropdown com opções como "Status", "Agent", "Channel", "Labels", etc. * **Campo 2 - Operador:** Dropdown com operadores como: * "Equal to" (Igual a) * "Not equal to" (Diferente de) * "Contains" (Contém) * "Does not contain" (Não contém) * **Campo 3 - Valor:** Dropdown ou campo de texto com o valor específico (ex: "Pending") * **Botão Remover:** Ícone "X" à direita para remover o filtro individual **Exemplo prático:** * **Filtro:** Status = Equal to = Pending * **Resultado:** Mostra apenas conversas com status "Pendente" #### Adicionar Novo Filtro * **Botão "Add Filter":** Com ícone de "+" no centro do modal * **Funcionalidade:** Permite adicionar múltiplos critérios de filtragem * **Uso:** Clique para adicionar uma nova linha de filtro #### Botões de Ação Na parte inferior do modal: * **Clear Filters:** Remove todos os filtros aplicados * **Cancel:** Fecha o modal sem aplicar alterações * **Apply Filters:** Botão verde que aplica os filtros configurados e atualiza a lista ### Tipos de Filtros Disponíveis Os filtros podem ser aplicados por: * **Status:** Pendente, Aberta, Resolvida, Fechada * **Agente:** Filtrar por agente atribuído * **Canal:** WhatsApp, Email, Telegram, Facebook, Instagram, SMS, API, Website Widget * **Etiquetas (Labels):** Filtrar por etiquetas aplicadas * **Data:** Período de criação ou última atualização * **Prioridade:** Nível de prioridade da conversa *** ## Considerações Finais * A interface de conversas foi projetada para navegação e interação intuitivas * A busca permite localizar conversas rapidamente por nome ou conteúdo * Os filtros ajudam a organizar e gerenciar grandes volumes de conversas * A distinção entre respostas públicas e notas privadas é fundamental para comunicação interna da equipe * Todas as mensagens são sincronizadas em tempo real entre todos os agentes * O status da conversa pode ser alterado diretamente na interface * Cada canal de comunicação possui ícones e indicadores específicos para fácil identificação # Visão Geral do Dashboard Source: https://docs.evolutionfoundation.com.br/user-guides/getting-started/dashboard-overview O **Dashboard** é a tela inicial do Evo CRM e oferece uma visão consolidada dos principais indicadores operacionais do seu workspace. A partir daqui, você acompanha o desempenho da equipe, o volume de mensagens, os tempos de resposta e o status das conversas em tempo real. Visão geral do Dashboard *** ## Acessando o Dashboard O Dashboard fica disponível na barra lateral esquerda, identificado pelo ícone de relógio e pelo nome **Dashboard**. Ele é a primeira tela exibida ao fazer login no Evo CRM. *** ## Filtros e Período de Análise No topo da página, você encontra o botão **Filtros** e o seletor de período. O período padrão exibe os últimos 31 dias, mas pode ser ajustado conforme necessário para análises de intervalos específicos. * **Filtros**: permite segmentar os dados por canal, equipe, agente ou outros critérios disponíveis. * **Período**: exibe o intervalo de datas atualmente selecionado (ex.: `15/03/2026 - 13/04/2026 (31 dias)`). *** ## Status da Operação Agora Esta seção apresenta quatro indicadores-chave para leitura rápida da saúde operacional do seu time. ### Mensagens Recebidas Exibe o total de mensagens recebidas no período selecionado, acompanhado do total de mensagens enviadas. * **Badge de contexto**: indica se o volume está dentro ou fora do esperado. * **Dado exibido**: número absoluto de mensagens recebidas e enviadas. ### Tempo Médio de Resposta Mostra o tempo médio que a equipe leva para responder às mensagens dos contatos. * **Badge de contexto**: `Dentro do esperado` ou outro status de acordo com os limiares configurados. * **Dado exibido**: tempo médio em segundos, minutos ou horas. * **Nota**: o valor `Dados reais` indica que o cálculo usa dados efetivos de resposta, não estimados. ### CSAT Médio Apresenta a média de satisfação dos clientes (Customer Satisfaction Score) com base nas avaliações coletadas no período. * **Badge de contexto**: `Sem base` quando ainda não há avaliações suficientes para cálculo. * **Dado exibido**: nota média em escala de `0.00 / 5` e o total de avaliações recebidas. ### Follow-ups Pendentes Indica quantos follow-ups estão aguardando ação da equipe. * **Badge de contexto**: `Dentro do esperado` ou status de alerta. * **Dado exibido**: total de follow-ups pendentes e quantos estão em atraso. *** ## IA vs Humano Esta seção compara o volume de respostas geradas pela IA com as respostas realizadas por atendentes humanos no período selecionado. Quando não há dados disponíveis (IA inativa ou respostas não classificadas), a seguinte mensagem é exibida: > *IA ainda não está ativa neste período, ou as respostas não foram classificadas.* Assim que a IA estiver configurada e ativa, este gráfico exibirá a distribuição entre atendimentos automatizados e humanos. *** ## Conversas Ativas Agora Exibe o número de conversas em andamento no momento atual, representando o backlog operacional em tempo real. * **Badge de contexto**: `Dentro do esperado` ou alerta quando o volume ultrapassa os limiares definidos. * **Dado exibido**: total de conversas ativas no instante da consulta. *** ## Considerações Finais O **Dashboard** é o ponto de partida para entender a saúde operacional do seu workspace no Evo CRM. Use os filtros e o seletor de período para navegar entre diferentes intervalos de análise e identificar tendências no atendimento. Para configurações avançadas de limiares e alertas, acesse a seção **Configurações**. # Primeiro Login Source: https://docs.evolutionfoundation.com.br/user-guides/getting-started/first-login O **Primeiro Login** é o processo inicial de acesso à plataforma Evo CRM. Este guia irá orientá-lo através dos passos necessários para fazer seu primeiro login e configurar sua conta inicial. ## Recebendo Suas Credenciais Antes de fazer seu primeiro login, você precisa receber suas credenciais de acesso: 1. **Credenciais enviadas por email:** Um administrador do sistema criou sua conta e você recebeu um email com suas credenciais de acesso. 2. **Credenciais fornecidas diretamente:** Um administrador forneceu suas credenciais pessoalmente ou através de um canal seguro. As credenciais geralmente incluem: * **Email:** Seu endereço de email cadastrado no sistema. * **Senha temporária:** Uma senha inicial que você precisará alterar no primeiro acesso. Mantenha suas credenciais seguras e nunca compartilhe sua senha com outras pessoas. Se você suspeitar que sua conta foi comprometida, entre em contato com o administrador do sistema imediatamente. ## Acessando a Plataforma Para fazer seu primeiro login: 1. Abra seu navegador web preferido (Chrome, Firefox, Safari, Edge,). 2. Navegue até a URL da plataforma Evo CRM fornecida pelo administrador. 3. Você será direcionado para a página de login. *** ## Página de Login A página de login apresenta uma interface moderna com tema escuro e os seguintes elementos: Seletor de idioma na página de login ### Cabeçalho da Página * **Logo evoai:** Exibido no canto superior esquerdo da página, apresentando o logo da plataforma com elementos gráficos verdes característicos. * **Seletor de Idioma:** Localizado no canto superior direito, permite alternar entre os idiomas disponíveis: * Português (BR) * English * Español * Français * Italiano ### Abas de Navegação No topo do painel de login central, você encontrará duas abas: * **Sign In:** Aba ativa para realizar o login (padrão). * **Recover:** Aba para recuperação de senha. ### Painel de Login O painel central de login contém os seguintes elementos: #### Título e Instruções * **Título:** "Sign in to your account" (Entre na sua conta) * **Instruções:** "Enter your credentials to access the system" (Digite suas credenciais para acessar o sistema) #### Campos de Entrada * **Campo de Email:** * Label: "Email" * Digite o endereço de email associado à sua conta * O campo aceita endereços de email válidos * **Campo de Senha:** * Label: "Password" * Digite sua senha (inicialmente a senha temporária fornecida) * Os caracteres são mascarados por segurança #### Aviso de Segurança Abaixo dos campos de entrada, há um aviso informando: * "This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply." * Os links "Privacy Policy" e "Terms of Service" são clicáveis. #### Botões e Ações * **Botão "Sign In":** * Botão principal com fundo verde/teal vibrante e texto branco. * Clique neste botão para realizar o login após preencher suas credenciais. * **Link "Forgot my password":** * Link localizado abaixo do botão "Sign In". * Clique aqui se você esqueceu sua senha e deseja recuperá-la. * Alternativamente, você pode usar a aba "Recover" no topo do painel. Preenchendo email e senha na página de login ### Mensagens de Erro Se as credenciais estiverem incorretas, uma mensagem de erro será exibida: * **Ícone de erro:** Um círculo com ponto de exclamação em vermelho. * **Texto:** "Error" seguido de "Login error". * A mensagem aparece em uma caixa com borda vermelha abaixo das instruções. Mensagem de erro de login ### Rodapé No rodapé da página, fora do painel de login, há um aviso legal: * "By continuing, you agree to our Terms of Service and Privacy Policy." * Os links "Terms of Service" e "Privacy Policy" são clicáveis. *** ## Realizando o Login Para fazer login na plataforma: 1. **Selecione o idioma (opcional):** Se desejar, clique no seletor de idioma no canto superior direito e escolha seu idioma preferido 2. **Digite seu email:** No campo "Email", insira o endereço de email associado à sua conta * Certifique-se de digitar o email completo e correto. * Verifique se não há espaços extras antes ou depois do email. 3. **Digite sua senha:** No campo "Password", insira sua senha temporária ou senha atual * Os caracteres serão mascarados por segurança. * Certifique-se de que a tecla Caps Lock não está ativada. 4. **Verifique os dados:** Confirme que o email e senha estão corretos antes de prosseguir. 5. **Clique em "Sign In":** Clique no botão verde "Sign In" para acessar a plataforma. 6. **Aguarde a autenticação:** O sistema validará suas credenciais e você será redirecionado. Preenchendo email e senha na página de login *** ## Recuperação de Senha Se você esqueceu sua senha, você pode recuperá-la de duas formas: ### Método 1: Usando a Aba "Recover" 1. **Clique na aba "Recover":** No topo do painel de login, clique na aba "Recover" 2. **Visualize a tela de recuperação:** A tela exibirá: * Título: "Recover password" * Instruções: "Enter your email to receive recovery instructions" 3. **Digite seu email:** No campo "Email", insira o endereço de email associado à sua conta 4. **Clique em "Send instructions":** Clique no botão "Send instructions" para receber as instruções de recuperação por email 5. **Verifique seu email:** Acesse sua caixa de entrada e siga as instruções recebidas Tela de recuperação de senha ### Método 2: Usando o Link "Forgot my password" 1. **Clique em "Forgot my password":** Na aba "Sign In", clique no link "Forgot my password" abaixo do botão "Sign In" 2. **Siga os passos acima:** O processo é o mesmo descrito no Método 1 As instruções de recuperação de senha serão enviadas para o email cadastrado na sua conta. Certifique-se de ter acesso a esse email antes de solicitar a recuperação. *** ## Primeiro Acesso - Alteração de Senha Na primeira vez que você faz login com uma senha temporária, o sistema pode solicitar que você altere sua senha: ### Processo de Alteração de Senha 1. **Solicitação automática:** Após o login bem-sucedido, uma tela de alteração de senha pode aparecer automaticamente 2. **Preencha os campos:** * **Senha Atual:** Digite a senha temporária fornecida. * **Nova Senha:** Crie uma senha forte seguindo os requisitos do sistema. * **Confirmar Nova Senha:** Digite a nova senha novamente para confirmação. 3. **Requisitos de senha:** Certifique-se de que sua nova senha atende aos requisitos mínimos: * Mínimo de 8 caracteres (ou conforme política da organização) * Pelo menos uma letra maiúscula. * Pelo menos uma letra minúscula. * Pelo menos um número. * Pelo menos um caractere especial (se exigido). 4. **Salve a alteração:** Clique no botão "Update Password" ou "Save" para confirmar a alteração Escolha uma senha forte e única. Evite usar senhas que você já utiliza em outros serviços. Considere usar um gerenciador de senhas para manter suas credenciais seguras. *** ## Problemas Comuns no Login ### Credenciais Inválidas Se você receber uma mensagem de erro "Login error" indicando que as credenciais estão incorretas: 1. **Verifique o email:** Confirme que você está usando o email correto (verifique erros de digitação) 2. **Verifique a senha:** Certifique-se de que a senha está correta e que não há espaços extras 3. **Verifique Caps Lock:** Confirme que a tecla Caps Lock não está ativada 4. **Verifique o formato do email:** Certifique-se de que o email está completo e no formato correto 5. **Tente novamente:** Após verificar, tente fazer login novamente ### Conta Bloqueada Se sua conta estiver bloqueada após várias tentativas de login: 1. **Aguarde alguns minutos:** O sistema pode bloquear temporariamente após múltiplas tentativas falhas 2. **Use a recuperação de senha:** Clique na aba "Recover" ou no link "Forgot my password" para redefinir sua senha 3. **Entre em contato com o administrador:** Se o problema persistir, contate o administrador do sistema ### Email Não Encontrado Se você receber uma mensagem indicando que o email não foi encontrado: 1. **Verifique o email:** Confirme que você está usando o email correto que foi cadastrado 2. **Verifique erros de digitação:** Certifique-se de que não há erros de digitação no email 3. **Entre em contato com o administrador:** Se você tem certeza de que o email está correto, entre em contato com o administrador para verificar se sua conta foi criada corretamente ### Problemas com reCAPTCHA Se você encontrar problemas relacionados ao reCAPTCHA: 1. **Verifique sua conexão:** Certifique-se de que sua conexão com a internet está estável 2. **Tente atualizar a página:** Recarregue a página e tente novamente 3. **Desative bloqueadores de anúncios:** Alguns bloqueadores podem interferir com o reCAPTCHA 4. **Tente outro navegador:** Se o problema persistir, tente usar outro navegador *** ## Após o Login Bem-Sucedido Após fazer login com sucesso, você será redirecionado para: 1. **Dashboard principal:** A tela inicial da plataforma com visão geral das suas atividades 2. **Tela de onboarding:** Se for seu primeiro acesso, você pode ser direcionado para um processo de onboarding que guiará você através das funcionalidades principais 3. **Última página visitada:** O sistema pode redirecioná-lo para a última página que você estava visualizando antes de sair *** ## Próximos Passos Após fazer seu primeiro login com sucesso: * [Visão Geral do Dashboard](/user-guides/getting-started/dashboard-overview) - Explore o dashboard principal e suas funcionalidades * [Processo de Onboarding](/user-guides/getting-started/onboarding) - Aprenda sobre as funcionalidades principais da plataforma * [Configurações da Conta](/user-guides/settings/account-settings) - Configure suas preferências pessoais e da conta *** ## Segurança e Boas Práticas ### Mantendo Sua Conta Segura * **Use senhas fortes:** Crie senhas únicas e complexas que atendam aos requisitos do sistema * **Não compartilhe credenciais:** Nunca compartilhe seu email e senha com outras pessoas * **Use autenticação de dois fatores:** Se disponível, ative a autenticação de dois fatores para maior segurança * **Faça logout:** Sempre faça logout quando terminar de usar a plataforma, especialmente em computadores compartilhados * **Mantenha seu navegador atualizado:** Use versões atualizadas do seu navegador para maior segurança * **Verifique o reCAPTCHA:** O sistema utiliza reCAPTCHA para proteger contra acessos não autorizados ### Em Dispositivos Compartilhados * **Sempre faça logout:** Certifique-se de fazer logout ao terminar sua sessão * **Limpe o cache:** Considere limpar o cache e cookies do navegador após usar a plataforma em dispositivos compartilhados * **Não salve credenciais:** Evite salvar suas credenciais no navegador em dispositivos compartilhados *** ## Suporte Se você encontrar problemas durante o processo de login: 1. **Verifique este guia:** Revise as seções de problemas comuns acima 2. **Use a recuperação de senha:** Se você esqueceu sua senha, use a aba "Recover" ou o link "Forgot my password" disponível na página de login 3. **Entre em contato com o administrador:** Se o problema persistir, entre em contato com o administrador do sistema ou suporte técnico 4. **Verifique a documentação:** Consulte outros guias disponíveis na documentação da plataforma # Gerenciando Pipelines Source: https://docs.evolutionfoundation.com.br/user-guides/pipelines/managing-pipelines Este documento explica como **criar, configurar e gerenciar pipelines**, incluindo a definição de informações básicas, estágios e ações disponíveis. *** ## Criando um Novo Pipeline Para iniciar a criação de um pipeline, utilize o botão destacado na interface. Criando um novo pipeline O botão **New Pipeline** permite criar um novo fluxo de etapas para organizar conversas.\ Quando não existir nenhum pipeline criado, o botão **Create Pipeline** também será exibido no centro da tela. *** ## Configurando as Informações do Pipeline Após iniciar a criação, será exibida a tela de configuração do pipeline. Configuração do pipeline Nesta tela, é possível definir: * **Pipeline Name**\ Nome do pipeline que será exibido na listagem. * **Description**\ Descrição opcional para identificar o objetivo do pipeline. * **Type**\ Tipo do pipeline, utilizado para categorização interna. * **Visibility**\ Define se o pipeline será público ou privado. *** ## Configurando os Stages (Etapas) Ainda na tela de criação, é possível configurar os **stages** do pipeline. * Os estágios representam as fases do fluxo. * É possível adicionar novos estágios informando: * Nome do estágio * Descrição (opcional) * A ordem dos estágios define o fluxo das conversas. *** ## Pipeline Criado Após a criação, o pipeline passa a ser exibido na lista. Pipeline criado No card do pipeline, são exibidas as seguintes informações: * **Nome do Pipeline** * **Status** (Active ou Inactive) * **Item**\ Quantidade de conversas associadas ao pipeline. * **Stages**\ Número total de estágios configurados. * **Type**\ Tipo definido na criação. *** ## Ações do Pipeline Cada pipeline possui um menu de ações acessível pelo ícone de **três pontos**. Ações do pipeline As opções disponíveis são: * **Edit**\ Permite editar todas as configurações do pipeline, incluindo nome, descrição, tipo, visibilidade e estágios. * **Duplicate**\ Cria uma cópia do pipeline com a mesma estrutura de estágios. * **Deactivate**\ Desativa o pipeline, impedindo seu uso sem removê-lo do sistema. * **Delete**\ Remove o pipeline permanentemente. *** ## Acessando o Pipeline Ao clicar em um pipeline, você acessa sua visualização completa em formato **Kanban**. Pipeline acessado ### Visualização Kanban A visualização Kanban apresenta o pipeline como um quadro de colunas, onde cada coluna representa um estágio do processo. Esta interface permite visualizar e gerenciar o fluxo de conversas de forma visual e intuitiva. ### Cabeçalho do Pipeline No topo da visualização, você encontra: * **Nome do Pipeline:** Exibido em um dropdown no canto superior esquerdo, junto com a descrição do pipeline * **Métricas:** No canto superior direito, são exibidas: * **Items:** Quantidade total de conversas associadas ao pipeline * **Stages:** Número total de estágios configurados * **Botão "+ Add Item":** Permite adicionar novas conversas diretamente ao pipeline ### Colunas de Estágios Cada estágio é representado por uma coluna vertical no quadro Kanban: * **Nome do Estágio:** Exibido no topo de cada coluna * **Indicador de Cor:** Um ponto colorido identifica visualmente cada estágio * **Contador:** Mostra quantas conversas estão em cada estágio * **Área de Conteúdo:** Exibe as conversas associadas ao estágio ou a mensagem "No conversation in this stage" quando vazio ### Adicionando Novos Estágios À direita do último estágio, há um botão **"Add Stage"** destacado: * **Ícone:** Círculo verde com sinal de adição (+) * **Função:** Permite criar novos estágios diretamente na visualização Kanban * **Uso:** Clique no botão para adicionar uma nova fase ao pipeline sem sair da visualização ### Funcionalidades Disponíveis Nesta visualização, você pode: * **Visualizar todos os estágios lado a lado:** Acompanhe o progresso completo do fluxo * **Mover conversas entre estágios:** Arraste e solte conversas para movê-las entre as colunas * **Adicionar novos estágios:** Use o botão "Add Stage" para expandir o pipeline * **Adicionar novos itens:** Use o botão "+ Add Item" para incluir conversas no pipeline * **Acompanhar métricas:** Visualize quantas conversas estão em cada estágio *** ## Considerações Finais O gerenciamento de pipelines permite estruturar fluxos de atendimento de forma visual e organizada. Com pipelines bem definidos, é possível: * **Acompanhar o progresso:** Visualize onde cada conversa está no processo através do quadro Kanban * **Padronizar processos:** Defina estágios claros que refletem seu fluxo de trabalho real * **Melhorar a eficiência:** Identifique gargalos e oportunidades de otimização observando a distribuição de conversas entre estágios * **Organizar equipes:** Atribua responsabilidades por estágio e acompanhe o desempenho de cada fase * **Automatizar movimentações:** Configure regras para mover conversas automaticamente entre estágios baseado em condições específicas *** ## Automação por Estágio Cada estágio do pipeline pode ter regras de automação configuradas na aba **Automation** do modal de edição do estágio. As regras seguem o modelo `trigger → action`: * **Triggers:** `label_added`, `conversation_status_changed`, `custom_attribute_updated`. * **Actions:** `move_to_stage`, `assign_agent`, `apply_label`, e (a partir do `v1.0.0-rc3`) `move_to_pipeline`. ### Action `move_to_pipeline` (rc3) Permite mover o item de pipeline para um **pipeline diferente**, preservando o `id` do item. Útil para fluxos como "se label `qualificado` foi adicionada no pipeline Leads, mova para o pipeline Vendas". A action faz bypass automático da validação `same-pipeline` (que normalmente impediria movimentação entre pipelines distintos). ### Garantias * **Dedup em janela de 5s** para `pipeline_stage_updated` por `(rule, pipeline_item, stage)` — evita disparo em rajada. * **Loop prevention** — uma regra `move_to_stage` não dispara outra regra do mesmo tipo recursivamente. * **Logs centralizados** em `Configurações → Automação → Logs` — visualize execuções, conditions avaliadas e erros. Para o modelo completo de automation rules, ver [Visão Geral](/user-guides/automation/overview) e [Regras](/user-guides/automation/rules). *** ## Vinculando Produtos a Itens (a partir do v1.0.0-rc3) Cada item de pipeline tem um painel **Venda** onde você pode registrar qual produto do catálogo está sendo negociado. Útil para reports de conversão por produto. O agente de IA também pode fazer essa vinculação automaticamente durante uma conversa, usando a tool nativa `link_product_to_pipeline_item`. Quando o cliente confirma interesse, o agente registra a vinculação sem intervenção manual. Ver [Catálogo de Produtos](/user-guides/products/overview). *** ## Ações de Pipeline no menu de cards (a partir do v1.0.0-rc3) Cards do kanban agora expõem as ações de pipeline tanto via menu **três pontos** (`⋮`) no canto do card quanto via **clique direito** (context menu). As ações disponíveis incluem mover entre estágios, atribuir agente, aplicar label e abrir o detalhe do item. Lembre-se de revisar e ajustar seus pipelines regularmente conforme sua operação evolui, garantindo que eles continuem refletindo seus processos de negócio de forma eficiente. *** # Visão Geral de Pipelines Source: https://docs.evolutionfoundation.com.br/user-guides/pipelines/overview O módulo **Pipelines** permite organizar conversas em **etapas visuais (stages)**, facilitando o acompanhamento do progresso de atendimentos, leads ou processos internos por meio de um **quadro kanban**. ### O que é um Pipeline? Um **pipeline** é um fluxo de trabalho estruturado que organiza conversas e contatos em diferentes estágios, permitindo visualizar e gerenciar o progresso de cada interação de forma clara e organizada. Cada pipeline representa um processo de negócio específico, como vendas, suporte ao cliente, onboarding ou qualquer outro fluxo que sua equipe precise acompanhar. ### Como Funcionam os Pipelines? Cada pipeline é composto por **estágios (stages)** personalizados que representam as diferentes fases do processo. Por exemplo, um pipeline de vendas pode ter estágios como "Lead", "Qualificação", "Proposta" e "Fechamento". As conversas e contatos podem ser movidos entre esses estágios conforme avançam no processo, criando uma visualização clara do funil de trabalho. ### Benefícios dos Pipelines * **Visualização Clara:** A interface tipo kanban permite ver rapidamente onde cada conversa está no processo * **Organização:** Mantém todas as conversas relacionadas organizadas em um único lugar * **Acompanhamento:** Facilita identificar gargalos e oportunidades de melhoria nos processos * **Automação:** Permite configurar regras automáticas para mover conversas entre estágios * **Métricas:** Oferece visibilidade sobre o desempenho de cada estágio do processo ### Casos de Uso Comuns * **Funil de Vendas:** Acompanhar leads desde o primeiro contato até o fechamento * **Suporte ao Cliente:** Organizar tickets por prioridade e status de resolução * **Onboarding:** Gerenciar o processo de integração de novos clientes * **Processos Internos:** Organizar qualquer fluxo de trabalho que envolva múltiplas etapas Cada pipeline representa um fluxo de trabalho independente, composto por estágios personalizados que você pode configurar de acordo com suas necessidades específicas. *** ## Acessando o Módulo de Pipelines O acesso ao módulo é feito pelo menu principal da plataforma. Acessando o módulo de Pipelines Ao entrar, você verá a tela principal de Pipelines. Caso nenhum pipeline tenha sido criado, o sistema exibirá um estado inicial com a opção de criação. *** ## Lista de Pipelines e Busca Na parte superior da tela, está disponível o campo de **busca**, que permite localizar pipelines pelo nome. Busca de pipelines Esse recurso é útil em ambientes com múltiplos pipelines ativos, facilitando a navegação e o gerenciamento. *** ## Criando um Novo Pipeline (Ponto de Entrada) A partir da tela principal, é possível iniciar a criação de um pipeline clicando no botão **New Pipeline**, destacado no canto superior direito, ou no botão central exibido quando não há pipelines criados. Criar novo pipeline > A configuração detalhada do pipeline, estágios e automações é abordada no guia **Gerenciando Pipelines**. *** ## Considerações Finais O **Pipelines Overview** fornece uma visão clara dos fluxos existentes, permitindo: * Visualizar pipelines disponíveis * Buscar pipelines rapidamente * Identificar o ponto de entrada para criação de novos fluxos Esse módulo é a base para organizar conversas de forma estruturada antes de avançar para configurações mais avançadas de gerenciamento. # Visão Geral de Produtos Source: https://docs.evolutionfoundation.com.br/user-guides/products/overview O módulo **Produtos** permite cadastrar o catálogo de itens vendidos pela sua operação e disponibilizá-lo para agentes de IA e para o pipeline de vendas. Cada produto pode ter **variantes** (tamanho, cor, plano, etc.), e pode ser **vinculado a itens de pipeline** para acompanhar oportunidades de venda em curso. > Disponível a partir do `v1.0.0-rc3`. ### O que é o Catálogo de Produtos? O catálogo é uma lista central de produtos da sua operação. Em vez de manter essa informação espalhada (planilhas, integrações externas, prompt de agente colado manualmente), você mantém uma fonte única dentro do CRM. Quando o agente de IA precisa falar de oferta, ele consulta esse catálogo. Quando um atendimento vira oportunidade, você liga o produto ao item de pipeline correspondente. ### Como Funcionam os Produtos? Cada produto tem: * **Informações básicas:** nome, descrição, preço, status (ativo/inativo). * **Variantes:** versões diferentes do mesmo produto (ex.: "Plano Básico", "Plano Pro", "Plano Enterprise"), cada uma com seu próprio preço e SKU. * **Vinculação a agentes:** você escolhe quais agentes têm acesso a quais produtos. Os produtos vinculados são injetados no contexto do agente no momento da conversa. * **Vinculação a pipeline:** dentro de um item de pipeline (uma oportunidade), você registra qual produto está sendo negociado. Útil para reports de venda por pipeline. ### Casos de Uso Comuns * **Atendimento comercial via WhatsApp:** o agente conhece o catálogo e responde sobre preços/variantes sem que o operador precise colar tabela no prompt. * **Acompanhamento de funil:** cada conversa no pipeline registra o produto sob negociação, permitindo medir conversão por produto. * **Carteira de produtos por agente:** times diferentes (vendas, suporte, retenção) podem ter agentes com catálogos distintos. *** ## Acessando o Módulo de Produtos O acesso é feito pelo menu principal da plataforma, na seção **Produtos**. > A visibilidade do menu depende das permissões `products.read` no seu papel. Se o item não aparece, peça ao administrador para conceder a permissão (ver [Funções Personalizadas](/user-guides/settings/custom-roles)). *** ## Criando um Produto Na tela do catálogo, clique em **Novo Produto** para abrir o formulário. Campos obrigatórios: * **Nome** — como aparece para o agente e para o operador. * **Descrição** — explicação curta usada pelo agente para contextualizar a oferta. * **Status** — `ativo` (disponível para venda) ou `inativo` (não aparece nas seleções). Campos opcionais: * **Preço base** — referência usada quando não há variante. * **SKU** — código de inventário, se aplicável. *** ## Trabalhando com Variantes Variantes representam versões do mesmo produto com atributos distintos (preço, características, SKU). Exemplos: * Plano de software: "Básico", "Pro", "Enterprise" — preços diferentes, mesmo produto raiz. * Roupa: "P", "M", "G" — SKU e estoque diferentes. * Curso: "Mensal", "Anual" — periodicidade e preço diferentes. Cada variante tem nome, preço próprio e pode ter SKU. Quando um agente fala de um produto que tem variantes, ele apresenta as opções e ajuda o cliente a escolher. *** ## Vinculando Produtos a Agentes Na tela de configuração do agente, há uma aba **Produtos**. Lá você escolhe quais itens do catálogo o agente conhece. Apenas produtos com status `ativo` ficam disponíveis para vinculação. Ao vincular, o catálogo é injetado no contexto do agente em runtime. Isso significa que mudanças no catálogo (preço, descrição, nova variante) refletem na próxima conversa do agente, **sem reconfigurar o prompt**. Ver detalhes em [Configuração de Agentes](/user-guides/agents/agent-configuration). *** ## Vinculando Produtos a Itens de Pipeline Dentro do detalhe de um item de pipeline, há um painel **Venda** onde você registra: * Qual produto está sendo negociado. * Qual variante (se houver). * Valor da negociação (pode diferir do preço de catálogo, em caso de desconto). O agente de IA também pode fazer esse vínculo automaticamente durante uma conversa, usando a tool nativa `link_product_to_pipeline_item`. Quando o cliente confirma interesse em um item específico, o agente registra a vinculação sem intervenção manual. *** ## Permissões O acesso ao módulo é controlado por três permissões no recurso `products`: | Permissão | O que permite | | ----------------- | --------------------------------------------- | | `products.read` | Ver o catálogo e acessar produtos individuais | | `products.manage` | Criar, editar, arquivar produtos e variantes | | (nenhuma) | Esconde o menu Produtos do usuário | Por padrão, `account_owner` recebe `manage` e `agent` recebe `read`. Papéis customizados podem ter qualquer combinação. Ver [Funções Personalizadas](/user-guides/settings/custom-roles). *** ## Considerações Finais O catálogo de produtos: * Centraliza informação de oferta em um único lugar. * Conecta agentes de IA ao que sua empresa de fato vende. * Acopla pipeline de vendas ao catálogo, permitindo reports de conversão. Para o passo a passo de **vincular o catálogo ao agente**, ver [Configuração de Agentes](/user-guides/agents/agent-configuration). Para **registrar vendas no pipeline**, ver [Gerenciando Pipelines](/user-guides/pipelines/managing-pipelines). # Autenticação em Duas Etapas (2FA) Source: https://docs.evolutionfoundation.com.br/user-guides/security/two-factor-authentication A autenticação em duas etapas (2FA) adiciona uma camada extra de segurança ao login. Além da senha, o usuário precisa apresentar um código gerado por um aplicativo autenticador (TOTP). Caso perca acesso ao app, **backup codes** permitem recuperar a conta. *** ## Ativando 2FA na sua conta 1. Acesse `Perfil → Segurança`. 2. Clique em **Ativar autenticação em duas etapas**. 3. Escaneie o QR code com um app autenticador (Google Authenticator, Authy, 1Password, Bitwarden, etc.). 4. Digite o código de 6 dígitos exibido pelo app para confirmar. 5. **Guarde os backup codes** apresentados na tela em um local seguro (gerenciador de senhas, cofre físico). 6. Confirme. > A partir desse momento, todo login exigirá senha + código do app. *** ## Backup codes Backup codes são códigos de uso único que permitem fazer login sem o app autenticador — útil se você perder o celular, trocar de aparelho, ou o app falhar. ### Como funcionam * Cada code só pode ser usado **uma vez**. Após o uso, ele é invalidado. * Você recebe um conjunto de codes ao ativar 2FA. Quando estiverem para acabar, regenere o conjunto. * Codes são armazenados com hash BCrypt no banco (a partir do `v1.0.0-rc3` — EVO-991). Nem o operador da instalação consegue ler os codes em texto claro. ### Regenerando codes `Perfil → Segurança → Regerar backup codes`. > Atenção: ao regenerar, **os codes antigos param de funcionar**. Faça isso apenas se tiver acesso ao app autenticador no momento, para confirmar a regeneração. ### Quando regenerar * **Após usar um code** — para manter o estoque cheio. * **Após suspeita de comprometimento** — se você acha que alguém pode ter visto sua lista de codes. * **Após mudança organizacional** — se você passou de função e a lista antiga estava em um lugar acessível a terceiros. > Para instalações que existiam **antes do `v1.0.0-rc3`**: codes gerados naquela época ficavam em plaintext no banco. Se o histórico do banco esteve acessível a alguém fora do operador da instalação, recomenda-se regenerar. *** ## Recuperação de conta sem 2FA nem backup codes Se você perder **tanto** o app autenticador **quanto** os backup codes: 1. Contate o **administrador da instalação** (`super_admin`). 2. O administrador pode desativar 2FA na sua conta via console administrativo. 3. Após o login subsequente, **reative 2FA imediatamente** com um novo dispositivo e guarde novos backup codes. > O administrador da instalação **não consegue ler** seus codes (armazenados com hash). A única operação possível é zerar o 2FA da conta para você reconfigurar. *** ## Recomendações de segurança * **Use app autenticador, não SMS.** SMS é vulnerável a SIM swap. * **Guarde backup codes em gerenciador de senhas.** Evite imprimir e jogar em gaveta. * **Não compartilhe backup codes.** Eles equivalem ao seu segundo fator. * **Ative 2FA em contas administrativas.** Especialmente `super_admin` e `account_owner`. *** ## Considerações Finais 2FA é o controle de acesso mais barato e eficaz contra credenciais vazadas. Combine com senhas fortes (validação inline ajuda — EVO-1063) e revisão periódica de papéis em [Funções Personalizadas](/user-guides/settings/custom-roles). # Tokens de Acesso Source: https://docs.evolutionfoundation.com.br/user-guides/settings/access-tokens A seção de **Tokens de Acesso** (Access Tokens) permite que você crie e gerencie tokens de autenticação para uso da API do sistema. Com os tokens de acesso, você pode autenticar requisições à API, permitindo que aplicações externas ou integrações interajam com o sistema de forma segura e controlada. Cada token de acesso pode ter um nome descritivo, um conjunto específico de permissões (scopes) que definem quais recursos e ações o token pode acessar, e um proprietário (Account ou usuário específico). Os tokens são essenciais para integrações, automações e acesso programático ao sistema. ## Acessando Tokens de Acesso Para acessar a área de gerenciamento de tokens de acesso: 1. No menu lateral esquerdo, clique em **Settings** (Configurações). 2. Na lista de opções de configurações, selecione **Access Tokens** (Tokens de Acesso). Navegação para Tokens de Acesso - Item Access Tokens destacado no menu lateral e estado vazio A tela principal de tokens de acesso será exibida, mostrando todos os tokens criados ou uma mensagem indicando que nenhum token foi criado ainda. *** ## Pesquisando Tokens de Acesso A barra de pesquisa permite localizar tokens rapidamente pelo nome. ### Como pesquisar 1. Na parte superior da tela, localize o campo **"Search access tokens..."** com o ícone de lupa 2. Digite o nome ou parte do nome do token desejado 3. A tabela de tokens será atualizada automaticamente conforme o termo digitado, mostrando apenas os tokens que correspondem à busca Barra de pesquisa de tokens de acesso destacada com termo de busca digitado A busca é realizada em tempo real, facilitando a localização de tokens específicos quando há muitos cadastrados. *** ## Criando um Novo Token de Acesso Existem duas formas de iniciar a criação de um novo token de acesso: ### Opção 1: Botão no Cabeçalho 1. Clique no botão verde **"+ New Token"** localizado no canto superior direito da tela Botão New Token no cabeçalho destacado ### Opção 2: Botão no Estado Vazio Quando não há tokens criados, clique no botão verde **"New Token"** no centro da tela. ### Preenchendo o Formulário de Criação Após clicar em qualquer um dos botões, um modal será exibido com fundo escuro contendo: * **Título:** **"New Access Token"** no topo do modal * **Descrição:** "Manage access tokens for API authentication." logo abaixo do título * **Botão de Fechar:** Um ícone "X" no canto superior direito para fechar o modal sem salvar Modal de criação de novo token de acesso com todos os campos destacados No formulário, preencha os seguintes campos: #### 1. Nome do Token (Obrigatório) * **Campo:** **Token Name** * **Tipo:** Campo de texto simples * **Descrição:** Nome descritivo para identificar este token de acesso * **Texto de Ajuda:** "Descriptive name to identify this access token" abaixo do campo * **Valor Padrão:** O campo pode vir pré-preenchido com um nome padrão como "API Token - 2026-01-22" (incluindo a data atual) * **Exemplo:** "API Token - 2026-01-22", "Integração WhatsApp", "Automação de Relatórios" * **Recomendação:** Use nomes descritivos que indiquem o propósito do token e quando foi criado * **Localização:** Primeiro campo do formulário #### 2. Permissões (Scopes) A seção de **Permissions (Scopes)** permite definir quais recursos e ações o token pode acessar na API. As permissões são organizadas em categorias principais: ##### Visão Geral das Permissões * **Texto Explicativo:** "Select the permissions this token will have access to" * **Barra de Pesquisa:** Campo com ícone de lupa e placeholder "Search resources and actions..." para localizar permissões específicas rapidamente * **Contador de Seleção:** Exibe "0 permission selected" ou "X permission selected" indicando quantas permissões foram selecionadas no total * **Botão Select All:** Checkbox no topo para selecionar todas as permissões disponíveis de uma vez ##### Categorias de Permissões Disponíveis As permissões são organizadas em categorias, cada uma com um contador mostrando quantas permissões foram selecionadas do total disponível: 1. **Users (0/13)** * Descrição: Permissões relacionadas ao gerenciamento de usuários * Exemplos de scopes: `users.read`, `users.create`, `users.update` * Total: 13 permissões disponíveis 2. **Accounts (0/10)** * Descrição: Permissões relacionadas ao gerenciamento de contas * Total: 10 permissões disponíveis 3. **Access Tokens (0/5)** * Descrição: Permissões relacionadas ao gerenciamento de tokens de acesso * Total: 5 permissões disponíveis 4. **Roles (0/10)** * Descrição: Permissões relacionadas ao gerenciamento de funções e papéis * Total: 10 permissões disponíveis 5. **OAuth Applications (0/5)** * Descrição: Permissões relacionadas ao gerenciamento de aplicações OAuth * Total: 5 permissões disponíveis 6. **Features (0/7)** * Descrição: Permissões relacionadas ao gerenciamento de funcionalidades * Total: 7 permissões disponíveis **Nota:** A lista de categorias é scrollável, indicando que podem existir mais categorias além das visíveis inicialmente. ### Como Selecionar Permissões 1. **Busca de Permissões:** Use a barra de pesquisa "Search resources and actions..." para localizar permissões específicas rapidamente 2. **Seleção Individual:** Clique nos checkboxes individuais de cada categoria para conceder todas as permissões daquela categoria 3. **Seleção Total:** Clique no checkbox "Select All" no topo da seção para selecionar todas as permissões disponíveis 4. **Visualização de Seleção:** O contador "X permission selected" é atualizado em tempo real conforme você seleciona ou remove permissões **Importante:** Siga o princípio do menor privilégio - conceda apenas as permissões necessárias para o propósito específico do token. Tokens com muitas permissões podem representar um risco de segurança se comprometidos. ### Finalizando a Criação Na parte inferior do modal, há dois botões de ação: * **Cancel:** Botão escuro com texto branco, localizado à esquerda * **New Token:** Botão verde/turquesa brilhante com texto branco, localizado à direita Após preencher os campos desejados: 1. Revise as informações inseridas, especialmente o nome e as permissões selecionadas 2. Clique no botão verde **"New Token"** para criar o token de acesso 3. Ou clique em **"Cancel"** para fechar o modal sem salvar 4. Alternativamente, clique no ícone "X" no canto superior direito para fechar sem salvar **Atenção:** Após criar o token, o valor do token será exibido uma única vez. Certifique-se de copiar e armazenar o token em um local seguro, pois ele não poderá ser visualizado novamente após fechar a tela inicial. O token será criado e aparecerá imediatamente na tabela de tokens de acesso. *** ## Visualizando Tokens de Acesso na Tabela Após criar tokens de acesso, eles serão exibidos em uma tabela com as seguintes colunas: ### Colunas da Tabela * **Name:** Nome do token (ordenável - indicado por seta para cima/baixo) * Exibe o nome descritivo do token (ex: "API Token - 2026-01-22") * Abaixo do nome, exibe o ID único do token no formato "ID: 25600b00-25bd-4e76-b770-4e4ca0ede485" * **Scopes:** Permissões (scopes) atribuídas ao token * Exibe tags com os nomes dos scopes (ex: "users.read", "users.create", "users.update") * Quando há muitos scopes, exibe os primeiros e um indicador "+X" mostrando quantos scopes adicionais existem (ex: "+377") * **Owner:** Proprietário do token * Exibe um badge indicando se o token pertence à "Account" ou a um usuário específico * **Created At:** Data de criação do token (ordenável - indicado por seta para cima/baixo) * Exibe a data no formato "DD/MM/AAAA" (ex: "22/01/2026") * **Actions:** Menu de ações para gerenciar o token * Ícone de três pontos verticais (`...`) que abre um menu dropdown com opções ### Funcionalidades da Tabela * **Ordenação:** Clique nos cabeçalhos das colunas "Name" ou "Created At" para ordenar a tabela em ordem crescente ou decrescente * **Busca Integrada:** A barra de pesquisa acima da tabela filtra os resultados em tempo real * **Visualização de Scopes:** Os scopes são exibidos como tags, facilitando a visualização rápida das permissões do token *** ## Visualizando um Token Para visualizar os detalhes completos de um token: 1. Na tabela de tokens de acesso, localize o token que deseja visualizar 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente ao token 3. Um menu dropdown será exibido com as opções disponíveis Menu de ações do token destacado - opções View Token, Copy Token, Edit, Regenerate Token e Delete 4. No menu dropdown, clique em **View Token** (acompanhado de um ícone de olho) Uma tela ou modal será exibido mostrando os detalhes completos do token, incluindo o valor do token (se ainda estiver disponível) e todas as informações associadas. **Nota:** O valor completo do token só pode ser visualizado imediatamente após a criação. Se o token já foi criado anteriormente, apenas as informações de metadados serão exibidas. *** ## Copiando um Token Para copiar o valor de um token para a área de transferência: 1. Na tabela de tokens de acesso, localize o token que deseja copiar 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente ao token 3. Um menu dropdown será exibido com as opções disponíveis 4. No menu dropdown, clique em **Copy Token** (acompanhado de um ícone de cópia) O valor do token será copiado para a área de transferência e você poderá colá-lo onde necessário. **Atenção:** Certifique-se de copiar o token apenas em locais seguros e nunca compartilhe tokens de acesso publicamente ou em canais não seguros. *** ## Editando um Token de Acesso Para modificar um token de acesso existente: 1. Na tabela de tokens de acesso, localize o token que deseja editar 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente ao token 3. Um menu dropdown será exibido com as opções disponíveis 4. No menu dropdown, clique em **Edit** (acompanhado de um ícone de lápis) 5. Um modal semelhante ao de criação será aberto, mas com o título **"Edit Access Token"** e os campos já preenchidos com os valores atuais do token 6. Modifique os campos desejados: * Nome do token * Permissões (scopes) - adicione ou remova permissões conforme necessário 7. Revise as alterações 8. Clique no botão verde **"Update Token"** ou **"Save"** para salvar as alterações 9. Ou clique em **"Cancel"** para descartar as alterações As alterações serão aplicadas imediatamente e refletidas na tabela de tokens de acesso. **Nota:** A edição de um token não altera o valor do token em si, apenas seus metadados (nome e permissões). Se você precisar de um novo valor de token, use a opção "Regenerate Token". *** ## Regenerando um Token de Acesso Para gerar um novo valor para um token existente (mantendo o mesmo ID e metadados): 1. Na tabela de tokens de acesso, localize o token que deseja regenerar 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente ao token 3. Um menu dropdown será exibido com as opções disponíveis 4. No menu dropdown, clique em **Regenerate Token** (acompanhado de um ícone de chave) 5. Um diálogo de confirmação será exibido 6. Confirme a regeneração no diálogo que aparecer **Atenção:** * A regeneração criará um novo valor para o token, invalidando o valor anterior * O ID do token permanecerá o mesmo, mas o valor do token será completamente novo * Certifique-se de atualizar todas as aplicações e integrações que usam este token com o novo valor * O valor antigo do token deixará de funcionar imediatamente após a regeneração * O novo valor do token será exibido uma única vez após a regeneração - certifique-se de copiá-lo e armazená-lo em local seguro *** ## Excluindo um Token de Acesso Para remover um token de acesso: 1. Na tabela de tokens de acesso, localize o token que deseja excluir 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente ao token 3. Um menu dropdown será exibido com as opções disponíveis 4. No menu dropdown, clique em **Delete** (acompanhado de um ícone de lixeira, exibido em texto vermelho para indicar uma ação destrutiva) 5. Um diálogo de confirmação será exibido 6. Confirme a exclusão no diálogo que aparecer **Atenção:** * A exclusão de um token de acesso é permanente e não pode ser desfeita * Todas as aplicações e integrações que usam este token perderão acesso imediatamente após a exclusão * Verifique se não há sistemas críticos dependendo deste token antes de excluí-lo * Recomenda-se regenerar o token em vez de excluí-lo se você suspeitar que ele foi comprometido, mas ainda precisa manter a integração funcionando *** ## Considerações Finais * **Princípio do Menor Privilégio:** Conceda apenas as permissões necessárias para cada token realizar sua função específica, evitando acesso excessivo * **Nomenclatura Clara:** Use nomes descritivos e claros para que todos os membros da equipe entendam o propósito de cada token * **Armazenamento Seguro:** Armazene tokens de acesso em locais seguros, como gerenciadores de senhas ou variáveis de ambiente criptografadas. Nunca commite tokens em repositórios de código * **Rotação Regular:** Considere regenerar tokens periodicamente como parte de uma estratégia de segurança * **Auditoria:** Revise periodicamente os tokens existentes para garantir que todos ainda estão em uso e têm as permissões adequadas * **Permissões Granulares:** Utilize as permissões granulares para criar tokens específicos que atendam exatamente às necessidades de cada integração ou aplicação * **Monitoramento:** Monitore o uso dos tokens para identificar atividades suspeitas ou não autorizadas * **Documentação:** Documente o propósito e uso de cada token para facilitar a manutenção e o gerenciamento Os tokens de acesso são uma ferramenta essencial para integrações e automações, permitindo que aplicações externas interajam com o sistema de forma segura e controlada. O gerenciamento adequado dos tokens é fundamental para manter a segurança e a integridade do sistema. # Configurações da Conta Source: https://docs.evolutionfoundation.com.br/user-guides/settings/account-settings As Configurações da Conta permitem que você gerencie as informações básicas da sua conta, configure a resolução automática de conversas, habilite a transcrição de áudio e acesse identificadores importantes para integrações. ## Acessando Configurações da Conta Para acessar esta tela, siga os passos abaixo: 1. No menu lateral esquerdo, clique em **Settings** (Configurações). 2. No submenu que se abre, clique em **Account** (Conta). Acessando Configurações da Conta *** ## Configurações Gerais (General Settings) Nesta seção, você define as informações fundamentais da sua conta no Evo CRM: * **Account Name (Nome da Conta):** O nome identificador da sua conta na plataforma. * **Language (Idioma):** O idioma padrão da interface para esta conta. * **Botão Save Settings:** Após realizar qualquer alteração nestes campos, clique aqui para salvar. Preenchendo dados da conta *** ## Auto-Resolução de Conversas (Conversation Auto-Resolution) Esta funcionalidade ajuda a manter sua caixa de entrada organizada, fechando automaticamente conversas que ficaram inativas por um tempo determinado. * **Ativar/Desativar:** Utilize o interruptor (toggle) no canto superior direito para habilitar a função. * **Auto-Resolution Time (Tempo para Auto-Resolução):** Defina o tempo em minutos de inatividade antes que a conversa seja resolvida automaticamente. * **Auto-Resolution Message (Mensagem de Auto-Resolução):** Uma mensagem opcional que será enviada ao cliente quando o sistema encerrar a conversa. * **Ignore conversations waiting for response (Ignorar conversas aguardando resposta):** Se ativado, o sistema não encerrará conversas onde o agente ainda não respondeu ao cliente. * **Apply label (Aplicar etiqueta):** Você pode configurar uma etiqueta específica para ser aplicada automaticamente às conversas resolvidas por este processo. * **Botão Update Auto-Resolution:** Salva as preferências de resolução automática. *** ## Transcrição de Áudio (Audio Transcription) O Evo CRM possui integração para converter mensagens de voz em texto automaticamente. * **Ativar Transcrição:** Ao habilitar esta opção, o sistema tentará transcrever todas as mensagens de áudio recebidas nas caixas de entrada conectadas, facilitando a leitura e busca de informações. *** ## ID da Conta (Account ID) O **Account ID** é um identificador único universal (UUID) da sua conta. Ele é essencial para: * Realizar chamadas via API. * Configurar webhooks externos. * Realizar integrações personalizadas com outros sistemas. Você pode copiar o ID rapidamente clicando no ícone de cópia ao lado do código. *** ## Exclusão de Conta (Account Deletion) Esta é uma ação crítica e irreversível. * **Delete Account:** Ao clicar neste botão, você iniciará o processo para apagar permanentemente sua conta e todos os dados associados a ela (contatos, conversas, configurações). A exclusão da conta não pode ser desfeita. Certifique-se de ter feito backup de dados importantes antes de prosseguir. *** ## Considerações Finais Manter as configurações de conta atualizadas é fundamental para o bom funcionamento das automações e para a correta identificação da sua conta em processos de integração. # Respostas Rápidas Source: https://docs.evolutionfoundation.com.br/user-guides/settings/canned-responses A seção de **Respostas Rápidas** (Canned Responses) permite que você crie e gerencie respostas pré-definidas para acelerar o atendimento aos clientes. Com as respostas rápidas, você pode criar templates de mensagens que podem ser personalizadas com variáveis dinâmicas, como nome do contato, nome do agente e nome da conta. Cada resposta rápida possui um código único identificador e um conteúdo que pode incluir variáveis dinâmicas que serão substituídas automaticamente quando a resposta for utilizada. As respostas rápidas também podem incluir anexos como imagens, áudios, vídeos e documentos. ## Acessando Respostas Rápidas Para acessar a área de gerenciamento de respostas rápidas: 1. No menu lateral esquerdo, clique em **Settings** (Configurações). 2. Na lista de opções de configurações, selecione **Canned Responses** (Respostas Rápidas). Navegação para Respostas Rápidas - Item Canned Responses destacado no menu lateral e estado vazio A tela principal de respostas rápidas será exibida, mostrando todas as respostas criadas ou uma mensagem indicando que nenhuma resposta foi criada ainda. *** ## Pesquisando Respostas Rápidas A barra de pesquisa permite localizar respostas rápidas rapidamente pelo código ou pelo conteúdo. ### Como pesquisar 1. Na parte superior da tela, localize o campo **"Search by code or content..."** com o ícone de lupa 2. Digite o código ou parte do conteúdo da resposta desejada 3. A tabela de respostas será atualizada automaticamente conforme o termo digitado, mostrando apenas as respostas que correspondem à busca Barra de pesquisa de respostas rápidas destacada com termo de busca digitado A busca é realizada em tempo real, facilitando a localização de respostas específicas quando há muitas cadastradas. *** ## Criando uma Nova Resposta Rápida Existem duas formas de iniciar a criação de uma nova resposta rápida: ### Opção 1: Botão no Cabeçalho 1. Clique no botão verde **"+ New Response"** localizado no canto superior direito da tela ### Opção 2: Botão no Estado Vazio Quando não há respostas rápidas criadas, clique no botão verde **"New Response"** no centro da tela. Estado vazio de respostas rápidas com botões New Response destacados ### Preenchendo o Formulário de Criação Após clicar em qualquer um dos botões, um modal será exibido com fundo escuro contendo: * **Título:** **"New Canned Response"** no topo do modal * **Descrição:** "Create a new canned response to accelerate your customer's response." logo abaixo do título * **Botão de Fechar:** Um ícone "X" no canto superior direito para fechar o modal sem salvar Modal de criação de nova resposta rápida com todos os campos destacados No formulário, preencha os seguintes campos: #### 1. Código (Obrigatório) * **Campo:** **Code** (marcado com asterisco `*` indicando campo obrigatório) * **Tipo:** Campo de texto simples * **Descrição:** Código único para identificar esta resposta * **Texto de Ajuda:** "Unique code to identify this response. Use only letters, numbers, underscores and hyphens." * **Regras:** Use apenas letras, números, underscores e hífens * **Exemplo:** `ol_contactname_`, `greeting_message`, `follow-up-response` * **Recomendação:** Use códigos descritivos e curtos que facilitem a identificação rápida da resposta * **Localização:** Primeiro campo do formulário #### 2. Conteúdo (Obrigatório) * **Campo:** **Content** (marcado com asterisco `*` indicando campo obrigatório) * **Tipo:** Área de texto (textarea) grande * **Descrição:** Conteúdo da resposta que será enviada automaticamente * **Texto de Ajuda:** "Content of the response that will be sent automatically." * **Variáveis Dinâmicas:** Você pode usar variáveis entre chaves duplas `{{ }}` que serão substituídas automaticamente: * `{{contact.name}}` - Nome do contato * `{{agent.name}}` - Nome do agente * `{{account.name}}` - Nome da conta * `{{conversation.id}}` - ID da conversa * **Exemplo:** ``` Olá, {{contact.name}}!😊 Sou {{agent.name}} da {{account.name}}. Recebemos sua mensagem e já vamos te ajudar. Pode me contar um pouco mais sobre o que você precisa? ``` * **Emojis:** Você pode incluir emojis no conteúdo da resposta * **Localização:** Segundo campo do formulário, abaixo do campo Code #### 3. Anexos (Opcional) * **Campo:** **Attachments (Images, Audios, Videos, Documents)** * **Tipo:** Upload de arquivos * **Descrição:** Permite adicionar arquivos à resposta rápida * **Botão:** **"Add File"** com ícone de clipe de papel * **Limitações:** * Máximo de 10MB por arquivo * Formatos aceitos: imagens, áudios, vídeos, PDF, DOC * **Uso:** Adicione arquivos que complementem a resposta, como imagens explicativas, documentos ou áudios * **Localização:** Terceiro campo do formulário, abaixo do campo Content #### 4. Variáveis Disponíveis * **Seção:** **"Available Variables:"** * **Tipo:** Caixa informativa com lista de variáveis * **Descrição:** Lista todas as variáveis que podem ser usadas no campo Content * **Variáveis Disponíveis:** * `{{contact.name}}` - Contact Name (Nome do Contato) * `{{agent.name}}` - Agent Name (Nome do Agente) * `{{conversation.id}}` - Conversation ID (ID da Conversa) * `{{account.name}}` - Account Name (Nome da Conta) * **Uso:** Clique ou digite as variáveis diretamente no campo Content para personalizar a resposta * **Localização:** Quarta seção do formulário, abaixo do campo de Anexos ### Finalizando a Criação Na parte inferior do modal, há dois botões de ação: * **Cancel:** Botão cinza escuro com texto branco, localizado à esquerda * **Create:** Botão verde/turquesa brilhante com texto branco, localizado à direita Após preencher os campos desejados: 1. Revise as informações inseridas, especialmente o código e o conteúdo 2. Verifique se as variáveis estão corretamente escritas (com chaves duplas `{{ }}`) 3. Se necessário, adicione anexos à resposta 4. Clique no botão verde **"Create"** para criar a resposta rápida 5. Ou clique em **"Cancel"** para fechar o modal sem salvar 6. Alternativamente, clique no ícone "X" no canto superior direito para fechar sem salvar A resposta rápida será criada e aparecerá imediatamente na tabela de respostas rápidas. *** ## Visualizando Respostas Rápidas na Tabela Após criar respostas rápidas, elas serão exibidas em uma tabela com as seguintes colunas: ### Colunas da Tabela * **Checkbox:** Seleção individual ou em massa de respostas rápidas * **Code:** Código único identificador da resposta rápida * Exibe o código definido durante a criação (ex: `ol_contactname_`) * O código pode ser clicável ou destacado visualmente * **Content:** Conteúdo completo da resposta rápida * Exibe o texto completo da resposta, incluindo variáveis dinâmicas (ex: `Olá, {{contact.name}}!😊 Sou {{agent.name}} da {{account.name}}....`) * As variáveis são exibidas como estão escritas, com as chaves duplas * **Created at:** Data de criação da resposta rápida * Exibe a data no formato DD/MM/AAAA (ex: "22/01/2026") * **Actions:** Menu de ações para gerenciar a resposta rápida * Ícone de três pontos horizontais (`...`) que abre um menu dropdown com opções Tabela de respostas rápidas com menu de ações destacado - opções Edit e Delete ### Funcionalidades da Tabela * **Seleção Múltipla:** Use os checkboxes para selecionar múltiplas respostas rápidas e realizar ações em lote * **Busca Integrada:** A barra de pesquisa acima da tabela filtra os resultados em tempo real por código ou conteúdo * **Visualização Completa:** O conteúdo completo da resposta é exibido na tabela, facilitando a identificação rápida *** ## Editando uma Resposta Rápida Para modificar uma resposta rápida existente: 1. Na tabela de respostas rápidas, localize a resposta que deseja editar 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente à resposta 3. Um menu dropdown será exibido com as opções disponíveis Menu de ações da resposta rápida destacado - opções Edit e Delete 4. No menu dropdown, clique em **Edit** (acompanhado de um ícone de lápis) 5. Um modal semelhante ao de criação será aberto, mas com o título **"Edit Canned Response"** e os campos já preenchidos com os valores atuais da resposta 6. Modifique os campos desejados: * Código (se necessário) * Conteúdo (incluindo variáveis dinâmicas) * Anexos (adicione ou remova arquivos conforme necessário) 7. Revise as alterações, especialmente as variáveis dinâmicas 8. Clique no botão verde **"Update"** ou **"Save"** para salvar as alterações 9. Ou clique em **"Cancel"** para descartar as alterações As alterações serão aplicadas imediatamente e refletidas na tabela de respostas rápidas. **Nota:** Ao editar uma resposta rápida, certifique-se de que as variáveis dinâmicas estão corretamente escritas para evitar erros na substituição quando a resposta for utilizada. *** ## Excluindo uma Resposta Rápida Para remover uma resposta rápida: 1. Na tabela de respostas rápidas, localize a resposta que deseja excluir 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente à resposta 3. Um menu dropdown será exibido com as opções disponíveis 4. No menu dropdown, clique em **Delete** (acompanhado de um ícone de lixeira, exibido em texto vermelho para indicar uma ação destrutiva) 5. Um diálogo de confirmação será exibido 6. Confirme a exclusão no diálogo que aparecer **Atenção:** * A exclusão de uma resposta rápida é permanente e não pode ser desfeita * Verifique se não há processos ou usuários dependendo desta resposta antes de excluí-la * Considere editar a resposta em vez de excluí-la se houver dúvidas sobre seu uso futuro *** ## Usando Variáveis Dinâmicas As variáveis dinâmicas são uma funcionalidade poderosa das respostas rápidas, permitindo personalizar automaticamente as mensagens com informações específicas do contexto. ### Variáveis Disponíveis * **`{{contact.name}}`** - Substituído pelo nome do contato na conversa * **`{{agent.name}}`** - Substituído pelo nome do agente que está utilizando a resposta * **`{{account.name}}`** - Substituído pelo nome da conta/organização * **`{{conversation.id}}`** - Substituído pelo ID único da conversa ### Como Usar Variáveis 1. Ao criar ou editar uma resposta rápida, digite as variáveis diretamente no campo Content 2. Use a sintaxe exata: chaves duplas `{{ }}` com o nome da variável dentro 3. Exemplo de uso: ``` Olá, {{contact.name}}! Sou {{agent.name}} da {{account.name}}. Recebemos sua mensagem e já vamos te ajudar. ``` 4. Quando a resposta for utilizada, as variáveis serão automaticamente substituídas pelos valores reais ### Dicas de Uso * **Personalização:** Use `{{contact.name}}` para tornar as mensagens mais pessoais e amigáveis * **Identificação:** Use `{{agent.name}}` e `{{account.name}}` para identificar claramente quem está respondendo * **Rastreamento:** Use `{{conversation.id}}` quando precisar referenciar a conversa específica * **Combinação:** Combine múltiplas variáveis na mesma resposta para máxima personalização *** ## Considerações Finais * **Códigos Únicos:** Certifique-se de usar códigos únicos e descritivos para facilitar a identificação rápida das respostas * **Variáveis Dinâmicas:** Aproveite as variáveis dinâmicas para personalizar as respostas e melhorar a experiência do cliente * **Conteúdo Claro:** Escreva conteúdos claros e objetivos que transmitam a mensagem desejada de forma eficiente * **Anexos:** Use anexos quando necessário para complementar a resposta com informações visuais ou documentos * **Organização:** Mantenha as respostas rápidas organizadas com códigos consistentes e fáceis de lembrar * **Revisão Regular:** Revise periodicamente as respostas existentes para garantir que continuam relevantes e atualizadas * **Teste:** Teste as variáveis dinâmicas antes de usar em produção para garantir que estão funcionando corretamente * **Nomenclatura:** Use códigos que sigam um padrão consistente para facilitar a busca e organização As respostas rápidas são uma ferramenta essencial para acelerar o atendimento e melhorar a eficiência da equipe, permitindo respostas consistentes e personalizadas aos clientes de forma rápida e eficiente. # Atributos Personalizados Source: https://docs.evolutionfoundation.com.br/user-guides/settings/custom-attributes A seção de **Atributos Personalizados** (Custom Attributes) permite que você crie e gerencie campos personalizados para coletar informações específicas sobre conversas, contatos ou itens do pipeline. Com os atributos personalizados, você pode estender os dados padrão do sistema e coletar informações relevantes para o seu negócio. Cada atributo personalizado possui um nome de exibição, uma chave técnica para identificação na API, uma descrição, um tipo de dado e opcionalmente validação por expressão regular (regex). Os atributos podem ser aplicados a diferentes contextos: **Conversas**, **Contatos** ou **Pipeline** (com sub-opções para Pipeline, Estágio ou Item). ## Acessando Atributos Personalizados Para acessar a área de gerenciamento de atributos personalizados: 1. No menu lateral esquerdo, clique em **Settings** (Configurações). 2. Na lista de opções de configurações, selecione **Custom Attributes** (Atributos Personalizados). Acessando Atributos Personalizados - Item Custom Attributes destacado no menu lateral e estado vazio A tela principal de atributos personalizados será exibida, mostrando todos os atributos criados ou uma mensagem indicando que nenhum atributo foi criado ainda. *** ## Categorias de Atributos Os atributos personalizados são organizados em três categorias principais, acessíveis através de abas na parte superior da tela: * **Conversas (Conversations):** Atributos aplicados às conversas * **Contatos (Contacts):** Atributos aplicados aos contatos * **Pipeline:** Atributos aplicados a pipelines, estágios ou itens Estado vazio de atributos personalizados com botões New Attribute destacados e abas Conversas, Contatos e Pipeline *** ## Pesquisando Atributos Personalizados A barra de pesquisa permite localizar atributos personalizados rapidamente pelo nome, descrição ou chave. ### Como pesquisar 1. Na parte superior da tela, localize o campo **"Search custom attributes..."** com o ícone de lupa 2. Digite o nome, descrição ou chave do atributo desejado 3. A tabela de atributos será atualizada automaticamente conforme o termo digitado, mostrando apenas os atributos que correspondem à busca Barra de pesquisa de atributos personalizados destacada com termo de busca digitado mostrando resultado na tabela A busca é realizada em tempo real, facilitando a localização de atributos específicos quando há muitos cadastrados. *** ## Visualizando Atributos Personalizados na Tabela Após criar atributos personalizados, eles serão exibidos em uma tabela com as seguintes colunas: ### Colunas da Tabela * **Name (Nome):** Nome de exibição do atributo personalizado * Exibe o nome definido durante a criação (ex: "Prioridade do Lead", "Cargo", "Motivo do Contato") * A coluna é ordenável (indicada por setas para cima/baixo) * **Description (Descrição):** Descrição completa do atributo * Exibe a descrição definida durante a criação * Ajuda a entender o propósito do atributo * **Type (Tipo):** Tipo de dado do atributo * Exibido em uma tag azul (ex: "Texto", "Número", "Data") * Indica o formato de dados aceito pelo atributo * **Key (Chave):** Chave técnica do atributo * Exibida em uma tag cinza (ex: "prioridade\_do\_lead", "cargo", "motivo\_do\_contato") * Usada para identificar o atributo na API * **Values (Valores):** Valores pré-definidos (se aplicável) * Exibe valores pré-definidos para atributos do tipo lista ou seleção * Mostra "-" quando não aplicável * **Regex:** Indica se o atributo possui validação por expressão regular * Exibido em uma tag verde com "Yes" quando há regex configurada * Exibido como "-" quando não há validação regex * **Created at (Criado em):** Data de criação do atributo * Exibe a data no formato DD/MM/AAAA (ex: "23/01/2026") * A coluna é ordenável (indicada por setas para cima/baixo) * **Model (Modelo):** Modelo ao qual o atributo se aplica (apenas para Pipeline) * Exibe "Item", "Stage" ou "Pipeline" para atributos de pipeline * Não exibido para atributos de Conversas ou Contatos * **Actions (Ações):** Menu de ações para gerenciar o atributo * Ícone de três pontos horizontais (`...`) que abre um menu dropdown com opções Modelo visual da tabela de atributos personalizados mostrando todas as colunas ### Funcionalidades da Tabela * **Ordenação:** As colunas Name e Created at podem ser ordenadas clicando no cabeçalho * **Busca Integrada:** A barra de pesquisa acima da tabela filtra os resultados em tempo real * **Filtro por Categoria:** Use as abas (Conversas, Contatos, Pipeline) para filtrar atributos por categoria * **Contador:** O número total de atributos na categoria atual é exibido abaixo do título *** ## Atributos para Conversas Os atributos de conversas permitem coletar informações específicas sobre conversas, como motivo do contato, satisfação do cliente, ou qualquer outro dado relevante ao contexto da conversa. ### Criando um Atributo para Conversas Para criar um novo atributo personalizado para conversas: 1. Na tela de Atributos Personalizados, clique na aba **"Conversas"** para filtrar apenas atributos de conversas 2. Clique no botão verde **"+ New Custom Attribute"** no canto superior direito da tela 3. Um modal será exibido com o título **"New Custom Attribute"** Modal de criação de novo atributo personalizado para Conversas com todos os campos destacados #### Preenchendo o Formulário No formulário, preencha os seguintes campos: **1. Apply to (Aplicar a) - Obrigatório** * Selecione **"Conversas"** no dropdown * O texto de ajuda exibirá: "Atributos aplicados às conversas" **2. Display Name (Nome de Exibição) - Obrigatório** * Digite um nome amigável que será exibido aos usuários * **Exemplo:** "Motivo do Contato" **3. Attribute Key (Chave do Atributo) - Obrigatório** * A chave técnica será gerada automaticamente a partir do Display Name * Use apenas letras minúsculas, números e underscores * **Exemplo:** `motivo_do_contato` **4. Description (Descrição) - Obrigatório** * Explique o propósito do atributo * **Exemplo:** "Identify the main reason why the customer contacted you." **5. Type (Tipo) - Obrigatório** * Selecione o tipo de dado (Texto, Número, Data, Booleano, Lista) * Para o exemplo "Motivo do Contato", selecione **"Texto"** **6. Regex Validation (Validação Regex) - Opcional** * Ative o toggle se desejar validar o formato do texto * **Exemplo de Regex Pattern:** `^.{5,}$` (mínimo 5 caracteres) * **Exemplo de Regex Cue:** "Describe the reason for contacting us (minimum 5 characters)." #### Finalizando a Criação Após preencher todos os campos obrigatórios: 1. Revise as informações inseridas 2. Verifique se a validação regex está configurada corretamente (se aplicável) 3. Clique no botão verde **"Create"** para criar o atributo 4. O atributo será criado e aparecerá na tabela de atributos de Conversas ### Editando um Atributo de Conversas Para modificar um atributo de conversas existente: Modal de edição de atributo personalizado para Conversas com exemplo Motivo do Contato e validação regex 1. Na tabela de atributos, certifique-se de que a aba **"Conversas"** está selecionada 2. Localize o atributo que deseja editar 3. Na coluna **Actions**, clique no ícone de três pontos (`...`) 4. No menu dropdown, clique em **Edit** (ícone de lápis) 5. Um modal será aberto com o título **"Edit Custom Attribute"** e os campos já preenchidos 6. Modifique os campos desejados: * Display Name * Description * Type (cuidado ao alterar, pois pode afetar dados existentes) * Regex Validation (ativar/desativar ou modificar padrão e dica) 7. Clique no botão verde **"Update"** para salvar as alterações Tenha cuidado ao alterar o **Attribute Key** ou o **Type** de um atributo existente, pois isso pode afetar integrações via API e dados já coletados. ### Excluindo um Atributo de Conversas Para remover um atributo de conversas: 1. Na tabela de atributos, localize o atributo que deseja excluir 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) 3. No menu dropdown, clique em **Delete** (ícone de lixeira em vermelho) 4. Confirme a exclusão no diálogo que aparecer **Atenção:** A exclusão é permanente e todos os dados coletados através deste atributo serão perdidos. *** ## Atributos para Contatos Os atributos de contatos permitem armazenar informações adicionais sobre contatos, como cargo, departamento, preferências ou qualquer outro dado relevante ao perfil do contato. ### Criando um Atributo para Contatos Para criar um novo atributo personalizado para contatos: 1. Na tela de Atributos Personalizados, clique na aba **"Contatos"** para filtrar apenas atributos de contatos 2. Clique no botão verde **"+ New Custom Attribute"** no canto superior direito da tela 3. Um modal será exibido com o título **"New Custom Attribute"** Modal de criação de novo atributo personalizado para Contatos com exemplo Cargo e validação regex ativada #### Preenchendo o Formulário No formulário, preencha os seguintes campos: **1. Apply to (Aplicar a) - Obrigatório** * Selecione **"Contatos"** no dropdown * O texto de ajuda exibirá: "Atributos aplicados aos contatos" **2. Display Name (Nome de Exibição) - Obrigatório** * Digite um nome amigável que será exibido aos usuários * **Exemplo:** "Cargo" **3. Attribute Key (Chave do Atributo) - Obrigatório** * A chave técnica será gerada automaticamente a partir do Display Name * Use apenas letras minúsculas, números e underscores * **Exemplo:** `cargo` **4. Description (Descrição) - Obrigatório** * Explique o propósito do atributo * **Exemplo:** "Indicates the contact's position or role within the company." **5. Type (Tipo) - Obrigatório** * Selecione o tipo de dado (Texto, Número, Data, Booleano, Lista) * Para o exemplo "Cargo", selecione **"Texto"** **6. Regex Validation (Validação Regex) - Opcional** * Ative o toggle se desejar validar o formato do texto * **Exemplo de Regex Pattern:** `^.{2,}$` (mínimo 2 caracteres) * **Exemplo de Regex Cue:** "Please provide the contact's job title (minimum 2 characters)." #### Finalizando a Criação Após preencher todos os campos obrigatórios: 1. Revise as informações inseridas 2. Verifique se a validação regex está configurada corretamente (se aplicável) 3. Clique no botão verde **"Create"** para criar o atributo 4. O atributo será criado e aparecerá na tabela de atributos de Contatos ### Editando um Atributo de Contatos Para modificar um atributo de contatos existente: Modal de edição de atributo personalizado para Contatos 1. Na tabela de atributos, certifique-se de que a aba **"Contatos"** está selecionada 2. Localize o atributo que deseja editar 3. Na coluna **Actions**, clique no ícone de três pontos (`...`) 4. No menu dropdown, clique em **Edit** (ícone de lápis) 5. Um modal será aberto com o título **"Edit Custom Attribute"** e os campos já preenchidos 6. Modifique os campos desejados 7. Clique no botão verde **"Update"** para salvar as alterações Tenha cuidado ao alterar o **Attribute Key** ou o **Type** de um atributo existente, pois isso pode afetar integrações via API e dados já coletados. ### Excluindo um Atributo de Contatos Para remover um atributo de contatos: 1. Na tabela de atributos, localize o atributo que deseja excluir 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) 3. No menu dropdown, clique em **Delete** (ícone de lixeira em vermelho) 4. Confirme a exclusão no diálogo que aparecer **Atenção:** A exclusão é permanente e todos os dados coletados através deste atributo serão perdidos. *** ## Atributos para Pipeline Os atributos de pipeline permitem coletar informações específicas sobre oportunidades de vendas. Eles podem ser aplicados ao pipeline como um todo, aos estágios ou aos itens (deals/leads). ### Criando um Atributo para Pipeline Para criar um novo atributo personalizado para pipeline: 1. Na tela de Atributos Personalizados, clique na aba **"Pipeline"** para filtrar apenas atributos de pipeline 2. Clique no botão verde **"+ New Custom Attribute"** no canto superior direito da tela 3. Um modal será exibido com o título **"New Custom Attribute"** Modal de criação de novo atributo personalizado para Pipeline com campo Pipeline Type destacado e exemplo Prioridade do Lead #### Preenchendo o Formulário No formulário, preencha os seguintes campos: **1. Apply to (Aplicar a) - Obrigatório** * Selecione **"Pipeline"** no dropdown * O texto de ajuda exibirá: "Atributos aplicados a pipelines, estágios ou items" * **Importante:** Quando "Pipeline" é selecionado, um campo adicional "Pipeline Type" será exibido **2. Pipeline Type (Tipo de Pipeline) - Obrigatório** * Selecione uma das opções: * **Pipeline:** Atributos aplicados ao pipeline como um todo * **Stage:** Atributos aplicados aos estágios do pipeline * **Item:** Atributos aplicados aos itens (deals/leads) do pipeline * **Exemplo:** Para "Prioridade do Lead", selecione **"Item"** * O texto de ajuda exibirá: "Atributos aplicados aos items (deals/leads) do pipeline" **3. Display Name (Nome de Exibição) - Obrigatório** * Digite um nome amigável que será exibido aos usuários * **Exemplo:** "Prioridade do Lead" **4. Attribute Key (Chave do Atributo) - Obrigatório** * A chave técnica será gerada automaticamente a partir do Display Name * Use apenas letras minúsculas, números e underscores * **Exemplo:** `prioridade_do_lead` **5. Description (Descrição) - Obrigatório** * Explique o propósito do atributo * **Exemplo:** "Define a prioridade da oportunidade no pipeline de vendas." **6. Type (Tipo) - Obrigatório** * Selecione o tipo de dado (Texto, Número, Data, Booleano, Lista) * Para o exemplo "Prioridade do Lead", selecione **"Texto"** **7. Regex Validation (Validação Regex) - Opcional** * Ative o toggle se desejar validar o formato do texto * **Exemplo de Regex Pattern:** `^(Baixa|Media|Alta)$` (aceita apenas "Baixa", "Media" ou "Alta") * **Exemplo de Regex Cue:** "Use apenas: Baixa, Media ou Alta" #### Finalizando a Criação Após preencher todos os campos obrigatórios: 1. Revise as informações inseridas, especialmente o Pipeline Type 2. Verifique se a validação regex está configurada corretamente (se aplicável) 3. Clique no botão verde **"Create"** para criar o atributo 4. O atributo será criado e aparecerá na tabela de atributos de Pipeline ### Editando um Atributo de Pipeline Para modificar um atributo de pipeline existente: Modal de edição de atributo personalizado para Pipeline 1. Na tabela de atributos, certifique-se de que a aba **"Pipeline"** está selecionada 2. Localize o atributo que deseja editar 3. Na coluna **Actions**, clique no ícone de três pontos (`...`) 4. No menu dropdown, clique em **Edit** (ícone de lápis) 5. Um modal será aberto com o título **"Edit Custom Attribute"** e os campos já preenchidos 6. Modifique os campos desejados: * Pipeline Type (se necessário) * Display Name * Description * Type (cuidado ao alterar, pois pode afetar dados existentes) * Regex Validation (ativar/desativar ou modificar padrão e dica) 7. Clique no botão verde **"Update"** para salvar as alterações Tenha cuidado ao alterar o **Attribute Key**, **Pipeline Type** ou o **Type** de um atributo existente, pois isso pode afetar integrações via API e dados já coletados. ### Excluindo um Atributo de Pipeline Para remover um atributo de pipeline: 1. Na tabela de atributos, localize o atributo que deseja excluir 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) 3. No menu dropdown, clique em **Delete** (ícone de lixeira em vermelho) 4. Confirme a exclusão no diálogo que aparecer **Atenção:** A exclusão é permanente e todos os dados coletados através deste atributo serão perdidos. *** ## Campos do Formulário em Detalhes ### Apply to (Aplicar a) - Obrigatório * **Campo:** **Apply to** (marcado com asterisco `*` indicando campo obrigatório) * **Tipo:** Dropdown (menu suspenso) * **Descrição:** Define onde o atributo será aplicado * **Opções Disponíveis:** * **Conversas:** Atributos aplicados às conversas * **Contatos:** Atributos aplicados aos contatos * **Pipeline:** Atributos aplicados a pipelines, estágios ou itens * **Texto de Ajuda:** Exibe uma descrição explicando o contexto selecionado * **Localização:** Primeiro campo do formulário **Nota:** Quando "Pipeline" é selecionado, um campo adicional "Pipeline Type" será exibido. ### Pipeline Type (Tipo de Pipeline) - Obrigatório (apenas para Pipeline) * **Campo:** **Pipeline Type** (marcado com asterisco `*` indicando campo obrigatório) * **Tipo:** Dropdown (menu suspenso) * **Descrição:** Define se o atributo se aplica ao pipeline, estágio ou item * **Opções Disponíveis:** * **Pipeline:** Atributos aplicados ao pipeline como um todo * **Stage:** Atributos aplicados aos estágios do pipeline * **Item:** Atributos aplicados aos itens (deals/leads) do pipeline * **Texto de Ajuda:** "Select whether this attribute applies to the pipeline, stage, or item." * **Localização:** Segundo campo do formulário, exibido apenas quando "Pipeline" é selecionado em "Apply to" ### Display Name (Nome de Exibição) - Obrigatório * **Campo:** **Display Name** (marcado com asterisco `*` indicando campo obrigatório) * **Tipo:** Campo de texto simples * **Descrição:** Nome amigável que será exibido aos usuários * **Exemplos:** "Prioridade do Lead", "Cargo", "Motivo do Contato" * **Recomendação:** Use nomes descritivos e claros que facilitem a identificação do atributo * **Localização:** Terceiro campo do formulário (ou segundo, se não for Pipeline) ### Attribute Key (Chave do Atributo) - Obrigatório * **Campo:** **Attribute Key** (marcado com asterisco `*` indicando campo obrigatório) * **Tipo:** Campo de texto simples * **Descrição:** Chave técnica usada para identificar o atributo na API * **Texto de Ajuda:** "The key will be used to identify this attribute in the API. Use only lowercase letters, numbers and underscores." * **Regras:** * Use apenas letras minúsculas, números e underscores * Não use espaços ou caracteres especiais * Geralmente é gerado automaticamente a partir do Display Name * **Exemplos:** `prioridade_do_lead`, `cargo`, `motivo_do_contato` * **Localização:** Quarto campo do formulário (ou terceiro, se não for Pipeline) ### Description (Descrição) - Obrigatório * **Campo:** **Description** (marcado com asterisco `*` indicando campo obrigatório) * **Tipo:** Área de texto (textarea) * **Descrição:** Explicação detalhada do propósito do atributo * **Exemplos:** * "Define a prioridade da oportunidade no pipeline de vendas." * "Indicates the contact's position or role within the company." * "Identify the main reason why the customer contacted you." * **Recomendação:** Seja claro e objetivo sobre o que o atributo representa * **Localização:** Quinto campo do formulário (ou quarto, se não for Pipeline) ### Type (Tipo) - Obrigatório * **Campo:** **Type** (marcado com asterisco `*` indicando campo obrigatório) * **Tipo:** Dropdown (menu suspenso) * **Descrição:** Define o tipo de dado que o atributo aceitará * **Opções Disponíveis:** * **Texto:** Campo de texto simples * **Descrição:** "Campo de texto simples" * Permite qualquer texto livre * **Número:** Campo numérico * **Data:** Campo de data * **Booleano:** Campo verdadeiro/falso * **Lista:** Lista de valores pré-definidos * **Texto de Ajuda:** Exibe uma descrição do tipo selecionado * **Localização:** Sexto campo do formulário (ou quinto, se não for Pipeline) ### Regex Validation (Validação Regex) - Opcional Esta seção permite adicionar validação por expressão regular para garantir que os valores inseridos sigam um padrão específico. * **Seção:** **"Regex Validation"** * **Descrição:** "Add a regex pattern to validate the values of this attribute" * **Toggle Switch:** Interruptor no canto superior direito da seção * **Desativado:** Validação regex não será aplicada * **Ativado:** Validação regex será aplicada (indicado por cor verde/turquesa) Quando o toggle está ativado, dois campos adicionais são exibidos: #### Regex Pattern (Padrão Regex) * **Campo:** **Regex Pattern** * **Tipo:** Campo de texto simples * **Descrição:** Expressão regular que define o padrão de validação * **Exemplos:** * `^(Baixa|Media|Alta)$` - Aceita apenas "Baixa", "Media" ou "Alta" * `^.{2,}$` - Aceita qualquer texto com no mínimo 2 caracteres * `^.{5,}$` - Aceita qualquer texto com no mínimo 5 caracteres * **Recomendação:** Teste o padrão regex antes de salvar para garantir que funciona como esperado #### Regex Cue (Dica Regex) * **Campo:** **Regex Cue** * **Tipo:** Área de texto (textarea) * **Descrição:** Mensagem de ajuda exibida aos usuários quando preenchem o campo * **Texto de Ajuda:** "This cue will be displayed to users when they fill in the field" * **Exemplos:** * "Use apenas: Baixa, Media ou Alta" * "Please provide the contact's job title (minimum 2 characters)." * "Describe the reason for contacting us (minimum 5 characters)." * **Recomendação:** Seja claro e específico sobre o formato esperado *** ## Tipos de Atributos Disponíveis ### Texto (Text) * **Descrição:** Campo de texto simples * **Uso:** Permite inserir qualquer texto livre * **Exemplos de uso:** * Nome do cargo do contato * Motivo do contato * Observações gerais * **Validação:** Pode ser combinado com regex para restringir o formato ou tamanho ### Número (Number) * **Descrição:** Campo numérico * **Uso:** Permite inserir valores numéricos * **Exemplos de uso:** * Valor estimado de uma oportunidade * Número de funcionários da empresa * Pontuação de satisfação ### Data (Date) * **Descrição:** Campo de data * **Uso:** Permite selecionar ou inserir uma data * **Exemplos de uso:** * Data de aniversário do contato * Data prevista de fechamento da oportunidade * Data de último contato ### Booleano (Boolean) * **Descrição:** Campo verdadeiro/falso * **Uso:** Permite marcar como verdadeiro ou falso * **Exemplos de uso:** * Cliente VIP (sim/não) * Aceita receber marketing (sim/não) * Oportunidade qualificada (sim/não) ### Lista (List) * **Descrição:** Lista de valores pré-definidos * **Uso:** Permite selecionar um valor de uma lista pré-definida * **Exemplos de uso:** * Prioridade (Baixa, Média, Alta) * Status (Ativo, Inativo, Pendente) * Fonte do lead (Website, Referência, Campanha) *** ## Validação por Expressão Regular (Regex) A validação por regex permite garantir que os valores inseridos nos atributos sigam um padrão específico, melhorando a qualidade e consistência dos dados coletados. ### Quando Usar Regex * **Valores Pré-definidos:** Quando você quer restringir a entrada a valores específicos (ex: "Baixa", "Media", "Alta") * **Formato Específico:** Quando você precisa de um formato específico (ex: código de produto, número de telefone) * **Tamanho Mínimo/Máximo:** Quando você precisa garantir um tamanho mínimo ou máximo de texto * **Padrões Complexos:** Quando você precisa validar padrões mais complexos (ex: emails, URLs, códigos) ### Exemplos de Padrões Regex #### Valores Pré-definidos ``` ^(Baixa|Media|Alta)$ ``` * Aceita apenas "Baixa", "Media" ou "Alta" * Regex Cue: "Use apenas: Baixa, Media ou Alta" #### Tamanho Mínimo ``` ^.{2,}$ ``` * Aceita qualquer texto com no mínimo 2 caracteres * Regex Cue: "Please provide at least 2 characters." ``` ^.{5,}$ ``` * Aceita qualquer texto com no mínimo 5 caracteres * Regex Cue: "Describe the reason for contacting us (minimum 5 characters)." #### Formato de Email ``` ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$ ``` * Valida formato de email básico * Regex Cue: "Please provide a valid email address." ### Dicas para Regex * **Teste Antes:** Sempre teste seu padrão regex antes de salvar para garantir que funciona como esperado * **Seja Específico:** Use Regex Cue para explicar claramente o formato esperado aos usuários * **Documentação:** Considere documentar padrões regex complexos para facilitar manutenção futura * **Performance:** Padrões regex muito complexos podem afetar a performance, use com moderação *** ## Considerações Finais * **Nomenclatura Consistente:** Use nomes de exibição e chaves consistentes para facilitar a organização e busca * **Descrições Claras:** Escreva descrições claras e objetivas que expliquem o propósito de cada atributo * **Validação Apropriada:** Use validação regex quando necessário para garantir qualidade dos dados, mas não seja excessivamente restritivo * **Categorização:** Organize os atributos nas categorias apropriadas (Conversas, Contatos, Pipeline) para facilitar o gerenciamento * **Revisão Regular:** Revise periodicamente os atributos existentes para garantir que continuam relevantes e atualizados * **Documentação:** Documente atributos personalizados complexos ou com padrões regex específicos para facilitar o uso pela equipe * **Integração API:** Lembre-se de que o Attribute Key é usado na API - mantenha consistência e evite alterações desnecessárias * **Impacto em Dados:** Considere o impacto em dados existentes antes de alterar o Type ou excluir um atributo * **Uso Estratégico:** Use atributos personalizados para coletar informações que agregam valor ao seu processo de negócio Os atributos personalizados são uma ferramenta poderosa para estender a funcionalidade do sistema e coletar informações específicas do seu negócio, permitindo uma gestão mais completa e personalizada de conversas, contatos e oportunidades de vendas. # Funções Personalizadas Source: https://docs.evolutionfoundation.com.br/user-guides/settings/custom-roles A seção de **Funções Personalizadas** (Custom Roles) permite que você crie e gerencie funções personalizadas com permissões granulares para controlar o acesso de usuários a diferentes recursos e funcionalidades do sistema. Com as funções personalizadas, você pode definir exatamente quais ações cada função pode realizar em cada recurso, proporcionando controle preciso sobre o que cada membro da equipe pode visualizar, criar, editar ou excluir. Cada função personalizada pode ter um nome, descrição, status (ativo/inativo) e um conjunto detalhado de permissões organizadas em categorias: Core Features (Funcionalidades Principais), AI Agents (Agentes de IA) e Settings (Configurações). ## Acessando Funções Personalizadas Para acessar a área de gerenciamento de funções personalizadas: 1. No menu lateral esquerdo, clique em **Settings** (Configurações). 2. Na lista de opções de configurações, selecione **Custom Roles** (Funções Personalizadas). Navegação para Funções Personalizadas - Item Custom Roles destacado no menu lateral A tela principal de funções personalizadas será exibida, mostrando todas as funções criadas ou uma mensagem indicando que nenhuma função foi criada ainda. *** ## Visualizando a Lista de Funções Personalizadas A tela principal de funções personalizadas exibe: * **Título:** "Custom Roles" no topo esquerdo em fonte grande e em negrito * **Subtítulo:** "Manage custom roles with granular permissions" abaixo do título * **Barra de Pesquisa:** Campo para filtrar funções por nome, localizado abaixo do subtítulo com placeholder "Search roles..." * **Botão de Criação:** Botão verde **"+ New Role"** no canto superior direito da tela * **Alternância de Visualização:** Ícones de grid e lista abaixo do botão "+ New Role" para alternar entre visualizações * **Estado Vazio:** Quando não há funções criadas, uma mensagem central "No custom roles yet" com um botão "Create Custom Role" *** ## Pesquisando Funções Personalizadas A barra de pesquisa permite localizar funções rapidamente pelo nome. ### Como pesquisar 1. Na parte superior da tela, localize o campo **"Search roles..."** com o ícone de lupa 2. Digite o nome ou parte do nome da função desejada 3. A lista de funções será atualizada automaticamente conforme o termo digitado, mostrando apenas as funções que correspondem à busca Barra de pesquisa de funções personalizadas destacada A busca é realizada em tempo real, facilitando a localização de funções específicas quando há muitas cadastradas. *** ## Criando uma Nova Função Personalizada Existem duas formas de iniciar a criação de uma nova função personalizada: ### Opção 1: Botão no Cabeçalho 1. Clique no botão verde **"+ New Role"** localizado no canto superior direito da tela Botão New Role no cabeçalho destacado ### Opção 2: Botão no Estado Vazio Quando não há funções criadas, clique no botão verde **"Create Custom Role"** no centro da tela. ### Preenchendo o Formulário de Criação Após clicar em qualquer um dos botões, um modal será exibido com fundo escuro contendo: * **Título:** **"New Custom Role"** no topo do modal * **Descrição:** "Create a new role with specific permissions." logo abaixo do título Modal de criação de nova função personalizada com todos os campos destacados No formulário, preencha os seguintes campos: #### 1. Informações Básicas ##### Nome (Obrigatório) * **Campo:** **Name** (marcado com asterisco vermelho `*` indicando campo obrigatório) * **Tipo:** Campo de texto simples * **Descrição:** Nome identificador da função personalizada * **Exemplo:** "Gerente de Vendas", "Analista de Suporte", "Administrador de IA" * **Recomendação:** Use nomes claros e descritivos que indiquem o propósito da função * **Localização:** Primeiro campo do formulário, na seção "Basic Information" ##### Descrição (Opcional) * **Campo:** **Description** (sem asterisco, indicando campo opcional) * **Tipo:** Área de texto (textarea) maior que o campo de nome * **Descrição:** Texto explicativo sobre o propósito e responsabilidades da função * **Exemplo:** "Responsible for managing the sales team, monitoring performance, setting goals, analyzing reports, and making strategic business decisions." * **Uso:** Ajuda outros membros da equipe a entenderem quando atribuir esta função * **Localização:** Segundo campo do formulário, abaixo do campo Name ##### Status Ativo * **Campo:** **Active** * **Tipo:** Toggle switch (interruptor) * **Descrição:** Define se a função está ativa e pode ser atribuída a usuários * **Estado Visual:** * **Quando Ativado:** O toggle fica na posição "on" com fundo verde/turquesa * **Quando Desativado:** O toggle fica na posição "off" com fundo cinza * **Comportamento:** * **Quando Ativado:** A função pode ser atribuída a usuários e está disponível para uso * **Quando Desativado:** A função existe, mas não pode ser atribuída a novos usuários * **Localização:** Terceiro campo do formulário, abaixo do campo Description #### 2. Permissões A seção de **Permissions** (Permissões) permite definir quais ações a função pode realizar em cada recurso do sistema. As permissões são organizadas em três categorias principais: ##### Visão Geral das Permissões * **Texto Explicativo:** "Select which actions this role can perform on each resource" * **Contador de Seleção:** Exibe "0 selected" ou "X selected" indicando quantas permissões foram selecionadas no total * **Botão Select All:** Permite selecionar todas as permissões disponíveis de uma vez ##### Core Features (Funcionalidades Principais) Esta categoria contém permissões relacionadas às funcionalidades principais do sistema: * **Contador:** Exibe "0/21" ou "X/21" indicando quantas permissões foram selecionadas de um total de 21 * **Select All:** Checkbox para selecionar todas as permissões desta categoria * **Ícone de Expansão:** Seta para expandir/colapsar a seção Seção Core Features expandida mostrando todas as subcategorias e permissões disponíveis **Subcategorias disponíveis:** 1. **Dashboard (0/1)** * Descrição: "Main panel with metrics and overview" * Permissões: View 2. **Conversations (0/4)** * Descrição: "Manage customer conversations" * Permissões: View, Create, Edit, Delete 3. **Contacts (0/4)** * Descrição: "Manage contacts and leads" * Permissões: View, Create, Edit, Delete 4. **Pipelines (0/4)** * Descrição: "Manage sales pipelines" * Permissões: View, Create, Edit, Delete 5. **Journeys (0/4)** * Descrição: "Automate customer journeys" * Permissões: View, Create, Edit, Delete 6. **Channels (0/4)** * Descrição: "Manage communication channels" * Permissões: View, Create, Edit, Delete 7. **Products (0/4)** *(a partir do v1.0.0-rc3)* * Descrição: "Manage product catalog and variants" * Permissões: View, Create, Edit, Delete * Por padrão, `account_owner` recebe todas; `agent` recebe View. Ver [Produtos](/user-guides/products/overview). 8. **Template Bundles (0/2)** *(a partir do v1.0.0-rc3)* * Descrição: "Export and import configuration bundles" * Permissões: View, Manage * Por padrão, apenas `account_owner` recebe Manage. Conceder a outros papéis com cuidado — Manage permite sobrescrever configuração crítica. Ver [Bundles](/user-guides/settings/template-bundles). Cada subcategoria possui: * Um checkbox principal à direita para selecionar todas as permissões da subcategoria * Checkboxes individuais para cada ação (View, Create, Edit, Delete) ##### AI Agents (Agentes de IA) Esta categoria contém permissões relacionadas à gestão de agentes de inteligência artificial: * **Contador:** Exibe "0/14" ou "X/14" indicando quantas permissões foram selecionadas de um total de 14 * **Select All:** Checkbox para selecionar todas as permissões desta categoria * **Ícone de Expansão:** Seta para expandir/colapsar a seção Seção AI Agents expandida mostrando todas as subcategorias e permissões disponíveis **Subcategorias disponíveis:** 1. **AI Agents (0/4)** * Descrição: "Manage artificial intelligence agents" * Permissões: View, Create, Edit, Delete 2. **Custom Tools (0/4)** * Descrição: "Create custom tools for agents" * Permissões: View, Create, Edit, Delete 3. **Custom MCP Servers (0/4)** * Descrição: "Configure custom MCP servers" * Permissões: View, Create, Edit, Delete 4. **MCP Servers (0/1)** * Descrição: "Manage system MCP servers" * Permissões: View 5. **AI Tools (0/1)** * Descrição: "Tools available for agents" * Permissões: View Cada subcategoria possui: * Um checkbox principal à direita para selecionar todas as permissões da subcategoria * Checkboxes individuais para cada ação disponível ##### Settings (Configurações) Esta categoria contém permissões relacionadas às configurações do sistema: * **Contador:** Exibe "0/45" ou "X/45" indicando quantas permissões foram selecionadas de um total de 45 * **Select All:** Checkbox para selecionar todas as permissões desta categoria * **Ícone de Expansão:** Seta para expandir/colapsar a seção Seção Settings expandida mostrando todas as subcategorias e permissões disponíveis **Subcategorias disponíveis:** 1. **Account (0/2)** * Descrição: "Account settings" * Permissões: View, Edit 2. **Users (0/4)** * Descrição: "Manage account users" * Permissões: View, Create, Edit, Delete 3. **Teams (0/4)** * Descrição: "Manage teams and groups" * Permissões: View, Create, Edit, Delete 4. **Custom Roles (0/4)** * Descrição: "Create and manage custom roles" * Permissões: View, Create, Edit, Delete 5. **Labels (0/4)** * Descrição: "Manage labels for organization" * Permissões: View, Create, Edit, Delete 6. **Custom Attributes (0/4)** * Descrição: "Create custom fields" * Permissões: View, Create, Edit, Delete 7. **Canned Responses (0/4)** * Descrição: "Pre-defined messages" * Permissões: View, Create, Edit, Delete 8. **Macros (0/4)** * Descrição: "Automate repetitive actions" * Permissões: View, Create, Edit, Delete Cada subcategoria possui: * Um checkbox principal à direita para selecionar todas as permissões da subcategoria * Checkboxes individuais para cada ação disponível ### Como Selecionar Permissões 1. **Seleção Individual:** Clique nos checkboxes individuais de cada ação (View, Create, Edit, Delete) para conceder permissões específicas 2. **Seleção por Subcategoria:** Clique no checkbox principal à direita de cada subcategoria para selecionar todas as permissões daquela subcategoria 3. **Seleção por Categoria:** Clique no checkbox "Select All" no cabeçalho de cada categoria (Core Features, AI Agents, Settings) para selecionar todas as permissões da categoria 4. **Seleção Total:** Clique no botão "Select All" no topo da seção de permissões para selecionar todas as permissões disponíveis ### Finalizando a Criação Na parte inferior do modal, há dois botões de ação: * **Cancel:** Botão cinza escuro com texto branco, localizado à esquerda * **Create Role:** Botão verde/turquesa brilhante com texto branco, localizado à direita Após preencher os campos desejados: 1. Revise as informações inseridas, especialmente as permissões selecionadas 2. Clique no botão verde **"Create Role"** para criar a função personalizada 3. Ou clique em **"Cancel"** para fechar o modal sem salvar A função será criada e aparecerá imediatamente na lista de funções personalizadas. *** ## Visualizando Funções Personalizadas na Lista Após criar funções personalizadas, elas serão exibidas em cards com as seguintes informações: ### Informações do Card * **Nome da Função:** Título em negrito no topo do card * **Descrição:** Texto descritivo da função (pode estar truncado com "...") * **Status:** Badge indicando se a função está "Active" (Ativa) ou "Inactive" (Inativa) * **Estatísticas:** Três métricas exibidas na parte inferior do card: * **Users:** Número de usuários atribuídos a esta função (ex: "0 users") * **Permissions:** Número de permissões concedidas à função (ex: "0 permissions") * **Scopes:** Número de escopos configurados (ex: "0 scopes") * **Menu de Ações:** Ícone de três pontos (`...`) no canto superior direito do card para acessar opções ### Funcionalidades da Lista * **Busca Integrada:** A barra de pesquisa acima da lista filtra os resultados em tempo real * **Alternância de Visualização:** Use os ícones de grid e lista para alternar entre visualizações diferentes *** ## Editando uma Função Personalizada Para modificar uma função personalizada existente: 1. Na lista de funções personalizadas, localize a função que deseja editar 2. No card da função, clique no ícone de três pontos (`...`) no canto superior direito 3. Um menu dropdown será exibido com as opções disponíveis 4. No menu dropdown, clique em **Edit** (acompanhado de um ícone de lápis) 5. Um modal semelhante ao de criação será aberto, mas com o título **"Edit Custom Role"** e os campos já preenchidos com os valores atuais da função Menu de ações da função personalizada destacado - opções Edit, Activate e Delete 6. Modifique os campos desejados: * Nome * Descrição * Status Ativo (toggle) * Permissões (adicione ou remova permissões conforme necessário) 7. Revise as alterações 8. Clique no botão verde **"Update Role"** ou **"Save"** para salvar as alterações 9. Ou clique em **"Cancel"** para descartar as alterações As alterações serão aplicadas imediatamente e refletidas na lista de funções personalizadas e nos usuários que possuem esta função atribuída. *** ## Ativando/Desativando uma Função Personalizada Para alterar o status de uma função personalizada: 1. Na lista de funções personalizadas, localize a função que deseja ativar ou desativar 2. No card da função, clique no ícone de três pontos (`...`) no canto superior direito 3. No menu dropdown que aparece: * Se a função estiver **Inativa**, clique em **"Activate"** para ativá-la * Se a função estiver **Ativa**, clique em **"Deactivate"** para desativá-la **Observação:** Funções inativas não podem ser atribuídas a novos usuários, mas usuários que já possuem a função atribuída mantêm suas permissões até que a função seja removida manualmente. *** ## Excluindo uma Função Personalizada Para remover uma função personalizada: 1. Na lista de funções personalizadas, localize a função que deseja excluir 2. No card da função, clique no ícone de três pontos (`...`) no canto superior direito 3. No menu dropdown que aparece, clique em **Delete** (acompanhado de um ícone de lixeira, exibido em texto vermelho para indicar uma ação destrutiva) 4. Um diálogo de confirmação será exibido 5. Confirme a exclusão no diálogo que aparecer **Atenção:** A exclusão de uma função personalizada pode afetar os usuários que possuem esta função atribuída. Verifique se não há dependências antes de excluir. A ação de exclusão é permanente e não pode ser desfeita. Recomenda-se revisar quais usuários possuem a função antes de excluí-la. *** ## Considerações Finais * **Princípio do Menor Privilégio:** Conceda apenas as permissões necessárias para cada função realizar seu trabalho, evitando acesso excessivo * **Nomenclatura Clara:** Use nomes descritivos e claros para que todos os membros da equipe entendam o propósito de cada função * **Descrições Detalhadas:** Preencha as descrições das funções para documentar responsabilidades e quando utilizá-las * **Revisão Regular:** Revise periodicamente as permissões das funções para garantir que continuam adequadas às necessidades da equipe * **Status Ativo:** Mantenha apenas funções ativas que estão em uso, desativando funções obsoletas em vez de excluí-las imediatamente * **Permissões Granulares:** Utilize as permissões granulares para criar funções específicas que atendam exatamente às necessidades de cada equipe ou departamento * **Teste de Permissões:** Após criar uma função, teste atribuindo-a a um usuário de teste para garantir que as permissões funcionam como esperado As funções personalizadas são uma ferramenta poderosa para controle de acesso e segurança, permitindo que você defina exatamente o que cada membro da equipe pode fazer no sistema, melhorando a segurança e a organização do trabalho em equipe. *** ## Guard de Privilege Escalation (a partir do v1.0.0-rc3) A partir do `v1.0.0-rc3`, o endpoint de criação/edição de funções aplica uma proteção contra **privilege escalation via delegation** (EVO-1061): * Um `account_owner` só pode **delegar permissões que ele mesmo detém**. * Tentar criar uma função com uma permissão fora do conjunto do solicitante retorna `403 Forbidden` com motivo explícito. * O escopo do `super_admin` (permissões `installation_configs.manage`) continua exclusivo — outros papéis não podem delegar essas permissões. Isso impede que um `account_owner` crie uma função "Super Helper" que dá a um agente comum acesso ao painel de instalação. O comportamento é estrito por design. # Etiquetas Source: https://docs.evolutionfoundation.com.br/user-guides/settings/labels A seção de **Etiquetas** permite que você organize e categorize suas conversas através de rótulos personalizados. Com as etiquetas, você pode marcar conversas com identificadores visuais (cores), facilitando a identificação rápida e a organização do trabalho da equipe. Cada etiqueta pode ter um nome, descrição, cor personalizada e pode ser configurada para aparecer na barra lateral de conversas para acesso rápido. ## Acessando Etiquetas Para acessar a área de gerenciamento de etiquetas: 1. No menu lateral esquerdo, clique em **Settings** (Configurações). 2. Na lista de opções de configurações, selecione **Labels** (Etiquetas). Navegação para Etiquetas - Item Labels destacado no menu lateral A tela principal de etiquetas será exibida, mostrando todas as etiquetas criadas ou uma mensagem indicando que nenhuma etiqueta foi criada ainda. *** ## Visualizando a Lista de Etiquetas A tela principal de etiquetas exibe: * **Título:** "Labels" no topo esquerdo em fonte grande e em negrito * **Contador:** O número total de etiquetas criadas logo abaixo do título (ex: "0 labels in total" ou "1 label in total") * **Barra de Pesquisa:** Campo para filtrar etiquetas por nome, localizado abaixo do título e contador * **Botão de Criação:** Botão verde/turquesa **"+ New Label"** no canto superior direito da tela * **Tabela de Etiquetas:** Lista todas as etiquetas com suas informações quando há etiquetas criadas *** ## Pesquisando Etiquetas A barra de pesquisa permite localizar etiquetas rapidamente pelo nome. ### Como pesquisar 1. Na parte superior da tela, localize o campo **"Search labels..."** com o ícone de lupa 2. Digite o nome ou parte do nome da etiqueta desejada 3. A tabela de etiquetas será atualizada automaticamente conforme o termo digitado, mostrando apenas as etiquetas que correspondem à busca Barra de pesquisa de etiquetas destacada em vermelho A busca é realizada em tempo real, facilitando a localização de etiquetas específicas quando há muitas cadastradas. *** ## Criando uma Nova Etiqueta Existem duas formas de iniciar a criação de uma nova etiqueta: Botão New Label no cabeçalho destacado ### Opção 1: Botão no Cabeçalho 1. Clique no botão verde **"+ New Label"** localizado no canto superior direito da tela ### Opção 2: Botão no Estado Vazio Quando não há etiquetas criadas, clique no botão verde **"New Label"** no centro da tela. ### Preenchendo o Formulário de Criação Após clicar em qualquer um dos botões, um modal será exibido com fundo escuro contendo: Modal de criação de nova etiqueta com todos os campos destacados * **Título:** **"New Label"** no topo do modal * **Descrição:** "Create a new label to organize your conversations." logo abaixo do título * **Botão de Fechar:** Um ícone "X" no canto superior direito para fechar o modal sem salvar No formulário, preencha os seguintes campos: #### 1. Nome (Obrigatório) * **Campo:** **Name** (marcado com asterisco vermelho `*` indicando campo obrigatório) * **Tipo:** Campo de texto simples * **Descrição:** Nome identificador da etiqueta * **Exemplo:** "work", "urgent", "follow-up" * **Recomendação:** Use nomes curtos e descritivos * **Localização:** Primeiro campo do formulário #### 2. Descrição (Opcional) * **Campo:** **Description** (sem asterisco, indicando campo opcional) * **Tipo:** Área de texto (textarea) maior que o campo de nome * **Descrição:** Texto explicativo sobre o propósito da etiqueta * **Exemplo:** "Conversations related to projects, tasks, and professional demands." * **Uso:** Ajuda outros membros da equipe a entenderem quando usar esta etiqueta * **Localização:** Segundo campo do formulário, abaixo do campo Name #### 3. Cor (Obrigatório) * **Campo:** **Color** (marcado com asterisco vermelho `*` indicando campo obrigatório) * **Descrição:** Cor visual que identifica a etiqueta * **Seleção de Cor:** * **Visualização:** Um quadrado colorido sólido à esquerda mostra a cor atualmente selecionada * **Código Hexadecimal:** Um campo de entrada ao lado do quadrado permite inserir diretamente um código de cor (ex: `#2ed573` para verde vibrante) * **Paleta de Cores:** Uma grade de cores pré-definidas está disponível abaixo do campo de código hexadecimal, permitindo seleção rápida * **Cor Selecionada:** A cor escolhida na paleta fica destacada/highlighted * **Cores Disponíveis:** A paleta inclui diversas opções como azul, vermelho, rosa, laranja, roxo, verde claro, verde escuro, cinza, preto, entre outras * **Localização:** Terceiro campo do formulário, abaixo do campo Description #### 4. Mostrar na Barra Lateral * **Campo:** **Show on sidebar** * **Tipo:** Toggle switch (interruptor) * **Descrição:** Texto explicativo abaixo do título: "Makes the label visible in the conversations sidebar" * **Estado Visual:** * **Quando Ativado:** O toggle fica na posição "on" com fundo verde/turquesa * **Quando Desativado:** O toggle fica na posição "off" com fundo cinza * **Comportamento:** * **Quando Ativado:** A etiqueta aparecerá na barra lateral de conversas para acesso rápido * **Quando Desativado:** A etiqueta existirá, mas não será exibida na barra lateral * **Localização:** Quarto campo do formulário, abaixo da seleção de cor ### Finalizando a Criação Na parte inferior do modal, há dois botões de ação: * **Cancel:** Botão cinza escuro com texto branco, localizado à esquerda * **Create:** Botão verde/turquesa brilhante com texto branco, localizado à direita (cor corresponde à cor selecionada para a etiqueta) Após preencher os campos desejados: 1. Revise as informações inseridas 2. Clique no botão verde **"Create"** para criar a etiqueta 3. Ou clique em **"Cancel"** para fechar o modal sem salvar 4. Alternativamente, clique no ícone "X" no canto superior direito para fechar sem salvar A etiqueta será criada e aparecerá imediatamente na tabela de etiquetas. *** ## Visualizando Etiquetas na Tabela Após criar etiquetas, elas serão exibidas em uma tabela com as seguintes colunas: ### Colunas da Tabela * **Checkbox:** Seleção individual ou em massa de etiquetas * **Name:** Nome da etiqueta (ordenável) * **Description:** Descrição da etiqueta * **Color:** Cor da etiqueta com código hexadecimal * **Sidebar:** Indica se a etiqueta está visível na barra lateral (Yes/No) * **Created at:** Data de criação da etiqueta (ordenável) * **Actions:** Menu de ações para gerenciar a etiqueta ### Funcionalidades da Tabela * **Seleção Múltipla:** Use os checkboxes para selecionar múltiplas etiquetas e realizar ações em lote * **Ordenação:** Clique nos cabeçalhos das colunas "Name" ou "Created at" para ordenar a tabela * **Busca Integrada:** A barra de pesquisa acima da tabela filtra os resultados em tempo real *** ## Editando uma Etiqueta Para modificar uma etiqueta existente: 1. Na tabela de etiquetas, localize a etiqueta que deseja editar 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente à etiqueta 3. Um menu dropdown será exibido com as opções disponíveis Menu de ações da etiqueta destacado - opções Edit e Delete 4. No menu dropdown, clique em **Edit** (acompanhado de um ícone de lápis) 5. Um modal semelhante ao de criação será aberto, mas com o título **"Edit Label"** e os campos já preenchidos com os valores atuais da etiqueta 6. Modifique os campos desejados: * Nome * Descrição * Cor (selecione uma nova cor na paleta ou insira um novo código hexadecimal) * Visibilidade na barra lateral (toggle Show on sidebar) 7. Revise as alterações 8. Clique no botão verde **"Update"** ou **"Save"** para salvar as alterações 9. Ou clique em **"Cancel"** para descartar as alterações As alterações serão aplicadas imediatamente e refletidas na tabela de etiquetas. *** ## Excluindo uma Etiqueta Para remover uma etiqueta: 1. Na tabela de etiquetas, localize a etiqueta que deseja excluir 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente à etiqueta 3. No menu dropdown que aparece, clique em **Delete** (acompanhado de um ícone de lixeira, exibido em texto vermelho para indicar uma ação destrutiva) 4. Um diálogo de confirmação será exibido 5. Confirme a exclusão no diálogo que aparecer **Atenção:** A exclusão de uma etiqueta pode afetar as conversas que foram marcadas com ela. Verifique se não há dependências antes de excluir. A ação de exclusão é permanente e não pode ser desfeita. *** ## Considerações Finais * **Organização:** Use etiquetas de forma consistente para facilitar a organização e busca de conversas * **Cores:** Escolha cores distintas para diferentes tipos de etiquetas, facilitando a identificação visual rápida * **Barra Lateral:** Ative "Show on sidebar" apenas para etiquetas frequentemente utilizadas, mantendo a barra lateral organizada * **Nomenclatura:** Use nomes claros e descritivos para que todos os membros da equipe entendam o propósito de cada etiqueta * **Descrições:** Preencha as descrições das etiquetas para documentar quando e como utilizá-las As etiquetas são uma ferramenta poderosa para categorizar e organizar conversas, melhorando a eficiência do trabalho em equipe e facilitando o acompanhamento de diferentes tipos de interações com os contatos. # Macros Source: https://docs.evolutionfoundation.com.br/user-guides/settings/macros A seção de **Macros** permite que você crie e gerencie macros para automatizar tarefas repetitivas no sistema. Com as macros, você pode definir sequências de ações que serão executadas automaticamente em uma ordem específica, economizando tempo e garantindo consistência nas operações realizadas pela equipe. Cada macro pode ter um nome descritivo, configuração de visibilidade (privada ou pública) e uma sequência de ações que serão executadas na ordem definida. As macros são especialmente úteis para padronizar processos comuns, como atribuir conversas a equipes específicas, aplicar etiquetas, ou realizar outras ações recorrentes. ## Acessando Macros Para acessar a área de gerenciamento de macros: 1. No menu lateral esquerdo, clique em **Settings** (Configurações). 2. Na lista de opções de configurações, selecione **Macros**. Navegação para Macros - Item Macros destacado no menu lateral e estado vazio A tela principal de macros será exibida, mostrando todas as macros criadas ou uma mensagem indicando que nenhuma macro foi criada ainda. *** ## Pesquisando Macros A barra de pesquisa permite localizar macros rapidamente pelo nome. ### Como pesquisar 1. Na parte superior da tela, localize o campo **"Search macros..."** com o ícone de lupa 2. Digite o nome ou parte do nome da macro desejada 3. A tabela de macros será atualizada automaticamente conforme o termo digitado, mostrando apenas as macros que correspondem à busca Barra de pesquisa de macros destacada com termo de busca digitado A busca é realizada em tempo real, facilitando a localização de macros específicas quando há muitas cadastradas. *** ## Criando uma Nova Macro Existem duas formas de iniciar a criação de uma nova macro: ### Opção 1: Botão no Cabeçalho 1. Clique no botão verde **"+ New Macro"** localizado no canto superior direito da tela ### Opção 2: Botão no Estado Vazio Quando não há macros criadas, clique no botão verde **"New Macro"** no centro da tela. Estado vazio de macros com botões New Macro destacados ### Preenchendo o Formulário de Criação Após clicar em qualquer um dos botões, um modal será exibido com fundo escuro contendo: * **Título:** **"New Macro"** no topo do modal * **Botão de Fechar:** Um ícone "X" no canto superior direito para fechar o modal sem salvar Modal de criação de nova macro com todos os campos destacados No formulário, preencha os seguintes campos: #### 1. Nome (Obrigatório) * **Campo:** **Name** (marcado com asterisco `*` indicando campo obrigatório) * **Tipo:** Campo de texto simples * **Descrição:** Nome identificador da macro * **Exemplo:** "Commercial Leader", "Atribuir Equipe de Vendas", "Resposta Padrão" * **Recomendação:** Use nomes descritivos que indiquem claramente o propósito da macro * **Localização:** Primeiro campo do formulário #### 2. Visibilidade * **Campo:** **Visibility** * **Tipo:** Seleção de opção (radio buttons) * **Descrição:** Define quem pode usar esta macro * **Opções disponíveis:** **Private (Privada):** * **Ícone:** Cadeado (lock icon) * **Descrição:** "This macro will be private and available only to you" * **Comportamento:** A macro será visível e utilizável apenas por você * **Recomendação:** Use para macros pessoais ou específicas do seu trabalho **Public (Pública):** * **Ícone:** Globo (globe icon) * **Descrição:** "This macro will be public and available to all agents" * **Comportamento:** A macro será visível e utilizável por todos os agentes do sistema * **Recomendação:** Use para macros que padronizam processos da equipe * **Seleção:** A opção selecionada fica destacada com uma borda verde * **Padrão:** Private (Privada) é selecionada por padrão * **Localização:** Segundo campo do formulário, abaixo do campo Name #### 3. Ações * **Campo:** **Actions** * **Tipo:** Lista de ações configuráveis * **Descrição:** Define a sequência de ações que a macro executará * **Texto Explicativo:** "Macros will execute actions in the defined order" - indica que as ações serão executadas na ordem em que são definidas * **Botão de Adicionar:** **"+ Add Action"** localizado no canto direito do cabeçalho da seção, permite adicionar novas ações à macro **Configurando uma Ação:** Cada ação possui dois componentes principais: 1. **Action (Ação):** * **Tipo:** Dropdown/Select * **Descrição:** Tipo de ação a ser executada * **Exemplo:** "Atribuir equipe" (Assign team) * **Texto de Ajuda:** Abaixo da seleção, aparece uma descrição explicativa da ação selecionada (ex: "Atribui a conversa a uma equipe específica") * **Localização:** Primeiro campo de cada ação 2. **Configuration (Configuração):** * **Tipo:** Dropdown/Select * **Descrição:** Parâmetros específicos para a ação selecionada * **Placeholder:** "Select an option" quando nenhuma opção foi selecionada * **Comportamento:** As opções disponíveis dependem da ação selecionada * **Exemplo:** Se a ação for "Atribuir equipe", a configuração permitirá selecionar qual equipe será atribuída * **Localização:** Segundo campo de cada ação, ao lado do campo Action **Tipos de Ações Disponíveis:** * **Atribuir equipe (Assign team):** Atribui a conversa a uma equipe específica * Outras ações podem estar disponíveis dependendo das funcionalidades do sistema **Adicionando Múltiplas Ações:** 1. Clique no botão **"+ Add Action"** para adicionar uma nova ação à sequência 2. Configure a ação e sua configuração 3. Repita o processo para adicionar quantas ações forem necessárias 4. As ações serão executadas na ordem em que aparecem na lista (de cima para baixo) * **Localização:** Terceiro campo do formulário, abaixo da seção Visibility ### Finalizando a Criação Na parte inferior do modal, há dois botões de ação: * **Cancel:** Botão cinza escuro com texto branco, localizado à esquerda * **Create:** Botão verde/turquesa brilhante com texto branco, localizado à direita Após preencher os campos desejados: 1. Revise as informações inseridas, especialmente o nome, visibilidade e a sequência de ações 2. Certifique-se de que todas as ações têm suas configurações preenchidas corretamente 3. Clique no botão verde **"Create"** para criar a macro 4. Ou clique em **"Cancel"** para fechar o modal sem salvar 5. Alternativamente, clique no ícone "X" no canto superior direito para fechar sem salvar A macro será criada e aparecerá imediatamente na tabela de macros. *** ## Visualizando Macros na Tabela Após criar macros, elas serão exibidas em uma tabela com as seguintes colunas: ### Colunas da Tabela * **Name:** Nome da macro (ordenável - indicado por seta para cima/baixo) * Exibe o nome descritivo da macro (ex: "Commercial Leader") * Abaixo do nome, exibe o número de ações configuradas (ex: "1 action") * **Created by:** Criador da macro * Exibe o nome do usuário que criou a macro ou um traço ("-") se não houver informação disponível * **Updated by:** Último usuário que atualizou a macro * Exibe o nome do usuário que atualizou a macro ou um traço ("-") se não houver informação disponível * **Visibility:** Visibilidade da macro * Exibe um ícone de cadeado seguido de "Private" em texto azul para macros privadas * Exibe um ícone de globo seguido de "Public" para macros públicas * **ID:** Identificador único da macro (ordenável - indicado por seta para cima/baixo) * Exibe o UUID da macro (ex: "5d83859d-3d52-4a26-a14f-27c63c868be5") * **Actions:** Menu de ações para gerenciar a macro * Ícone de três pontos verticais (`...`) que abre um menu dropdown com opções ### Funcionalidades da Tabela * **Ordenação:** Clique nos cabeçalhos das colunas "Name" ou "ID" para ordenar a tabela em ordem crescente ou decrescente * **Busca Integrada:** A barra de pesquisa acima da tabela filtra os resultados em tempo real * **Visualização de Ações:** O número de ações configuradas é exibido abaixo do nome da macro, facilitando a identificação rápida da complexidade da macro *** ## Visualizando uma Macro Para visualizar os detalhes completos de uma macro: 1. Na tabela de macros, localize a macro que deseja visualizar 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente à macro 3. Um menu dropdown será exibido com as opções disponíveis Menu de ações da macro destacado - opções View, Execute, Edit e Delete 4. No menu dropdown, clique em **View** (acompanhado de um ícone de olho) Uma tela ou modal será exibido mostrando os detalhes completos da macro, incluindo todas as ações configuradas e suas respectivas configurações. *** ## Executando uma Macro Para executar uma macro manualmente: 1. Na tabela de macros, localize a macro que deseja executar 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente à macro 3. Um menu dropdown será exibido com as opções disponíveis 4. No menu dropdown, clique em **Execute** (acompanhado de um ícone de play/triângulo) A macro será executada imediatamente, realizando todas as ações configuradas na ordem definida. **Atenção:** Certifique-se de que você está no contexto correto (por exemplo, uma conversa específica) antes de executar a macro, pois as ações serão aplicadas ao contexto atual. *** ## Editando uma Macro Para modificar uma macro existente: 1. Na tabela de macros, localize a macro que deseja editar 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente à macro 3. Um menu dropdown será exibido com as opções disponíveis 4. No menu dropdown, clique em **Edit** (acompanhado de um ícone de lápis) 5. Um modal semelhante ao de criação será aberto, mas com o título **"Edit Macro"** e os campos já preenchidos com os valores atuais da macro 6. Modifique os campos desejados: * Nome * Visibilidade (Private/Public) * Ações (adicione, remova ou reordene ações conforme necessário) * Configurações de cada ação 7. Revise as alterações 8. Clique no botão verde **"Update"** ou **"Save"** para salvar as alterações 9. Ou clique em **"Cancel"** para descartar as alterações As alterações serão aplicadas imediatamente e refletidas na tabela de macros. **Nota:** Ao editar uma macro pública, as alterações afetarão todos os usuários que têm acesso à macro. Considere criar uma nova macro se precisar de uma versão diferente para uso pessoal. *** ## Excluindo uma Macro Para remover uma macro: 1. Na tabela de macros, localize a macro que deseja excluir 2. Na coluna **Actions**, clique no ícone de três pontos (`...`) correspondente à macro 3. Um menu dropdown será exibido com as opções disponíveis 4. No menu dropdown, clique em **Delete** (acompanhado de um ícone de lixeira, exibido em texto vermelho para indicar uma ação destrutiva) 5. Um diálogo de confirmação será exibido 6. Confirme a exclusão no diálogo que aparecer **Atenção:** * A exclusão de uma macro é permanente e não pode ser desfeita * Se a macro for pública, todos os agentes perderão acesso a ela após a exclusão * Verifique se não há processos ou usuários dependendo desta macro antes de excluí-la * Considere desativar ou tornar a macro privada em vez de excluí-la se houver dúvidas sobre seu uso futuro *** ## Considerações Finais * **Nomenclatura Clara:** Use nomes descritivos e claros para que todos os membros da equipe entendam o propósito de cada macro * **Ordem das Ações:** Lembre-se de que as ações são executadas na ordem em que são definidas. Planeje a sequência cuidadosamente para garantir o resultado desejado * **Visibilidade:** Use macros privadas para processos pessoais e macros públicas para padronizar processos da equipe * **Teste Antes de Compartilhar:** Teste macros públicas antes de disponibilizá-las para toda a equipe, garantindo que funcionam corretamente * **Documentação:** Considere usar nomes descritivos que funcionem como documentação do processo automatizado * **Revisão Regular:** Revise periodicamente as macros existentes para garantir que continuam relevantes e funcionando corretamente * **Reutilização:** Crie macros para tarefas que são realizadas frequentemente, maximizando o ganho de eficiência * **Configurações Corretas:** Certifique-se de que todas as ações têm suas configurações preenchidas corretamente antes de criar ou atualizar uma macro As macros são uma ferramenta poderosa para automatizar tarefas repetitivas, economizando tempo da equipe e garantindo consistência nas operações realizadas no sistema. O uso adequado de macros pode aumentar significativamente a produtividade e a padronização dos processos de trabalho. # Equipes Source: https://docs.evolutionfoundation.com.br/user-guides/settings/teams As Equipes permitem que você organize seus agentes em grupos lógicos para melhor gestão e atribuição automática de conversas. Você pode criar equipes como "Vendas", "Suporte" ou "Financeiro" e associar agentes específicos a cada uma delas. ## Acessando Equipes Para acessar a gestão de equipes, siga os passos abaixo: 1. No menu lateral esquerdo, clique em **Settings** (Configurações). 2. No submenu que se abre, clique em **Teams** (Equipes). Tela Inicial de Equipes *** ## Criando uma Nova Equipe Para criar uma estrutura organizacional: 1. Clique no botão **+ New Team** no canto superior direito ou no centro da tela (caso não existam equipes). 2. Na janela que se abre (**Create New Team**), preencha: * **Team Name (Nome da Equipe):** Ex: Vendas, Suporte ao Cliente. * **Description (Descrição):** Descreva o propósito e as responsabilidades desta equipe. * **Auto-assignment of conversations (Atribuição Automática):** Habilite o interruptor se deseja que conversas enviadas a esta equipe sejam distribuídas automaticamente entre os membros. 3. Clique em **Create Team**. Criar Nova Equipe *** ## Gerenciando Equipes Após criadas, as equipes aparecem em formato de cards ou lista, onde você pode: * **Pesquisar:** Encontrar equipes pelo nome usando a barra de busca no topo. Barra de Busca de Equipes * **Visualização de Membros:** O card exibe a quantidade de agentes vinculados. * **Auto-assignment:** Um indicador mostra se a atribuição automática está ativa para aquela equipe. *** ## Ações e Membros Cada card de equipe possui botões de ação na parte inferior: * **Users (Usuários):** Clique para gerenciar quais agentes pertencem a esta equipe. * **Edit (Editar):** Altere o nome, descrição ou configurações de atribuição. * **Delete (Excluir):** Remove permanentemente a equipe (ícone de lixeira em vermelho). Ações da Equipe *** ## Considerações Finais A organização por equipes facilita o direcionamento correto das conversas (via regras de automação ou escolha manual no widget) e melhora as métricas de desempenho por departamento. # Bundles de Configuração Source: https://docs.evolutionfoundation.com.br/user-guides/settings/template-bundles A funcionalidade **Bundles de Configuração** permite exportar e importar a configuração da sua instalação como um arquivo ZIP portável. É útil para migrar entre ambientes (staging → produção), replicar setups entre clientes ou criar templates de instalação reutilizáveis. > Disponível a partir do `v1.0.0-rc3` (EVO-1116). ### O que vai dentro de um Bundle? Um bundle inclui (quando você marca cada categoria no wizard de export): * **Inboxes** — canais conectados (configuração, sem credenciais sensíveis). * **Agentes de IA** — prompts, ferramentas, configurações de modelo. * **Automation rules** — regras `trigger → action`. * **Respostas prontas (canned responses)**. * **Templates de mensagem** — incluindo variáveis declaradas. * **Funções personalizadas** — papéis customizados com permissões. > **O que NÃO vai:** credenciais (tokens, senhas, API keys), dados de conversa, contatos, histórico. Bundles são **configuração**, não dados de operação. *** ## Acessando `Configurações → Templates / Bundles` (a entrada aparece se você tiver permissão `template_bundles.read` ou `template_bundles.manage`). *** ## Exportando um Bundle 1. Clique em **Exportar Bundle**. 2. No wizard, marque as categorias que deseja incluir. Cada categoria expõe a lista de itens disponíveis — você pode escolher exportar tudo ou apenas alguns itens específicos. 3. Confirme. O sistema gera um ZIP com a estrutura interna do bundle. 4. Faça o download. O nome padrão é `bundle-{instalação}-{data}.zip`. Você pode renomear livremente após o download. ### O que esperar * Bundles pequenos (apenas templates e canned responses) saem rápido. * Bundles grandes (todos os agentes + automation rules) podem levar alguns segundos. * Não há limite duro de tamanho, mas mantenha bundles focados (não exporte tudo se você só precisa migrar um agente). *** ## Importando um Bundle 1. Clique em **Importar Bundle**. 2. Selecione o arquivo ZIP. 3. O sistema valida o conteúdo e mostra preview do que será importado. 4. Você decide o que **importar**, **sobrescrever** ou **ignorar** item a item. 5. Confirme. ### Comportamento em caso de conflito Quando um item do bundle já existe na instalação de destino (mesmo nome / mesmo identificador): * **Importar como novo:** cria com sufixo para evitar colisão (ex.: `Boas-vindas (importado)`). * **Sobrescrever:** substitui o existente. Use com cuidado em produção. * **Ignorar:** pula esse item específico, mas segue com o resto do bundle. > Não há rollback automático após confirmar o import. Faça backup do banco antes de importar em produção. *** ## Casos de Uso ### 1. Staging → Produção Você ajusta agentes e automations em staging, valida com a equipe e exporta um bundle. Em produção, importa sobrescrevendo apenas os itens validados. ### 2. Template de instalação Você mantém um bundle "template padrão" com automations e canned responses que toda nova instalação deve ter. Ao subir uma nova instância, basta importar. ### 3. Migração entre clientes (multi-tenant) Empresas que prestam serviço de implantação podem ter um catálogo de bundles por vertical (varejo, saúde, educação) e importar o relevante ao iniciar um cliente. *** ## Permissões | Permissão | O que permite | | ------------------------- | --------------------------------------------------- | | `template_bundles.read` | Ver bundles disponíveis e baixar exports anteriores | | `template_bundles.manage` | Criar exports, importar bundles novos | Por padrão apenas o `account_owner` recebe `manage`. Conceda a outros papéis com cuidado — `manage` permite sobrescrever configuração crítica. *** ## Limitações conhecidas * **Credenciais não viajam.** Após importar um inbox WhatsApp, você precisa reconectar o canal manualmente (o token de instância não está no bundle). * **Referências cruzadas.** Se um agente referencia um Knowledge Nexus space que não existe no destino, o agente é importado mas a referência fica quebrada (visível na UI como "space não encontrado"). Configure os spaces no destino antes de importar. * **Versões de schema.** Bundles exportados em versões diferentes do CRM podem precisar de adaptação. Mantenha staging e produção próximos em versão. *** ## Considerações Finais Bundles são a forma recomendada de **mover configuração** entre instalações do CRM Community. Para mover **dados** (contatos, conversas), use as funcionalidades específicas de import/export de cada módulo. # Usuários Source: https://docs.evolutionfoundation.com.br/user-guides/settings/users A seção de Usuários permite que você gerencie todos os agentes e administradores com acesso à sua conta. Aqui você pode convidar novos membros, definir níveis de permissão (funções), exportar dados de usuários e realizar convites em massa. ## Acessando a Gestão de Usuários 1. No menu lateral, clique em **Settings** (Configurações). 2. Selecione a opção **Users** (Usuários). Tela Principal de Usuários *** ## Pesquisando e Filtrando Usuários A plataforma oferece ferramentas para localizar membros da equipe de forma ágil: * **Busca Direta:** Utilize a barra de pesquisa no topo para filtrar por nome ou e-mail. * **Filtros Avançados:** Utilize o botão de filtros para critérios mais complexos. Barra de Pesquisa de Usuários Filtros de Usuários *** ## Criando um Novo Usuário Para adicionar um membro individualmente à sua equipe: 1. Clique no botão **+ New User** no canto superior direito. Botão Novo Usuário 2. Preencha os campos obrigatórios no formulário: * **Name (Nome):** Nome completo do colaborador. * **Email:** O endereço de e-mail que será usado para login. * **Role (Função):** Define o nível de acesso (Ex: Account Administrator, Agent). * **Availability Status (Status de Disponibilidade):** Define se o usuário inicia como Online, Offline ou Busy. * **Password (Senha):** Defina uma senha inicial e confirme no campo abaixo. 3. Clique em **Create User** para finalizar. Formulário de Novo Usuário *** ## Convite em Massa (Bulk Invite) Esta funcionalidade é ideal para adicionar grandes equipes de uma só vez. 1. Clique no botão **Bulk Invite**. Botão Convite em Massa 2. No modal que será exibido: * Cole a lista de e-mails, um por linha ou separados por vírgula. * O sistema removerá e-mails duplicados automaticamente. * Os usuários receberão um e-mail de convite para criar suas contas. 3. Clique em **Send Invites**. Modal de Convite em Massa *** ## Exportando Dados Você pode gerar um arquivo com a lista de todos os usuários da conta para fins de auditoria ou gestão externa. 1. Clique no botão **Export** localizado no cabeçalho da página. 2. O sistema processará o download dos dados dos usuários. Botão Exportar *** ## Considerações Finais Lembre-se de revisar as funções (Roles) atribuídas a cada usuário para garantir que cada membro da equipe tenha apenas o acesso necessário para realizar seu trabalho. # Creating agents Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/creating-agents Esta página ainda está em inglês. A tradução para português está em andamento. # Creating a Custom Agent This guide walks through creating a new agent from scratch. > **Quick method:** Use the `create-agent` skill — it guides you through the process interactively. Just say "create an agent" or "new agent" in Claude Code. ## Core vs Custom Agents | | Core | Custom | | ------------- | ------------------------------- | --------------------------------------- | | **Location** | `.claude/agents/{name}.md` | `.claude/agents/custom-{name}.md` | | **Git** | Tracked (ships with repo) | Gitignored (personal to your workspace) | | **Dashboard** | Green "core" badge | Gray "custom" badge | | **Examples** | clawdia-assistant, flux-finance | custom-devops, custom-support | Custom agents use the `custom-` prefix, which triggers gitignore rules so they stay personal to your workspace. The dashboard auto-discovers them and shows them alongside core agents. ## File Structure An agent requires two files: ``` .claude/ agents/custom-my-agent.md # System prompt + frontmatter commands/custom-my-agent.md # Slash command definition ``` ## Step 1: Agent File Create `.claude/agents/my-agent.md` with YAML frontmatter followed by the system prompt. ### Frontmatter Format ```yaml theme={null} --- name: "my-agent" description: "Use this agent when... (routing description with examples)" model: sonnet color: green memory: project --- ``` | Field | Required | Description | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------- | | `name` | Yes | Unique identifier, matches filename without `.md` | | `description` | Yes | Routing description. Claude uses this to decide when to activate the agent. Include example user messages. | | `model` | Yes | Model to use: `sonnet`, `opus`, `haiku` | | `color` | No | Terminal color for the agent label | | `memory` | No | Memory scope: `project` (shared) or `user` (personal) | ### Description Field (Important) The `description` field controls auto-routing. It should include concrete examples of user messages that should trigger this agent: ```yaml theme={null} description: "Use this agent when the user needs help with customer support tickets, bug reports, or user complaints.\n\nExamples:\n\n- user: \"check support tickets\"\n assistant: \"I will use the support agent to review open tickets.\"\n\n- user: \"a customer reported a bug\"\n assistant: \"I will activate the support agent to investigate.\"" ``` ## Step 2: System Prompt Below the frontmatter, write the system prompt. This defines the agent's identity and behavior. ```markdown theme={null} --- name: "support-agent" description: "Use this agent when..." model: sonnet color: yellow memory: project --- You are **Support** — the customer support specialist. Direct, empathetic, and solution-oriented. ## Responsibilities 1. **Ticket Triage**: Review and prioritize support tickets 2. **Bug Investigation**: Reproduce and document reported bugs 3. **Customer Communication**: Draft professional responses ## Before Starting - Read `workspace/support/overview.md` for current context - Check recent tickets in the support system ## Working Standards - Save files to `workspace/support/` with `[C]` prefix - Always include ticket ID when referencing issues - Escalate critical issues immediately ``` ## Step 3: Command File Create `.claude/commands/my-agent.md`: ```markdown theme={null} Use the @support-agent agent to help the user with the following support matter: $ARGUMENTS If no arguments were provided, ask the user how you can help (ticket triage, bug investigation, customer responses, etc). ``` The `$ARGUMENTS` placeholder passes whatever the user types after the slash command. ## Step 4: Agent Memory Directory The memory directory at `.claude/agent-memory//` is created automatically when the agent first saves a memory. No manual setup needed. If you want to pre-populate memory, create the directory and add a `MEMORY.md` index file: ```bash theme={null} mkdir -p .claude/agent-memory/support-agent echo "" > .claude/agent-memory/support-agent/MEMORY.md ``` ## Best Practices for System Prompts ### Do * **Define identity clearly** in the first line: name, role, tone * **List specific responsibilities** so the agent knows its scope * **Set anti-patterns** — things the agent should never do * **Point to context files** the agent should read before starting * **Specify output locations** — which folder, what file prefix * **Include memory instructions** to build knowledge over time ### Don't * Write prompts longer than 300 lines (agent + memory boilerplate) * Overlap responsibilities with existing agents * Include API keys or secrets in the prompt * Make the agent too generic — specialization is the point ## Full Example: Support Agent `.claude/agents/support-agent.md`: ```markdown theme={null} --- name: "support-agent" description: "Use this agent when the user needs help with customer support, bug reports, user complaints, or ticket management.\n\nExamples:\n\n- user: \"check support tickets\"\n assistant: \"I will use the support agent to review open tickets.\"\n\n- user: \"a customer is having issues with login\"\n assistant: \"I will activate the support agent to investigate.\"" model: sonnet color: yellow memory: project --- You are **Support** — the customer support specialist. Direct, empathetic, solution-oriented. ## Identity - Name: Support - Tone: professional, empathetic, concise - Language: English ## Responsibilities 1. **Ticket Triage**: Review open tickets, prioritize by severity 2. **Bug Investigation**: Reproduce issues, document steps, identify root cause 3. **Response Drafting**: Write customer-facing responses 4. **Escalation**: Flag critical issues to the team ## Before Starting - Read `workspace/support/overview.md` for context - Check `.claude/agent-memory/support-agent/` for prior context ## Working Standards - Files go in `workspace/support/` with `[C]` prefix - Reference ticket IDs in all outputs - Classify severity: P0 (critical), P1 (high), P2 (medium), P3 (low) ## Anti-patterns - Never promise timelines without checking with the team - Never share internal details with customers - Never close tickets without confirmation **Update your agent memory** when you discover recurring issues, customer patterns, or resolution workflows. ``` `.claude/commands/support.md`: ```markdown theme={null} Use the @support-agent agent to help the user with the following support matter: $ARGUMENTS If no arguments were provided, ask the user how you can help (ticket triage, bug reports, customer responses, etc). ``` After creating both files, the agent is immediately available via `/support` in Claude Code. # Visão Geral dos Agentes Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/overview 38 agentes especializados em duas camadas — negócio e engenharia # Visão Geral dos Agentes Agentes são o núcleo do EvoNexus. Cada agente é uma persona de IA especializada com seu próprio domínio, system prompt, skills e memória persistente. O EvoNexus organiza os agentes em **duas camadas ortogonais**: * **Business Layer (17 agentes)** — operações, finanças, comunidade, marketing, RH, jurídico, produto, dados, vendas, retenção de aprendizado. Construída e mantida pelo EvoNexus. * **Engineering Layer (21 agentes)** — desenvolvimento de software, code review, testes, debugging, segurança, design, orquestração de ciclo, retrospectiva. 19 derivados do [oh-my-claudecode](https://github.com/yeachan-heo/oh-my-claudecode) (MIT, por Yeachan Heo) + 2 nativos (Helm, Mirror). Segue um workflow canônico de 6 fases. Veja [Engineering Layer](engineering-layer) para detalhes. As duas camadas são independentes — tarefas de negócio vão para agentes de negócio, tarefas de engenharia para agentes de engenharia — mas handoffs entre camadas são comuns (ex.: `@nova` escreve um PRD → `@apex-architect` faz o review de arquitetura → `@bolt-executor` implementa → `@mirror-retro` captura lições). **Total: 38 agentes** + agentes customizados que você criar. ## O que é um Agente? Um agente é um arquivo markdown em `.claude/agents/` que contém: * **Frontmatter** com metadados (name, description, model, color, memory scope) * **System prompt** que define a identidade, responsabilidades, tom e comportamento do agente Quando invocado, o Claude Code carrega o system prompt do agente e opera dentro dessa persona durante a tarefa. ## Como Invocar um Agente ### Slash commands Cada agente tem um comando correspondente em `.claude/commands/`: **Business Layer (17):** ``` /clawdia-assistant — Hub de ops: agenda, e-mails, tarefas, decisões /flux-finance — Finanças: Stripe, ERP, fluxo de caixa, relatórios /atlas-project — Projetos: Linear, GitHub, sprints, milestones /pulse-community — Comunidade: Discord, WhatsApp, sentimento, FAQ /pixel-social-media — Redes sociais: conteúdo, calendário, analytics /sage-strategy — Estratégia: OKRs, roadmap, análise competitiva /nex-sales — Vendas: pipeline, propostas, qualificação /mentor-courses — Cursos: trilhas de aprendizado, módulos /lumen-learning — Retenção de aprendizado: repetição espaçada, captura de fatos, quizzes /kai-personal-assistant — Pessoal: saúde, hábitos, rotina /oracle — Conhecimento do workspace: docs, how-to, configuração /mako-marketing — Marketing: campanhas, SEO, e-mail, marca /aria-hr — RH / Pessoas: recrutamento, onboarding, desempenho /zara-cs — Customer Success: triagem, escalação, KB /lex-legal — Jurídico / Compliance: contratos, NDA, LGPD /nova-product — Produto: specs, roadmaps, métricas, pesquisa /dex-data — Dados / BI: análise, SQL, dashboards ``` **Engineering Layer (19):** ``` /apex-architect — Architect: design, debugging, tradeoffs (READ-ONLY) /echo-analyst — Analyst: discovery, gap analysis (READ-ONLY) /compass-planner — Planner: planos de 3-6 passos guiados por entrevista /raven-critic — Critic: revisão adversarial multi-perspectiva (READ-ONLY) /bolt-executor — Executor: implementação no menor diff viável /hawk-debugger — Debugger: causa-raiz, erros de build /lens-reviewer — Code reviewer: 2 estágios, OWASP, SOLID (READ-ONLY) /zen-simplifier — Simplificador de código: refactor sem mudar comportamento /vault-security — Security: OWASP Top 10, secrets, deps (READ-ONLY) /grid-tester — Test engineer: TDD, pirâmide, diagnóstico de flakiness /probe-qa — QA tester: sessões interativas em tmux /oath-verifier — Verifier: completude baseada em evidência (READ-ONLY) /trail-tracer — Tracer: investigação causal com hipóteses /scout-explorer — Explorer: busca paralela no codebase (READ-ONLY) /flow-git — Git master: commits atômicos, rebase seguro /scroll-docs — Document specialist: docs externas de SDK/API (READ-ONLY) /quill-writer — Writer: docs técnicos com exemplos verificados /canvas-designer — Designer: UI/UX em qualidade de produção /prism-scientist — Scientist: análise estatística formal ``` Uso no Claude Code: ``` /clawdia-assistant ver meus e-mails /flux-finance qual é a saúde financeira da empresa? /apex-architect por que o bot runtime está travando no reconnect? /dev-autopilot construa uma API CRUD para inventário de livraria ``` ### Roteamento automático Você não precisa escolher o agente certo manualmente. Apenas descreva o que precisa e o Claude roteia ao agente correto com base no campo `description` do frontmatter de cada agente. Exemplos: | Você diz | Agente ativado | | ---------------------------------------- | -------------- | | "bom dia" | Clawdia | | "fechamento mensal" | Flux | | "ver PRs do github" | Atlas | | "sentimento da comunidade" | Pulse | | "escrever um post no LinkedIn" | Pixel | | "devemos priorizar X ou Y?" | Sage | | "preparar uma proposta para o cliente Z" | Nex | | "criar um módulo de curso" | Mentor | | "como está minha saúde?" | Kai | A lógica de roteamento usa interações de exemplo no campo `description` de cada agente para casar com a intenção do usuário. ## Memória dos Agentes Todo agente tem memória persistente baseada em arquivos em: ``` .claude/agent-memory// ``` Memória organizada por tipo: | Tipo | Propósito | | ----------- | --------------------------------------- | | `user` | Quem é o usuário, papel, preferências | | `feedback` | Correções e abordagens confirmadas | | `project` | Trabalho em andamento, prazos, decisões | | `reference` | Ponteiros para sistemas externos | Cada arquivo de memória usa frontmatter (`name`, `description`, `type`) e um arquivo `MEMORY.md` indexa todas as entradas. Os agentes leem a memória no início de cada sessão e a atualizam conforme aprendem. ## Agentes Customizados Você pode criar seus próprios agentes com o prefixo `custom-`. Agentes customizados são gitignored (pessoais ao seu workspace) e aparecem no dashboard com um badge "custom" cinza. Para criar um agente custom, use a skill `create-agent` ou veja [Criando Agentes](creating-agents). ``` .claude/agents/custom-devops.md # Prompt do agente .claude/commands/custom-devops.md # Slash command .claude/agent-memory/custom-devops/ # Memória persistente ``` ## Business Layer — 17 Agentes Core | Agente | Comando | Domínio | Cor | | ---------------------- | ------------------------- | ----------------------------------------------------------------------------- | ------ | | [**Clawdia**](clawdia) | `/clawdia-assistant` | Ops: agenda, e-mails, tarefas, reuniões, decisões | cyan | | [**Flux**](flux) | `/flux-finance` | Finanças: Stripe, Omie, fluxo de caixa, fechamento mensal | orange | | [**Atlas**](atlas) | `/atlas-project` | Projetos: Linear, GitHub, sprints, licenciamento | green | | [**Pulse**](pulse) | `/pulse-community` | Comunidade: Discord, WhatsApp, sentimento, FAQ | blue | | [**Pixel**](pixel) | `/pixel-social-media` | Social: conteúdo, calendário, analytics multiplataforma | yellow | | [**Sage**](sage) | `/sage-strategy` | Estratégia: OKRs, roadmap, análise competitiva | orange | | [**Nex**](nex) | `/nex-sales` | Vendas: pipeline, propostas, qualificação | red | | [**Mentor**](mentor) | `/mentor-courses` | Cursos: trilhas, módulos, academy | purple | | **Lumen** | `/lumen-learning` | Retenção de aprendizado: repetição espaçada (SM-2), captura de fatos, quizzes | yellow | | [**Kai**](kai) | `/kai-personal-assistant` | Pessoal: saúde, hábitos, rotina (isolado) | blue | | [**Oracle**](oracle) | `/oracle` | Conhecimento do workspace: docs, how-to, configuração | amber | | [**Mako**](mako) | `/mako-marketing` | Marketing: campanhas, SEO, sequências de e-mail, marca | orange | | [**Aria**](aria) | `/aria-hr` | RH / Pessoas: recrutamento, onboarding, desempenho | pink | | [**Zara**](zara) | `/zara-cs` | Customer Success: triagem, escalação, health scores | cyan | | [**Lex**](lex) | `/lex-legal` | Jurídico / Compliance: contratos, NDA, LGPD, risco | purple | | [**Nova**](nova) | `/nova-product` | Produto: specs, roadmaps, métricas, pesquisa | blue | | [**Dex**](dex) | `/dex-data` | Dados / BI: análise, SQL, dashboards, visualizações | yellow | ## Engineering Layer — 19 Agentes Especialistas em desenvolvimento de software. Cada agente tem um papel específico no workflow de dev: design, planejamento, implementação, review, testes, debugging, verificação. ### Reasoning (opus) | Agente | Comando | Papel | | ----------- | ------------------ | --------------------------------------------------------------------- | | **Apex** | `/apex-architect` | Architect — design arquitetural, debugging read-only, tradeoffs | | **Echo** | `/echo-analyst` | Analyst — discovery, gaps de requisitos, premissas escondidas | | **Compass** | `/compass-planner` | Planner — planejamento tático de 3-6 passos com entrevista | | **Raven** | `/raven-critic` | Critic — desafia planos antes da execução, multi-perspectiva | | **Lens** | `/lens-reviewer` | Code Reviewer — review em 2 estágios (spec + qualidade), OWASP, SOLID | | **Zen** | `/zen-simplifier` | Simplificador de código — deslop, refactoring, clareza | | **Vault** | `/vault-security` | Security Reviewer — OWASP Top 10, secrets, auditoria de dependências | ### Execution (sonnet) | Agente | Comando | Papel | | ---------- | ------------------ | ----------------------------------------------------------- | | **Bolt** | `/bolt-executor` | Executor — implementação precisa em múltiplos arquivos | | **Hawk** | `/hawk-debugger` | Debugger — causa-raiz, regressões, stack traces | | **Grid** | `/grid-tester` | Test Engineer — TDD, estratégia em pirâmide, cobertura | | **Probe** | `/probe-qa` | QA Tester — testes interativos, diagnóstico de flakiness | | **Oath** | `/oath-verifier` | Verifier — verificação de conclusão baseada em evidências | | **Trail** | `/trail-tracer` | Tracer — tracing causal, hipóteses competindo | | **Flow** | `/flow-git` | Git Master — commits atômicos, rebase, limpeza de histórico | | **Scroll** | `/scroll-docs` | Document Specialist — docs externas (SDKs, APIs) via web | | **Canvas** | `/canvas-designer` | Designer — UI/UX para produto (Evo CRM, dashboards) | | **Prism** | `/prism-scientist` | Scientist — análise estatística formal, teste de hipóteses | ### Speed (haiku) | Agente | Comando | Papel | | --------- | ----------------- | --------------------------------------------------- | | **Scout** | `/scout-explorer` | Explorer — busca paralela no codebase (Glob/Grep) | | **Quill** | `/quill-writer` | Writer — docs técnicos rápidos, README, comentários | Veja a página dedicada [Engineering Layer](engineering-layer) para pipelines, atribuições e workflows detalhados. ### Detalhes dos Papéis dos Agentes **Clawdia** é o agente padrão e o hub operacional. Briefings da manhã, triagem de e-mail, gestão de tarefas, resumos de reunião e consolidação de fim de dia passam todos pela Clawdia. **Flux** atua como CFO virtual. Consulta o Stripe para MRR/churn e o Omie para contas a pagar/receber, gera relatórios financeiros e gerencia o fechamento mensal. **Atlas** acompanha trabalho de desenvolvimento no Linear e GitHub. Status de sprint, reviews de PR, acompanhamento de issues e telemetria de licenciamento open source são seu domínio. **Pulse** monitora a saúde da comunidade no Discord e WhatsApp. Gera relatórios de pulso diários/semanais/mensais, acompanha sentimento, identifica perguntas recorrentes e mantém o FAQ. **Pixel** gerencia redes sociais no YouTube, Instagram e LinkedIn. Criação de conteúdo, planejamento de calendário, analytics multiplataforma e acompanhamento de engajamento. **Sage** lida com estratégia de alto nível. Reviews de OKR, análise competitiva, digests de estratégia e frameworks de decisão. **Nex** gerencia o pipeline de vendas. Qualificação de leads, propostas e workflows comerciais. **Mentor** lida com a plataforma de cursos (Evo Academy). Trilhas de aprendizado, criação de módulos e conteúdo educacional. **Kai** é o assistente pessoal com domínio isolado. Acompanhamento de saúde, hábitos, compromissos pessoais e rotinas. Não lida com assuntos profissionais. **Oracle** é o agente do conhecimento do workspace. Responde perguntas sobre como o EvoNexus funciona — agentes, skills, rotinas, integrações, dashboard, configuração e arquitetura — lendo a documentação real antes de responder. Sem RAG ou banco vetorial. **Mako** lida com marketing. Planejamento de campanhas, criação de conteúdo, reviews de marca, auditorias de SEO, sequências de e-mail e relatórios de performance. **Aria** gerencia RH e Operações de Pessoas. Pipeline de recrutamento, performance reviews, checklists de onboarding, análise de comp e planejamento organizacional. **Zara** lida com customer success. Triagem de tickets, empacotamento de escalações, pesquisa de cliente, drafts de resposta e artigos de KB. **Lex** gerencia jurídico e compliance. Review de contratos, triagem de NDA, checagens de LGPD, análise de risco e briefs jurídicos. **Nova** lida com gestão de produto. Specs/PRDs, reviews de métricas, atualizações de roadmap, brainstorms e updates para stakeholders. **Dex** é o agente de dados e BI. Análise de dados, queries SQL, dashboards interativos, análise estatística e validação de dados. **Lumen** é o agente de retenção de conhecimento. Captura fatos atômicos a partir de conteúdo colado, executa sessões de revisão por repetição espaçada SM-2, gera quizzes de prática de recuperação e reporta métricas de retenção por deck. Use Lumen para fixar o que você lê — Mentor cria conteúdo de aprendizado, Lumen faz colar. ## Skills Pré-carregadas Cada agente tem um campo `skills` no frontmatter que pré-carrega skills específicas do domínio no contexto do agente na inicialização. Isso significa que o agente não precisa descobrir ou carregar skills durante a execução — elas estão imediatamente disponíveis. ```yaml theme={null} --- name: "flux-finance" skills: - fin-daily-pulse - fin-weekly-report - int-stripe - int-omie --- ``` ## Agent Teams (Experimental) Para tarefas de consolidação que cobrem múltiplos domínios (digest de estratégia, dashboard, weekly review), os Agent Teams podem rodar agentes específicos de domínio em paralelo. Cada teammate coleta dados do seu domínio simultaneamente, então o agente líder sintetiza os resultados. Agent Teams são opt-in e custam \~3-5x mais tokens. Execute manualmente: ```bash theme={null} make team-strategy # @sage lidera, @atlas + @flux + @pulse + @pixel como teammates make team-dashboard # @clawdia lidera, @atlas + @flux + @pulse + @dex como teammates make team-weekly # @clawdia lidera, @atlas + @flux + @pulse como teammates ``` Veja [Visão Geral de Rotinas](../routines/overview) para detalhes sobre Agent Teams. # Arquitetura Source: https://docs.evolutionfoundation.com.br/evo-nexus/architecture Como agentes, skills, rotinas e integrações se encaixam no EvoNexus ## Visão Geral O EvoNexus é um framework baseado em arquivos e amigável ao git. Tudo é markdown, YAML e scripts Python. Não exige banco de dados para o core (SQLite é usado apenas pelo dashboard). O EvoNexus organiza 38 agentes em **duas camadas ortogonais**: uma Business Layer (17 agentes para ops/finanças/comunidade/retenção de aprendizado/etc.) e uma Engineering Layer (21 agentes para desenvolvimento de software — 19 derivados do [oh-my-claudecode](https://github.com/yeachan-heo/oh-my-claudecode), MIT, por Yeachan Heo, mais 2 nativos: Helm e Mirror). As duas camadas compartilham a mesma infraestrutura de skills, memória e integrações, mas não atrapalham uma à outra: tarefas de negócio vão para agentes de negócio, tarefas de engenharia vão para agentes de engenharia. Handoffs entre camadas são comuns (ex.: Nova escreve um PRD → Apex revisa → Bolt implementa → Mirror captura lições). A engineering layer segue um workflow canônico de 6 fases (Discovery → Planning → Solutioning → Build → Verify → Retro) documentado em [`.claude/rules/dev-phases.md`](https://github.com/evolution-foundation/evo-nexus/blob/main/.claude/rules/dev-phases.md). ``` ┌──────────────────────────────────────────────────────────────────────┐ │ Usuário (humano) │ │ │ │ │ Claude Code CLI │ │ │ │ │ ┌────────────────────────────────────────────────────────────┐ │ │ │ BUSINESS LAYER (17) — operações / finanças / comunidade │ │ │ │ Clawdia Flux Atlas Pulse Pixel Sage Nex Mentor Lumen │ │ │ │ Kai Oracle Mako Aria Zara Lex Nova Dex │ │ │ └──────────────────────────┬─────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────┴─────────────────────────────────┐ │ │ │ ENGINEERING LAYER (19) — desenvolvimento de software │ │ │ │ apex echo compass raven bolt hawk lens zen vault grid │ │ │ │ probe oath trail scout flow scroll quill canvas prism │ │ │ │ (derivados do oh-my-claudecode por Yeachan Heo, MIT) │ │ │ └──────────────────────────┬─────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────┴─────────────────────────────────┐ │ │ │ Skills (175+) │ │ │ │ Negócio: fin- / social- / int- / hr- / legal- / pm- /... │ │ │ │ Engenharia: dev-* (25 skills, 3 tiers) │ │ │ └──────────────────────────┬─────────────────────────────────┘ │ │ │ │ │ ┌──────────────────────────┴─────────────────────────────────┐ │ │ │ Integrações (APIs + MCPs) │ │ │ │ Gmail / Calendar / Discord / Stripe / GitHub / Linear /… │ │ │ └────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────┘ ┌───────────────────────┐ │ Scheduler (cron) │ ─── routines.yaml │ ADW Runner │ ─── 4 core + ~23 exemplos custom │ Logs JSONL │ ─── métricas + custos └───────────────────────┘ ┌───────────────────────┐ │ Dashboard (web) │ │ Flask + React │ │ SQLite (só auth) │ └───────────────────────┘ ``` ## Componentes ### Agentes (`.claude/agents/`) Cada agente é um arquivo markdown com um system prompt que define seu domínio, responsabilidades e regras de comportamento. Agentes são invocados via slash commands (`/clawdia-assistant`, `/flux-finance`, `/apex-architect`, `/bolt-executor`, etc.) ou automaticamente pelo Claude com base na solicitação do usuário. ### Skills (`.claude/skills/`) Skills são instruções específicas de domínio que ensinam o Claude a executar tarefas. Organizadas por prefixo: | Prefixo | Domínio | Quantidade | | ---------- | ------------- | ---------- | | `social-` | Redes sociais | 17 | | `int-` | Integrações | 13 | | `fin-` | Finanças | 11 | | `prod-` | Produtividade | 9 | | `mkt-` | Marketing | 8 | | `gog-` | Google | 6 | | `obs-` | Obsidian | 5 | | `discord-` | Discord | 5 | | `pulse-` | Comunidade | 4 | | `sage-` | Estratégia | 3 | > **Nota:** as skills `evo-` (\~45) são mantidas no projeto separado [EVO-METHOD](https://github.com/evolution-foundation/EVO-METHOD). Elas são gitignored neste repositório, mas funcionam normalmente se instaladas localmente. O repo entrega 175+ skills não-evo. ### Rotinas (`ADWs/routines/`) Workflows automatizados que rodam em uma agenda. Cada rotina é um script Python que invoca o Claude Code CLI com um agente e uma skill específicos. As rotinas são divididas em duas camadas: * **Core** (`ADWs/routines/`) — 4 rotinas que vêm com o repo (good\_morning, end\_of\_day, memory\_sync, weekly\_review). * **Examples** (`ADWs/routines/examples/`) — \~23 rotinas de exemplo versionadas (comunidade, finanças, social, licenciamento, etc.). * **Custom** (`ADWs/routines/custom/`) — rotinas criadas pelo usuário (gitignored). Copie dos exemplos ou crie as suas. **Runner** (`ADWs/runner.py`) — A engine de execução que: * Invoca o Claude Code CLI com `--output-format json` * Captura uso de tokens e custo * Registra logs em arquivos JSONL * Envia notificações pelo Telegram * Acompanha métricas por rotina **Scheduler** (`scheduler.py`) — Lê `config/routines.yaml` e executa as rotinas nos horários configurados usando a biblioteca `schedule`. ### Memória Memória persistente em duas camadas seguindo o **padrão LLM Wiki** (ingest → query → lint): 1. **CLAUDE.md** — Hot cache carregado a cada início de sessão. Contém o contexto-chave sobre o usuário, empresa, projetos ativos e preferências. 2. **memory/** — Diretório de memória global com arquivos tipados (pessoas, projetos, glossário, tendências). Os agentes leem conforme necessário. * `index.md` — Catálogo centralizado de todos os arquivos de memória por categoria (atualizado automaticamente pelo memory-sync) * `log.md` — Registro cronológico append-only de todas as operações de memória (ingest, lint, atualizações) 3. **agent-memory/** — Memória por agente que persiste entre sessões. Três operações mantêm a base de conhecimento: * **Ingest** (diário, via memory-sync) — Extrai conhecimento novo dos logs diários, reuniões e mudanças no git. Propaga atualizações entre arquivos de memória relacionados (ex.: uma mudança de cargo de uma pessoa atualiza o arquivo dela em people/, o glossary.md e o CLAUDE.md). * **Query** (durante conversas) — Sínteses complexas podem ser arquivadas como novas entradas de memória, fazendo o conhecimento se acumular pelo uso. * **Lint** (semanal, via memory-lint) — Health check que detecta contradições, afirmações desatualizadas, arquivos órfãos, gaps de cobertura e referências cruzadas faltando. ### Dashboard (`dashboard/`) UI web construída com: * **Backend**: Flask + SQLAlchemy + Flask-Login + WebSocket * **Frontend**: React + TypeScript + Tailwind + Recharts + xterm.js * **Auth**: SQLite com roles (admin/operator/viewer), permissões customizáveis, audit log * **Terminal**: terminal real do Claude Code no navegador via WebSocket PTY ### Integrações Clientes de API em `.claude/skills/int-*/scripts/` que se conectam a serviços externos. Cada integração tem um SKILL.md descrevendo o uso e um script Python como cliente. # Primeiros Passos com o EvoNexus Source: https://docs.evolutionfoundation.com.br/evo-nexus/getting-started Como instalar e configurar o EvoNexus # Primeiros Passos com o EvoNexus ## Escolha seu método de instalação | Método | Ideal para | Requer | | ----------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | **[Docker](guides/docker-install)** | Quem quer uma instalação com um comando que funciona igual em qualquer SO (Linux, macOS, Windows+WSL2, VPS) | Docker Engine 24+ | | **CLI (`npx`)** | Usuários que querem rodar o EvoNexus junto com o Claude Code CLI já instalado | Claude Code, Python 3.11+, Node 18+, uv | | **Clone manual** | Desenvolvedores que querem modificar o código-fonte | git, Claude Code, Python 3.11+, Node 18+, uv | Em caso de dúvida, escolha o fluxo Docker. Continue lendo para o fluxo CLI. ## Pré-requisitos (apenas fluxo CLI) * **Claude Code CLI** — [Instalar Claude Code](https://claude.ai/claude-code) * **Python 3.11+** com [uv](https://docs.astral.sh/uv/) * **Node.js 18+** (para o dashboard) * **Chaves de API** das integrações que você quiser usar ## Instalação ### Opção A — Docker (mais rápido) Baixa as imagens oficiais multi-arch e roda o wizard em [http://localhost:8080](http://localhost:8080). Guia completo: [Instalando com Docker](guides/docker-install). ```bash theme={null} curl -O https://raw.githubusercontent.com/evolution-foundation/evo-nexus/main/docker-compose.hub.yml docker compose -f docker-compose.hub.yml up -d open http://localhost:8080 ``` Pule para [Use o Claude Code — comece pelo /oracle](#6-use-o-claude-code--comece-pelo-oracle) após o wizard concluir. ### Opção B — `npx` (fluxo CLI) ```bash theme={null} npx @evoapi/evo-nexus ``` Isso baixa e executa o wizard de setup interativo automaticamente. ### Opção C — Clone manual ```bash theme={null} git clone --depth 1 https://github.com/evolution-foundation/evo-nexus.git cd evo-nexus # Wizard de setup interativo make setup # Ou: python setup.py ``` O wizard pergunta: * Seu nome e empresa * Fuso horário e idioma * **Qual provedor de IA usar** (Anthropic por padrão; alternativas via OpenClaude) * Quais agentes habilitar * Quais integrações configurar E gera: * `config/workspace.yaml` — config central * `config/routines.yaml` — agendas das rotinas * `config/providers.json` — provedor de IA ativo + config do CLI backend * `.env` — chaves de API (preencha após o setup) * `CLAUDE.md` — arquivo de contexto para o Claude ### 2. Escolha seu Provedor de IA O wizard pergunta qual backend deve alimentar o EvoNexus. **A Anthropic é o padrão** — se você já tem o Claude Code autenticado, não precisa fazer mais nada. Para qualquer outro provedor (OpenRouter, OpenAI, Gemini, AWS Bedrock, Vertex AI, Codex Auth), o EvoNexus usa o [OpenClaude](https://www.npmjs.com/package/@gitlawb/openclaude), um binário drop-in compatível com o protocolo do Claude CLI. Instale uma vez: ```bash theme={null} npm install -g @gitlawb/openclaude ``` Em seguida, selecione o provedor no wizard (ou depois pela página **Providers** no dashboard) e preencha as chaves. O provedor ativo é armazenado em `config/providers.json` e tanto o terminal-server quanto o ADW runner releem o arquivo a cada nova sessão — não precisa reiniciar ao trocar. Veja [dashboard/providers](dashboard/providers) para a referência completa de provedores e [reference/env-variables](reference/env-variables) para todas as variáveis de ambiente relacionadas. ### 3. Configure as Chaves de API Edite `.env` com suas chaves: ```bash theme={null} nano .env ``` No mínimo, você precisa de: * Nenhuma chave para operação básica (agentes e skills funcionam sem integrações) * `DISCORD_BOT_TOKEN` — para monitoramento de comunidade * `STRIPE_SECRET_KEY` — para rotinas financeiras * Chaves OAuth de redes sociais — via página Integrations no dashboard ### 4. Inicie o Dashboard **Em VPS (remoto):** O wizard de setup cria automaticamente um usuário de sistema dedicado `evonexus` (o Claude Code recusa `--dangerously-skip-permissions` como root) e instala um **serviço systemd** que inicia no boot: ```bash theme={null} systemctl status evo-nexus # ver status systemctl restart evo-nexus # reiniciar journalctl -u evo-nexus -f # acompanhar logs su - evonexus # trocar para o usuário do serviço ``` Você também pode instalar o serviço systemd manualmente em uma instalação existente: ```bash theme={null} sudo bash install-service.sh ``` **Local (macOS/Linux):** ```bash theme={null} make dashboard-app ``` Abra [http://localhost:8080](http://localhost:8080) — a primeira execução mostra um wizard onde você cria a conta de admin e configura o workspace. Dashboard ### 5. Inicie as Rotinas Automatizadas Em VPS, o scheduler roda automaticamente dentro do serviço do dashboard. Localmente: ```bash theme={null} make scheduler ``` Isso inicia o scheduler que executa as rotinas nos horários configurados (veja `config/routines.yaml`). ### 6. Use o Claude Code — comece pelo `/oracle` Abra o Claude Code neste diretório. Ele lê o `CLAUDE.md` automaticamente e tem acesso a todos os agentes e skills. **A primeira coisa a executar: `/oracle`.** O Oracle é o ponto de entrada oficial — entrevista você sobre seu negócio, mapeia as capacidades do workspace para suas dores e entrega um **plano de ativação faseado** via skill `prod-activation-plan` (arquivo de índice + pasta-por-fase + arquivo-por-item, cada um com time de agentes sugerido e decisões pendentes). Você nunca precisa adivinhar o próximo passo. ```bash theme={null} /oracle # Comece aqui — discovery do negócio + plano de ativação ``` Após o plano ficar pronto, você pode invocar agentes individuais: ```bash theme={null} /clawdia # Hub de operações /flux # Análise financeira /atlas # Gestão de projetos /pulse # Pulso da comunidade /pixel # Redes sociais # Ou deixe o Claude rotear automaticamente conforme sua solicitação ``` ## Próximos Passos * Leia [Arquitetura](architecture) para entender como agentes, skills e rotinas trabalham juntos * Navegue por `.claude/skills/CLAUDE.md` para o índice completo de skills (175+ skills) * Confira `ROUTINES.md` para a documentação de rotinas * Customize `config/routines.yaml` para ajustar agendas # O que é o EvoNexus Source: https://docs.evolutionfoundation.com.br/evo-nexus/introduction Camada multi-agente para operação e desenvolvimento — 38 agentes especializados orquestrados via Claude Code > **Nota:** EvoNexus é um projeto **independente, open-source não-oficial**. **Não é afiliado, endossado ou patrocinado pela Anthropic**. "Claude" e "Claude Code" são marcas registradas da Anthropic, PBC. Este projeto integra-se ao Claude Code como ferramenta de terceiros e exige que os usuários forneçam sua própria instalação e credenciais. ## O Problema Tocar uma empresa significa lidar com dezenas de ferramentas, dashboards e canais de comunicação todos os dias. E-mail, calendário, gestão de projetos, controle financeiro, moderação de comunidade, redes sociais — cada um exige atenção, e nenhum conversa com o outro. A maioria dos "assistentes de IA" são chatbots. Você faz uma pergunta, recebe uma resposta, e volta a copiar dados manualmente entre ferramentas. Isso não escala. ## O que é o EvoNexus EvoNexus é um workspace multi-agente compatível com [Claude Code](https://docs.anthropic.com/en/docs/claude-code) e outras ferramentas de LLM. Ele transforma uma única instalação do Claude Code em um time de **38 agentes especializados** organizados em duas camadas ortogonais — uma para operações de negócio, outra para engenharia de software. A **Business Layer** tem 17 agentes que cuidam de domínios distintos (finanças, projetos, comunidade, redes sociais, estratégia, vendas, cursos, retenção de aprendizado, bem-estar pessoal, marketing, RH, customer success, jurídico, produto, dados, conhecimento) e produzem entregáveis operacionais reais: relatórios em HTML, caixas de entrada triadas, atas de reunião sincronizadas, snapshots financeiros, checagens de saúde da comunidade. A **Engineering Layer** tem 21 agentes para desenvolvimento de software (arquitetura, planejamento, implementação, code review, testes, debugging, segurança, design, orquestração de ciclo, retrospectiva) — 19 derivados do [oh-my-claudecode](https://github.com/yeachan-heo/oh-my-claudecode) (MIT, por Yeachan Heo) + 2 nativos (`helm-conductor` para orquestração de ciclo e `mirror-retro` para retrospectivas blameless). A camada segue um workflow canônico de 6 fases (Discovery → Planning → Solutioning → Build → Verify → Retro) que leva um briefing até uma feature verificada, revisada, testada e com lições capturadas. Um scheduler executa rotinas em cadência diária, semanal e mensal. Handoffs entre camadas são comuns — Nova escreve um PRD, Apex revisa a arquitetura, Bolt implementa, Lens revisa, Oath verifica. **Isso não é um chatbot.** É uma camada operacional para o seu negócio **e** para o seu time de engenharia. ## Para quem é * **Founders solo** que precisam tocar a operação sem montar um time de ops * **CEOs de empresas pequenas** gerenciando múltiplos produtos e comunidades * **Times pequenos** que querem relatórios e coordenação automatizados * **Desenvolvedores** que já usam Claude Code e querem estendê-lo ## Como é diferente | Chatbot | EvoNexus | | ---------------------------- | --------------------------------------------------------------------------------------------------------- | | Você pergunta, ele responde | Agentes executam rotinas na agenda | | Esquece entre sessões | Memória persistente entre sessões | | Uma única thread de conversa | 38 agentes com domínios isolados (17 de negócio + 21 de engenharia) | | Helper genérico | Papéis especializados por camada: ops, finanças, code review, auditoria de segurança, debugging | | Sem integrações | 18+ integrações (Google, GitHub, Stripe, Discord, etc.) | | Saída em texto | Relatórios HTML, dashboards, artefatos estruturados | | Manual toda vez | Workflows automatizados diários/semanais/mensais + pipelines sob demanda (`dev-autopilot`, `dev-ralplan`) | | Persona única de LLM | Consenso multi-perspectiva (Planner + Architect + Critic) para decisões de alto risco | ## Conceitos-Chave ### Agentes 17 agentes especializados, cada um com um system prompt, slash command, memória persistente e skills específicas do domínio: | Agente | Domínio | Comando | | ------- | ------------------------------------------------------------------------------ | ----------------- | | Clawdia | Operações — agenda, e-mails, tarefas, decisões | `/clawdia` | | Flux | Finanças — Stripe, ERP, fluxo de caixa, relatórios | `/flux` | | Atlas | Projetos — Linear, GitHub, sprints | `/atlas` | | Pulse | Comunidade — Discord, WhatsApp, sentimento | `/pulse` | | Pixel | Redes sociais — conteúdo, calendário, analytics | `/pixel` | | Sage | Estratégia — OKRs, roadmap, priorização | `/sage` | | Nex | Vendas — pipeline, propostas, qualificação | `/nex` | | Mentor | Cursos — trilhas de aprendizado, módulos | `/mentor` | | Kai | Pessoal — saúde, hábitos, rotina | `/kai` | | Oracle | Conhecimento — docs do workspace, how-to, config | `/oracle` | | Mako | Marketing — campanhas, SEO, marca, conteúdo | `/mako` | | Aria | RH / Pessoas — recrutamento, onboarding, desempenho | `/aria` | | Zara | Customer Success — triagem, escalação, saúde | `/zara` | | Lex | Jurídico — contratos, compliance, NDA, risco | `/lex` | | Nova | Produto — specs, roadmaps, métricas, pesquisa | `/nova` | | Dex | Dados / BI — análise, SQL, dashboards | `/dex` | | Lumen | Retenção de Aprendizado — repetição espaçada (SM-2), captura de fatos, quizzes | `/lumen-learning` | ### Skills 175+ capacidades reutilizáveis organizadas por prefixo (`fin-`, `social-`, `int-`, `prod-`, `hr-`, `legal-`, `ops-`, `cs-`, `data-`, `pm-`, `mkt-`, etc.). Skills são arquivos markdown que ensinam os agentes a executar tarefas específicas — sem plugins, sem código. ### Rotinas Workflows automatizados (ADWs) que rodam na agenda via um scheduler em Python. Briefings da manhã, triagem de e-mail, snapshots financeiros, monitoramento de comunidade, consolidação de fim de dia. Cada rotina registra métricas de execução (tokens, custo, duração) em formato JSONL. ### Dashboard Uma UI web (React + Flask) para gerenciar tudo: ver relatórios, iniciar/parar serviços, navegar pelos agentes e skills, gerenciar usuários e roles, e interagir com o Claude Code via terminal embutido. Dashboard Web ### Base de Conhecimento Busca semântica opcional via [MemPalace](https://github.com/milla-jovovich/mempalace). Indexe o código do seu projeto, documentação e conhecimento para busca em linguagem natural — tudo roda localmente com ChromaDB. Habilite com um clique no Dashboard. ### Memória Persistência em duas camadas. `CLAUDE.md` guarda a memória de trabalho (quem você é, projetos ativos, pessoas-chave). O diretório `memory/` armazena contexto profundo (perfis de pessoas, glossário, histórico de projetos). Ambos sobrevivem entre sessões. ### Provedores de IA EvoNexus roda sobre o CLI `claude` da Anthropic por padrão, mas pode trocar para qualquer um dos 6 backends alternativos (OpenRouter, OpenAI, Gemini, AWS Bedrock, Google Vertex AI, Codex Auth) via [OpenClaude](https://www.npmjs.com/package/@gitlawb/openclaude). O provedor ativo é armazenado em `config/providers.json` e pode ser alterado pela página Providers no dashboard — tanto o terminal-server quanto o ADW runner releem o config a cada nova sessão, então a troca tem efeito imediato. Sem vendor lock-in, sua escolha de modelo, suas chaves. Veja [dashboard/providers](dashboard/providers) para a referência completa. ## Open Source EvoNexus é licenciado sob Apache 2.0, construído pela [Evolution Foundation](https://evolutionfoundation.com.br). O código-fonte está em [github.com/evolution-foundation/evo-nexus](https://github.com/evolution-foundation/evo-nexus). Este é um projeto comunitário não-oficial — não afiliado nem endossado pela Anthropic. Foi desenhado para ser forkado e adaptado. Adicione seus próprios agentes, skills, rotinas e integrações. A arquitetura é markdown-first — sem sistemas de plugin complexos, apenas arquivos que o Claude Code lê. # Variáveis de Ambiente Source: https://docs.evolutionfoundation.com.br/self-hosted/configuration/environment-variables O arquivo `.env` é onde você diz para a plataforma como ela deve se comportar: onde está o banco de dados, qual senha usar, quais serviços se comunicam entre si. Sem ele configurado corretamente, nada funciona. A boa notícia: para a maioria das instalações com Docker, você **não precisa mudar quase nada**. *** ## Como funciona Toda a configuração fica em **um único arquivo `.env`** na raiz do projeto. Ele é criado a partir de um modelo pronto: ```bash theme={null} cp .env.example .env ``` O `.env.example` já vem com valores padrão que funcionam imediatamente para rodar a plataforma localmente com Docker. Abra o `.env` com qualquer editor de texto e ajuste apenas o que for necessário para o seu ambiente. O arquivo `.env.example` é o arquivo com a lista completa de todas as variáveis disponíveis. Consulte-o sempre que precisar de uma referência completa. *** ## Banco de dados (PostgreSQL) Todos os serviços compartilham o mesmo banco de dados. Com Docker, essas variáveis já estão configuradas e funcionam sem alteração. ```bash theme={null} # Servidor e porta POSTGRES_HOST=postgres POSTGRES_PORT=5432 # Credenciais POSTGRES_USERNAME=postgres POSTGRES_PASSWORD=sua_senha_segura # Nome do banco POSTGRES_DATABASE=evo_community ``` O serviço **Core** (`evo-ai-core-service-community`) usa um conjunto separado de variáveis com o mesmo banco: ```bash theme={null} DB_HOST=postgres DB_PORT=5432 DB_USER=postgres DB_PASSWORD=sua_senha_segura DB_NAME=evo_community DB_SSLMODE=disable ``` O serviço **Processor** usa o formato de string de conexão: ```bash theme={null} POSTGRES_CONNECTION_STRING=postgresql://postgres:sua_senha_segura@postgres:5432/evo_community ``` O Evo CRM Community **não é compatível** com MySQL, MariaDB ou SQLite. Use sempre PostgreSQL 16 ou superior com a extensão pgVector habilitada. *** ## Redis (cache e filas) O Redis é usado para manter sessões ativas e processar tarefas em segundo plano. Com Docker, ele já sobe automaticamente. ```bash theme={null} # Auth e CRM usam URL completa REDIS_URL=redis://:sua_senha_redis@redis:6379 REDIS_PASSWORD=sua_senha_redis # Processor usa variáveis separadas REDIS_HOST=redis REDIS_PORT=6379 REDIS_DB=0 REDIS_SSL=false ``` *** ## Secrets compartilhados Essas são as variáveis mais importantes para a segurança da plataforma. Elas devem ter o **mesmo valor** em todos os serviços que as utilizam. ```bash theme={null} # Usado por: auth, crm, core-service (assinatura de tokens JWT) SECRET_KEY_BASE=gere-uma-chave-longa-e-aleatoria-com-rails-secret JWT_SECRET_KEY=gere-uma-chave-longa-e-aleatoria-com-rails-secret # Usado por: core-service, processor (criptografia de chaves de API) ENCRYPTION_KEY=gere-uma-chave-base64-de-32-bytes # Usado por: auth, crm, processor (autenticação entre serviços) EVOAI_CRM_API_TOKEN=gere-um-uuid-unico-aqui ``` **Como gerar os valores:** ```bash theme={null} # Para SECRET_KEY_BASE e JWT_SECRET_KEY make shell-auth # dentro do container: rails secret # Para ENCRYPTION_KEY (base64 de 32 bytes) openssl rand -base64 32 # Para EVOAI_CRM_API_TOKEN (UUID) uuidgen ``` Em produção, **nunca use os valores do `.env.example`**. Gere valores únicos para cada instalação. Todos os serviços que compartilham uma chave devem usar exatamente o mesmo valor. *** ## Frontend As variáveis do frontend começam com `VITE_` e são incorporadas ao código no momento do build. Elas usam `localhost` porque o navegador as acessa diretamente — não pelo Docker. ```bash theme={null} VITE_APP_ENV=development # Endereços dos serviços (acessados pelo navegador) VITE_API_URL=http://localhost:3000 VITE_AUTH_API_URL=http://localhost:3001 VITE_EVOAI_API_URL=http://localhost:5555 VITE_AGENT_PROCESSOR_URL=http://localhost:8000 ``` Em produção, substitua `localhost` pelos domínios reais da sua instalação: ```bash theme={null} VITE_APP_ENV=production VITE_API_URL=https://api.seudominio.com VITE_AUTH_API_URL=https://auth.seudominio.com VITE_EVOAI_API_URL=https://core.seudominio.com VITE_AGENT_PROCESSOR_URL=https://processor.seudominio.com ``` *** ## E-mail (SMTP) Em desenvolvimento, a plataforma usa o **Mailhog** — um servidor de e-mail local que captura as mensagens sem enviá-las de verdade. Acesse `http://localhost:8025` para ver os e-mails capturados. ```bash theme={null} # Desenvolvimento com Mailhog (padrão — não precisa alterar) SMTP_ADDRESS=mailhog SMTP_PORT=1025 SMTP_DOMAIN=evoai-community.local SMTP_AUTHENTICATION=plain SMTP_ENABLE_STARTTLS_AUTO=false SMTP_USERNAME= SMTP_PASSWORD= MAILER_SENDER_EMAIL=noreply@evoai-community.local ``` Para produção, substitua pelos dados do seu provedor de e-mail: ```bash theme={null} SMTP_ADDRESS=smtp.seudominio.com SMTP_PORT=587 SMTP_DOMAIN=seudominio.com SMTP_AUTHENTICATION=plain SMTP_ENABLE_STARTTLS_AUTO=true SMTP_USERNAME=noreply@seudominio.com SMTP_PASSWORD=sua_senha_smtp MAILER_SENDER_EMAIL=noreply@seudominio.com ``` ### Configuração via UI em runtime (a partir do v1.0.0-rc3) A partir do `v1.0.0-rc3` (EVO-1049), as configurações de SMTP, **BMS** e **Resend** podem ser alteradas via UI no painel `/settings/admin` e são aplicadas **em runtime**, sem reiniciar o container. Antes era necessário restart para que mudanças refletissem. Isso significa que você pode: * Manter `.env` apenas com defaults (ou nem configurar SMTP no `.env`, deixando vazio). * Configurar credenciais de produção pela UI após o boot. * Trocar provedor (de SMTP para Resend, por exemplo) sem downtime. > O acesso ao painel `/settings/admin` é exclusivo do papel `super_admin` — o operador da instalação, separado do `account_owner`. *** ## Licensing e Operador A partir do `v1.0.0-rc3`, o `.env.example` documenta a variável de operador: ```bash theme={null} # E-mail do operador da instalação (usado em eventos de licensing) EVOLUTION_OPERATOR_EMAIL=ops@seudominio.com ``` Este e-mail é referência para auto-ativação e telemetria. Para detalhes, ver [Licensing](/licensing). *** ## Canais opcionais Essas variáveis ficam comentadas no `.env.example` e só precisam ser configuradas se você for usar os respectivos canais. ```bash theme={null} # WhatsApp Cloud API WP_APP_ID=seu_app_id WP_VERIFY_TOKEN=seu_token_de_verificacao WP_APP_SECRET=seu_app_secret # Facebook Messenger FB_APP_SECRET=seu_app_secret FB_APP_ID=seu_app_id # Google OAuth (integração com Gmail) GOOGLE_OAUTH_CLIENT_ID=seu_client_id GOOGLE_OAUTH_CLIENT_SECRET=seu_client_secret # Slack SLACK_CLIENT_ID=seu_client_id SLACK_CLIENT_SECRET=seu_client_secret ``` *** ## Dicas de segurança * **Nunca envie o arquivo `.env` para o GitHub ou GitLab.** Ele já está no `.gitignore` por padrão. * O arquivo `.env.example` é seguro para versionar — ele contém apenas exemplos sem dados reais. * Em produção, gere valores únicos para `SECRET_KEY_BASE`, `JWT_SECRET_KEY`, `ENCRYPTION_KEY` e `EVOAI_CRM_API_TOKEN`. * Use senhas fortes e únicas para `POSTGRES_PASSWORD` e `REDIS_PASSWORD`. *** ## Solução de problemas ### Banco de dados não conecta Se após o `make setup` você vir erros de conexão: 1. Verifique se os containers estão rodando: `make status` 2. Confira os valores de `POSTGRES_HOST`, `POSTGRES_USERNAME` e `POSTGRES_PASSWORD` no `.env` 3. Para banco em nuvem, verifique se o acesso externo está liberado no painel do provedor ### E-mail não está sendo enviado Em desenvolvimento, os e-mails não são enviados de verdade — ficam retidos no Mailhog. Acesse `http://localhost:8025` para visualizá-los. ### Serviço não sobe após o setup ```bash theme={null} # Ver logs de um serviço específico make logs SERVICE=evo-crm # Ver todos os logs de uma vez make logs ``` Os logs mostram exatamente qual variável está faltando ou com valor incorreto. # Aria Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/aria Esta página ainda está em inglês. A tradução para português está em andamento. # Aria — HR & People **Command:** `/aria-hr` | **Color:** pink | **Model:** Sonnet Aria is the HR and People Operations agent — it manages the recruiting pipeline, performance reviews, onboarding, compensation benchmarking, org planning, and policy lookup. Aria helps you build and maintain a healthy organization by keeping people processes structured, documented, and on schedule. ## When to Use * Check the current recruiting pipeline status and candidate progress * Generate an onboarding checklist for a new hire starting next week * Kick off the quarterly performance review cycle * Run a compensation benchmark for a specific role or level * Look up the remote work policy or any other company policy ## Preloaded Skills | Skill | What it does | | ------------------------ | ----------------------------------------------------------------- | | `hr-recruiting-pipeline` | Track and manage hiring pipeline stages and candidate status | | `hr-performance-review` | Set up review cycles with self-assessment and manager templates | | `hr-onboarding` | Generate first-week checklists and onboarding plans | | `hr-comp-analysis` | Benchmark salaries and model compensation packages | | `hr-draft-offer` | Draft offer letters with compensation details and terms | | `hr-interview-prep` | Create structured interview plans with competency-based questions | | `hr-org-planning` | Plan headcount, org design, and team structure | | `hr-people-report` | Generate headcount, attrition, and organizational health reports | | `hr-policy-lookup` | Find and explain company policies in plain language | ## Example Interactions ``` /aria-hr show me the recruiting pipeline status /aria-hr create an onboarding checklist for a new backend developer /aria-hr run a compensation benchmark for senior engineers in Brazil ``` ## Routines This agent is not used in any scheduled routines. ## Memory Persistent memory at `.claude/agent-memory/aria/`. Stores project context, user preferences, and feedback across sessions. # Atlas Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/atlas Esta página ainda está em inglês. A tradução para português está em andamento. # Atlas — Projects & Ops **Command:** `/atlas-project` | **Color:** green | **Model:** Sonnet Atlas is the project management agent — tracking Linear issues, GitHub pull requests, sprint progress, licensing telemetry, capacity planning, and status reports. Atlas keeps all development workstreams visible and helps identify blockers before they become problems. ## When to Use * Checking project status, sprint progress, or blockers * Reviewing open GitHub PRs and community issues * Monitoring open source licensing growth and telemetry * Planning team capacity and workload distribution * Generating status reports with KPIs and risk flags ## Preloaded Skills | Skill | What it does | | ------------------------ | --------------------------------------------------- | | `int-github-review` | Repo health — open PRs, issues, stars, releases | | `int-linear-review` | Sprint and issue tracking in Linear | | `int-licensing` | Open source telemetry — instances, geo, versions | | `prod-licensing-daily` | Daily growth snapshot from licensing data | | `prod-licensing-weekly` | Weekly trends in licensing telemetry | | `prod-licensing-monthly` | Monthly deep analysis of licensing growth | | `ops-capacity-plan` | Team workload analysis and utilization forecast | | `ops-status-report` | KPI reports with risk flags and action items | | `ops-change-request` | Change management with impact analysis and rollback | ## Example Interactions ``` /atlas-project what's the sprint status for this week? /atlas-project check open PRs on evolution-api /atlas-project how's licensing growth looking this month? ``` ## Routines | Time | Routine | | ----------------- | ----------------- | | Mon/Wed/Fri 09:00 | Linear Review | | Mon/Wed/Fri 09:15 | GitHub Review | | Daily 18:30 | Licensing Daily | | Friday 07:45 | Licensing Weekly | | 1st of month | Licensing Monthly | ## Memory Persistent memory at `.claude/agent-memory/atlas/`. Stores project context, user preferences, and feedback across sessions. # Clawdia Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/clawdia Esta página ainda está em inglês. A tradução para português está em andamento. # Clawdia — Operations & COO **Command:** `/clawdia-assistant` | **Color:** cyan | **Model:** Sonnet Clawdia is the operational hub and default agent — a COO-like partner that manages your calendar, emails, tasks, meetings, prioritization, decisions, research, and documentation. She keeps the daily rhythm running smoothly, from morning briefings to end-of-day consolidation, ensuring nothing falls through the cracks. ## When to Use * Starting your day with "good morning" to get a full briefing of agenda, emails, and tasks * Checking, triaging, or drafting email replies * Reviewing and organizing Todoist tasks * Summarizing a meeting recording or syncing Fathom transcripts * Making a decision between options and need a structured analysis ## Preloaded Skills | Skill | What it does | | -------------------------- | ----------------------------------------------------------- | | `prod-good-morning` | Morning briefing with agenda, emails, tasks, and priorities | | `prod-end-of-day` | Daily consolidation of work done, decisions, and learnings | | `prod-dashboard` | 360 dashboard combining all routine outputs | | `prod-memory-management` | Persistent memory system for context across sessions | | `prod-review-todoist` | Task organization and cleanup in Todoist | | `prod-trends` | Weekly trends analysis across metrics | | `gog-calendar` | Google Calendar — view agenda and schedule events | | `gog-email-triage` | Inbox prioritization and classification | | `gog-email-draft` | Draft email replies with tone matching | | `gog-email-send` | Send emails with explicit confirmation | | `gog-followups` | Track stale email threads and generate reminders | | `gog-tasks` | Task management and prioritization | | `int-fathom` | Meeting recordings, transcripts, and summaries | | `int-sync-meetings` | Sync Fathom recordings to local workspace | | `int-todoist` | Todoist integration for task management | | `schedule-task` | One-off task scheduling | | `ops-process-doc` | Business process documentation with flowcharts and RACI | | `ops-runbook` | Operational runbooks for recurring procedures | | `ops-process-optimization` | Workflow improvement and bottleneck analysis | ## Example Interactions ``` /clawdia-assistant good morning /clawdia-assistant check my emails and flag anything urgent /clawdia-assistant summarize yesterday's meeting with HostGator ``` ## Routines | Time | Routine | | ------------ | ---------------------- | | Daily 06:50 | Review Todoist | | Daily 07:00 | Good Morning | | Daily 07:15 | Email Triage | | Every 30min | Sync Meetings | | Daily 21:00 | End of Day | | Daily 21:15 | Memory Sync | | Daily 21:30 | Consolidated Dashboard | | Friday 08:00 | Weekly Review | | Sunday 09:00 | Memory Lint | ## Memory Persistent memory at `.claude/agent-memory/clawdia/`. Stores project context, user preferences, and feedback across sessions. # Dex Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/dex Esta página ainda está em inglês. A tradução para português está em andamento. # Dex — Data & BI **Command:** `/dex-data` | **Color:** yellow | **Model:** Sonnet Dex is the Data and BI agent, specializing in data analysis, SQL queries, interactive dashboards (Chart.js), statistical analysis, data profiling, and validation. He connects to Stripe, Omie, and Licensing APIs to turn raw data into actionable insights, visualizations, and quality-checked deliverables. ## When to Use * You need to analyze a financial trend like MRR over the last 3 months * You want an optimized SQL query for a specific data question (e.g., churned customers) * You need an interactive HTML dashboard for licensing growth or revenue metrics * You want to run statistical analysis on conversion rates or experiment results * A dataset needs profiling or validation before publishing or sharing ## Preloaded Skills | Skill | What it does | | --------------------------- | ------------------------------------------------------------------- | | `data-analyze` | Answers ad-hoc data questions from quick lookups to full reports | | `data-build-dashboard` | Builds interactive HTML dashboards with charts, filters, and tables | | `data-write-query` | Writes optimized SQL for PostgreSQL with best practices | | `data-explore` | Profiles datasets for shape, quality, nulls, and distributions | | `data-create-viz` | Creates professional Python visualizations in Evolution theme | | `data-statistical-analysis` | Runs descriptive stats, trend analysis, and hypothesis testing | | `data-validate` | Pre-delivery QA for methodology, accuracy, and bias checks | | `int-stripe` | Accesses Stripe financial data (charges, subscriptions, MRR) | | `int-omie` | Accesses Omie ERP data (clients, invoices, financials) | | `int-licensing` | Queries open source telemetry (instances, geo, versions) | ## Example Interactions ``` /dex-data analyze MRR trend for the last 3 months /dex-data build a licensing growth dashboard with geo breakdown /dex-data run statistical analysis on trial-to-paid conversion rates ``` ## Routines This agent is not used in any scheduled routines. ## Memory Persistent memory at `.claude/agent-memory/dex/`. Stores project context, user preferences, and feedback across sessions. # Engineering layer Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/engineering-layer Esta página ainda está em inglês. A tradução para português está em andamento. # Engineering Layer > **Attribution:** the Engineering Layer is derived from [oh-my-claudecode](https://github.com/yeachan-heo/oh-my-claudecode) (MIT, by **Yeachan Heo**). EvoNexus imports the agents and adapts them to the workspace conventions (themed names, EvoNexus standard pattern, `workspace/development/` paths). See [NOTICE.md](https://github.com/evolution-foundation/evo-nexus/blob/main/NOTICE.md) at the repo root for the full list of derived components and modifications. > **Native additions (v0.13.0):** `helm-conductor` and `mirror-retro` are native EvoNexus agents, not derived from oh-my-claudecode. Helm orchestrates the engineering cycle and routes tasks to phase owners; Mirror runs blameless retrospectives at the end of features and sprints. ## What It Is The Engineering Layer is a complete software development team built into EvoNexus. **21 specialized agents** (19 derived + 2 native) + **25 `dev-*` skills** + **15 templates** + a **canonical 6-phase workflow** ([`dev-phases.md`](https://github.com/evolution-foundation/evo-nexus/blob/main/.claude/rules/dev-phases.md)) that cover the full dev lifecycle: discovery, planning, solutioning, build, verify, retro. It exists as a layer ortogonal to the Business Layer (Clawdia, Flux, Atlas, etc.). Business agents handle operations (emails, finance, community); engineering agents handle code (architecture, bugs, reviews, tests). Cross-layer handoffs are common — e.g., Nova writes a PRD → Apex reviews the architecture → Bolt implements → Lens reviews → Oath verifies → Mirror captures lessons. ## When to Use * You write code on top of EvoNexus * You want a structured dev workflow with separation of concerns (planner ≠ executor ≠ reviewer ≠ verifier) * You want code review, security audits, and verification as first-class agents * You want autonomous end-to-end execution from a brief to working code (`dev-autopilot`) If you only need EvoNexus for ops/business work, you can ignore the Engineering Layer entirely — it doesn't get in the way. ## The 21 Agents ### Reasoning (opus / sonnet) — 8 agents These agents do deep cognitive work: design, analysis, planning, critique, reflection. Higher token cost, higher quality output. | Agent | Slash | Role | READ-ONLY? | | ------------ | ------------------ | ------------------------------------------------------------------------------------------------- | ---------- | | **Apex** | `/apex-architect` | Architect — architectural design, debugging diagnosis, tradeoffs with file:line citations | ✅ | | **Echo** | `/echo-analyst` | Analyst — discovery, gap analysis, hidden assumptions, missing acceptance criteria | ✅ | | **Compass** | `/compass-planner` | Planner — interview-driven 3-6 step work plans + PRD production with explicit ADRs | | | **Raven** | `/raven-critic` | Critic — multi-perspective adversarial review with pre-commitment predictions | ✅ | | **Lens** | `/lens-reviewer` | Code Reviewer — 2-stage review (spec compliance + quality), OWASP, SOLID, severity ratings | ✅ | | **Zen** | `/zen-simplifier` | Code Simplifier — deslop, reduce nesting, eliminate redundancy without changing behavior | | | **Vault** | `/vault-security` | Security Reviewer — OWASP Top 10, secrets scan, dependency audit, prioritized remediation | ✅ | | **Mirror** ⭐ | `/mirror-retro` | Retrospective — blameless lessons learned, reads the full feature folder, proposes memory updates | | ### Execution (sonnet) — 11 agents These agents do focused implementation work: writing code, running tests, investigating bugs, producing artifacts, sequencing work. | Agent | Slash | Role | | ---------- | ------------------ | ------------------------------------------------------------------------------------- | | **Bolt** | `/bolt-executor` | Executor — precise multi-file implementation with smallest viable diff | | **Hawk** | `/hawk-debugger` | Debugger — root cause analysis, build error fixing, 3-failure circuit breaker | | **Grid** | `/grid-tester` | Test Engineer — TDD discipline, test pyramid (70/20/10), flaky test diagnosis | | **Probe** | `/probe-qa` | QA Tester — interactive tmux sessions, real commands, real output, always cleans up | | **Oath** | `/oath-verifier` | Verifier — evidence-based completion checks, never trusts "should work" | | **Trail** | `/trail-tracer` | Tracer — causal investigation with competing hypotheses, ranks by evidence strength | | **Flow** | `/flow-git` | Git Master — atomic commits, style detection, safe rebasing | | **Scroll** | `/scroll-docs` | Document Specialist — external SDK/API docs lookup with citations | | **Canvas** | `/canvas-designer` | Designer — production-grade UI/UX, framework-idiomatic, distinctive aesthetic | | **Prism** | `/prism-scientist` | Scientist — formal statistical analysis with CI, effect size, p-value | | **Helm** ⭐ | `/helm-conductor` | Conductor — cycle orchestration, sequencing, routing to phase owners, sprint planning | ⭐ = native EvoNexus agent (not derived from oh-my-claudecode) ### Speed (haiku) — 2 agents Fast, parallel, low-token agents for high-volume work. | Agent | Slash | Role | | --------- | ----------------- | ----------------------------------------------------------------------------------- | | **Scout** | `/scout-explorer` | Explorer — parallel codebase search (Glob/Grep), absolute paths, file:line evidence | | **Quill** | `/quill-writer` | Writer — quick technical docs, README, comments, every code example tested | ## The 6-Phase Workflow The engineering layer follows a canonical workflow documented in [`.claude/rules/dev-phases.md`](https://github.com/evolution-foundation/evo-nexus/blob/main/.claude/rules/dev-phases.md). It is a **guide**, not a rigid gate — simple changes can skip phases, complex features should follow them in order. ``` Discovery → Planning → Solutioning → Build → Verify → Retro ``` | Phase | Owner | Output | | -------------- | ------------------ | --------------------------------------------------------------- | | 1. Discovery | `@echo-analyst` | `[C]discovery-{feature}.md` — gaps, assumptions, open questions | | 2. Planning | `@compass-planner` | `[C]prd-{feature}.md` + `[C]plan-{feature}.md` | | 3. Solutioning | `@apex-architect` | `[C]architecture-{feature}.md` (ADR format) | | 4. Build | `@bolt-executor` | code + tests + commits | | 5. Verify | `@oath-verifier` | `[C]verification-{feature}.md` — evidence-based PASS/FAIL | | 6. Retro | `@mirror-retro` | `[C]retro-{feature}.md` — lessons + memory updates | **Cycle orchestration** — `@helm-conductor` sits above the phases and answers "what next?", "who does it?", and "what's blocked?". Call Helm when you have multiple active features or need sprint sequencing. **Feature folders** — non-trivial work lives in `workspace/development/features/{feature-slug}/` where all artifacts of one feature are grouped together. Standalone artifacts continue to live in `workspace/development/{type}/`. ## The 25 `dev-*` Skills Skills that orchestrate the engineering agents. ### Tier 1 — Core orchestration (15) * `dev-autopilot` — full lifecycle: spec → plan → code → QA → validation * `dev-plan` — interview-driven planning (delegates to compass-planner) * `dev-ralplan` — multi-perspective consensus (Planner + Architect + Critic) * `dev-deep-interview` — Socratic Q\&A to crystallize requirements * `dev-deep-dive` — causal trace + requirements crystallization combined * `dev-external-context` — parallel external doc lookups * `dev-trace` — evidence-driven causal investigation * `dev-verify` — evidence-based completion verification * `dev-ultraqa` — QA cycling loop (build/lint/test/fix up to 5 cycles) * `dev-visual-verdict` — visual regression testing * `dev-ai-slop-cleaner` — post-AI cleanup (single-use helpers, over-abstractions) * `dev-sciomc` — scientific method scaffolding * `dev-team` — on-demand parallel agent spawning * `dev-ccg` — tri-model orchestration (Claude + Codex + Gemini) * `dev-ralph` — persistence loop with iteration-based circuit breaker ### Tier 2 — Setup & infrastructure (5) * `dev-mcp-setup` — configure MCP servers * `dev-deepinit` — generate hierarchical AGENTS.md / CLAUDE.md for new projects * `dev-project-session-manager` — git worktrees per issue/PR * `dev-configure-notifications` — Telegram/Discord/Slack alerts for eng events * `dev-release` — generic release prep (changelog, version bump, tag) ### Tier 3 — Meta / utilities (5) * `dev-cancel` — clean stop of any active eng workflow * `dev-remember` — quick context persistence (lighter than mempalace) * `dev-ask` — single-shot query to a specific model (Claude/Codex/Gemini) * `dev-learner` — extract reusable skills from conversation patterns * `dev-skillify` — convert current conversation into a new skill ## Recommended Pipelines ### End-to-end implementation ``` User: "build me a CRUD API for a bookstore inventory in TypeScript" ↓ dev-autopilot ├── Phase 0: echo-analyst → spec ├── Phase 1: compass-planner → plan ├── Phase 2: bolt-executor → code (parallel where safe) ├── Phase 3: dev-ultraqa → build/test/fix loop ├── Phase 4: lens-reviewer + vault-security + apex-architect → validation └── Phase 5: oath-verifier → final evidence-based verdict ``` ### High-stakes plan ``` User: "we need to migrate auth from JWT to session cookies" ↓ dev-ralplan (consensus mode) ├── compass-planner → initial plan with principles, drivers, options ├── apex-architect → consensus addendum (steelman antithesis, tradeoff tension) └── raven-critic → adversarial review (gap analysis, severity ratings) ↓ Final plan with ADR + pre-mortem (deliberate mode) ``` ### Bug investigation ``` User: "the bot drops messages but only on Tuesdays" ↓ trail-tracer (multi-hypothesis) ├── Generate 2+ competing explanations ├── Collect evidence FOR and AGAINST each ├── Apply lenses (systems / premortem / science) └── Identify the discriminating probe ↓ hawk-debugger (once root cause is clear) ├── Reproduce ├── Minimal fix └── 3-failure circuit breaker ↓ oath-verifier (regression check) ``` ### Pre-merge gate ``` git diff ↓ lens-reviewer (code quality, severity-rated) ↓ vault-security (OWASP audit) ↓ dev-ultraqa (build/test/fix until green) ↓ oath-verifier (acceptance criteria mapping) ↓ flow-git (atomic commits matching project style) ``` ## Working Folder All engineering layer artifacts persist in `workspace/development/`: ``` workspace/development/ ├── architecture/ — apex-architect: ADRs, design tradeoffs, debug analyses ├── plans/ — compass-planner: work plans, RALPLAN-DR consensus, open questions ├── specs/ — echo-analyst, dev-deep-interview: gap analyses, requirement specs ├── reviews/ — lens-reviewer, vault-security: code reviews, security audits ├── debug/ — hawk-debugger, trail-tracer: bug reports, trace investigations ├── verifications/ — oath-verifier, grid-tester, probe-qa: verification reports, test strategies ├── research/ — scroll-docs, prism-scientist, scout-explorer: external research, statistical analyses └── README.md ``` **Distinction from `workspace/projects/`:** * `workspace/development/` — engineering layer **artifacts** (analyses, plans, reports). Owned by Claude. * `workspace/projects/` — **active git projects** (Evolution API, Evo AI, Evo Go). Owned by you. Engineering agents read for context; only `bolt-executor` writes code there, and only with your approval. ## Templates Each engineering agent has a template at `.claude/templates/dev-*.md` for its primary output: | Agent | Template | | -------------------------------- | ------------------------------ | | apex-architect | `dev-architecture-decision.md` | | compass-planner | `dev-work-plan.md` | | lens-reviewer | `dev-code-review.md` | | hawk-debugger | `dev-bug-report.md` | | oath-verifier | `dev-verification-report.md` | | echo-analyst, dev-deep-interview | `dev-deep-interview-spec.md` | | vault-security | `dev-security-audit.md` | | grid-tester | `dev-test-strategy.md` | | trail-tracer | `dev-trace-report.md` | | scout-explorer | `dev-explore-report.md` | | canvas-designer | `dev-design-spec.md` | | prism-scientist | `dev-analysis-report.md` | | scroll-docs | `dev-research-brief.md` | | raven-critic | `dev-critique.md` | | zen-simplifier | `dev-simplification-report.md` | ## Memory Each engineering agent has its own memory folder at `.claude/agent-memory/{agent-name}/`. Agents update memory with patterns worth carrying forward (anti-patterns, gotchas, codebase conventions). Engineering agents use a **lighter memory pattern** than business agents — no rich auto-memory block with user/feedback/project/reference types. They are tools, not "colleagues" — Apex doesn't need to learn "the Davidson way", it just needs to remember the architecture patterns of this codebase. ## Cross-Layer Handoffs The two layers cooperate naturally: | Trigger | Business → Engineering | | ------------------------------------------- | -------------------------------------------- | | `@nova` writes a PRD | → `@apex-architect` reviews the architecture | | `@dex-data` finds a metric anomaly | → `@trail-tracer` investigates causally | | `@atlas-project` flags an open PR | → `@lens-reviewer` reviews it | | `@lex-legal` flags a compliance gap in code | → `@vault-security` audits | | `@mako-marketing` needs a landing page | → `@canvas-designer` builds it | ## Attribution The Engineering Layer is **derived** from [oh-my-claudecode](https://github.com/yeachan-heo/oh-my-claudecode): * **Author:** Yeachan Heo * **License:** MIT (Copyright © 2025 Yeachan Heo) * **Version imported:** v4.11.4 * **Date imported:** 2026-04-10 EvoNexus modifications: * Renamed agents to themed names (`architect` → `apex-architect`) * Added `dev-` prefix to all skills for namespace consistency * Adapted memory structure to match EvoNexus per-agent pattern * Removed runtime dependencies on OMC TypeScript `src/` (kept only the markdown definitions) * Discarded skills that overlapped with EvoNexus builtins or were OMC meta-skills See [NOTICE.md](https://github.com/evolution-foundation/evo-nexus/blob/main/NOTICE.md) for the complete attribution and modification list. # Flux Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/flux Esta página ainda está em inglês. A tradução para português está em andamento. # Flux — Finance & CFO **Command:** `/flux-finance` | **Color:** orange | **Model:** Sonnet Flux is the virtual CFO — managing all financial operations including cash flow analysis, income statements, Stripe MRR tracking, Omie ERP integration, monthly closing processes, journal entries, reconciliation, and variance analysis. Flux ensures financial health is always visible and actionable. ## When to Use * Running the monthly closing process or checking close status * Reviewing financial health, cash flow, or MRR trends * Checking pending invoices, accounts payable, or receivable * Preparing journal entries or reconciling accounts * Analyzing budget vs. actual variances ## Preloaded Skills | Skill | What it does | | --------------------------- | -------------------------------------------------------- | | `fin-daily-pulse` | Daily financial snapshot from Stripe and Omie | | `fin-weekly-report` | Weekly consolidation of revenue, expenses, and cash flow | | `fin-monthly-close-kickoff` | Initiates month-end closing with checklist and P\&L | | `fin-close-management` | Track close tasks, dependencies, and status | | `fin-financial-statements` | Generate P\&L, balance sheet, and cash flow statements | | `fin-journal-entry` | Prepare journal entries with debits and credits | | `fin-journal-entry-prep` | Month-end entry preparation with supporting docs | | `fin-reconciliation` | GL vs subledger and bank reconciliation | | `fin-variance-analysis` | Budget vs actual decomposition with narratives | | `fin-audit-support` | SOX compliance documentation and support | | `fin-sox-testing` | Control testing sample selection and workpapers | | `int-stripe` | Stripe API — charges, subscriptions, MRR, churn | | `int-omie` | Omie ERP — clients, invoices, financials | ## Example Interactions ``` /flux-finance how's our cash flow this month? /flux-finance start the monthly closing for March /flux-finance what's our current MRR and churn rate? ``` ## Routines | Time | Routine | | ------------ | --------------------- | | Daily 19:00 | Financial Pulse | | Friday 07:30 | Financial Weekly | | 1st of month | Monthly Close Kickoff | ## Memory Persistent memory at `.claude/agent-memory/flux/`. Stores project context, user preferences, and feedback across sessions. # Kai Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/kai Esta página ainda está em inglês. A tradução para português está em andamento. # Kai — Personal Assistant **Command:** `/kai-personal-assistant` | **Color:** blue | **Model:** Sonnet Kai is your personal assistant — completely isolated from professional matters. It handles health tracking, habits, personal routines, appointments, and travel planning. Kai reads health data from `workspace/personal/data/health-data.js` and keeps your personal life organized without mixing it into work context. ## When to Use * Check your health progress or review recent health metrics * Schedule a blood test, doctor visit, or other medical appointment * Plan a personal trip or vacation itinerary * Review personal appointments for the week * Track habits and daily routines ## Preloaded Skills | Skill | What it does | | -------------- | ------------------------------------------------ | | `gog-calendar` | Manage personal appointments and schedule events | | `gog-tasks` | Create and organize personal to-do items | ## Example Interactions ``` /kai-personal-assistant how is my health progress this month? /kai-personal-assistant schedule a blood test for next Tuesday morning /kai-personal-assistant plan a 5-day trip to Lisbon in July ``` ## Routines | Day | Time | Routine | Make | | ------ | ----- | --------------- | ------------- | | Sunday | 10:00 | Health Check-in | `make health` | ## Memory Persistent memory at `.claude/agent-memory/kai/`. Stores project context, user preferences, and feedback across sessions. # Lex Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/lex Esta página ainda está em inglês. A tradução para português está em andamento. # Lex — Legal & Compliance **Command:** `/lex-legal` | **Color:** purple | **Model:** Sonnet Lex is the Legal and Compliance agent, handling contract review, NDA triage, LGPD compliance, risk assessment, legal briefs, vendor checks, and signature requests. He provides clause-by-clause analysis, flags regulatory concerns, and ensures legal workflows move efficiently from review to execution. ## When to Use * You need to review a contract and flag risky or non-standard clauses * An NDA arrived from a vendor and needs quick green/yellow/red classification * You want to run a LGPD or regulatory compliance check on a product feature or initiative * You need to assess the legal risk of a vendor agreement or partnership * You want to draft a legal brief or prepare for a meeting with legal context ## Preloaded Skills | Skill | What it does | | ------------------------- | -------------------------------------------------------------- | | `legal-review-contract` | Clause-by-clause contract review against negotiation playbook | | `legal-compliance-check` | Regulatory assessment for proposed actions or features | | `legal-triage-nda` | Quick NDA classification as green, yellow, or red | | `legal-brief` | Contextual legal briefings for daily work or incident response | | `legal-response` | Templated legal responses with escalation checks | | `legal-risk-assessment` | Severity x likelihood risk matrix with escalation criteria | | `legal-meeting-briefing` | Meeting prep with legal context and action item tracking | | `legal-signature-request` | E-signature workflow with pre-signature checklist | | `legal-vendor-check` | Vendor agreement audit across connected systems | | `ops-risk-assessment` | Operational risk evaluation and mitigation planning | | `ops-compliance-tracking` | Audit readiness tracking and compliance requirement monitoring | ## Example Interactions ``` /lex-legal review this contract and flag risky clauses /lex-legal triage the NDA we received from vendor X /lex-legal run a LGPD compliance check on the new analytics feature ``` ## Routines This agent is not used in any scheduled routines. ## Memory Persistent memory at `.claude/agent-memory/lex/`. Stores project context, user preferences, and feedback across sessions. # Mako Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/mako Esta página ainda está em inglês. A tradução para português está em andamento. # Mako — Marketing **Command:** `/mako-marketing` | **Color:** orange | **Model:** Sonnet Mako is the marketing agent — it handles campaigns, content strategy, brand voice, SEO, email sequences, competitive positioning, and performance reports. Mako helps you plan, create, and measure marketing efforts across all channels, ensuring consistency with your brand and strategic goals. ## When to Use * Create a campaign brief for a product launch or lead-gen initiative * Run an SEO audit on your blog or landing pages * Draft a multi-step email sequence for onboarding or nurture * Generate a marketing performance report with key metrics and trends * Build a content calendar aligned with your brand voice and pillars ## Preloaded Skills | Skill | What it does | | ------------------------ | ----------------------------------------------------------------------------- | | `mkt-brand-review` | Audit content against brand voice and style guide | | `mkt-campaign-plan` | Generate full campaign briefs with objectives, audience, and channel strategy | | `mkt-competitive-brief` | Research competitors and generate positioning comparisons | | `mkt-content-creation` | Draft marketing content across channels (blog, social, email, landing pages) | | `mkt-draft-content` | Write blog posts, social media, email newsletters, and press releases | | `mkt-email-sequence` | Design multi-email drip campaigns with timing and branching logic | | `mkt-performance-report` | Build marketing performance reports with trend analysis and recommendations | | `mkt-seo-audit` | Run comprehensive SEO audits with keyword research and technical checks | ## Example Interactions ``` /mako-marketing create a campaign brief for the Evo AI launch /mako-marketing run an SEO audit on our blog /mako-marketing draft a 5-email onboarding sequence for new users ``` ## Routines This agent is not used in any scheduled routines. ## Memory Persistent memory at `.claude/agent-memory/mako/`. Stores project context, user preferences, and feedback across sessions. # Mentor Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/mentor Esta página ainda está em inglês. A tradução para português está em andamento. # Mentor — Courses & Education **Command:** `/mentor-courses` | **Color:** purple | **Model:** Sonnet Mentor is the education agent focused on course creation, learning paths, study plans, and didactic material for the Evo Academy platform. It helps structure educational content from scratch, build progressive learning journeys, and produce lesson material that is clear, engaging, and well-organized. ## When to Use * You need to structure a new course from objectives to modules and lessons * You want to create a learning path that guides students through a topic progressively * You need to build a specific module or lesson about a given subject * You want to explain a technical concept in a way suitable for a course lesson * You need a study plan for learning a new technology or framework ## Preloaded Skills | Skill | What it does | | ----------------------- | ------------------------------------------------------------------------------------------- | | `obs-obsidian-markdown` | Create and edit Obsidian-flavored markdown content with wikilinks, callouts, and properties | | `obs-obsidian-cli` | Interact with Obsidian vaults — read, create, search, and manage notes | ## Example Interactions ``` /mentor-courses structure a course on building AI agents with the Evolution API /mentor-courses create a learning path for someone new to WhatsApp automation /mentor-courses build a module about webhook configuration for intermediate users ``` ## Routines This agent is not used in any scheduled routines. ## Memory Persistent memory at `.claude/agent-memory/mentor/`. Stores project context, user preferences, and feedback across sessions. # Nex Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/nex Esta página ainda está em inglês. A tradução para português está em andamento. # Nex — Sales **Command:** `/nex-sales` | **Color:** red | **Model:** Sonnet Nex is the sales agent responsible for pipeline management, lead qualification, proposal drafting, and commercial KPIs. It operates at L1 Observer level — meaning it generates reports and drafts for approval but never sends anything directly. Use Nex for all commercial and sales-related tasks. ## When to Use * You need a snapshot of the current sales pipeline status * You want to prepare or review a commercial proposal * You need to qualify a new lead or score existing ones * You want to track commercial KPIs (conversion rate, deal velocity, win rate) * You need to evaluate a vendor or compare vendor proposals ## Preloaded Skills | Skill | What it does | | ------------------- | ------------------------------------------------------------------------ | | `int-evo-crm` | Access CRM data — contacts, conversations, pipelines, stages, and labels | | `ops-vendor-review` | Evaluate vendors with cost analysis, risk assessment, and recommendation | ## Example Interactions ``` /nex-sales what's the current state of our sales pipeline? /nex-sales prepare a proposal for the HostGator partnership renewal /nex-sales qualify this lead: mid-size SaaS company, 50 employees, looking for WhatsApp automation ``` ## Routines This agent is not used in any scheduled routines. ## Memory Persistent memory at `.claude/agent-memory/nex/`. Stores project context, user preferences, and feedback across sessions. # Nova Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/nova Esta página ainda está em inglês. A tradução para português está em andamento. # Nova — Product Management **Command:** `/nova-product` | **Color:** blue | **Model:** Sonnet Nova is the Product Management agent, covering feature specs and PRDs, product metrics analysis, roadmap management, brainstorming sessions, stakeholder updates, and user research synthesis. She turns ideas into structured documents, keeps the roadmap current, and ensures stakeholders stay informed with data-driven updates. ## When to Use * You need to write a PRD or feature spec from a problem statement or idea * You want to review sprint or product metrics and spot trends * The roadmap needs updating after new priorities or market changes * You want to brainstorm ideas for a new feature or product direction * You need to prepare a stakeholder update on quarterly progress ## Preloaded Skills | Skill | What it does | | -------------------------- | ----------------------------------------------------------- | | `pm-write-spec` | Creates feature specs and PRDs from problem statements | | `pm-metrics-review` | Analyzes product metrics with trend detection and insights | | `pm-roadmap-update` | Manages roadmap priorities, additions, and trade-offs | | `pm-product-brainstorming` | Facilitates structured ideation and problem exploration | | `pm-stakeholder-update` | Generates audience-tailored status updates | | `pm-synthesize-research` | Synthesizes interviews, surveys, and feedback into insights | | `int-linear-review` | Tracks sprint progress, issues, and blockers in Linear | | `mkt-competitive-brief` | Competitive positioning and messaging comparison | | `evo-sprint-planning` | Sprint planning and task generation from epics | ## Example Interactions ``` /nova-product write a PRD for the new agent builder feature /nova-product review sprint metrics and highlight risks /nova-product brainstorm ideas for improving the onboarding flow ``` ## Routines This agent is not used in any scheduled routines. ## Memory Persistent memory at `.claude/agent-memory/nova/`. Stores project context, user preferences, and feedback across sessions. # Oracle Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/oracle Esta página ainda está em inglês. A tradução para português está em andamento. # Oracle — Workspace Knowledge **Command:** `/oracle` | **Color:** amber | **Model:** Sonnet Oracle is the workspace knowledge agent — it answers questions about EvoNexus itself. Agents, skills, routines, integrations, the dashboard, configuration, and architecture are all in its domain. Oracle reads documentation before answering and never guesses. If it does not find the answer in the docs, it says so. ## When to Use * Understand how to create a new routine, agent, or skill * Find out what agents are available and what each one does * Learn how the scheduler works or how routines are triggered * Check what skills a specific agent has access to * Discover how to add a new integration or configure an existing one ## Preloaded Skills | Skill | What it does | | ---------------- | ------------------------------------------------------------------------- | | `initial-setup` | Onboard new users — introduce agents, skills, routines, and the dashboard | | `create-agent` | Guided wizard to create a new custom agent | | `create-command` | Create a new slash command for Claude Code | | `create-routine` | Guided wizard to create a new automated routine | ## Example Interactions ``` /oracle how do I create a new routine? /oracle what skills does Flux have? /oracle how do I add a new MCP integration? ``` ## Routines This agent is not used in any scheduled routines. ## Memory Oracle has no persistent agent memory. It reads documentation on every invocation to provide accurate, up-to-date answers rather than building institutional knowledge. # Pixel Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/pixel Esta página ainda está em inglês. A tradução para português está em andamento. # Pixel — Social Media **Command:** `/pixel-social-media` | **Color:** yellow | **Model:** Sonnet Pixel is the social media agent responsible for content creation, editorial calendar management, and cross-platform analytics. It covers YouTube, Instagram, LinkedIn, Twitter/X, Threads, and Bluesky — writing posts, threads, and carousels, analyzing engagement metrics, tracking audience growth, and generating unified performance reports across all platforms. ## When to Use * You need to write a LinkedIn post, Twitter thread, or carousel * You want to create or update a content calendar for the week/month * You need a cross-platform analytics report or platform-specific report (YouTube, Instagram, LinkedIn) * You want to repurpose a blog post or video into social media content * You need recommendations on what's working and how to improve engagement ## Preloaded Skills | Skill | What it does | | --------------------------------- | -------------------------------------------------------- | | `social-post-writer` | Write posts for LinkedIn, Twitter/X, Threads, or Bluesky | | `social-thread-writer` | Create multi-part threads for Twitter/X or LinkedIn | | `social-carousel-writer` | Build LinkedIn carousel slide content | | `social-hook-writer` | Craft attention-grabbing opening lines | | `social-content-calendar` | Plan and organize a posting schedule | | `social-content-strategy` | Define topic clusters and content mix | | `social-content-repurposer` | Adapt one piece of content across multiple platforms | | `social-content-pattern-analyzer` | Identify what content types and topics perform best | | `social-performance-analyzer` | Analyze post-level metrics and engagement | | `social-optimization-advisor` | Get concrete improvement recommendations | | `social-platform-strategy` | Platform-specific tactical guidance | | `social-audience-growth-tracker` | Track and analyze follower growth trends | | `social-context` | Set up or update profile, voice, and audience context | | `social-analytics-report` | Unified cross-platform analytics dashboard | | `social-instagram-report` | Instagram-specific analytics report | | `social-linkedin-report` | LinkedIn-specific analytics report | | `social-youtube-report` | YouTube-specific analytics report | | `int-instagram` | Query Instagram Graph API for metrics and insights | | `int-linkedin` | Query LinkedIn API for profile and org stats | | `int-youtube` | Query YouTube Data API for channel and video stats | ## Example Interactions ``` /pixel-social-media write a LinkedIn post about our new AI agents feature /pixel-social-media create a content calendar for next week /pixel-social-media youtube report — how did our channel perform this month? ``` ## Routines | Time | Routine | Command | | ------------ | ------------------------ | ------------- | | Daily 18:00 | Social Analytics | `make social` | | Friday 08:15 | Social Analytics Weekly | `make social` | | 1st of month | Social Analytics Monthly | `make social` | ## Memory Persistent memory at `.claude/agent-memory/pixel/`. Stores project context, user preferences, and feedback across sessions. # Pulse Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/pulse Esta página ainda está em inglês. A tradução para português está em andamento. # Pulse — Community **Command:** `/pulse-community` | **Color:** blue | **Model:** Sonnet Pulse is the community monitoring agent — tracking Discord channels, WhatsApp groups, sentiment analysis, FAQ management, and engagement metrics. Pulse keeps a finger on the community's pulse, surfacing recurring questions, emerging issues, and contributor highlights so nothing important gets missed. ## When to Use * Checking how the community is doing overall * Identifying frequently asked questions or recurring support topics * Analyzing sentiment trends across Discord and WhatsApp * Investigating community issues or escalations * Generating monthly engagement summaries or creating community updates ## Preloaded Skills | Skill | What it does | | ------------------------ | -------------------------------------------------- | | `pulse-daily` | 24h community pulse across Discord and WhatsApp | | `pulse-weekly` | Weekly engagement analysis and trends | | `pulse-monthly` | Monthly community report with growth and sentiment | | `pulse-faq-sync` | Update FAQ from recurring community questions | | `discord-get-messages` | Read and search Discord channel messages | | `discord-send-message` | Post messages to Discord channels | | `discord-list-channels` | Audit server channel structure | | `discord-create-channel` | Create new Discord channels | | `discord-manage-channel` | Update channel settings and permissions | | `int-whatsapp` | WhatsApp group messages and stats | ## Example Interactions ``` /pulse-community how's the community doing this week? /pulse-community what are the most frequent questions in Discord? /pulse-community generate the monthly engagement summary ``` ## Routines | Time | Routine | | ------------ | ----------------- | | Daily 20:00 | Community Pulse | | Daily 20:15 | FAQ Sync | | Monday 09:30 | Community Weekly | | 1st of month | Community Monthly | ## Memory Persistent memory at `.claude/agent-memory/pulse/`. Stores project context, user preferences, and feedback across sessions. # Sage Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/sage Esta página ainda está em inglês. A tradução para português está em andamento. # Sage — Strategy **Command:** `/sage-strategy` | **Color:** orange | **Model:** Sonnet Sage is the senior strategist agent. It handles OKR tracking, competitive analysis, roadmap planning, decision frameworks, and weekly strategy digests that synthesize financial, product, and community data into actionable strategic insights. Use Sage when you need to think about the big picture, weigh trade-offs, or make informed decisions about company direction. ## When to Use * You need to decide whether to prioritize initiative X over Y * You want to review OKR progress or define new quarterly objectives * You need a competitive landscape analysis or market positioning review * You want a strategy digest that consolidates data across all domains * You need a decision framework for a partnership, monetization approach, or negotiation ## Preloaded Skills | Skill | What it does | | --------------------------- | ---------------------------------------------------------------------------- | | `sage-strategy-digest` | Weekly strategic synthesis of financial, product, community, and market data | | `sage-okr-review` | Track OKR progress, update key results, and flag at-risk objectives | | `sage-competitive-analysis` | Analyze competitors and evaluate market positioning | ## Example Interactions ``` /sage-strategy should we prioritize the self-hosted plan or the managed cloud offering? /sage-strategy OKR progress — how are we tracking for Q2? /sage-strategy competitive analysis of the AI CRM space ``` ## Routines | Day | Routine | Command | | ------------ | --------------- | --------------- | | Friday 09:00 | Strategy Digest | `make strategy` | ## Memory Persistent memory at `.claude/agent-memory/sage/`. Stores project context, user preferences, and feedback across sessions. # Zara Source: https://docs.evolutionfoundation.com.br/evo-nexus/agents/zara Esta página ainda está em inglês. A tradução para português está em andamento. # Zara — Customer Success **Command:** `/zara-cs` | **Color:** cyan | **Model:** Sonnet Zara is the Customer Success agent, responsible for ticket triage, escalation packaging, customer research, draft responses, knowledge base articles, and CRM integration. She ensures support tickets are prioritized correctly, customers get professional replies, and recurring issues are captured as self-service documentation. ## When to Use * You need to triage open support tickets and assign priority levels (P1-P4) * You want to draft a professional response to a customer complaint (e.g., downtime, billing issue) * A bug or incident needs to be escalated to engineering or product with full context * A resolved ticket should be turned into a knowledge base article for self-service * You want to identify which customers are at churn risk based on recent interactions ## Preloaded Skills | Skill | What it does | | ------------------------ | ------------------------------------------------------------------------- | | `cs-ticket-triage` | Classifies and prioritizes support tickets from P1 (critical) to P4 (low) | | `cs-customer-escalation` | Packages escalations with full context for devs or product teams | | `cs-customer-research` | Multi-source lookup to gather customer history and context | | `cs-draft-response` | Generates professional, situation-aware customer replies | | `cs-kb-article` | Creates knowledge base articles from resolved issues | | `int-evo-crm` | Accesses CRM data for customer records, conversations, and pipelines | ## Example Interactions ``` /zara-cs triage the open support tickets from today /zara-cs draft a response for the customer reporting downtime on instance X /zara-cs escalate the authentication bug to engineering with full context ``` ## Routines This agent is not used in any scheduled routines. ## Memory Persistent memory at `.claude/agent-memory/zara/`. Stores project context, user preferences, and feedback across sessions. # Env editor Source: https://docs.evolutionfoundation.com.br/evo-nexus/dashboard/env-editor Esta página ainda está em inglês. A tradução para português está em andamento. # Settings The **Settings** page (`/settings`) is the central configuration hub for the workspace. It replaces the old Config page and provides three tabs. ## Workspace Tab Edit `config/workspace.yaml` fields: | Field | Description | | ------------------ | ----------------------------------------------------------------------------- | | **Workspace Name** | Display name for the workspace | | **Owner** | Workspace owner name | | **Company** | Organization name | | **Language** | Response language (20 options: pt-BR, en-US, es, fr, de, ja, ko, zh-CN, etc.) | | **Timezone** | Schedule timezone (default: America/Sao\_Paulo) | | **Dashboard Port** | Port the dashboard runs on (default: 8080) | Changes are saved to `config/workspace.yaml` using a read-merge-write pattern that preserves other YAML keys. ## Routines Tab View and manage all scheduled routines from `config/routines.yaml`: * **Toggle switch** — enable or disable any routine instantly * **Inline schedule edit** — click the time/interval to edit, press Enter to save * **Grouped by frequency** — daily, weekly, and monthly sections * **Agent badges** — shows which agent owns each routine * **Reload scheduler** — after changes, the scheduler is automatically notified via sentinel file Routine creation and deletion are handled by agents (via the `create-routine` skill), not the UI. ## Reference Tab Read-only views of key configuration files: * **CLAUDE.md** — rendered workspace instructions * **Makefile targets** — all available `make` commands * **Commands** — slash command definitions ## API Reference ### Workspace ``` GET /api/settings/workspace — read workspace config PUT /api/settings/workspace — update workspace fields ``` ### Routines ``` GET /api/settings/routines — list all routines PATCH /api/settings/routines///toggle — toggle enabled PUT /api/settings/routines// — update schedule/fields ``` ### Scheduler ``` POST /api/settings/scheduler/reload — trigger scheduler reload ``` All write endpoints require authentication and `config:manage` permission. # Knowledge Source: https://docs.evolutionfoundation.com.br/evo-nexus/dashboard/knowledge Esta página ainda está em inglês. A tradução para português está em andamento. # Knowledge Base (pgvector) The Knowledge Base page provides **multi-server hybrid search** (vector + BM25) over your documents with OCR, chunking, and async classification. It is powered by **pgvector** on Postgres — Bring Your Own Database (BYO). > Different from [MemPalace](knowledge-base.md): MemPalace is offline/local for personal notes; Knowledge is multi-tenant, API-first, for teams and external integrations (Evo Academy, client knowledge bases). ## Architecture at a glance ``` EvoNexus (client-only) ├── SQLite local: knowledge_connections (credentials encrypted at rest) ├── Flask API: /api/knowledge/* (internal) + /api/knowledge/v1/* (external, API keys) ├── Worker subprocess: parse → chunk → embed → enqueue classify ├── Classify worker: async LLM classification (content_type, difficulty, topics) └── Skills: knowledge-{query,summarize,ingest,reindex,browse,organize,admin} Your Postgres (not managed by EvoNexus) ├── pgvector extension ├── Tables: knowledge_{config,spaces,units,documents,chunks,api_keys,api_usage,classify_queue} └── Alembic-managed schema ``` **EvoNexus does NOT install or run Postgres.** You bring your own (Supabase, Neon, RDS, self-hosted). EvoNexus connects, auto-migrates the schema, and uses it. ## First-time setup ### 1. Encryption key (auto-generated) Since v0.26.0, `KNOWLEDGE_MASTER_KEY` is generated automatically on first setup (`make setup` wizard) and on Docker first boot (`entrypoint.sh`). You do NOT need to run `make init-key` manually on fresh installs. **Back up your `.env`** — losing `KNOWLEDGE_MASTER_KEY` loses access to all encrypted credentials. > Legacy: if you need to regenerate (lost key, rotated secrets), the CLI is still available: `make init-key` / `evonexus init-key`. Idempotent — preserves an existing key. ### 2. Prepare your Postgres You need: * **Postgres ≥ 14** * **pgvector ≥ 0.5** extension installed (`CREATE EXTENSION vector;`) * A **database** already created * A user with `CONNECT`, `CREATE`, and ideally `CREATE EXTENSION` permissions EvoNexus does NOT create databases — you must create the DB first. ### 3. Connect via UI or skill **UI:** navigate to `/knowledge` → Connections → **+ New Connection** → fill credentials → **Connect & Configure**. **Skill:** ``` /knowledge-admin action=connect ``` The skill walks you through the wizard interactively. ### 4. Create a space Spaces are logical groupings inside a connection (e.g., "academy", "support-kb", "sales-playbook"). Create via UI or: ``` /knowledge-organize action=create space_id= slug= title="..." ``` ## Concepts | Concept | Description | | -------------- | ---------------------------------------------------------------------- | | **Connection** | One Postgres + pgvector server. You can have many. | | **Space** | Logical grouping inside a connection (ex: "academy", "community"). | | **Unit** | Learning unit / module grouping documents (ex: "Module 3 — WhatsApp"). | | **Document** | Uploaded file (PDF, DOCX, etc.) — gets parsed, chunked, embedded. | | **Chunk** | Content piece (\~500 tokens) with embedding, used for search. | ## Parser **Marker** (MIT, \~500MB model bundle) is the default parser. Supports PDF, DOCX, PPTX, XLSX, HTML, EPUB, images (with OCR). First use: click **Install Parser Models** in UI or run: ``` /knowledge-admin action=install-parser ``` Download takes a few minutes. Idempotent — re-running is a no-op. **LlamaParse** (optional, cloud API) available if you set `LLAMAPARSE_API_KEY`. ## Embedder * **local** (default, 768 dim): `sentence-transformers/paraphrase-multilingual-mpnet-base-v2`. Free, offline, pt-BR native. * **openai** (opt-in, 1536 dim): `text-embedding-3-small`. Costs \~\$0.02 / 1M tokens. Requires `OPENAI_API_KEY`. * **gemini** (opt-in, 768 / 1536 / 3072 dim via MRL): `gemini-embedding-001` (stable, text-only, task-type aware) or `gemini-embedding-2-preview` (multimodal, 8192-token input). Requires `GEMINI_API_KEY` (free tier on [aistudio.google.com/apikey](https://aistudio.google.com/apikey)). Default dim is 768 to align storage cost with `local`. **Embedder is GLOBAL per EvoNexus instance.** Changing it after you have data requires removing all connections and recreating them (reindex skill planned for v0.25.1). ## Search: hybrid + metadata boost Query combines **3 signals** via Reciprocal Rank Fusion (RRF): 1. **Vector similarity** (HNSW cosine) 2. **BM25** (Postgres `tsvector` em português) 3. **Content-type boost** (configurable per space): | content\_type | default boost | | ------------- | ------------- | | faq | 1.20 | | reference | 1.15 | | lesson | 1.10 | | tutorial | 1.05 | | article | 1.00 | | decision | 1.00 | | note | 0.90 | | transcript | 0.80 | Override boosts per space via `content_type_boosts` JSONB column. ## Skills | Skill | Group | Purpose | | ------------------------------------------------------------------------ | --------- | -------------------------------------------------------- | | [knowledge-query](../../.claude/skills/knowledge-query/SKILL.md) | Consumo | Hybrid search + optional RAG answer | | [knowledge-summarize](../../.claude/skills/knowledge-summarize/SKILL.md) | Consumo | TL;DR of document or unit | | [knowledge-ingest](../../.claude/skills/knowledge-ingest/SKILL.md) | Ingestão | Upload file or URL | | knowledge-reindex | Ingestão | Re-parse/re-embed (single or bulk) — deferred to v0.25.1 | | [knowledge-browse](../../.claude/skills/knowledge-browse/SKILL.md) | Curadoria | List/filter docs + units | | [knowledge-organize](../../.claude/skills/knowledge-organize/SKILL.md) | Curadoria | Units: create/move/reorder/link | | [knowledge-admin](../../.claude/skills/knowledge-admin/SKILL.md) | Admin | Connections, health, stats, export, parser install | All skills auto-use the first `ready` connection. Pass `connection="slug"` to target a specific one. ## Authentication Two modes — clear separation: * **`DASHBOARD_API_TOKEN`** (existing, in `.env`) → internal use by skills, heartbeats, routines. **Bypasses rate limit.** * **`knowledge_api_keys`** → external use (Academy app, webhooks, third-party). Scoped by `connection_id` + `space_ids`. Rate-limited (fixed window). Create API keys via UI (`/knowledge/api-keys`) or via the REST API. ### Example (external — Evo Academy calling Knowledge) ```bash theme={null} curl -H "Authorization: Bearer evo_k_abc.xyz..." \ -H "Content-Type: application/json" \ -H "X-Knowledge-Connection: academy" \ -d '{"query": "how does onboarding work?", "space": "aulas-2026"}' \ https://evonexus.local/api/knowledge/v1/search ``` ## Permissions | Permission | Who has it | What it allows | | ------------------ | ----------------------- | ----------------------------------------------------- | | `knowledge:view` | admin, operator, viewer | View connections, spaces, search | | `knowledge:manage` | admin | Create connections, upload, delete, generate API keys | ## API endpoints ### Internal (UI-only, session auth) | Method | Endpoint | Description | | -------- | ------------------------------------------ | ------------------------- | | GET/POST | `/api/knowledge/connections` | List/create connections | | POST | `/api/knowledge/connections/:id/configure` | Run auto-migration | | GET | `/api/knowledge/connections/:id/health` | Health check | | CRUD | `/api/knowledge/api-keys` | Manage tokens | | GET/PUT | `/api/knowledge/settings` | Embedder + parser globals | ### Public v1 (Bearer token) | Method | Endpoint | Description | | ------ | ---------------------------------------- | ---------------------------- | | CRUD | `/api/knowledge/v1/spaces` | Spaces | | CRUD | `/api/knowledge/v1/units` | Learning units | | CRUD | `/api/knowledge/v1/documents` | Documents (upload multipart) | | POST | `/api/knowledge/v1/search` | Hybrid search | | GET | `/api/knowledge/v1/documents/:id/status` | Ingestion progress | ## Troubleshooting **"PgBouncer detected"** — Supabase pooler (port 6543) is not supported. Use direct connection (port 5432). Same for AWS RDS Proxy. **Connection status `needs_migration`** — EvoNexus was upgraded and remote schema is old. Click **Run migrations** in UI or `POST /connections/:id/migrate`. **Marker timeout on large PDFs** — default 10min. Adjust `MARKER_TIMEOUT_SECONDS` in `.env`. **Classify queue stuck** — check if `ANTHROPIC_API_KEY` or `GEMINI_API_KEY` is set. Without either, classification is skipped (not fatal). **Embedder provider locked** — you have data using current dim. To change the provider, remove all connections and recreate them. Reindex skill is planned for v0.25.1. # Knowledge base Source: https://docs.evolutionfoundation.com.br/evo-nexus/dashboard/knowledge-base Esta página ainda está em inglês. A tradução para português está em andamento. # Knowledge Base (MemPalace) The Knowledge Base page provides semantic search over your code, documentation, and project knowledge. It is powered by **[MemPalace](https://github.com/milla-jovovich/mempalace)**, an open-source local memory system that indexes content into a searchable vector database. > **GitHub:** [github.com/milla-jovovich/mempalace](https://github.com/milla-jovovich/mempalace) — MIT License, 27k+ stars Everything runs locally — no external APIs, no data leaves your machine. Knowledge Base ## Enabling MemPalace MemPalace is an **optional** feature. When you first visit the Knowledge Base page, you'll see an "Enable MemPalace" button. 1. Go to **Dashboard > Knowledge** 2. Click **Install MemPalace** 3. Wait for the installation to complete (installs via pip) **Requirements:** Python 3.9+ The installation adds the `mempalace` package and its dependency `chromadb` (the vector database engine). ## How It Works MemPalace organizes knowledge using a "memory palace" metaphor: | Concept | Description | | ---------- | ---------------------------------------------------------------------- | | **Wing** | A project or top-level category (e.g., `evo-ai`, `docs`) | | **Room** | A topic within a wing (e.g., `technical`, `architecture`, `decisions`) | | **Drawer** | A chunk of content (\~800 characters) stored with metadata | When you index a directory, MemPalace: 1. Scans all files (respecting `.gitignore`) 2. Splits content into chunks of \~800 characters 3. Classifies each chunk into a room based on content and file path 4. Stores vector embeddings in ChromaDB for semantic search All data is stored locally at `dashboard/data/mempalace/`. ## Adding Sources Sources are directories you want to index — project code, documentation folders, etc. 1. Go to the **Sources** tab 2. Enter the **directory path** (absolute path on your machine) 3. Optionally set a **label** (display name) and **wing override** (custom project name) 4. Click **Add** MemPalace only re-processes files that have changed since the last indexing, so re-indexing is fast. ## Indexing (Mining) After adding sources, click the **Play** button next to a source to index it, or use **Index All** to process everything. Mining runs in the background — you can navigate away and check progress on the **Status** tab. The status indicator shows when mining is active. ## Searching The **Search** tab provides semantic search across all indexed content: 1. Type your query in natural language (e.g., "how does authentication work") 2. Optionally filter by **wing** (project) or **room** (category) 3. Press Enter or click **Search** Results show: * The matched content snippet * Source file path * Similarity score (higher = more relevant) * Wing and room tags Semantic search finds results by meaning, not just keyword matching. For example, searching "auth" will also find content about "login", "session tokens", and "JWT". ## Permissions | Permission | Who has it | What it allows | | ------------------ | ----------------------- | ----------------------------------------- | | `mempalace:view` | admin, operator, viewer | View status, sources, and search | | `mempalace:manage` | admin | Install, add/remove sources, run indexing | ## API Endpoints All endpoints require authentication and appropriate permissions. | Method | Endpoint | Description | | -------- | ----------------------------- | --------------------------------------------------------- | | `GET` | `/api/mempalace/status` | Installation status, palace stats, mining status | | `POST` | `/api/mempalace/install` | Install MemPalace package | | `GET` | `/api/mempalace/sources` | List configured sources | | `POST` | `/api/mempalace/sources` | Add a new source directory | | `DELETE` | `/api/mempalace/sources/:idx` | Remove a source by index | | `POST` | `/api/mempalace/mine` | Start indexing (background process) | | `GET` | `/api/mempalace/search?q=...` | Semantic search with optional `wing`, `room`, `n` filters | ## MCP Integration For advanced users, MemPalace can also be registered as an MCP server for direct Claude Code access: ```bash theme={null} claude mcp add mempalace -- python -m mempalace.mcp_server --palace dashboard/data/mempalace ``` This enables Claude to query your knowledge base directly during conversations. # Visão Geral do Dashboard Source: https://docs.evolutionfoundation.com.br/evo-nexus/dashboard/overview O dashboard web do EvoNexus — interface visual para gerenciar agentes, rotinas, integrações e mais # Visão Geral do Dashboard O dashboard web do EvoNexus é uma aplicação React + Flask que oferece uma interface visual para gerenciar agentes, rotinas, integrações, memória e mais. ## Iniciando o Dashboard ```bash theme={null} make dashboard-app ``` Isso inicia o backend Flask (com suporte a WebSocket) e serve o frontend React em uma única porta. Padrão: `http://localhost:8080`. ### Mudando a Porta Defina a porta em `config/workspace.yaml`: ```yaml theme={null} dashboard: port: 8080 ``` Ou via variável de ambiente: ```bash theme={null} EVONEXUS_PORT=9090 make dashboard-app ``` ## Setup na Primeira Execução Quando não há usuários no banco, o dashboard redireciona para um wizard de setup em `/setup`. O wizard passa por: 1. **Informações do workspace** — nome, empresa, fuso horário 2. **Conta admin** — crie seu primeiro usuário (username + senha) 3. **Agentes** — escolha quais dos 17 agentes habilitar 4. **Integrações** — selecione quais serviços conectar Após o setup terminar, você está logado como admin e tem acesso a todas as páginas. ## Páginas do Dashboard ### Overview Dashboard de métricas unificado. Mostra dados agregados de todos os agentes — snapshot financeiro, saúde da comunidade, status de projetos, alcance social. É a página inicial após o login. Overview ### Systems Registre apps e serviços externos que seu time usa. Cada sistema tem nome, URL, tipo (container Docker, URL externa ou iframe) e ícone. Útil para links rápidos a ferramentas como Grafana, Portainer ou apps internos. Lista de Systems App Systems ### Reports Navegue pelos relatórios HTML gerados pelas rotinas automatizadas. Os relatórios são armazenados em subpastas de `workspace/` e exibidos com data, agente e tipo. Clique em qualquer relatório para abrir o HTML completo em uma nova aba. Lista de Reports Report aberto ### Agents Visualize as definições dos 17 agentes. Cada card mostra o nome do agente, slash command, domínio e o system prompt completo (carregado de `.claude/agents/`). Agentes core têm ícones e cores dedicados; agentes customizados aparecem com badge cinza. Agents ### Routines Métricas de cada rotina automatizada: total de execuções, taxa de sucesso, duração média, uso de tokens e custo. Inclui um botão "Run Now" para disparar qualquer rotina manualmente. Routines ### Tasks Crie e gerencie ações agendadas pontuais. Agende uma skill, prompt ou script para rodar em uma data/hora específica. Filtre por status (pending, running, completed, failed), crie novas tasks, execute imediatamente ou veja resultados. Veja [Scheduled Tasks](../routines/scheduled-tasks) para detalhes. Tasks ### Triggers Triggers reativos por evento — webhooks e eventos. Crie triggers que executam skills ou rotinas em resposta a eventos externos (push no GitHub, pagamento no Stripe, atualizações no Linear). Filtre por tipo (webhooks, eventos), status (enabled, disabled) e gerencie configurações. Triggers ### Skills Navegue por todas as skills instaladas, agrupadas por prefixo (`social-`, `fin-`, `int-`, `prod-`, etc). Clique em uma skill para ver descrição completa, condições de trigger e arquivo de origem. Skills ### Templates Faça preview dos templates HTML de relatório em `.claude/templates/html/`. Veja como cada template renderiza antes que as rotinas o usem. Templates ### Services Inicie e pare serviços em background (scheduler, bot do Telegram) direto da UI. Mostra logs ao vivo via WebSocket. Indicadores de status mostram se cada serviço está rodando. Services ### Workspace Navegue pelos relatórios e arquivos de saída do workspace, organizados por domínio (community, courses, daily-logs, finance, meetings, personal, projects, social, strategy). Navegue por pastas, filtre arquivos e abra relatórios direto do dashboard. Workspace ### Memory Navegue pelo sistema de memória de duas camadas: * **CLAUDE.md** — memória de trabalho, carregada toda sessão * **memory/** — arquivos detalhados (pessoas, projetos, glossário, tendências) * **Memória de agente** — contexto por agente em `.claude/agent-memory/` Memory ### Knowledge Base Busca semântica opcional via [MemPalace](https://github.com/milla-jovovich/mempalace). Habilite com um clique, adicione diretórios (código, docs, notas) como fontes, indexe-os e busque por significado — não só palavras-chave. Tudo roda localmente usando vetores ChromaDB. Veja [knowledge-base](knowledge-base) para detalhes. Knowledge Base ### Integrations Painel de status para todas as 18 integrações. Mostra quais estão conectadas (verde), quais precisam de configuração (amarelo) e quais estão desabilitadas. Contas de redes sociais (YouTube, Instagram, LinkedIn) podem ser conectadas via OAuth direto desta página. Integrations ### Providers Escolha e configure qual backend LLM alimenta o EvoNexus — Anthropic (padrão) ou qualquer um dos 6 alternativos via [OpenClaude](https://www.npmjs.com/package/@gitlawb/openclaude): OpenRouter, OpenAI, Gemini, Codex Auth, AWS Bedrock, Vertex AI. Cada card de provedor mostra status de instalação (claude vs openclaude), flags configurado/não-configurado e um botão Test que executa ` --version` com o env mesclado. Trocar provedor tem efeito imediato — tanto o terminal-server quanto o ADW runner releem `config/providers.json` a cada nova sessão, sem restart. Secrets são mascarados na UI e em toda resposta da API. Veja [providers](providers) para a referência completa. ### Chat Terminal Claude Code embutido com xterm.js + WebSocket. Execute comandos do Claude Code, invoque agentes via slash commands e veja o output em tempo real — tudo no navegador. Chat ### Users Página de gestão de usuários (apenas admin). Crie, edite, desative usuários. Atribua roles. Veja timestamps do último login. Users ### Roles Defina roles customizadas com matriz granular de permissões. Cada role mapeia recursos (chat, services, reports, etc.) para ações (view, execute, manage). Roles built-in (admin, operator, viewer) não podem ser deletadas mas podem ser clonadas. Roles ### Costs Acompanhamento de uso de tokens e custo por rotina. Exibe gráficos com tendências de custo no tempo, breakdown de consumo de tokens (input vs output) e comparação de custo por rotina. Útil para monitorar gastos com a API do Claude entre workflows automatizados. Costs ### Files Navegue pelos arquivos do workspace direto do dashboard. Navegue na estrutura de pastas, faça preview de arquivos e entenda como o workspace está organizado sem precisar de acesso ao terminal. Files ### Scheduler Gerencie serviços em background e rotinas agendadas. Mostra todas as rotinas registradas com badges core/custom, suas agendas, estado enabled/disabled e status da última execução. Inicie, pare ou dispare rotinas desta página. ### Audit Log Trilha completa de auditoria de todas as ações: logins, mudanças de config, execuções de rotinas, gestão de usuários. Filtrável por usuário, ação, recurso e período. Audit Log ### Backups Exporte e restaure dados do workspace (todos os arquivos gitignored do usuário). Crie backups locais, baixe ZIPs, restaure em modo merge ou replace. Mostra status da configuração S3 quando o backup em nuvem está disponível. A rotina de backup diário roda automaticamente às 21:00. ### Settings Hub de configuração do workspace com três abas: * **Workspace** — edite nome do workspace, dono, empresa, idioma, fuso horário e porta do dashboard (`config/workspace.yaml`) * **Routines** — ative/desative rotinas, edite agendas inline, veja agentes e scripts (`config/routines.yaml`). Mudanças disparam reload automático do scheduler. * **Reference** — visualizações read-only de CLAUDE.md, targets do Makefile e slash commands # Providers Source: https://docs.evolutionfoundation.com.br/evo-nexus/dashboard/providers Esta página ainda está em inglês. A tradução para português está em andamento. # AI Providers The **Providers** page lets you choose which LLM backend powers EvoNexus, configure its credentials, and test the connection — all from the dashboard. It lives under **System → Providers** in the sidebar and requires the `config:manage` permission. EvoNexus uses Anthropic's `claude` CLI by default. To run on any other backend (OpenRouter, OpenAI, Gemini, AWS Bedrock, Google Vertex AI, Codex Auth), it switches to [OpenClaude](https://www.npmjs.com/package/@gitlawb/openclaude) — a drop-in binary that speaks the same CLI protocol but dispatches to the provider of your choice via environment variables. ## Supported Providers | Provider | Binary | Notes | | ----------------------- | ------------ | ---------------------------------------------------------- | | **Anthropic** (default) | `claude` | Native Anthropic auth, no extra config | | **OpenRouter** | `openclaude` | 200+ models via one API — Claude, GPT, Gemini, Llama, etc. | | **OpenAI** | `openclaude` | GPT-4o, GPT-4.1, o3 via OpenAI API | | **Google Gemini** | `openclaude` | Gemini 2.5 Pro/Flash via Google AI | | **Codex Auth** | `openclaude` | Reuses Codex CLI's OAuth session to access OpenAI models | | **AWS Bedrock** | `openclaude` | Claude via AWS Bedrock | | **Google Vertex AI** | `openclaude` | Claude via GCP Vertex AI | ## Install OpenClaude (one-time) If you plan to use any non-Anthropic provider, install OpenClaude globally: ```bash theme={null} npm install -g @gitlawb/openclaude ``` The Providers page shows a banner at the top indicating whether `claude` and `openclaude` are installed and in `$PATH`. If `openclaude` is missing, the banner shows the install command. ## Activating a Provider 1. Open **System → Providers** in the sidebar 2. Click **Configure** on the provider you want to use 3. Fill in the required fields (API key, base URL, model, region — depending on provider). Secrets are masked in the form and in every API response; placeholders like `sk-...` guide the format 4. Click **Save & Activate** The active provider is stored in `config/providers.json`. Both the terminal-server and the ADW runner re-read this file on every session spawn, so switching takes effect **immediately** — no restart needed. A green "Active" badge marks the currently selected provider. Every other provider can still be configured and tested without affecting the active one. ## Testing a Provider Each provider card has a **Test** button that runs ` --version` with the configured env vars merged into the environment, then reports success or failure inline. This is a sanity check — it verifies that the binary is installed, in `$PATH`, and that the env var injection works. It does **not** validate that your API key actually authenticates against the remote service (use the terminal after activating for that). ## Security: Allowlists and Secret Masking Both the Python runner (`ADWs/runner.py`) and the JS terminal bridge (`dashboard/terminal-server/src/claude-bridge.js`) enforce two allowlists when reading `config/providers.json`: * **CLI allowlist** — only `claude` and `openclaude` are accepted as spawn targets. Any other value falls back to `claude`. * **Env var allowlist** — only the 13 variables listed in [env-variables.md](../reference/env-variables.md#ai-provider-configuration) are injected. Anything else is silently dropped. The REST API that backs the Providers page masks secrets (`*_KEY`, `*_SECRET`, `*_TOKEN`) as `first6****last4` on every response. When you open the config modal, the form starts empty for those fields — type a new value to replace, or leave empty to keep the current one. Values containing `****` are treated as masked placeholders and skipped on save (so a round-trip through the UI doesn't accidentally overwrite a real secret with the mask string). The backend also rejects any env var value containing shell metacharacters (`;`, `&`, `|`, backtick, `$`, newlines) — defense in depth against injection if someone points EvoNexus at a compromised `providers.json`. ## Logout Warning When you switch away from Anthropic to any other provider, OpenClaude inherits your Anthropic Claude Code login state. To avoid confusion, run `/logout` inside Claude Code **once** after activating a non-Anthropic provider if you were previously logged in. The dashboard surfaces this warning on any provider marked `requires_logout`. ## Where It's Stored * `config/providers.json` — active provider + per-provider CLI + env vars (**gitignored**, contains secrets) * `config/providers.example.json` — template copied on first boot if no real file exists (checked into git) * `.env` — unchanged by this feature. AI provider env vars live in `providers.json`, not `.env` ## Configuring at Install Time The interactive setup wizard (`make setup`) asks which provider to use as step 3. If you pick anything other than Anthropic, it checks whether OpenClaude is installed, offers to install it, then prompts for the provider-specific keys and saves them to `config/providers.json`. You can re-run the wizard or use the dashboard to change providers later. ## Related * [Environment Variables Reference](../reference/env-variables.md#ai-provider-configuration) * [Getting Started](../getting-started.md) — step 3 covers provider choice * [OpenClaude on npm](https://www.npmjs.com/package/@gitlawb/openclaude) # Users and roles Source: https://docs.evolutionfoundation.com.br/evo-nexus/dashboard/users-and-roles Esta página ainda está em inglês. A tradução para português está em andamento. # Users and Roles EvoNexus uses a role-based access control (RBAC) system. Every user has exactly one role, and each role defines what resources the user can access and what actions they can perform. ## Default Roles Three built-in roles ship with every installation: | Role | Description | | ------------ | -------------------------------------------------------------------------------------------------------- | | **admin** | Full access to all resources and actions | | **operator** | Can view and execute (run routines, use chat, manage services) but cannot manage users, audit, or config | | **viewer** | Read-only access to dashboards, reports, memory, and skills | Built-in roles cannot be deleted, but you can create custom roles with any permission combination. ### Permission Comparison | Resource | admin | operator | viewer | | ------------ | --------------------- | ------------- | ------ | | chat | view, execute, manage | view, execute | -- | | services | view, execute, manage | view, execute | view | | systems | view, execute, manage | view, execute | view | | integrations | view, execute, manage | view, execute | view | | reports | view, manage | view | view | | agents | view, manage | view | view | | memory | view, manage | view | view | | skills | view, manage | view | view | | costs | view, manage | view | view | | config | view, manage | view | view | | users | view, manage | -- | -- | | audit | view | -- | -- | | files | view, manage | view | view | | templates | view | view | view | | routines | view, execute | view, execute | view | | scheduler | view, execute | view, execute | view | ## Creating Users ### Via the Dashboard 1. Navigate to **Users** in the sidebar (requires `users:manage` permission) 2. Click **Add User** 3. Fill in: * **Username** (unique, used for login) * **Email** (optional) * **Display name** (shown in the UI) * **Password** (minimum 8 characters, hashed with bcrypt) * **Role** (select from available roles) 4. Click **Create** The new user can immediately log in at the dashboard URL. User Management ### First User (Setup Wizard) The very first user is created during the setup wizard when the dashboard starts with an empty database. This user is always assigned the `admin` role. ## Custom Roles ### Creating a Custom Role 1. Go to **Roles** in the sidebar 2. Click **Create Role** 3. Enter a **name** and **description** 4. Use the permission matrix to toggle actions per resource 5. Click **Save** Roles permission matrix ### Permission Matrix Each cell in the matrix is a resource + action combination: **Resources** (16 total): `chat`, `services`, `systems`, `integrations`, `reports`, `agents`, `memory`, `skills`, `costs`, `config`, `users`, `audit`, `files`, `templates`, `routines`, `scheduler` **Actions** (3 types): * **view** -- read data, see pages * **execute** -- run routines, use chat, start/stop services * **manage** -- create, update, delete (users, config, memory files) Not all resources support all actions. For example, `audit` only supports `view`, and `templates` only supports `view`. ### Example: "Finance Viewer" Role A role that can only see financial reports and costs: ```json theme={null} { "reports": ["view"], "costs": ["view"], "integrations": ["view"] } ``` ### Example: "Community Manager" Role A role that can run community routines and view reports: ```json theme={null} { "reports": ["view"], "routines": ["view", "execute"], "services": ["view"], "integrations": ["view"], "memory": ["view"] } ``` ## How Permissions Are Enforced Every API endpoint checks permissions using the `has_permission(role, resource, action)` function. If the current user's role does not include the required permission, the API returns `403 Forbidden`. The frontend also uses permissions to conditionally render sidebar items and action buttons -- if you lack `users:view`, the Users page does not appear in the navigation. ## Audit Trail All user-related actions are logged to the audit trail: * User creation and updates * Role changes * Login attempts (successful and failed) * Config changes (including `.env` edits) View the full audit log at **Audit Log** in the sidebar (requires `audit:view`). # Goals Source: https://docs.evolutionfoundation.com.br/evo-nexus/goals Hierarquia Mission → Project → Goal → Task que dá direção ao trabalho dos agentes # Goals Goals — árvore Mission → Project → Goal com progresso **Goals dão direção ao EvoNexus.** Sem um goal, rotinas e heartbeats são apenas atividade. Com um goal, cada execução de agente tem um alvo a perseguir — e o progresso é mensurável. ## A Hierarquia ``` Mission → Project → Goal → Task ``` Cada camada responde a uma pergunta diferente: | Camada | Pergunta | Exemplo | | ----------- | ----------------------------- | ---------------------------------------- | | **Mission** | Por que estamos fazendo isso? | "Crescer Evo AI para 10k usuários pagos" | | **Project** | Qual frente de trabalho? | "Vendas — Q2 2026" | | **Goal** | Qual resultado mensurável? | "Atingir 80k MRR até 30 de junho" | | **Task** | Qual ação concreta? | "Lançar plano de cobrança anual" | Missions são opcionais — um project pode existir sozinho. Goals devem obrigatoriamente pertencer a um project. Tasks opcionalmente pertencem a um goal (se pertencerem, completá-las soma em `current_value`). ## Por que importa Três coisas acontecem quando você liga trabalho a um goal: 1. **Rotinas injetam contexto do goal.** Uma rotina com `goal_id: mrr-80k` em `config/routines.yaml` informa ao agente: "este é o resultado que você está perseguindo." Relatórios, análises e recomendações ficam mais afiados porque o agente sabe como é o "bom". 2. **Heartbeats injetam contexto do goal.** Mesmo mecanismo — um heartbeat com `goal_id` dá ao agente proativo uma âncora. 3. **Progresso fica visível.** O dashboard mostra cada goal com `current_value / target_value`, prazo e status. Goals parados ou atrasados aparecem automaticamente. ## Criando um Goal ### Via skill `create-goal` (recomendado) No Claude Code: > "Crie um goal para atingir 80k MRR até 30 de junho." A skill conduz você por: 1. Escolher (ou criar) uma mission 2. Escolher (ou criar) um project sob ela 3. Definir o goal — título, tipo de métrica, target, due date 4. (Opcional) anexar tasks iniciais 5. (Opcional) ligar uma rotina existente ### Via dashboard A página **Goals** tem um formulário "Novo Goal". Mesmos campos, mesma hierarquia. ### Via API ```bash theme={null} # 1. Criar o project (se necessário) curl -X POST http://localhost:8080/api/projects \ -H "Content-Type: application/json" \ -d '{"slug": "sales-q2-2026", "title": "Sales — Q2 2026", "mission_id": 1}' # 2. Criar o goal curl -X POST http://localhost:8080/api/goals \ -H "Content-Type: application/json" \ -d '{ "slug": "mrr-80k", "project_id": 7, "title": "Atingir 80k MRR", "metric_type": "currency", "target_value": 80000, "current_value": 62000, "due_date": "2026-06-30" }' ``` O slug é o handle público. É o que rotinas e heartbeats referenciam. ## Tipos de Métrica | `metric_type` | Use para | | ------------- | ----------------------------------------------------------------------- | | `count` | Quantidade de coisas (usuários, signups, posts) | | `currency` | Receita, despesa, MRR (valor na menor unidade — centavos ou BRL) | | `percent` | Targets percentuais (NPS, taxa de conversão) | | `boolean` | Resultados de uma vez só ("lançado", "certificado") — `target_value: 1` | | `tasks` | Contagem de tasks completas sob o goal | O dashboard renderiza cada tipo com a formatação correta (currency com símbolo, percent com `%`, etc.). ## Acompanhamento de Progresso ### Automático (via tasks) Tasks somam em `current_value`: 1. Crie tasks com `goal_id: {numeric_id}` 2. Quando o `status` da task vira `done`, o backend recalcula `current_value` a partir da view SQL `goal_progress_v` 3. Quando `current_value >= target_value`, o `status` do goal vira `achieved` ### Manual (PATCH direto) Métricas que não são tasks (MRR, NPS, follower count) precisam de updates diretos: ```bash theme={null} curl -X PATCH http://localhost:8080/api/goals/{id} \ -H "Content-Type: application/json" \ -d '{"current_value": 67500}' ``` Você pode amarrar uma rotina para fazer isso na agenda — ex. uma rotina diária `fin-pulse` que faz PATCH no goal de MRR com o número mais recente do Stripe. ### Correção de drift Se a contagem de tasks ficar fora de sincronia com `current_value`: ```bash theme={null} curl -X POST http://localhost:8080/api/goals/{id}/recalculate ``` Força um recálculo a partir da view SQL. ## Ligando uma Rotina ```bash theme={null} curl -X POST http://localhost:8080/api/goals/link-routine \ -H "Content-Type: application/json" \ -d '{"routine_name": "financial-pulse", "goal_id": "mrr-80k"}' ``` Isso grava `goal_id: mrr-80k` na entrada correspondente em `config/routines.yaml`. Todas as próximas execuções dessa rotina verão o contexto do goal. ## Ligando um Heartbeat Heartbeats aceitam `goal_id` na entrada YAML: ```yaml theme={null} - id: flux-6h agent: flux-finance goal_id: mrr-80k # ... resto ``` Mesmo efeito das rotinas — o agente roda com contexto do goal. ## Ligando um Ticket Tickets aceitam um `goal_id` numérico na criação ou via PATCH: ```bash theme={null} curl -X POST http://localhost:8080/api/tickets \ -d '{"title": "...", "goal_id": 12}' ``` O ticket aparece na lista de tickets do goal e conta para sua atividade. ## Visualizando Progresso ### Dashboard A página **Goals** agrupa goals por project, mostra barras de progresso, sinaliza atrasos em vermelho e permite filtrar por status (`active`, `achieved`, `dropped`), janela de prazo (`overdue`, `this-week`, `this-month`) ou project. ### API ```bash theme={null} # Todos os goals ativos curl "http://localhost:8080/api/goals?status=active" # Goals atrasados curl "http://localhost:8080/api/goals?due_date=overdue" # Goals de um project, com tasks curl "http://localhost:8080/api/goals?project_id=7&include_tasks=true" ``` ## Anti-padrões * **Goals sem métrica.** "Melhorar o produto" não é um goal — é um desejo. Todo goal precisa de `metric_type`, `target_value` e `due_date`. * **Goals que nunca mudam de estado.** Se `current_value` não se move por semanas, o goal está parado (arquive-o) ou não está conectado a um sinal (adicione uma rotina que atualize). * **Sobrecarregar missions.** Uma mission deve cobrir um trimestre ou mais. Se você está criando uma mission por semana, achate-as em projects. * **Ligar uma rotina a um goal slug inexistente.** A API retorna 404. Confirme o slug com `GET /api/goals` antes. ## Skills do CLI | Skill | O que faz | | ------------- | ---------------------------------------------------- | | `create-goal` | Wizard interativo (mission → project → goal → tasks) | ## Relacionados * `docs/heartbeats.md` — acordar agentes em intervalos com contexto de goal * `docs/tickets.md` — unidades de trabalho persistentes que podem ser ligadas a goals * Código: `dashboard/backend/routes/goals.py`, `dashboard/backend/goal_context.py` # Channels Source: https://docs.evolutionfoundation.com.br/evo-nexus/guides/channels Esta página ainda está em inglês. A tradução para português está em andamento. # Channels — Bidirectional Chat with Claude Code Channels let you push messages into a running Claude Code session and receive replies back — like a chat bridge between external platforms and your terminal. > **Channels vs Integrations:** Integrations (API clients, MCP servers) are tools Claude calls on demand during a task. Channels are the reverse: external systems that **push** events into the session. You can have both — for example, Discord as an integration (community monitoring via @pulse) AND as a channel (bidirectional chat with Claude). ## Supported Channels | Channel | Platform | Type | Make Command | | ------------ | -------------- | --------------------- | ---------------------- | | **Telegram** | Mobile/Desktop | Bot (polling) | `make telegram` | | **Discord** | Desktop/Mobile | Bot (gateway) | `make discord-channel` | | **iMessage** | macOS only | Native (Messages.app) | `make imessage` | ## Prerequisites * **Claude Code v2.1.80+** (check with `claude --version`) * **Bun** installed (check with `bun --version`, install at [bun.sh](https://bun.sh)) * **claude.ai login** (Console and API key authentication are not supported) * **Plugin marketplace** configured: `/plugin marketplace add anthropics/claude-plugins-official` ## Setup: Telegram Full integration docs at [docs/integrations/telegram.md](../integrations/telegram.md). ### 1. Create a Bot 1. Open Telegram and message [@BotFather](https://t.me/BotFather) 2. Send `/newbot` and follow the prompts 3. Copy the **Bot Token** provided ### 2. Install the Plugin In Claude Code: ``` /plugin install telegram@claude-plugins-official ``` If the plugin is not found, update the marketplace: ``` /plugin marketplace update claude-plugins-official ``` Then reload: ``` /reload-plugins ``` ### 3. Configure the Token ``` /telegram:configure ``` This saves to `~/.claude/channels/telegram/.env`. Alternatively, set `TELEGRAM_BOT_TOKEN` in your shell environment. ### 4. Start the Channel **Manual (foreground):** ```bash theme={null} claude --channels plugin:telegram@claude-plugins-official ``` **Background (recommended):** ```bash theme={null} make telegram ``` This starts the bot in a background `screen` session with `--dangerously-skip-permissions`. ### 5. Pair Your Account 1. In Telegram, send any message to your bot 2. The bot replies with a **pairing code** 3. In Claude Code, run: ``` /telegram:access pair ``` 4. Lock down access to your account only: ``` /telegram:access policy allowlist ``` ### Manage | Command | What it does | | ---------------------- | --------------------------------------- | | `make telegram` | Start bot in background | | `make telegram-stop` | Stop the bot | | `make telegram-attach` | Attach to terminal (Ctrl+A D to detach) | *** ## Setup: Discord Channel > **Note:** This is the Discord **Channel** (bidirectional chat with Claude Code), separate from the Discord API integration used by @pulse for community monitoring. They are independent and can coexist. ### 1. Create a Discord Bot 1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) 2. Click **New Application** and give it a name 3. In the **Bot** section, click **Reset Token** and copy the token ### 2. Enable Message Content Intent In your bot settings, under **Privileged Gateway Intents**, enable: * **Message Content Intent** (required) ### 3. Invite the Bot to Your Server Go to **OAuth2 > URL Generator**. Select the `bot` scope and enable these permissions: * View Channels * Send Messages * Send Messages in Threads * Read Message History * Attach Files * Add Reactions Open the generated URL to add the bot to your server. ### 4. Install the Plugin In Claude Code: ``` /plugin install discord@claude-plugins-official ``` If not found, update the marketplace: ``` /plugin marketplace update claude-plugins-official ``` Then reload: ``` /reload-plugins ``` ### 5. Configure the Token ``` /discord:configure ``` Saves to `~/.claude/channels/discord/.env`. Alternatively, set `DISCORD_BOT_TOKEN` in your environment. ### 6. Start the Channel **Manual (foreground):** ```bash theme={null} claude --channels plugin:discord@claude-plugins-official ``` **Background (recommended):** ```bash theme={null} make discord-channel ``` ### 7. Pair Your Account 1. DM your bot on Discord 2. The bot replies with a **pairing code** 3. In Claude Code: ``` /discord:access pair ``` 4. Lock down access: ``` /discord:access policy allowlist ``` ### Manage | Command | What it does | | ----------------------------- | --------------------------------------- | | `make discord-channel` | Start channel in background | | `make discord-channel-stop` | Stop the channel | | `make discord-channel-attach` | Attach to terminal (Ctrl+A D to detach) | *** ## Setup: iMessage > **Requirement:** macOS only. Reads the Messages.app database directly and sends replies via AppleScript. No bot token or external service needed. ### 1. Grant Full Disk Access The Messages database (`~/Library/Messages/chat.db`) is protected by macOS. On the first read, macOS prompts for permission — click **Allow**. If the prompt doesn't appear or you clicked "Don't Allow", grant access manually: **System Settings > Privacy & Security > Full Disk Access** — add your terminal app (Terminal, iTerm, etc.) ### 2. Install the Plugin In Claude Code: ``` /plugin install imessage@claude-plugins-official ``` If not found: ``` /plugin marketplace update claude-plugins-official ``` ### 3. Start the Channel **Manual (foreground):** ```bash theme={null} claude --channels plugin:imessage@claude-plugins-official ``` **Background (recommended):** ```bash theme={null} make imessage ``` ### 4. Test — Send a Message to Yourself Open Messages on any device signed into your Apple ID and send a message **to yourself**. Self-chat works automatically with no access configuration needed. > On Claude's first reply, macOS prompts for Automation permission to control Messages. Click **OK**. ### 5. Allow Other Senders By default, only your own messages pass through. To allow another contact: ``` /imessage:access allow +15551234567 ``` Accepted handles: phone numbers with country code (`+1...`) or Apple ID emails. ### Manage | Command | What it does | | ---------------------- | --------------------------------------- | | `make imessage` | Start channel in background | | `make imessage-stop` | Stop the channel | | `make imessage-attach` | Attach to terminal (Ctrl+A D to detach) | *** ## Multiple Channels You can run multiple channels simultaneously. Each runs in its own `screen` session: ```bash theme={null} make telegram make discord-channel make imessage ``` Or in a single Claude Code session (foreground): ```bash theme={null} claude --channels plugin:telegram@claude-plugins-official plugin:discord@claude-plugins-official plugin:imessage@claude-plugins-official ``` ## Security * Each channel maintains a **sender allowlist** — only approved IDs can push messages * Telegram and Discord use **pairing**: the sender messages the bot, receives a code, and you approve it in Claude Code * iMessage allows self-chat automatically; other contacts are added by handle * **Permission relay**: bidirectional channels can forward permission prompts so you can approve/deny remotely (e.g., approve a `Bash` command from Telegram) * Being in `.mcp.json` is not enough — the server must also be named in `--channels` ## Enterprise / Team On Team and Enterprise plans, channels are **disabled by default**. The admin controls access via: | Setting | Purpose | | ----------------------- | -------------------------------------------------------------------------- | | `channelsEnabled` | Master switch. Must be `true` for any channel to work | | `allowedChannelPlugins` | Which plugins can register as channels (replaces Anthropic's default list) | Configure at: **claude.ai > Admin settings > Claude Code > Channels** ## Custom Channels You can build your own channels for systems that don't have a plugin yet (CI/CD, monitoring, webhooks). See the [Channels Reference](channels-reference.md) for the full technical documentation. ## Troubleshooting **Bot doesn't respond on Telegram/Discord:** * Make sure Claude Code is running with `--channels` (or via `make telegram` / `make discord-channel`) * Use `make telegram-attach` or `make discord-channel-attach` to view the terminal **"Plugin not found":** * Run `/plugin marketplace update claude-plugins-official` * Then `/reload-plugins` **"Blocked by org policy":** * Admin needs to enable `channelsEnabled` in managed settings **iMessage — "authorization denied":** * Grant Full Disk Access to your terminal in System Settings > Privacy & Security **Messages not arriving:** * Confirm you completed pairing (`/telegram:access pair`, `/discord:access pair`) * Confirm the policy is set to allowlist (`/telegram:access policy allowlist`) **Permission prompts block the session:** * Channels with permission relay forward the prompts. Reply from chat or the local terminal * For unattended use: `--dangerously-skip-permissions` (only in trusted environments) # Channels reference Source: https://docs.evolutionfoundation.com.br/evo-nexus/guides/channels-reference Esta página ainda está em inglês. A tradução para português está em andamento. # Channels Reference — Building Custom Channels Technical reference for building an MCP server that pushes webhooks, alerts, and chat messages into a Claude Code session. > To use existing channels (Telegram, Discord, iMessage), see the [Channels Guide](channels.md). ## Overview A channel is an MCP server that runs on the same machine as Claude Code. Claude Code spawns it as a subprocess and communicates over stdio. Your channel server bridges external systems and the session: * **Chat platforms** (Telegram, Discord): your plugin runs locally and polls the platform's API. When someone DMs the bot, the plugin receives the message and forwards it to Claude. * **Webhooks** (CI, monitoring): your server listens on a local HTTP port. External systems POST to that port, and your server pushes the payload to Claude. ## Requirements * [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) (MCP SDK) * Node.js-compatible runtime: [Bun](https://bun.sh), [Node](https://nodejs.org), or [Deno](https://deno.com) Your server must: 1. Declare the `claude/channel` capability so Claude Code registers a notification listener 2. Emit `notifications/claude/channel` events when something happens 3. Connect via [stdio transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-io) ## Example: Webhook Receiver A single-file server that listens for HTTP requests and forwards them into your Claude Code session. ### 1. Create the Project ```bash theme={null} mkdir webhook-channel && cd webhook-channel bun add @modelcontextprotocol/sdk ``` ### 2. Write the Server ```ts theme={null} // webhook.ts #!/usr/bin/env bun import { Server } from '@modelcontextprotocol/sdk/server/index.js' import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js' const mcp = new Server( { name: 'webhook', version: '0.0.1' }, { capabilities: { experimental: { 'claude/channel': {} } }, instructions: 'Events from the webhook channel arrive as . Read them and act, no reply expected.', }, ) await mcp.connect(new StdioServerTransport()) Bun.serve({ port: 8788, hostname: '127.0.0.1', async fetch(req) { const body = await req.text() await mcp.notification({ method: 'notifications/claude/channel', params: { content: body, meta: { path: new URL(req.url).pathname, method: req.method }, }, }) return new Response('ok') }, }) ``` ### 3. Register in MCP Config ```json theme={null} // .mcp.json { "mcpServers": { "webhook": { "command": "bun", "args": ["./webhook.ts"] } } } ``` ### 4. Test ```bash theme={null} # Terminal 1: start Claude Code with development flag claude --dangerously-load-development-channels server:webhook # Terminal 2: simulate a webhook curl -X POST localhost:8788 -d "build failed on main: https://ci.example.com/run/1234" ``` The payload arrives as: ``` build failed on main: https://ci.example.com/run/1234 ``` ## Server Options | Field | Type | Description | | -------------------------------------------------------- | -------- | ---------------------------------------------------------------- | | `capabilities.experimental['claude/channel']` | `object` | **Required.** Always `{}`. Registers the notification listener | | `capabilities.experimental['claude/channel/permission']` | `object` | Optional. Declares that the channel can receive permission relay | | `capabilities.tools` | `object` | Two-way only. Always `{}`. Enables tool discovery | | `instructions` | `string` | Recommended. Added to Claude's system prompt | ## Notification Format Emit `notifications/claude/channel` with two params: | Field | Type | Description | | --------- | ------------------------ | ---------------------------------------------------------------- | | `content` | `string` | The event body. Delivered as the body of the `` tag | | `meta` | `Record` | Optional. Each entry becomes an attribute on the `` tag | ```ts theme={null} await mcp.notification({ method: 'notifications/claude/channel', params: { content: 'build failed on main', meta: { severity: 'high', run_id: '1234' }, }, }) ``` Result in Claude's context: ``` build failed on main ``` **Note on meta keys:** only letters, digits, and underscores. Keys with hyphens are silently dropped. ## Expose a Reply Tool (Two-Way) For bidirectional channels (chat bridges), expose a standard MCP tool: ```ts theme={null} import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js' // Tool discovery mcp.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [{ name: 'reply', description: 'Send a message back over this channel', inputSchema: { type: 'object', properties: { chat_id: { type: 'string', description: 'The conversation to reply in' }, text: { type: 'string', description: 'The message to send' }, }, required: ['chat_id', 'text'], }, }], })) // Tool handler mcp.setRequestHandler(CallToolRequestSchema, async req => { if (req.params.name === 'reply') { const { chat_id, text } = req.params.arguments as { chat_id: string; text: string } await sendToYourPlatform(chat_id, text) return { content: [{ type: 'text', text: 'sent' }] } } throw new Error(`unknown tool: ${req.params.name}`) }) ``` Update `instructions` so Claude knows to use the tool: ```ts theme={null} instructions: 'Messages arrive as . Reply with the reply tool, passing the chat_id from the tag.' ``` ## Gate Inbound Messages (Security) An ungated channel is a prompt injection vector. Always check the sender against an allowlist **before** emitting: ```ts theme={null} const allowed = new Set(loadAllowlist()) // In your message handler: if (!allowed.has(message.from.id)) { return // drop silently } await mcp.notification({ ... }) ``` **Important:** Gate on the sender's ID (`message.from.id`), not the chat/room (`message.chat.id`). In group chats, anyone in the room could inject messages. ## Permission Relay > Requires Claude Code v2.1.81+ Bidirectional channels can forward permission prompts for remote approval. ### How It Works 1. Claude Code generates a request ID and notifies your server 2. Your server forwards the prompt to the chat platform 3. The remote user replies with `yes ` or `no ` 4. Your handler parses the reply and emits a verdict The local terminal dialog stays open — the first response (local or remote) is applied. ### Implementation **1. Declare the capability:** ```ts theme={null} capabilities: { experimental: { 'claude/channel': {}, 'claude/channel/permission': {}, // opt in to relay }, tools: {}, }, ``` **2. Handle incoming request:** ```ts theme={null} import { z } from 'zod' const PermissionRequestSchema = z.object({ method: z.literal('notifications/claude/channel/permission_request'), params: z.object({ request_id: z.string(), tool_name: z.string(), description: z.string(), input_preview: z.string(), }), }) mcp.setNotificationHandler(PermissionRequestSchema, async ({ params }) => { send( `Claude wants to run ${params.tool_name}: ${params.description}\n\n` + `Reply "yes ${params.request_id}" or "no ${params.request_id}"`, ) }) ``` **3. Intercept verdict in inbound handler:** ```ts theme={null} const PERMISSION_REPLY_RE = /^\s*(y|yes|n|no)\s+([a-km-z]{5})\s*$/i // In your inbound message handler: const m = PERMISSION_REPLY_RE.exec(message.text) if (m) { await mcp.notification({ method: 'notifications/claude/channel/permission', params: { request_id: m[2].toLowerCase(), behavior: m[1].toLowerCase().startsWith('y') ? 'allow' : 'deny', }, }) return // don't forward as chat } ``` ### Permission Request Fields | Field | Description | | --------------- | ----------------------------------------------------------------------------- | | `request_id` | 5 lowercase letters (no `l`). Include in the prompt to be echoed in the reply | | `tool_name` | Tool name (e.g., `Bash`, `Write`) | | `description` | Human-readable summary of what the tool call does | | `input_preview` | Tool arguments as JSON, truncated to 200 chars | ## Package as a Plugin To make your channel installable and shareable: 1. Package it as a [plugin](https://code.claude.com/docs/en/plugins) 2. Publish to a [marketplace](https://code.claude.com/docs/en/plugin-marketplaces) 3. Users install with `/plugin install` and enable with `--channels plugin:@` Channels published to custom marketplaces still require `--dangerously-load-development-channels` until added to the official allowlist or the organization's `allowedChannelPlugins`. ## Testing During the Research Preview Custom channels are not on the approved allowlist. Use the development flag: ```bash theme={null} # Plugin in development claude --dangerously-load-development-channels plugin:yourplugin@yourmarketplace # Bare .mcp.json server claude --dangerously-load-development-channels server:webhook ``` The bypass is per-entry. The `channelsEnabled` organization policy still applies. ## References * [Channels Guide](channels.md) — setup for official channels (Telegram, Discord, iMessage) * [Working implementations](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins) — complete server code with pairing, reply tools, and file attachments * [MCP](https://modelcontextprotocol.io) — the underlying protocol that channel servers implement # Creating routines Source: https://docs.evolutionfoundation.com.br/evo-nexus/guides/creating-routines Esta página ainda está em inglês. A tradução para português está em andamento. # Creating Routines Routines are automated tasks that run on a schedule — daily financial snapshots, community pulses, email triage, and more. Use the `create-routine` skill to generate everything you need. ## Quick Start Just say: ``` create a routine ``` or describe what you want: ``` I want to automate a daily competitor check ``` Claude walks you through the setup. ## What the Skill Asks The `create-routine` skill collects four things: 1. **What** — What should the routine do? (e.g., "Check competitor pricing pages and summarize changes") 2. **Which agent** — Who runs it? (e.g., Sage for strategy, Pulse for community) 3. **When** — Schedule in cron format or natural language (e.g., "every weekday at 9am", "Mondays and Fridays at 8:30") 4. **Output** — Where does the result go? (e.g., HTML report, markdown log, Telegram notification) ## What Gets Generated After you answer, the skill creates: ### 1. Python Script Located at `ADWs/routines/custom/.py`: ```python theme={null} """Daily Competitor Check — monitors competitor pricing and features.""" # Auto-generated routine script # Agent: sage # Schedule: 0 9 * * 1-5 import subprocess import sys def run(): prompt = """...""" subprocess.run([sys.executable, "-m", "claude", ...]) if __name__ == "__main__": run() ``` ### 2. YAML Entry Added to `config/routines.yaml`: ```yaml theme={null} - name: competitor-check description: Daily competitor pricing and feature check agent: sage schedule: "0 9 * * 1-5" script: ADWs/routines/custom/competitor-check.py make_target: competitor-check ``` ## Example: Daily Competitor Check Here's the full walkthrough: **You:** "I want to automate a daily competitor check" **Claude:** "What exactly should this routine check?" **You:** "Monitor competitor websites for pricing changes, new features, and blog posts. Compare against our positioning." **Claude:** "Which agent should run it? I'd suggest Sage since this is strategic intelligence." **You:** "Yes, Sage." **Claude:** "When should it run?" **You:** "Every weekday at 9am" **Claude:** "Where should the output go?" **You:** "HTML report in the strategy folder, plus a Telegram summary" Claude then generates the script and YAML entry. Routines are discovered dynamically — no Makefile changes needed. Test it immediately: ```bash theme={null} make run R=competitor-check ``` ## Where Files Live | File | Location | | ---------------------- | ------------------------------------------------------------------- | | Custom routine scripts | `ADWs/routines/custom/` | | Core routine scripts | `ADWs/routines/` | | Routine config | `config/routines.yaml` | | Generated reports | Varies by agent (e.g., `workspace/strategy/`, `workspace/finance/`) | ## Testing After creation, test your routine: ```bash theme={null} # Run by ID (dynamic discovery) make run R=competitor-check # List all available routines make list-routines # Check logs make logs ``` ## Managing Routines * **Edit schedule**: Update the entry in `config/routines.yaml` * **Disable**: Set `enabled: false` or remove the YAML entry * **View metrics**: `make metrics` shows token usage and cost per routine * **Scheduler**: `make scheduler` runs all routines on their configured schedules ## One-Off Actions If you need to run something **once** at a specific time (not recurring), use [Scheduled Tasks](../routines/scheduled-tasks.md) instead. Say "schedule this for Friday at 10am" or use the `schedule-task` skill. # Creating skills Source: https://docs.evolutionfoundation.com.br/evo-nexus/guides/creating-skills Esta página ainda está em inglês. A tradução para português está em andamento. # Creating Skills Skills are reusable instruction sets that teach Claude how to perform specific tasks. EvoNexus includes 126 built-in skills — you can create your own. ## Using the Skill Creator The fastest way: ``` create a skill for weekly team reports ``` The `skill-creator` plugin walks you through: 1. **Name and prefix** — follows the naming convention (e.g., `prod-weekly-team-report`) 2. **Description** — the trigger phrase that activates the skill 3. **Instructions** — what Claude should do when the skill is invoked ## Manual Creation Skills live in `.claude/skills/` organized by prefix. ### File Structure ``` .claude/skills/ prefix-name/ SKILL.md ``` ### SKILL.md Format ```markdown theme={null} --- name: weekly-team-report description: Generate a weekly team status report from Linear, GitHub, and meeting notes. Use when the user says 'team report', 'weekly team update', or 'what did the team do this week'. --- # Weekly Team Report ## Steps 1. Query Linear for completed issues this week 2. Query GitHub for merged PRs 3. Check meeting summaries from the week 4. Generate a structured report with: - Completed work by team member - In-progress items - Blockers - Next week priorities ## Output Generate an HTML report using the Evolution brand template. Save to `workspace/daily-logs/` with filename `[C] Team Report YYYY-MM-DD.html`. ## Rules - Always group by team member - Include links to Linear issues and GitHub PRs - Highlight blockers in red ``` ### Key Points * **The `description` field is the trigger.** Claude matches user intent against skill descriptions to decide which skill to activate. Make it specific and include common trigger phrases. * **The `name` field** is the skill identifier. * **The body** contains the full instructions Claude follows when the skill is activated. ## Naming Convention Skills use a prefix that indicates their category: | Prefix | Category | Examples | | ---------- | ------------ | ----------------------------------------------- | | `prod-` | Productivity | `prod-morning`, `prod-eod` | | `fin-` | Finance | `fin-daily-pulse`, `fin-journal-entry` | | `social-` | Social media | `social-post-writer`, `social-analytics-report` | | `int-` | Integrations | `int-stripe`, `int-github-review` | | `pulse-` | Community | `pulse-daily`, `pulse-faq-sync` | | `sage-` | Strategy | `sage-okr-review`, `sage-strategy-digest` | | `evo-` | Evo Method | `evo-dev`, `evo-create-prd` | | `mkt-` | Marketing | `mkt-campaign-plan`, `mkt-seo-audit` | | `gog-` | Google | `gog-calendar`, `gog-email-triage` | | `obs-` | Obsidian | `obs-obsidian-cli`, `obs-defuddle` | | `discord-` | Discord | `discord-get-messages`, `discord-send-message` | ## Example: Creating a "Weekly Report" Skill 1. Create the directory: ```bash theme={null} mkdir -p .claude/skills/prod-weekly-report ``` 2. Create `SKILL.md`: ```markdown theme={null} --- name: weekly-report description: Generate a consolidated weekly report covering projects, finance, community, and strategy. Use when the user says 'weekly report', 'week summary', 'what happened this week'. --- # Weekly Report Generator Consolidate data from all domains into a single weekly summary. ## Data Sources 1. **Projects** — Linear issues completed, GitHub PRs merged 2. **Finance** — Stripe MRR, revenue, churn 3. **Community** — Discord activity, support topics 4. **Strategy** — OKR progress, key decisions ## Output HTML report saved to `workspace/daily-logs/`. ``` 3. Test it — just describe the task: ``` generate a weekly report ``` Claude matches your intent to the skill description and follows the instructions. ## Tips * **Be specific in descriptions.** "Generate financial reports" is too vague. "Generate financial statements (income statement, balance sheet, cash flow) with period-over-period comparison" tells Claude exactly when to activate. * **Include trigger phrases.** Add common ways users might ask for the skill: "Use when the user says 'X', 'Y', or 'Z'." * **Reference other skills.** Skills can call other skills — e.g., a weekly report skill can reference the Stripe integration skill for financial data. * **Test iteratively.** Create the skill, test it, refine the instructions based on the output quality. # Daily workflow Source: https://docs.evolutionfoundation.com.br/evo-nexus/guides/daily-workflow Esta página ainda está em inglês. A tradução para português está em andamento. # Daily Workflow A practical guide to running your business day with EvoNexus — from morning briefing to end-of-day wrap-up. ## Morning (7:00 - 8:00) ### 1. Good Morning Briefing ``` good morning ``` Clawdia generates your daily briefing: * Today's calendar events * Unread emails (prioritized) * Open tasks from Todoist * Yesterday's unfinished items * Key metrics snapshot ### 2. Email Triage ``` triage my inbox ``` Clawdia reads unread emails, classifies by urgency, and proposes actions: * **Reply now** — urgent items needing immediate response * **Schedule** — items that need a response but not immediately * **Archive** — informational emails, no action needed * **Create task** — emails that represent work to be done ### 3. Task Review ``` review todoist ``` Clawdia organizes your tasks: uncategorized items get sorted, priorities are set, and you get a clear list of what to tackle today. ## During the Day (9:00 - 17:00) ### Project Updates ``` /atlas check linear /atlas check github ``` Atlas shows sprint progress, issues in review, blockers, open PRs, and anything that needs your attention. ### Community Monitoring ``` /pulse community pulse ``` Pulse analyzes Discord and WhatsApp activity: trending topics, unanswered questions, sentiment shifts, and contributor highlights. ### Content Creation ``` /pixel write a post about [topic] ``` Pixel drafts platform-specific content following your brand voice. Supports LinkedIn, Twitter/X, Threads, and Bluesky. ### Meetings Fathom syncs automatically every 30 minutes. After any meeting: ``` sync meetings ``` Get transcripts, summaries, and action items from your latest calls. ### Ad-hoc Questions Just ask naturally: * "How's the MRR trending?" (Flux answers) * "Any blockers on EVO-589?" (Atlas checks Linear) * "What's the community sentiment today?" (Pulse analyzes) * "Draft a reply to that email from Marcelo" (Clawdia helps) ## Evening (18:00 - 21:00) ### Social Analytics (18:00) ``` social analytics ``` Pixel generates a cross-platform report: YouTube, Instagram, LinkedIn engagement and growth. ### Licensing Report (18:30) ``` licensing daily ``` Atlas reports on open source telemetry: active instances, geographic distribution, version adoption. ### Financial Pulse (19:00) ``` financial pulse ``` Flux queries Stripe and Omie to produce a financial health snapshot: MRR, charges, churn, receivables, payables. ### Community Pulse (20:00) ``` community pulse ``` Pulse generates the full daily community report with Discord and WhatsApp analysis. ### End of Day (21:00) ``` end of day ``` Clawdia wraps up: summarizes what was accomplished, logs decisions, notes pending items, and prepares context for tomorrow. ### Dashboard (21:30) ``` dashboard ``` Clawdia consolidates all daily outputs into a unified 360-degree dashboard. ## Weekly Cadence | Day | Routine | Agent | | --------- | ---------------------------- | ------- | | Monday | Linear review, GitHub review | Atlas | | Wednesday | Linear review, GitHub review | Atlas | | Friday | Financial weekly | Flux | | Friday | Licensing weekly | Atlas | | Friday | Weekly review | Clawdia | | Friday | Social analytics weekly | Pixel | | Friday | Strategy digest | Sage | | Sunday | Health check-in | Kai | ### Friday Deep Dives Friday is the weekly synthesis day: ``` weekly review ``` Clawdia generates a comprehensive week-in-review. Follow up with: ``` strategy digest ``` Sage consolidates everything into strategic insights and recommendations. ## Monthly Close (1st of each month) ``` monthly close ``` Flux kicks off the month-end closing process: * Simplified P\&L * Pending reconciliations * Receivables and payables summary * Action items for the finance team Also runs: * Community monthly report (Pulse) * Licensing monthly report (Atlas) * Social analytics monthly (Pixel) ## Automation All these routines can run automatically via the scheduler: ```bash theme={null} make scheduler ``` See [Creating Routines](creating-routines.md) for details on the schedule and customization. # Docker install Source: https://docs.evolutionfoundation.com.br/evo-nexus/guides/docker-install Esta página ainda está em inglês. A tradução para português está em andamento. # Installing EvoNexus with Docker The fastest way to run EvoNexus on any machine — Linux, macOS (Intel or Apple Silicon), Windows with WSL2, or a bare VPS. Pulls official images from Docker Hub, no source checkout or build step required. ## TL;DR ```bash theme={null} curl -O https://raw.githubusercontent.com/evolution-foundation/evo-nexus/main/docker-compose.hub.yml docker compose -f docker-compose.hub.yml up -d open http://localhost:8080 ``` The setup wizard on first boot asks for a provider key (Anthropic, OpenAI or Codex). Everything else — integrations, Telegram, Stripe, Omie, Bling, Asaas, etc. — is configured through the UI. *** ## Prerequisites * **Docker Engine 24+** with Docker Compose v2. [Install on Mac / Windows / Linux](https://docs.docker.com/engine/install/). * **4 GB RAM minimum** (8 GB recommended — the Claude CLI and embedding models can be hungry). * **2 GB free disk** for images + a few hundred MB for data volumes. * An **Anthropic API key** (or OpenAI / ChatGPT Codex account) — you'll paste this into the wizard on first boot. No Node.js, Python, or any SDK needs to be installed on the host. The images ship everything. ### Multi-arch — ARM64 works out of the box Images are published as multi-arch manifests (`linux/amd64` + `linux/arm64`), so: * **Apple Silicon** (M1/M2/M3 Macs) — pulls `arm64` natively, no Rosetta overhead. * **AWS Graviton**, **Oracle Cloud ARM free tier**, **Raspberry Pi 4/5** — pulls `arm64` natively. * **Traditional x86\_64 servers** — pulls `amd64` as usual. You never pass `--platform`. Docker picks the right arch from the manifest list. *** ## Step 1 — Get the compose file Download the ready-to-run compose file. It pulls images from `evoapicloud/evo-nexus-{dashboard,runtime}` on Docker Hub — no git clone required. ```bash theme={null} curl -O https://raw.githubusercontent.com/evolution-foundation/evo-nexus/main/docker-compose.hub.yml ``` Open it — it's commented and self-explanatory. Key things to know: * **3 services**: `dashboard` (Flask + React + terminal), `telegram` (bot listener), `scheduler` (automated routines). Telegram and scheduler are optional — remove them from the file if you don't need them. * **Ports exposed**: `8080` (dashboard UI + API) and `32352` (terminal WebSocket). * **Volumes**: 6 named volumes that survive `docker compose down` and hold everything the UI configures. *** ## Step 2 — Start the stack ```bash theme={null} docker compose -f docker-compose.hub.yml up -d ``` First run downloads the images (\~800 MB total, a few minutes depending on your connection). Subsequent boots are instant. Check that all 3 services are up: ```bash theme={null} docker compose -f docker-compose.hub.yml ps ``` You should see: ``` NAME STATUS evonexus-dashboard Up (healthy) evonexus-telegram Up evonexus-scheduler Up ``` If the dashboard takes longer than 30 seconds to go healthy, check logs: ```bash theme={null} docker compose -f docker-compose.hub.yml logs -f dashboard ``` *** ## Step 3 — Open the UI and run the setup wizard Open **[http://localhost:8080](http://localhost:8080)** in your browser. You'll see the first-boot wizard: 1. **Create admin user** — username + password for the dashboard itself. 2. **Pick a provider** — paste your Anthropic API key, OpenAI key, or click "Login with ChatGPT" for Codex OAuth. 3. **Optional integrations** — Telegram bot token, Stripe, Omie, etc. Everything else is optional and can be added later. Once you save a provider key, the `telegram` and `scheduler` services (which were waiting in a 30s poll loop) pick it up and start working. No restart needed. *** ## Step 4 — Everyday commands | Action | Command | | ---------------- | ----------------------------------------------------- | | View logs | `docker compose -f docker-compose.hub.yml logs -f` | | Restart | `docker compose -f docker-compose.hub.yml restart` | | Stop | `docker compose -f docker-compose.hub.yml down` | | Stop + wipe data | `docker compose -f docker-compose.hub.yml down -v` ⚠️ | | Update to latest | See [Updating](#updating) below | *** ## Updating ### Pull the latest stable image ```bash theme={null} docker compose -f docker-compose.hub.yml pull docker compose -f docker-compose.hub.yml up -d ``` Your data volumes are preserved — everything you configured through the UI stays intact. ### Pin to a specific version Edit `docker-compose.hub.yml` and replace `:latest` with `:vX.Y.Z` (e.g. `:v0.30.4`). Available tags: [https://hub.docker.com/r/evoapicloud/evo-nexus-dashboard/tags](https://hub.docker.com/r/evoapicloud/evo-nexus-dashboard/tags) Rolling back is just bumping the tag down and running `pull && up -d`. *** ## Backup and restore Your configuration, workspace files, memory, and agent state live in 6 named volumes. To snapshot them all: ```bash theme={null} # Backup mkdir -p evonexus-backup for vol in config workspace dashboard_data memory adw_logs agent_memory; do docker run --rm \ -v evonexus_${vol}:/src:ro \ -v "$PWD/evonexus-backup":/dst \ alpine tar czf /dst/${vol}.tgz -C /src . done # Restore on a fresh host for vol in config workspace dashboard_data memory adw_logs agent_memory; do docker volume create evonexus_${vol} docker run --rm \ -v evonexus_${vol}:/dst \ -v "$PWD/evonexus-backup":/src:ro \ alpine tar xzf /src/${vol}.tgz -C /dst done ``` *** ## Advanced: passing secrets via environment variables The default flow is "configure everything through the UI, which writes to a persisted `.env` inside the `evonexus_config` volume." Most users should stick with that. If you prefer to keep secrets out of the volume (for CI/CD, Vault, Doppler, or immutable infra), you can pass any env var directly in the compose file. They **take precedence** over the volume's `.env`: ```yaml theme={null} services: dashboard: image: evoapicloud/evo-nexus-dashboard:latest environment: - TZ=America/Sao_Paulo - EVONEXUS_PORT=8080 # Bypass the UI — pass keys directly - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY} # read from shell or .env.compose - EVONEXUS_SECRET_KEY=${EVONEXUS_SECRET_KEY} - KNOWLEDGE_MASTER_KEY=${KNOWLEDGE_MASTER_KEY} env_file: - ./secrets.env # or load from a file — this file is NOT inside the volume ``` Tradeoffs: * **Pro**: secrets live with the infrastructure, not the user-editable volume. Rotate by redeploying. * **Con**: the Providers page in the UI will still work (and will write to the volume's `.env`), but any value you pass via `environment:` wins. This can be confusing for non-technical users. For the absolutely purist flow, pass `REQUIRE_ANTHROPIC_KEY=0` on the telegram and scheduler services so they don't wait for a UI-saved key — they'll just use whatever is in `environment:`. *** ## Advanced: Docker Secrets Every env var also supports a `_FILE` counterpart. Point it at a file, and the entrypoint reads the content into the var at boot. This works natively with Docker Secrets in Swarm mode: ```yaml theme={null} services: dashboard: environment: - ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic_key secrets: - anthropic_key secrets: anthropic_key: external: true ``` Additionally, every file under `/run/secrets/` is auto-discovered: `/run/secrets/anthropic_api_key` → sets `ANTHROPIC_API_KEY` if it's not already set. *** ## Running on a VPS with a public domain For production on a single-host VPS (not a Swarm cluster), put a reverse proxy in front of `docker-compose.hub.yml`. The simplest path is Caddy: ```yaml theme={null} # Caddyfile next to docker-compose.hub.yml evonexus.example.com { reverse_proxy /terminal/* localhost:32352 reverse_proxy localhost:8080 } ``` Then `caddy run` and you have HTTPS with automatic Let's Encrypt certificates pointing at your EvoNexus stack. For Docker Swarm with Traefik, see [README.swarm.md](https://github.com/evolution-foundation/evo-nexus/blob/main/README.swarm.md) and [`evonexus.stack.yml`](https://github.com/evolution-foundation/evo-nexus/blob/main/evonexus.stack.yml). *** ## Troubleshooting ### Dashboard port 8080 is already in use Another service on your host is bound to 8080. Change the host port in the compose file: ```yaml theme={null} ports: - "9090:8080" # host 9090 → container 8080 ``` Then open `http://localhost:9090`. ### Telegram / scheduler logs say "waiting for ANTHROPIC\_API\_KEY" Expected. These services poll `.env` every 30s. Configure a provider key in **Dashboard → Providers** and they'll pick it up automatically — no restart needed. ### Services keep restarting after `up -d` Check logs: ```bash theme={null} docker compose -f docker-compose.hub.yml logs --tail=50 ``` 99% of the time this is either (a) port conflict, (b) volume mount permission issue (rare, usually only on SELinux-enabled hosts — add `:Z` to volume mounts), or (c) disk full. ### Fresh install doesn't show any agents / skills on `/agents` or `/skills` On a brand-new volume, the APIs return `{"error": "Setup required", "needs_setup": true}` until the wizard completes. Open [http://localhost:8080](http://localhost:8080) and complete the wizard first. ### Want to see what's inside the running container ```bash theme={null} docker compose -f docker-compose.hub.yml exec dashboard bash ``` Useful paths inside the container: * `/workspace/config/.env` — everything the UI saves (ports, keys, integrations) * `/workspace/workspace/` — generated artifacts (reports, dashboards, daily logs) * `/workspace/memory/` — long-term memory the agents write * `/workspace/.claude/agent-memory/` — per-agent persistent state * `/workspace/ADWs/logs/` — routine execution logs (JSONL) *** ## Uninstall ```bash theme={null} docker compose -f docker-compose.hub.yml down -v ``` The `-v` flag also deletes the named volumes — **all your configuration and data is gone**. Skip the flag to keep volumes around for a future reinstall. *** ## See also * [Updating EvoNexus](./updating.md) — version bumps across all install methods * [README.swarm.md](https://github.com/evolution-foundation/evo-nexus/blob/main/README.swarm.md) — production Swarm / Portainer deployments with Traefik * [Environment variables reference](../reference/env-variables.md) — every variable the image recognizes # Initial setup skill Source: https://docs.evolutionfoundation.com.br/evo-nexus/guides/initial-setup-skill Esta página ainda está em inglês. A tradução para português está em andamento. # Initial Setup and Onboarding The `initial-setup` skill gives you a guided tour of EvoNexus when you first start using it. ## How to Trigger Say any of these: ``` get started what can you do show me around help me get started onboarding ``` ## What It Shows You ### 1. Agent Tour A quick overview of all 17 agents and what they do: * **Clawdia** — your operational hub (calendar, emails, tasks) * **Flux** — financial intelligence (Stripe, Omie, reports) * **Atlas** — project management (GitHub, Linear, milestones) * **Pulse** — community monitoring (Discord, WhatsApp) * **Pixel** — social media (content creation, analytics) * **Sage** — strategic planning (OKRs, roadmap, competitive) * **Kai** — personal wellness (health, habits) * **Nex** — sales pipeline (proposals, qualification) * **Mentor** — education (Evo Academy, courses) * **Lumen** — learning retention (spaced repetition, quizzes, fact capture) * **Oracle** — workspace knowledge (docs, how-to, config) * **Mako** — marketing (campaigns, SEO, brand, content) * **Aria** — HR / people (recruiting, onboarding, performance) * **Zara** — customer success (triage, escalation, health) * **Lex** — legal / compliance (contracts, NDA, risk) * **Nova** — product (specs, roadmaps, metrics, research) * **Dex** — data / BI (analysis, SQL, dashboards) ### 2. Dashboard Introduction How to access and use the web dashboard: * Overview page with key metrics * Agent status and recent activity * Routine execution logs * Report viewer for generated HTML reports * Documentation browser ### 3. Integration Status Which integrations are connected and ready: * Google (Calendar, Gmail) * GitHub, Linear * Stripe, Omie * Discord, WhatsApp, Telegram * YouTube, Instagram, LinkedIn ### 4. Quick Wins Three things you can do right now to see value: 1. **Say "good morning"** — get a full daily briefing 2. **Say "community pulse"** — see what your community is discussing 3. **Say "financial pulse"** — get a snapshot of your revenue and expenses ## After Setup Once you've completed the tour, you're ready to: * Set up your daily routines (`create a routine`) * Configure the scheduler (`make scheduler`) * Start using agents for daily work * Explore the 130+ available skills ## Re-running Setup You can trigger the setup tour again anytime — just say "show me around" or "onboarding". # Updating Source: https://docs.evolutionfoundation.com.br/evo-nexus/guides/updating Esta página ainda está em inglês. A tradução para português está em andamento. # Updating EvoNexus ## Check your current version Your version is shown in the sidebar footer of the dashboard. You can also check it via API: ```bash theme={null} curl http://localhost:8080/api/version ``` Or directly from `pyproject.toml` at the workspace root: ```bash theme={null} grep '^version' pyproject.toml ``` ## Update via Git (recommended) ```bash theme={null} cd /path/to/your/workspace git pull origin main ``` Then rebuild the frontend and restart the backend: ```bash theme={null} cd dashboard/frontend npm install npm run build # Restart the backend (or the full stack) cd ../backend # If running directly: kill $(lsof -ti :8080) 2>/dev/null python app.py & ``` ## Update via Docker (published images) Starting with **v0.30.2**, official multi-arch images (amd64 + arm64) are published to Docker Hub under the `evoapicloud` namespace: * `evoapicloud/evo-nexus-dashboard` — Flask + React + embedded terminal + Claude CLI * `evoapicloud/evo-nexus-runtime` — Node/Python runtime for the Telegram bot and the scheduler The images are public — no `docker login` required. ### docker compose (single host, from Docker Hub) If you deployed with [`docker-compose.hub.yml`](https://github.com/evolution-foundation/evo-nexus/blob/main/docker-compose.hub.yml) (the recommended flow documented in [Installing with Docker](./docker-install.md)): ```bash theme={null} docker compose -f docker-compose.hub.yml pull docker compose -f docker-compose.hub.yml up -d ``` Named volumes are preserved — all your configuration, providers, integrations, and memory stay intact. ### Docker Swarm / Portainer Bump the image tag in your stack (or leave `:latest` and force a redeploy). Example: ```bash theme={null} docker service update --image evoapicloud/evo-nexus-dashboard:v0.30.4 evonexus_evonexus_dashboard docker service update --image evoapicloud/evo-nexus-runtime:v0.30.4 evonexus_evonexus_telegram docker service update --image evoapicloud/evo-nexus-runtime:v0.30.4 evonexus_evonexus_scheduler ``` See [`README.swarm.md`](https://github.com/evolution-foundation/evo-nexus/blob/main/README.swarm.md) for the full Swarm / Portainer deployment guide and the `evonexus.stack.yml` template. ### Local docker compose (building from source) If you're running `docker-compose.yml` locally (building the image from source instead of pulling from Docker Hub): ```bash theme={null} cd /path/to/your/workspace git pull origin main docker compose build docker compose up -d ``` To rebuild without cache (useful if dependencies changed): ```bash theme={null} docker compose build --no-cache docker compose up -d ``` ## Custom routines and skills are safe Your custom routines (`ADWs/scripts/`), skills (`.claude/skills/`), and workspace configuration files are **gitignored** and will not be overwritten by `git pull`. The same applies to: * `.env` files * `dashboard/data/` (database, secrets) * `config/workspace.yaml` * `memory/` directory contents * Session logs in `workspace/daily-logs/` If you've modified a tracked file, `git pull` may show a merge conflict. In that case, stash your changes first: ```bash theme={null} git stash git pull origin main git stash pop ``` ## Checking for updates programmatically The dashboard checks for updates automatically (cached for 1 hour). You can also call: ```bash theme={null} curl http://localhost:8080/api/version/check ``` Returns: ```json theme={null} { "current": "0.3.2", "latest": "0.4.0", "update_available": true, "release_url": "https://github.com/evolution-foundation/evo-nexus/releases/tag/v0.4.0", "release_notes": "..." } ``` ## Changelog See all releases and changelogs on GitHub: [https://github.com/evolution-foundation/evo-nexus/releases](https://github.com/evolution-foundation/evo-nexus/releases) # Using agents Source: https://docs.evolutionfoundation.com.br/evo-nexus/guides/using-agents Esta página ainda está em inglês. A tradução para português está em andamento. # Using Agents EvoNexus ships with 16 specialized agents, each owning a specific domain. You don't need to memorize commands — just describe what you need and Claude routes to the right agent. ## Getting Started 1. Open Claude Code in the workspace directory 2. Start talking — agents activate automatically based on context ## Quick Examples ### Morning Briefing Just say: ``` good morning ``` Clawdia checks your calendar, emails, and tasks, then gives you a prioritized briefing for the day. ### Financial Pulse ``` /flux financial pulse ``` Flux queries Stripe and Omie, then generates an HTML report with MRR, charges, churn, receivables, and payables. ### GitHub Review ``` /atlas check github ``` Atlas reviews open PRs, community issues, stars/forks, and recent releases across all Evolution repositories. ### Community Pulse ``` /pulse community pulse ``` Pulse reads Discord and WhatsApp messages from the last 24 hours, analyzes sentiment, identifies top topics, and flags unanswered support questions. ### Social Media Content ``` /pixel write a post about our new release ``` Pixel drafts platform-specific posts (LinkedIn, Twitter/X, Threads) following your brand voice, content pillars, and audience context. ### Strategy Digest ``` /sage strategy digest ``` Sage consolidates financial, product, community, and market data into a weekly strategic summary with insights and recommended actions. ## How Agent Routing Works You don't have to use slash commands. Claude reads your intent and picks the right agent: | You say... | Agent activated | | ------------------------------------- | --------------- | | "check my inbox" | Clawdia | | "how's the MRR this month?" | Flux | | "any open PRs?" | Atlas | | "what's the community talking about?" | Pulse | | "draft a LinkedIn post" | Pixel | | "review our OKRs" | Sage | | "schedule a meeting" | Clawdia | | "who are our competitors?" | Sage | | "check my health data" | Kai | | "create a course module" | Mentor | ## All 16 Agents | Agent | Command | Domain | | ----------- | ---------- | ------------------------------------------------- | | **Clawdia** | `/clawdia` | Hub — calendar, emails, tasks, decisions | | **Flux** | `/flux` | Finance — cash flow, Stripe, Omie | | **Atlas** | `/atlas` | Projects — GitHub, Linear, milestones | | **Pulse** | `/pulse` | Community — Discord, WhatsApp, sentiment | | **Pixel** | `/pixel` | Social media — content, analytics | | **Sage** | `/sage` | Strategy — OKRs, roadmap, competitive | | **Kai** | `/kai` | Personal — health, habits, routine | | **Nex** | `/nex` | Sales — pipeline, proposals | | **Mentor** | `/mentor` | Courses — Evo Academy, modules | | **Oracle** | `/oracle` | Knowledge — workspace docs, how-to, config | | **Mako** | `/mako` | Marketing — campaigns, SEO, brand | | **Aria** | `/aria` | HR / People — recruiting, onboarding, performance | | **Zara** | `/zara` | Customer Success — triage, escalation, health | | **Lex** | `/lex` | Legal — contracts, compliance, NDA, risk | | **Nova** | `/nova` | Product — specs, roadmaps, metrics | | **Dex** | `/dex` | Data / BI — analysis, SQL, dashboards | ## Tips * **Agents share memory.** Context from one session is available in the next via the `memory/` directory. If you told Clawdia about a deadline, Sage can reference it when generating strategy. * **Combine agents naturally.** Say "check github and then write a post about the latest release" — Atlas reviews repos, then Pixel drafts the post. * **Agents respect your preferences.** All responses are in pt-BR, use Brasilia timezone, and follow your professional tone. * **Check agent definitions** in `.claude/agents/` to see exactly what each agent can do. # Heartbeats Source: https://docs.evolutionfoundation.com.br/evo-nexus/heartbeats Agentes proativos que acordam em uma agenda e decidem se devem agir # Heartbeats Heartbeats — agentes proativos com agenda, status e custo **Heartbeats são agentes proativos.** Um heartbeat é uma configuração que acorda um agente em uma agenda para que ele faça triagem de trabalho sem ser pedido. Em vez de você lembrar de perguntar ao Atlas "tem PR parado?" toda manhã, o Atlas acorda a cada 4 horas, verifica e age só se houver algo a fazer. ## O Modelo Mental Uma rotina é **sistemática** — o mesmo script roda todo dia às 7h. Um heartbeat é **proativo** — o agente acorda, observa e decide se deve agir. Cada execução de heartbeat responde a uma única pergunta: > Dado o estado atual do meu domínio, devo trabalhar agora ou pular? O agente retorna um veredicto em JSON. Se `action: work`, o dispatcher deixa o agente executar seus turnos. Se `action: skip`, a execução termina imediatamente com custo próximo de zero. ## Anatomia de um Heartbeat Heartbeats vivem em `config/heartbeats.yaml` (fonte da verdade) e são espelhados no banco do dashboard. Cada entrada tem: | Campo | O que faz | | ---------------------- | ------------------------------------------------------------------------- | | `id` | Slug único, kebab-case (ex. `atlas-4h`) | | `agent` | Qual agente acordar (`atlas-project`, `zara-cs`, …) | | `interval_seconds` | A cada quantos segundos o trigger por intervalo dispara. Mínimo 60 | | `max_turns` | Limite duro de turnos do Claude por execução (padrão 10) | | `timeout_seconds` | Timeout duro para matar o subprocesso (padrão 300) | | `lock_timeout_seconds` | Limite para limpeza de locks parados (padrão 1800) | | `wake_triggers` | Subconjunto de `[interval, new_task, mention, manual, approval_decision]` | | `decision_prompt` | A pergunta que o agente responde — precisa forçar um veredicto JSON | | `goal_id` | Slug opcional de goal para injeção de contexto | | `required_secrets` | Chaves do `.env` que o agente precisa | | `enabled` | Chave-mestra. Sempre começa em `false` | ## Início Rápido ### 1. Crie um heartbeat No Claude Code, use a skill `create-heartbeat`: > "Crie um heartbeat de 4 horas para atlas-project que triagem PRs e issues parados." A skill conduz pelos campos, deixa `enabled: false` por padrão e chama `POST /api/heartbeats`. A entrada aparece na página **Heartbeats** do dashboard como desabilitada. Alternativamente, edite `config/heartbeats.yaml` diretamente e chame `POST /api/heartbeats/reindex` para espelhar no banco. ### 2. Dry-run antes de habilitar No dashboard, clique em **Run now** no card (ou chame `POST /api/heartbeats/{id}/run`). Isso dispara uma execução manual única, independente do relógio do interval. Inspecione o resultado: * O agente retornou JSON válido? * A decisão foi razoável? * Ficou dentro de `max_turns` e `timeout_seconds`? Se sim, ative o toggle. O dispatcher pega no próximo tick do interval. ### 3. Monitore as execuções Cada execução registra `started_at`, `finished_at`, `status`, `tokens_input`, `tokens_output`, `cost_usd` e o `decision_json` parseado. A página **Heartbeats** no dashboard mostra as últimas 10 execuções por card e o custo agregado de 7 dias. ## Wake Triggers Um heartbeat acorda em qualquer um dos triggers listados em `wake_triggers`: * **interval** — o scheduler dispara a cada `interval_seconds`. Quase sempre incluído. * **manual** — alguém clica em "Run now" ou chama a API. Permite a operadores debugar. * **mention** — um `@agent-slug` num comentário de ticket dispara um mention trigger (se o agente tiver um heartbeat habilitado com `mention` nos wake\_triggers). Máximo 3 mentions por comentário. * **new\_task** — uma task de goal criada com este agente como `assignee_agent` acorda o heartbeat. * **approval\_decision** — uma solicitação de aprovação foi decidida (feature futura). Mais triggers = mais responsividade. Menos triggers = custo mais previsível. ## Controle de Custo Como heartbeats queimam tokens em cada execução, coloque guardrails: 1. **Comece com `enabled: false`**. Sempre. Revise a primeira execução manual antes de habilitar. 2. **Use um `decision_prompt` afiado**. Se o agente escreve um parágrafo quando devia escrever JSON, você desperdiça tokens. 3. **Tenda ao `skip`**. Treine o prompt para pular a menos que haja urgência genuína. Um heartbeat de 4 horas que pula 4 das 6 execuções diárias está fazendo seu trabalho. 4. **Mantenha `max_turns` baixo** para heartbeats puramente de triagem (5–10). Só aumente para agentes que podem precisar agir em múltiplos itens. 5. **Acompanhe `cost_7d`** no card do dashboard. Se um heartbeat sobe consistentemente, o prompt provavelmente está muito leniente — aperte os critérios de skip. ## Debugando ### Um heartbeat não está disparando 1. Cheque o `enabled` do heartbeat — está individualmente ligado? 2. Cheque o log do dispatcher (`journalctl -u evo-nexus -f` ou os logs do serviço do dashboard) para registro do interval. 3. Chame `POST /api/heartbeats/{id}/run` — uma execução manual funciona? Se sim, é problema de scheduler; se não, é problema do agente ou prompt. ### Uma execução falhou Olhe o `stderr_tail` e `stdout_tail` da execução. Causas comuns: * `required_secrets` faltando no `.env` * `decision_prompt` não forçou JSON — o parser não conseguiu extrair o veredicto * O agente bateu em `max_turns` antes de retornar (aumente o limite ou aperte o prompt) * O agente bateu em `timeout_seconds` (chamada de integração foi lenta — aumente o timeout ou adicione um retry dentro do agente) ### Drift entre YAML e banco Se você editou `config/heartbeats.yaml` à mão e o dashboard ainda mostra o estado antigo: ```bash theme={null} curl -X POST http://localhost:8080/api/heartbeats/reindex ``` Reconstrói as linhas do banco a partir do YAML. Seguro de rodar a qualquer momento. ## Skills do CLI | Skill | O que faz | | ------------------- | -------------------------------------------------------------------------------- | | `create-heartbeat` | Wizard interativo para adicionar um novo heartbeat | | `manage-heartbeats` | Listar, habilitar/desabilitar, disparar execuções manuais, inspecionar histórico | ## Relacionados * `docs/goals.md` — ligar um heartbeat a um goal para injeção de contexto * `docs/tickets.md` — `@mentions` em tickets acordam heartbeats * Código: `dashboard/backend/heartbeat_dispatcher.py`, `dashboard/backend/routes/heartbeats.py`, `dashboard/backend/heartbeat_schema.py` # Asaas Source: https://docs.evolutionfoundation.com.br/evo-nexus/integrations/asaas Esta página ainda está em inglês. A tradução para português está em andamento. # Asaas Integration Asaas is a Brazilian payment platform that handles billing via Pix, boleto, credit card, and subscriptions, plus marketplace split payments and webhook events. The @flux agent uses Asaas alongside Stripe for a complete picture of incoming revenue from Brazilian customers. The `int-asaas` skill talks to **Asaas API v3** via a static API key — no OAuth, no token rotation. Setup is a single `.env` edit. ## Setup ### 1. Get Your API Key 1. Log in at [asaas.com](https://www.asaas.com) 2. Go to **Minha Conta > Integrações > API** 3. Generate (or copy) your API key 4. Asaas has separate keys for **sandbox** and **production** — start with sandbox until you are confident the integration is behaving correctly ### 2. Configure .env ```env theme={null} ASAAS_API_KEY=your_api_key_here ASAAS_SANDBOX=true ``` **`ASAAS_SANDBOX=true` is the safe default.** It makes all calls hit `https://sandbox.asaas.com/api/v3` instead of production. Set it to `false` only when you are ready to move charges, customers, and subscriptions into your real account. ### 3. Test the Connection Use the skill directly through curl (the simplest test): ```bash theme={null} curl -H "access_token: $ASAAS_API_KEY" \ https://sandbox.asaas.com/api/v3/customers?limit=1 ``` If you get a JSON list (possibly empty), you are connected. Switch to `https://api.asaas.com/v3` for production. ## How Authentication Works Asaas uses a static API key sent as a custom HTTP header on every request: ``` access_token: ``` No OAuth, no refresh tokens, no expiration. The key stays valid until you rotate it manually in the Asaas dashboard. If you rotate, update `.env` and you are done. The base URL is chosen dynamically based on `ASAAS_SANDBOX`: * `ASAAS_SANDBOX=true` → `https://sandbox.asaas.com/api/v3` (default) * `ASAAS_SANDBOX=false` → `https://api.asaas.com/v3` ## Available Operations The `int-asaas` skill documents **15 operations** grouped by domain: | Category | Operations | | ----------------- | --------------------------------------------------------------------------------- | | **Payments** | create, get by ID, list (with filters), get Pix QR code, get boleto PDF + barcode | | **Customers** | create (with CPF/CNPJ validation), list | | **Subscriptions** | create, list, cancel (recurring billing) | | **Financial** | get account balance, create transfer (Pix out or TED) | | **Marketplace** | create subaccount (for split payments) | | **Utilities** | get installment details, list webhook events | ### Enums You Will Use Often **`billingType`** (how the customer pays): * `BOLETO` — Brazilian bank slip * `CREDIT_CARD` — credit card * `PIX` — instant transfer * `UNDEFINED` — let the customer choose at checkout **Payment `status`** (lifecycle): * `PENDING` — awaiting payment * `RECEIVED` — paid * `CONFIRMED` — paid and reconciled * `OVERDUE` — past due date * `REFUNDED` — refunded * `RECEIVED_IN_CASH` — marked as paid in cash * `REFUND_REQUESTED`, `CHARGEBACK_REQUESTED`, `AWAITING_CHARGEBACK_REVERSAL` * `DUNNING_REQUESTED`, `DUNNING_RECEIVED` — collections * `AWAITING_RISK_ANALYSIS` — under fraud review ### Data Formats All operations expect Brazilian document formats stripped of punctuation: | Field | Format | | ------ | -------------------------------------------- | | CPF | 11 digits, no dashes (e.g. `12345678900`) | | CNPJ | 14 digits, no dashes (e.g. `12345678000100`) | | CEP | 8 digits, no dashes (e.g. `01310100`) | | Dates | ISO `YYYY-MM-DD` | | Values | Decimal with dot (e.g. `99.90`) | ## Example Calls ```bash theme={null} # Create a customer curl -X POST https://sandbox.asaas.com/api/v3/customers \ -H "access_token: $ASAAS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"João Silva","cpfCnpj":"12345678900","email":"joao@example.com"}' # Create a Pix payment curl -X POST https://sandbox.asaas.com/api/v3/payments \ -H "access_token: $ASAAS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"customer":"cus_XXX","billingType":"PIX","value":99.90,"dueDate":"2026-04-15","description":"Plan subscription"}' # Get the Pix QR code for a payment curl https://sandbox.asaas.com/api/v3/payments/pay_XXX/pixQrCode \ -H "access_token: $ASAAS_API_KEY" # List subscriptions curl https://sandbox.asaas.com/api/v3/subscriptions?limit=20 \ -H "access_token: $ASAAS_API_KEY" # Get account balance curl https://sandbox.asaas.com/api/v3/finance/balance \ -H "access_token: $ASAAS_API_KEY" ``` ## Webhooks Asaas can send real-time events for payment status changes (created, received, overdue, refunded, chargeback) and subscription lifecycle. Configure the webhook URL in the Asaas dashboard under **Integrações > Webhooks** — this part is done in the dashboard, not via the API. The `get_webhook_events` operation is available to list the last events received by Asaas (useful for debugging delivery failures). ## Advanced Endpoints (Reference Only) The following are documented by the Asaas API but **not** wrapped by the skill yet: * Credit card tokenization (requires extra fields and PCI considerations) * Receivables anticipation (`antecipações`) * Tax/fiscal info attached to payments * Batch payment creation If you need any of these, extend the skill using the reference implementation at `workspace/projects/mcp-dev-brasil/packages/payments/asaas/` and the [official docs](https://docs.asaas.com). ## Skills That Use Asaas | Skill | What it does | | --------------------------- | ----------------------------------------------------------------------------------- | | `int-asaas` | Direct Asaas API queries — payments, customers, subscriptions, balance, transfers | | `fin-daily-pulse` | Daily snapshot — can include Asaas receipts alongside Stripe | | `fin-weekly-report` | Weekly consolidation across Stripe + Asaas + Omie + Bling | | `fin-monthly-close-kickoff` | Month-end close — Asaas subscriptions and payments feed into revenue reconciliation | ## Troubleshooting ### 401 `invalid_token` Your `ASAAS_API_KEY` is wrong, expired (manually rotated), or you are mixing sandbox and production keys. Re-copy the key from the Asaas dashboard, making sure you are on the correct environment, and confirm `ASAAS_SANDBOX` matches. ### 400 `invalid cpfCnpj` You passed a CPF or CNPJ with dots, dashes, or slashes. Asaas expects digits only — 11 for CPF, 14 for CNPJ. ### Sandbox calls returning production data (or vice versa) Double-check `ASAAS_SANDBOX` in `.env`. The two environments are completely isolated — a customer created in sandbox does **not** exist in production. ### Webhook is not firing Webhooks are configured in the Asaas dashboard, not in `.env`. Go to **Integrações > Webhooks**, make sure the URL is reachable from the public internet, and use `get_webhook_events` to inspect delivery attempts. # Bling Source: https://docs.evolutionfoundation.com.br/evo-nexus/integrations/bling Esta página ainda está em inglês. A tradução para português está em andamento. # Bling ERP Integration Bling is a Brazilian cloud ERP for managing products, sales orders, contacts (customers/suppliers), fiscal invoices (NF-e), and stock. The @flux agent uses Bling alongside Omie, Stripe, and Asaas to get a complete financial and operational picture for Brazilian businesses. The `int-bling` skill talks to **Bling API v3** via OAuth2 with **automatic token refresh** — you authenticate once with `make bling-auth` and the skill keeps the session alive forever. ## Setup ### 1. Create a Bling App 1. Log in at [developer.bling.com.br](https://developer.bling.com.br) 2. Go to **Meus Apps** and create a new application 3. Set the **redirect URI** to exactly: ``` http://localhost:8787/callback ``` 4. Copy the **Client ID** and **Client Secret** ### 2. Configure .env ```env theme={null} BLING_CLIENT_ID=your_client_id_here BLING_CLIENT_SECRET=your_client_secret_here ``` Leave `BLING_ACCESS_TOKEN` and `BLING_REFRESH_TOKEN` empty — the next step fills them in. ### 3. Run the OAuth Login ```bash theme={null} make bling-auth ``` What it does: 1. Starts a local callback server on `http://localhost:8787/callback` 2. Opens your browser at Bling's authorization page 3. You log in and approve the app 4. Bling redirects back to the local server with an authorization code 5. The helper exchanges the code for `access_token` + `refresh_token` 6. Both tokens are persisted to `.env` After a successful run, `.env` contains: ```env theme={null} BLING_CLIENT_ID=... BLING_CLIENT_SECRET=... BLING_ACCESS_TOKEN=... BLING_REFRESH_TOKEN=... ``` You only do this once per Bling account. From now on, the skill refreshes tokens automatically whenever they expire. ### 4. Test the Connection Run any read operation through the Python client: ```bash theme={null} python3 .claude/skills/int-bling/scripts/bling_client.py GET /produtos --params page=1 limit=10 ``` If the JSON response includes products, you are connected. If you get a `401`, the client will automatically refresh the token and retry once. ## How Automatic Refresh Works The Python client (`.claude/skills/int-bling/scripts/bling_client.py`) is the single entry point for all API calls. On any `HTTP 401`: 1. It exchanges `BLING_REFRESH_TOKEN` for a new `access_token` + `refresh_token` at `https://www.bling.com.br/Api/v3/oauth/token` using HTTP Basic auth with Client ID and Client Secret. 2. Both new tokens are persisted back to `.env` and to `os.environ`. 3. The original request is retried once with the fresh access token. > **Important:** Bling **rotates the refresh token on every refresh**, so always use the provided client. Never call the API directly with `curl` unless you are debugging — otherwise the next refresh will use a stale refresh token and the session will break. If that happens, run `make bling-auth` again to start over. ## Calling the Client ```bash theme={null} # List products (paginated) python3 .claude/skills/int-bling/scripts/bling_client.py GET /produtos --params page=1 limit=50 # List orders for a date range python3 .claude/skills/int-bling/scripts/bling_client.py GET /pedidos/vendas --params dataInicial=2026-01-01 dataFinal=2026-04-10 # Create a contact (PJ) python3 .claude/skills/int-bling/scripts/bling_client.py POST /contatos --body '{"nome":"Acme Ltda","tipo":"J","numeroDocumento":"12345678000100"}' # Update a product's price python3 .claude/skills/int-bling/scripts/bling_client.py PUT /produtos/123 --body '{"preco":99.90}' ``` The client prints the JSON response to stdout and writes errors to stderr. ## Available Operations The `int-bling` skill documents **10 operations** covering the core of an ERP workflow: | Category | Operations | | -------------------------- | --------------------------------------------------------------------------------------------------- | | **Products** | list, create (fields: `nome`, `codigo`, `preco`, `precoCusto`, `tipo` P/S/K, `formato` S/E/V) | | **Sales Orders** | list, create (fields: `contato.id`, `itens[]` with `produto.id`, `quantidade`, `valor`, `desconto`) | | **Contacts** | list, create (`F` for people, `J` for companies, with CPF/CNPJ) | | **Fiscal Invoices (NF-e)** | list, create (issued from an existing order) | | **Stock** | get stock level, update stock by warehouse (`depositoId`) | All list endpoints support pagination via `page` and `limit` (default 100). Dates use the `YYYY-MM-DD` format. ## Advanced Endpoints (Reference Only) The following are **not** wrapped by the skill yet — use the reference implementation in `workspace/projects/mcp-dev-brasil/packages/erp/bling/` and the [official API v3 docs](https://developer.bling.com.br) as guides: * Product categories and variations * Purchase orders and production management * Warehouse/depósito CRUD * Stock movement history and audit trails * NF-e cancellations and complementary invoices * Webhooks If you need any of these, extend `bling_client.py` and document the new operation in `.claude/skills/int-bling/SKILL.md`. ## Skills That Use Bling | Skill | What it does | | --------------------------- | ----------------------------------------------------------------------- | | `int-bling` | Direct Bling API queries — products, orders, contacts, NF-e, stock | | `fin-daily-pulse` | Daily snapshot — can include Bling invoices alongside Stripe/Asaas/Omie | | `fin-weekly-report` | Weekly consolidation across all connected ERPs and payment gateways | | `fin-monthly-close-kickoff` | Month-end close — Bling invoices feed into the revenue reconciliation | ## Troubleshooting ### `make bling-auth` says "missing BLING\_CLIENT\_ID / BLING\_CLIENT\_SECRET" Fill both values in `.env` first, then run again. ### Browser does not open automatically Copy the URL the CLI prints and paste it manually. The local callback server will still catch the redirect. ### Redirect URI mismatch Bling will show an error page if the app's redirect URI is not exactly `http://localhost:8787/callback`. Fix it in the app settings at `developer.bling.com.br`. ### 401 errors keep coming back Your refresh token is probably stale because some other process bypassed `bling_client.py`. Run `make bling-auth` again to get a fresh pair of tokens. ### State mismatch error The CLI refused the callback because of a CSRF check failure (very rare — usually means the browser returned an old callback). Re-run `make bling-auth`. # Databases Source: https://docs.evolutionfoundation.com.br/evo-nexus/integrations/databases Esta página ainda está em inglês. A tradução para português está em andamento. # Databases — Postgres & MySQL (v0.28+) Configure one or more databases via `.env` and query them from any agent via the `db-postgres` / `db-mysql` skills. Same pattern as the social integrations (`SOCIAL_YOUTUBE_N_*`, etc.) — numbered blocks, `.env` is gitignored, no extra infra. ## TL;DR ```env theme={null} DB_POSTGRES_1_LABEL=msgops-dev DB_POSTGRES_1_HOST=db.dev.internal DB_POSTGRES_1_PORT=5432 DB_POSTGRES_1_DATABASE=msgops DB_POSTGRES_1_USER=agent_readonly DB_POSTGRES_1_PASSWORD=*** DB_POSTGRES_1_SSL_MODE=require ``` ```bash theme={null} # one-time uv pip install psycopg2-binary # query python3 .claude/skills/db-postgres/scripts/db_client.py \ query msgops-dev "SELECT count(*) FROM users" ``` Writes are refused unless the connection opts in: ```env theme={null} DB_POSTGRES_1_ALLOW_WRITE=true ``` ## Supported flavors (v1) | Flavor | Skill | Driver | Default port | | --------------- | ------------- | ----------------- | ------------ | | PostgreSQL | `db-postgres` | `psycopg2-binary` | 5432 | | MySQL / MariaDB | `db-mysql` | `pymysql` | 3306 | Mongo and Redis are planned for v2 — same env-block pattern, different verbs. ## Env block reference ### Postgres | Key | Required | Default | Notes | | ------------------------------- | -------- | ------- | ------------------------------------------------------------------- | | `DB_POSTGRES__LABEL` | yes | — | Human name, how agents pick the connection. Case-insensitive match. | | `DB_POSTGRES__HOST` | yes\* | — | \*unless `DSN` is set | | `DB_POSTGRES__PORT` | no | 5432 | | | `DB_POSTGRES__DATABASE` | yes\* | — | \*unless `DSN` is set | | `DB_POSTGRES__USER` | yes\* | — | \*unless `DSN` is set | | `DB_POSTGRES__PASSWORD` | no | — | Omit for password-less local dev | | `DB_POSTGRES__SSL_MODE` | no | — | `disable`, `require`, `verify-ca`, `verify-full` | | `DB_POSTGRES__SSL_CA_PATH` | no | — | Path to CA cert (for `verify-*` modes) | | `DB_POSTGRES__DSN` | no | — | Full `postgresql://...` URI. Wins over components. | | `DB_POSTGRES__ALLOW_WRITE` | no | `false` | Set `true` to permit write verbs. | | `DB_POSTGRES__QUERY_TIMEOUT` | no | `30` | Seconds. Applied via `SET statement_timeout`. | | `DB_POSTGRES__MAX_ROWS` | no | `1000` | Rows returned inline; full result spills to CSV when truncated. | ### MySQL / MariaDB | Key | Required | Default | Notes | | ---------------------------- | -------- | ------- | --------------------------------------------------------------- | | `DB_MYSQL__LABEL` | yes | — | Human name, how agents pick the connection. | | `DB_MYSQL__HOST` | yes\* | — | \*unless `DSN` is set | | `DB_MYSQL__PORT` | no | 3306 | | | `DB_MYSQL__DATABASE` | yes\* | — | \*unless `DSN` is set | | `DB_MYSQL__USER` | yes\* | — | \*unless `DSN` is set | | `DB_MYSQL__PASSWORD` | no | — | | | `DB_MYSQL__SSL_CA_PATH` | no | — | Enables TLS verification when set | | `DB_MYSQL__DSN` | no | — | Full `mysql://...` URI. Wins over components. | | `DB_MYSQL__ALLOW_WRITE` | no | `false` | Set `true` to permit write verbs. | | `DB_MYSQL__QUERY_TIMEOUT` | no | `30` | Seconds. Applied via `SET SESSION MAX_EXECUTION_TIME`. | | `DB_MYSQL__MAX_ROWS` | no | `1000` | Rows returned inline; full result spills to CSV when truncated. | ## How agents pick a connection * **By label** (case-insensitive exact match): `query msgops-dev "SELECT ..."`. * **By index** (the `N` in the env key): `query 1 "SELECT ..."`. * If the label matches two blocks (user error — labels should be unique), the agent gets an `ambiguous` error and has to use the index. ## Commands (same surface across flavors) ```bash theme={null} # List configured connections — returns label, host, port, database, guardrails db_client.py accounts # RTT + 'SELECT 1' roundtrip, ~10s timeout db_client.py test # Run a query, streamed result (max MAX_ROWS inline, rest spilled to CSV) db_client.py query "" # List tables (excluding system schemas) db_client.py tables # Describe a single table (columns, types, nullability, defaults) db_client.py describe db_client.py describe .
``` All commands output one JSON line on stdout, safe to pipe. Errors go to stderr as JSON and exit non-zero. ## Guardrails * **Read-only by default.** Write verbs — `DELETE | UPDATE | INSERT | REPLACE | TRUNCATE | DROP | ALTER | CREATE | GRANT | REVOKE | ...` — are refused unless `ALLOW_WRITE=true` on that specific connection. * **One statement per call.** Multi-statement SQL (extra `;` with content after) is refused in v1. * **Timeouts are enforced server-side** (`statement_timeout` for Postgres, `MAX_EXECUTION_TIME` for MySQL 5.7.4+) — a runaway query hits the DB's own cancellation, not just a client-side timer. * **Row cap** — `MAX_ROWS` is a soft cap on what's returned inline. When exceeded, the script persists the full result to `ADWs/logs/db-queries/.csv` and signals `truncated: true` + `full_result_path` so the agent can read the file directly instead of re-running with a larger limit. * **Credentials stay in `.env`.** They never transit through the dashboard's process memory (unless you use the `/integrations/databases` Test button, which only reads them transiently for the test RTT), never get logged, and never enter the agent's context beyond the subprocess that executes the query with those env vars set. ## Error codes | Code | Meaning | | ------------------- | ------------------------------------------------------- | | `no_connections` | No `DB__N_*` blocks in `.env` | | `not_found` | Label/index doesn't match any block | | `ambiguous` | Multiple blocks share the same label — use the index | | `config_error` | A block exists but `LABEL` is missing | | `driver_missing` | `psycopg2`/`pymysql` not installed | | `connection_failed` | Network, auth, TLS, or timeout tripped | | `write_blocked` | Write verb detected on a `ALLOW_WRITE=false` connection | | `multi_statement` | More than one statement in a single call | | `usage` | Wrong CLI args | ## Rotating a password 1. Edit `.env` — replace the old value in the relevant block. 2. Restart the dashboard (or just source `.env` again in the shell you run agents from). 3. The next `db_client.py` call reads the new value — no restart of individual agents needed. ## FAQ **Why not a SQLite registry + encrypted credentials?** We considered it, chose `.env` for consistency with every other integration (Stripe, Omie, Social) and because it already solves the problem: `.env` is gitignored, editable in plain text, and there's an in-product env editor at `/integrations/env-editor` for dashboard-only flows. Zero new infra, no new master key, no new table. **What about DBs behind Auth0 / OIDC proxies?** v1 assumes a static password or DSN is enough. If a DB requires token-exchange, the current workaround is to set a service token as `PASSWORD` and let the proxy handle exchange. Native OIDC support is deferred. **Can I use this for the workspace's own SQLite DB (`dashboard.db`)?** Not in v1 — the `db-*` skills target network-attached SQL services. For `dashboard.db` introspection, keep using `data-analyze` / `data-write-query` which already know that shape. **Is the `/integrations/databases` page the source of truth?** No. `.env` is. The page is a read-only convenience view — it lists what's parsed from `.env`, offers a Test button, and can copy a block template to the clipboard. It never persists passwords. ## See also * [`db-postgres` SKILL.md](../../.claude/skills/db-postgres/SKILL.md) — full command reference + deep-dive references * [`db-mysql` SKILL.md](../../.claude/skills/db-mysql/SKILL.md) — full command reference + deep-dive references * [`data-write-query`](../skills/data-write-query.md) — SQL authoring skill (can compose with `db-*` via `--connection