> 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/extensoes-hyperflow/extensao-no-hyper-conversas.md). # Extensão no Hyper Conversas Construa mini-apps para acelerar atendimento dos seus agentes ### Antes de começar Nesta página, você vai aprender a **criar e utilizar uma extensão no HyperConversas**, permitindo que seus atendentes executem ações em sistemas terceiros sem sair da tela de atendimento. {% hint style="info" %} **Ainda não conhece as Extensões Hyperflow?** Antes de seguir este tutorial, recomendamos a leitura da página [Extensões Hyperflow](/docs/extensoes-hyperflow.md) para entender o que são e como funcionam. {% endhint %} ### 1. Pré-requisito: instalando o Node.js Para construir extensões, é necessário ter o **Node.js** instalado em sua máquina. O Node.js é o ambiente que permite executar as ferramentas de desenvolvimento da Hyperflow. Para verificar se você já possui o Node.js instalado, abra o seu terminal e execute: ```bash node -v ``` Se o comando retornar um número de versão (por exemplo, `v22.14.0`), o Node.js já está instalado e você pode seguir para o próximo passo. Caso contrário, siga a instalação de acordo com o seu sistema operacional: * **Windows e macOS:** acesse o [site oficial do Node.js](https://nodejs.org/pt), baixe a versão **LTS** e siga o instalador. * **Linux:** utilize o gerenciador de pacotes da sua distribuição ou siga as [instruções oficiais](https://nodejs.org/pt/download). {% hint style="warning" %} **Importante:** recomendamos utilizar sempre a versão **LTS** do Node.js, que oferece maior estabilidade e suporte. {% endhint %} ### 2. Instalando o Hyperflow DevKit Com o Node.js instalado, o próximo passo é instalar o **Hyperflow DevKit**, a ferramenta de linha de comando da Hyperflow que permite a construção de extensões. No seu terminal, execute o comando: ```bash npm install -g @hyperflow-global/devkit ``` Esse comando instala o DevKit de forma **global** em sua máquina, ou seja, ele ficará disponível em qualquer diretório do seu terminal. {% hint style="success" %} **Concluído!** Com o Hyperflow DevKit instalado, você já está pronto para criar a sua primeira extensão. {% endhint %} ### 3. Criando o projeto da extensão Agora vamos criar o projeto da sua extensão. No terminal, **navegue até a pasta onde deseja desenvolver as suas extensões** e execute o comando: ```bash hyperflow init ``` Esse comando inicia a criação de um novo projeto de extensão. O DevKit fará algumas perguntas para configurar o projeto: ``` ? Nome da extensão: consultaCEP ? Tipo do projeto: Node - Nó de fluxo no editor do Hyperflow Integrações ❯ App - Aplicação na tela de atendimento do Hyperflow Conversas ? Descrição da extensão: Extensão que irá consultar o CEP ? Criar projeto com essas configurações? Yes ``` * **Nome da extensão:** o nome que identifica a sua extensão. Neste tutorial, usaremos como exemplo `consultaCEP`. * **Tipo do projeto:** selecione **App**. * **Descrição da extensão:** um breve texto explicando o que a extensão faz. * **Criar projeto com essas configurações?:** confirme com **Yes**. {% hint style="warning" %} **Importante:** para criar uma extensão no HyperConversas, é essencial selecionar o tipo **App**. É essa opção que define que a extensão será uma aplicação na tela de atendimento (Desk), e não um nó de fluxo no Hyperflow Integrações. {% endhint %} Após confirmar as configurações, o projeto será criado e as dependências serão instaladas automaticamente: ``` ✔ Projeto criado em consultaCEP/ ✔ Dependências instaladas (React/MUI para o editor) ✔ Extensão "consultaCEP" inicializada! ℹ Próximos passos: cd consultaCEP && hyperflow dev ``` {% hint style="success" %} **Concluído!** Seu projeto de extensão foi criado. No próximo passo, vamos iniciar o servidor de desenvolvimento. {% endhint %} ### 4. Iniciando o servidor de desenvolvimento Navegue até a pasta do projeto criado e inicie o servidor de desenvolvimento: ```bash cd consultaCEP # Aqui será o nome do projeto que você criou hyperflow dev ``` Ao rodar o servidor, um ambiente de desenvolvimento será criado no endereço local [**http://localhost:3000**](http://localhost:3000). Nessa página, você consegue **visualizar como o seu mini app irá aparecer no Desk**, em uma simulação da tela de atendimento do HyperConversas. Para executar e abrir o seu app, basta **clicar no ícone da extensão no canto direito** da conversa, conforme indicado na imagem abaixo.

Imagem 01 - Ambiente de desenvolvimento local com a simulação da tela de atendimento. O ícone destacado abre o seu mini app.

