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.
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:
node -vSe 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, 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.
Importante: recomendamos utilizar sempre a versão LTS do Node.js, que oferece maior estabilidade e suporte.
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:
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.
Concluído! Com o Hyperflow DevKit instalado, você já está pronto para criar a sua primeira extensão.
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:
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: 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.
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.
Após confirmar as configurações, o projeto será criado e as dependências serão instaladas automaticamente:
Concluído! Seu projeto de extensão foi criado. No próximo passo, vamos iniciar o servidor de desenvolvimento.
4. Iniciando o servidor de desenvolvimento
Navegue até a pasta do projeto criado e inicie o servidor de desenvolvimento:
Ao rodar o servidor, um ambiente de desenvolvimento será criado no endereço local 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.
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:
O atendente insere um CEP no campo do app.
O app consulta o endereço correspondente.
O endereço é exibido em um card na tela.
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.
Veja um exemplo de como solicitar o app para a IA:
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.
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 e abra o seu app para visualizar como a interface irá se comportar na tela de atendimento.
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.
Concluído! Com o seu mini-app funcionando como esperado, chegou a hora de publicá-lo para que ele apareça no Hyper Conversas.
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.
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.
7.2. Publicando a extensão
De volta ao ambiente de desenvolvimento (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.
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.
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.
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.
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.
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
enderecoarmazena o endereço completo consultado no ViaCEP.
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.
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.
Last updated