> For the complete documentation index, see [llms.txt](https://help.hyperflow.global/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/controle-de-fluxo/agente.md). # Agente ## 🏆 Módulo Oportunidades O módulo **Oportunidades** permite que o seu chatbot interaja com o CRM do Desk durante uma conversa. Com ele, você pode criar novas oportunidades, consultá-las, movê-las entre etapas do funil, atualizá-las ou removê-las — tudo de forma automática, enquanto o atendimento acontece. **📷 Inserir print:** visão geral do nó Oportunidades no canvas do Builder *** ### 🗂️ Como acessar 1. No menu lateral, clique em **Aplicativo**. 2. Em seguida, clique em **Fluxos**. 3. Abra o fluxo desejado ou crie um novo. 4. No canvas do Builder, clique no botão **+** para adicionar um novo nó. 5. Localize e selecione **Oportunidades** na lista de módulos disponíveis. **📷 Inserir print:** lista de módulos com o item "Oportunidades" destacado {% hint style="warning" %} **Pré-requisito:** Para usar este módulo, o seu bot precisa ter uma conexão com o Desk configurada. Caso contrário, o módulo exibirá a mensagem *"Parece que você não tem uma conexão com o Desk"*. Acesse as configurações do bot, conecte o Desk e tente novamente. {% endhint %} *** ### 🧩 Conhecendo o módulo Ao adicionar o módulo Oportunidades ao fluxo, um painel de configuração é aberto. Nele, você define **o que o bot deve fazer** com as oportunidades do seu CRM. **📷 Inserir print:** painel de configuração do módulo Oportunidades aberto #### 🔧 Ação O primeiro passo é escolher **qual operação** o módulo deve executar. Clique no campo **Ação** e selecione uma das opções: | Ação | O que faz | | -------------------------- | -------------------------------------------------------------- | | **Criar oportunidade** | Cria um novo registro de oportunidade no funil selecionado | | **Listar oportunidades** | Busca e retorna uma lista de oportunidades com base em filtros | | **Mover oportunidade** | Move uma oportunidade existente para outra etapa do funil | | **Atualizar oportunidade** | Edita os dados de uma oportunidade existente | | **Remover oportunidade** | Exclui uma oportunidade do CRM | **📷 Inserir print:** campo de seleção de ação com as 5 opções visíveis #### 🔽 Funil (Pipeline) Após escolher a ação, selecione o **Funil** no qual a operação será realizada. Clique no campo **Selecionar funil** e escolha um dos funis cadastrados no seu Desk. {% hint style="info" %} Os campos e etapas disponíveis nas próximas configurações dependem do funil escolhido aqui. Certifique-se de selecionar o funil correto antes de continuar. {% endhint %} **📷 Inserir print:** campo de seleção de funil com lista de opções *** ### ⚙️ Configurações por ação As opções exibidas mudam conforme a ação selecionada. Veja abaixo o que configurar em cada caso. *** #### 1️⃣ Criar oportunidade **🎯 Propósito** Criar automaticamente uma nova oportunidade no CRM durante a conversa — por exemplo, quando um lead chega pelo chatbot. **✅ Como fazer na tela** 1. Selecione a ação **Criar oportunidade**. 2. Selecione o **Funil** desejado. 3. Selecione a **Etapa** do funil onde a oportunidade será criada. 4. No campo **Adicionar campos**, escolha quais informações o bot deve preencher na oportunidade (ex.: Título, Responsável, Anexo, campos personalizados do funil). 5. Preencha os valores de cada campo selecionado: * **Título** — Nome da oportunidade. Campo obrigatório. * **Responsável** — Pessoa responsável pela oportunidade. Você pode selecionar da lista de membros ou, ativando a opção **Usar uma variável ou e-mail do responsável**, inserir diretamente o e-mail ou uma variável do fluxo (ex.: `{{input.email}}`). * **Anexo** — Informe o **Nome do arquivo** e a **URL do arquivo** para vincular um documento à oportunidade. * **Campos personalizados** — Campos extras configurados no seu funil (texto, data, valor monetário, seleção única, múltipla escolha, etc.). 6. Ative **Adicionar contato à oportunidade** caso queira vincular automaticamente o contato do atendimento à oportunidade criada. 7. Em **Tags**, selecione as etiquetas que devem ser aplicadas à oportunidade. 8. Clique em **Salvar**. {% hint style="info" %} Datas devem ser preenchidas no formato **DD/MM/AAAA**. Exemplo: `31/12/2025`. {% endhint %} **📌 Resultado esperado** Uma nova oportunidade é criada no funil e na etapa escolhidos, com todos os dados preenchidos. O fluxo segue para o próximo nó conectado. **📷 Inserir print:** configuração completa da ação "Criar oportunidade" com campos preenchidos *** #### 2️⃣ Listar oportunidades **🎯 Propósito** Consultar oportunidades cadastradas no CRM com base em filtros, retornando os resultados para uso no fluxo (por exemplo, para exibir ao atendente ou tomar decisões). **✅ Como fazer na tela** 1. Selecione a ação **Listar oportunidades**. 2. Selecione o **Funil** desejado. 3. (Opcional) Selecione a **Etapa** para filtrar apenas as oportunidades de uma etapa específica. 4. Na seção **Filtros**, defina critérios de busca: * **Nome ou código** — Digite um nome parcial ou o código da oportunidade para filtrar os resultados. * **Responsável** — Filtre por responsável. Ative a opção **Usar uma variável ou e-mail do responsável** para usar um valor dinâmico (ex.: `{{input.email}}`), ou desative para selecionar um membro da lista. 5. Na seção **Paginação**, configure: * **Limite** — Quantidade máxima de resultados retornados (padrão: 10). * **Página** — Número da página a recuperar (opcional). 6. Clique em **Salvar**. **📌 Resultado esperado** O módulo retorna a lista de oportunidades que correspondem aos filtros. Os dados ficam disponíveis como variáveis para os próximos nós do fluxo. **📷 Inserir print:** configuração da ação "Listar oportunidades" com filtros aplicados *** #### 3️⃣ Mover oportunidade **🎯 Propósito** Mudar uma oportunidade de etapa dentro do funil — por exemplo, avançar automaticamente um lead no funil quando ele responde a uma mensagem. **✅ Como fazer na tela** 1. Selecione a ação **Mover oportunidade**. 2. Selecione o **Funil** desejado. 3. No campo **ID ou CÓDIGO**, informe o identificador da oportunidade que deve ser movida. Você pode usar uma variável do fluxo (ex.: `{{opportunity.id}}`). 4. Selecione a **Etapa de destino** — onde a oportunidade deve ir após ser movida. 5. Clique em **Salvar**. **📌 Resultado esperado** A oportunidade é movida para a nova etapa no CRM. O fluxo continua para o próximo nó. **📷 Inserir print:** configuração da ação "Mover oportunidade" com ID e etapa de destino preenchidos *** #### 4️⃣ Atualizar oportunidade **🎯 Propósito** Editar os dados de uma oportunidade já existente no CRM — por exemplo, atualizar o título ou o responsável com base em uma resposta do usuário. **✅ Como fazer na tela** 1. Selecione a ação **Atualizar oportunidade**. 2. Selecione o **Funil** desejado. 3. No campo **ID ou CÓDIGO**, informe o identificador da oportunidade a ser atualizada. 4. (Opcional) Selecione a **Etapa** para indicar em qual etapa a oportunidade está. 5. Em **Adicionar campos**, escolha quais campos devem ser atualizados. 6. Preencha os novos valores de cada campo selecionado (mesmas opções disponíveis na ação Criar). 7. Em **Tags**, selecione as etiquetas que devem ser aplicadas. 8. Clique em **Salvar**. **📌 Resultado esperado** Os campos selecionados da oportunidade são atualizados no CRM com os novos valores. O fluxo segue para o próximo nó. **📷 Inserir print:** configuração da ação "Atualizar oportunidade" *** #### 5️⃣ Remover oportunidade **🎯 Propósito** Excluir permanentemente uma oportunidade do CRM durante a execução do fluxo. **✅ Como fazer na tela** 1. Selecione a ação **Remover oportunidade**. 2. Selecione o **Funil** desejado. 3. No campo **ID ou CÓDIGO**, informe o identificador da oportunidade que deve ser removida. 4. Clique em **Salvar**. {% hint style="warning" %} A remoção de uma oportunidade é **permanente** e não pode ser desfeita. Certifique-se de que o ID informado é o correto antes de ativar esse módulo no fluxo. {% endhint %} **📌 Resultado esperado** A oportunidade é removida do CRM. O fluxo segue para o próximo nó conectado. **📷 Inserir print:** configuração da ação "Remover oportunidade" *** ### 🔀 Saídas do módulo no fluxo Após a execução, o módulo Oportunidades pode direcionar o fluxo por dois caminhos: | Saída | Quando acontece | | -------------- | ---------------------------------------------------------------------------------------------------- | | **Próximo** | A operação foi realizada com sucesso | | **Erro (ERR)** | Ocorreu um problema ao executar a operação (ex.: ID não encontrado, conexão com o Desk indisponível) | Conecte cada saída ao próximo nó conforme a lógica do seu fluxo — por exemplo, exibir uma mensagem de confirmação após o sucesso, ou uma mensagem de erro caso algo falhe. **📷 Inserir print:** nó Oportunidades no canvas mostrando as duas saídas (Próximo e ERR) conectadas *** ### 💡 Dicas úteis * **Variáveis no fluxo:** A maioria dos campos de texto aceita variáveis dinâmicas usando a sintaxe `{{nome.da.variavel}}`. Use isso para preencher automaticamente dados coletados durante a conversa. * **Campos personalizados:** Os campos extras disponíveis na seção de campos dependem da configuração do funil no Desk. Se um campo esperado não aparecer, verifique se ele está cadastrado no funil correto. * **Paginação na listagem:** Se o seu CRM tiver muitas oportunidades, use os campos **Limite** e **Página** para controlar quantos resultados o bot processa por vez. * **Responsável por e-mail:** Ao usar a opção de variável para o campo Responsável, certifique-se de que a variável contém um e-mail válido cadastrado no Desk — caso contrário, a operação retornará erro. *** ### 📋 Caso de uso **Cenário:** Uma empresa de vendas usa um chatbot no WhatsApp para qualificar leads. Quando um potencial cliente responde ao formulário de interesse, o bot cria automaticamente uma oportunidade no CRM e a associa ao vendedor responsável pela região do cliente. **Configuração principal:** 1. Adicione o módulo **Oportunidades** ao fluxo, após a etapa de coleta de dados do lead. 2. Selecione a ação **Criar oportunidade**. 3. Escolha o funil **Vendas** e a etapa **Novos leads**. 4. Em **Adicionar campos**, selecione **Título**, **Responsável** e campos personalizados como **Região** e **Interesse**. 5. Preencha **Título** com a variável `{{lead.nome}}` e **Responsável** com `{{lead.email_vendedor}}`. 6. Ative **Adicionar contato à oportunidade** para vincular o contato do WhatsApp. 7. Conecte a saída **Próximo** a um nó de mensagem que confirma o recebimento ao lead. 8. Conecte a saída **ERR** a um nó que notifica a equipe sobre a falha. **Resultado esperado no fluxo:** Ao final da conversa, o lead é automaticamente registrado no CRM como uma nova oportunidade, vinculado ao contato e ao vendedor correto, sem nenhuma ação manual da equipe. *** ### ✅ Resumo * O módulo **Oportunidades** conecta o chatbot ao CRM do Desk para realizar ações em tempo real durante o atendimento. * São 5 ações disponíveis: **Criar**, **Listar**, **Mover**, **Atualizar** e **Remover** oportunidades. * A configuração começa sempre pela seleção do **Funil**, que define quais etapas e campos personalizados estarão disponíveis. * Campos de texto aceitam **variáveis dinâmicas** do fluxo, permitindo automações personalizadas. * O módulo possui duas saídas: **Próximo** (sucesso) e **ERR** (erro), que devem ser conectadas a nós diferentes conforme a lógica do fluxo. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/controle-de-fluxo/agente.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.