{% hint style="info" %} Por padrão, o projeto é criado com um app de exemplo, que exibe apenas um campo simulando uma consulta de CPF. Nos próximos passos, vamos customizá-lo. {% endhint %} O ambiente de desenvolvimento também conta com um painel lateral com as abas **Console**, **Config**, **Integrações** e **Chat**, que permitem acompanhar as execuções do seu app durante o desenvolvimento. ### 5. Desenvolvendo o seu mini app Com o servidor de desenvolvimento rodando, o próximo passo é customizar o app para a sua necessidade. Para isso, **abra o projeto no seu editor de código com IA preferido**, como o Cursor, o Claude Code ou outro de sua preferência, e descreva o que você precisa que o app faça. Neste tutorial, vamos simular a criação de um app de **consulta de CEP**, com o seguinte funcionamento: 1. O atendente insere um **CEP** no campo do app. 2. O app consulta o **endereço** correspondente. 3. O endereço é exibido em um **card** na tela. 4. Um botão **"Copiar endereço"** permite que o atendente copie a informação para enviá-la ao cliente na conversa. Com o projeto aberto no editor, basta **descrever para a IA o que você quer que o mini app execute**. Você pode solicitar múltiplas telas, integrações e qualquer regra de negócio da sua operação. {% hint style="info" %} Ao criar o projeto pela CLI da Hyperflow, ele já é gerado com **todas as orientações necessárias para que os agentes de IA de código trabalhem no formato esperado** pelas Extensões Hyperflow. Ou seja, a IA já sabe como construir a interface e as integrações da forma correta, sem configurações adicionais. {% endhint %} Veja um exemplo de como solicitar o app para a IA:

Imagem 02 - Exemplo de prompt para a IA no editor de código, descrevendo o funcionamento esperado do mini app

**Exemplo de prompt utilizado:** > Quero que seja desenvolvido um modal, onde ele irá popular com a variável do usuário "cep" se ela existir, ou então o atendente poderá digitar manualmente. > > Após informar este cep, o usuário poderá clicar no botão de buscar ou apertar enter para executar uma busca. > > Essa busca deverá bater na API do viacep, buscando o cep informado, e exibir um card bonito contendo todas as informações do endereço encontrado. > > O usuário poderá buscar um novo endereço se desejar, ou então apertar em um botão de copiar, para copiar para a sua área de transferência o endereço completo, de forma que ele poderá enviar este endereço para o cliente na conversa. {% hint style="info" %} **Dica:** Quanto mais detalhado for o seu prompt, descrevendo campos, comportamentos e integrações, melhor será o resultado gerado pela IA. Com o servidor de desenvolvimento rodando (`hyperflow dev`), você pode acompanhar as alterações em tempo real no navegador. A qualidade do código gerado e o tempo para conclusão da tarefa dependem do modelo que você está utilizando para codificação. Recomendamos utilizar os modelos mais recentes para uma melhor performance. {% endhint %} ### 6. Testando e ajustando o seu mini app Após a conclusão do desenvolvimento pelo agente de IA, volte ao ambiente de teste em [**http://localhost:3000**](http://localhost:3000) e abra o seu app para **visualizar como a interface irá se comportar** na tela de atendimento.

Imagem 03 - Mini app de consulta de CEP em funcionamento no ambiente de teste.

Com base no resultado, você pode **continuar pedindo ajustes ao seu agente de código** conforme a sua necessidade, refinando textos, campos, comportamentos e integrações, até chegar no resultado desejado. A cada alteração, basta atualizar a visualização no ambiente de teste para conferir o comportamento. {% hint style="success" %} **Concluído!** Com o seu mini-app funcionando como esperado, chegou a hora de publicá-lo para que ele apareça no Hyper Conversas. {% endhint %} ### 7. Publicando o mini app (deploy) Uma vez finalizado o desenvolvimento, vamos para o processo de **deploy** do mini app, que fará com que a sua extensão fique disponível na tela de atendimento do Hyper Conversas. #### 7.1. Gerando o token de API Para publicar a extensão, você precisará de um **token de API**, que autoriza a publicação no seu workspace. Ele é obtido no **HyperConversas**: * Acesse o menu ***Configurações***. * Clique no botão ***Extensões***, no canto superior direito. * Selecione a aba ***Chaves de API***. * Clique em ***Criar chave da API*** e siga as instruções do modal.

Imagem 04 - Tela de Chaves de API no HyperConversas, acessada em Configurações > Extensões > Chaves de API

