For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Ainda não conhece as Extensões Hyperflow? Antes de seguir este tutorial, recomendamos a leitura da página Extensões Hyperflow para entender o que são e como funcionam.

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 -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:

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.

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.

Após confirmar as configurações, o projeto será criado e as dependências serão instaladas automaticamente:

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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.

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

Dica: ative a opção Salvar token nesta máquina para não precisar informá-lo novamente nas próximas publicações.

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.

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

Last updated