{% hint style="warning" %} **Importante:** ao ser exibida, **copie a sua chave de API e guarde-a em um local seguro**. Por segurança, não será possível consultá-la novamente depois. Caso a perca, será necessário criar uma nova chave. {% endhint %} #### 7.2. Publicando a extensão De volta ao ambiente de desenvolvimento ([**http://localhost:3000**](http://localhost:3000)), clique no botão ***Deploy***, no canto superior direito da tela. Será exibido o modal **"Publicar extensão"**, com o nome e a versão do seu app. Cole o seu **token de autenticação** no campo indicado e clique em ***Publicar***.

Imagem 05 - Modal de publicação da extensão, com o campo para inserir o token de autenticação

{% hint style="info" %} **Dica:** ative a opção ***Salvar token nesta máquina*** para não precisar informá-lo novamente nas próximas publicações. {% endhint %} Com isso, o modal exibirá o andamento de cada etapa da publicação: criação da nova versão, compilação dos componentes, empacotamento, upload e deploy. **Esse processo pode levar alguns minutos**, e o modal será atualizado automaticamente quando todos os passos forem concluídos.

Imagem 06 - Modal com todas as etapas da publicação concluídas.

{% hint style="success" %} **Pronto!** A sua extensão foi publicada e já está disponível para configuração no Hyper Conversas. Agora, falta apenas um último passo: **configurar quem pode ver e utilizar esta extensão** durante o atendimento. {% endhint %} {% hint style="warning" %} **Boa prática: versione o código da sua extensão.** Recomendamos manter o código-fonte do projeto em um sistema de versionamento, como o Git (GitHub, GitLab, Bitbucket ou outro de sua preferência). Sem o versionamento, o código pode se perder caso o desenvolvedor responsável saia da empresa ou a máquina utilizada fique indisponível. **Importante:** a Hyperflow **não tem acesso ao código-fonte da sua extensão**. Ao publicar, é enviada apenas uma **versão minificada e otimizada** para rodar no Hyper Conversas, que não permite recuperar o código original. {% endhint %} ### 8. Instalando a extensão e configurando quem pode usá-la O deploy **publica** a extensão no seu workspace, mas para que ela apareça para os atendentes é necessário **instalá-la** no HyperConversas. É nessa etapa que você define quem poderá ver e utilizar a extensão. * No HyperConversas, acesse ***Configurações*** e clique no botão ***Extensões***. * Na aba ***Extensões***, localize a seção **"Prontas para instalar"**. A sua extensão recém-publicada aparecerá ali (caso não apareça, atualize a página). * Clique em ***INSTALAR*** no card da extensão.

Imagem 07 - Tela de Extensões no HyperConversas, com a extensão publicada pronta para instalar

Ao clicar em instalar, será aberto o modal **"Instalar extensão"**, onde você poderá configurar: * **Versão:** a versão da extensão que será instalada. * **Título:** o nome exibido aos atendentes no menu do chat. Por padrão, é utilizado o nome da extensão. * **Departamentos:** define **quais departamentos poderão ver e usar a extensão**. Por exemplo: selecione apenas o departamento "SAC" para que somente os atendentes desse departamento tenham acesso. Deixe o campo vazio para disponibilizar a extensão para **todos os departamentos**. * **Mostrar na barra de ferramentas do chat:** define se a extensão ficará visível no canto superior direito da tela de atendimento. Quando desativado, a extensão não aparece no menu do cabeçalho do chat, mas os atendentes ainda podem abri-la por um campo de variável de protocolo do tipo Extensão. * **Variáveis de protocolo:** vínculo entre as variáveis utilizadas pela extensão e os campos do atendimento. No nosso exemplo, a variável `endereco` armazena o endereço completo consultado no ViaCEP.

Imagem 08 - Modal de instalação da extensão, com as configurações de título, departamentos e visibilidade

Confirme as informações clicando em ***Instalar***. ### 9. Utilizando a extensão no atendimento A partir de agora, ao atender uma conversa em um **departamento permitido** na instalação da extensão, o atendente verá o **ícone da extensão na barra de ferramentas do chat**, no canto superior direito da tela de atendimento. Basta clicar no ícone para abrir o mini app e utilizá-lo normalmente, sem sair da conversa. No nosso exemplo, o atendente informa o CEP, visualiza o endereço completo no card e clica em ***Copiar endereço*** para enviar a informação ao cliente.

Imagem 09 - Extensão consultaCEP em uso durante um atendimento real, aberta pelo ícone na barra de ferramentas do chat

{% hint style="success" %} **Parabéns!** Você chegou ao fim deste tutorial! 🎉 Você criou, publicou e instalou a sua primeira extensão no HyperConversas. Agora, os seus atendentes podem executar ações e consultas diretamente na tela de atendimento, sem sair da Hyperflow. {% endhint %}