> 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/canais-de-atendimento/copiloto.md).

# Copiloto

O **Copilot** é um assistente de inteligência artificial embarcável. Diferente de um canal tradicional (como WhatsApp ou Instagram), ele não depende de uma conta em outra plataforma: você conecta o Copilot a um **Agente de IA** já configurado no seu fluxo e recebe um **código de instalação** para colocar em qualquer site, ou usar em telas internas, como uma janela de chat com inteligência artificial.

{% hint style="info" %}
O Copilot conversa com quem estiver na tela onde ele foi instalado usando o **Agente de IA** selecionado na configuração. Cada resposta, cada ação e cada comando rápido disponível são definidos aqui, na Hyperflow Integrações.
{% endhint %}

**📷 Inserir print:** card do canal Copilot na tela de Canais, com os botões Visualizar e Conectar

***

### 🧭 Como acessar

1. No menu lateral, clique em **Canais**.
2. Localize o card do **Copilot**.
3. Para criar uma conexão nova, clique em **Conectar**. Para editar uma já existente, clique em **Visualizar** e depois no ícone de edição da conexão desejada.

**📷 Inserir print:** caminho Canais > card Copilot > botão Conectar

{% hint style="warning" %}
**Antes de usar este recurso:**

1. O que precisa existir antes: um nó **Agente de IA** já configurado dentro de um fluxo da sua conta.
2. Onde configurar: monte o agente no editor de fluxos (nó **Agente**) antes de criar o canal Copilot — sem um agente, o campo obrigatório **Agente Principal** fica vazio e a conexão não pode ser salva.
3. Como voltar para concluir: depois de ter o agente pronto, volte para **Canais > Copilot > Conectar** e selecione esse agente na aba **Apresentação**.
   {% endhint %}

***

### 🖥️ Conhecendo a tela

Ao clicar em **Conectar** (ou editar uma conexão existente), abre-se uma janela com **5 abas**: Apresentação, Ferramentas de Frontend, Icebreakers, Segurança e Instalar.

**📷 Inserir print:** janela de configuração do Copilot com as 5 abas visíveis no topo

***

#### 1️⃣ Apresentação

Define a identidade visual do Copilot e qual agente responde pelas conversas.

**🎨 Identidade e aparência**

| Campo               | O que preencher                                                                        |
| ------------------- | -------------------------------------------------------------------------------------- |
| **Nome**            | Nome do assistente, exibido no cabeçalho da janela de chat (obrigatório)               |
| **Avatar**          | Imagem exibida junto ao nome do assistente                                             |
| **Cor primária**    | Cor usada nos elementos principais da janela e no botão flutuante                      |
| **Tema**            | **Claro** ou **Escuro**                                                                |
| **Posição na tela** | **Inferior direito** ou **Inferior esquerdo** — onde o botão flutuante aparece no site |

**📷 Inserir print:** aba Apresentação com os campos Nome, Avatar, Cor primária, Tema e Posição preenchidos

**👋 Mensagem de boas-vindas**

Exibida na primeira vez que a pessoa abre o Copilot. Se ficar em branco, essa etapa é pulada.

| Campo                     | O que preencher                       |
| ------------------------- | ------------------------------------- |
| **Título da saudação**    | Ex.: *"Olá! 👋"*                      |
| **Subtítulo da saudação** | Ex.: *"Em que posso te ajudar hoje?"* |

**🌐 Idioma padrão**

Define o idioma inicial da interface do widget (botões, textos fixos). Hoje o Copilot está disponível em **Português (Brasil)** e **Inglês (Estados Unidos)**.

**🔀 Agente principal e aliases**

| Campo                 | O que preencher                                                                                                                                                                                       |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agente Principal**  | O nó de **Agente de IA**, dentro de um fluxo, que vai responder às conversas deste Copilot (obrigatório)                                                                                              |
| **Aliases de agente** | Opcional. Permite apontar, sob um nome alternativo, outro agente que deve ser usado quando a instalação do Copilot informar esse alias — útil para reaproveitar o mesmo canal em contextos diferentes |

**📷 Inserir print:** campo de seleção do Agente Principal e lista de aliases cadastrados

**🛠️ Opções do widget**

| Campo                                        | O que faz                                                                                  |
| -------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Mostrar histórico de conversas**           | Permite à pessoa navegar e retomar conversas anteriores pelo cabeçalho do widget           |
| **Mostrar uso de ferramentas**               | Exibe mensagens do tipo *"Usando a ferramenta X..."* enquanto a IA executa uma ação        |
| **Mostrar botão de fechar quando embarcado** | Exibe o **X** de fechar mesmo quando o Copilot está fixo dentro da página (modo embarcado) |

**📊 Limite de uso**

| Campo                            | O que preencher                                                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Limite de tokens por usuário** | Quantidade máxima de tokens (processamento de IA) que uma mesma pessoa pode consumir na janela de tempo abaixo. **0** = sem limite |
| **Janela (horas)**               | Depois de quantas horas, a partir da primeira mensagem da pessoa, o limite acima é zerado e recomeça a contagem                    |

**🚦 Comportamento**

| Campo                    | O que faz                                                        |
| ------------------------ | ---------------------------------------------------------------- |
| **Permitir Ativo**       | Libera o uso deste Copilot para iniciar conversas de forma ativa |
| **Permitir Transmissão** | Libera o uso deste Copilot em transmissões                       |

**📷 Inserir print:** seções Opções do widget, Limite de uso e Comportamento na aba Apresentação

***

#### 2️⃣ Ferramentas de Frontend

{% hint style="info" %}
São ferramentas que rodam **no navegador de quem está conversando**, dando ao Copilot acesso ao contexto da página e a algumas ações do navegador — diferente das ferramentas de um Agente de IA comum, que rodam no servidor.
{% endhint %}

| Categoria            | Ferramenta                                  | O que faz                                                                                  |
| -------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Contexto da página   | **Tirar Screenshot**                        | Captura uma imagem da tela atual                                                           |
| Contexto da página   | **Obter URL atual**                         | Retorna o endereço da página em que a pessoa está                                          |
| Contexto da página   | **Obter título da página**                  | Retorna o título da página atual                                                           |
| Contexto da página   | **Obter conteúdo da página**                | Extrai o texto visível da página                                                           |
| Interação do usuário | **Obter texto selecionado**                 | Retorna o trecho de texto que a pessoa selecionou na página                                |
| Interação do usuário | **Rolar até um elemento**                   | Move a tela até um elemento específico da página                                           |
| Interação do usuário | **Obter dados de formulário**               | Extrai os dados preenchidos em formulários visíveis na página                              |
| Interação do usuário | **Perguntar ao usuário (múltipla escolha)** | Exibe perguntas de múltipla escolha (com opção de texto livre) direto na janela do Copilot |
| Utilitários          | **Copiar para a área de transferência**     | Copia um texto para a área de transferência da pessoa                                      |

**📷 Inserir print:** aba Ferramentas de Frontend com as ferramentas marcadas e agrupadas por categoria

{% hint style="warning" %}
Marque apenas as ferramentas que fazem sentido para o contexto onde o Copilot será instalado. Ferramentas de contexto de página (como ler o conteúdo da tela) só têm efeito quando o Copilot está embarcado em uma página web — não em uma tela de atendimento interna, por exemplo.
{% endhint %}

***

#### 3️⃣ Icebreakers (comandos rápidos)

Os **icebreakers** são botões de atalho que aparecem antes mesmo da pessoa digitar qualquer coisa. Ao clicar em um deles, uma mensagem pré-definida (o **prompt**) é enviada direto para o Agente de IA, sem a pessoa precisar escrevê-la.

{% hint style="info" %}
O **prompt** de cada icebreaker fica **oculto** — a pessoa vê apenas o **Título** (e o **Subtítulo**, se preenchido) do botão. É o prompt, e não o título, que realmente chega até o Agente de IA.
{% endhint %}

**📷 Inserir print:** botões de icebreakers exibidos acima do campo de digitação do Copilot

**✅ Como cadastrar um icebreaker**

1. Na aba **Icebreakers**, clique em **+ Add icebreaker**.
2. Preencha:

| Campo                        | O que preencher                                                    |
| ---------------------------- | ------------------------------------------------------------------ |
| **Título**                   | O texto do botão que a pessoa vai ver e clicar                     |
| **Subtítulo**                | Opcional. Um complemento curto exibido junto ao título             |
| **Prompt enviado ao agente** | A mensagem real que o Agente de IA recebe quando o botão é clicado |

3. Repita para quantos comandos quiser cadastrar, **até o limite de 4 icebreakers** por canal.
4. Clique em **Salvar**.

**📷 Inserir print:** formulário de um icebreaker preenchido, com os campos Título, Subtítulo e Prompt

**💡 Exemplos de icebreakers**

| Título                  | Subtítulo                       | Prompt enviado ao agente                                                                                                                                 |
| ----------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Corrigir ortografia** | Revise o texto antes de enviar  | *"Corrija a ortografia e a gramática da última mensagem que eu escrevi, mantendo o mesmo sentido e o mesmo tom. Responda apenas com o texto corrigido."* |
| **Tira-dúvidas**        | Pergunte sobre a conversa atual | *"Com base no histórico desta conversa, responda de forma objetiva a dúvida que eu descrever a seguir."*                                                 |
| **Auxílio suporte**     | Peça uma sugestão de resposta   | *"Sugira uma resposta profissional e empática para a última mensagem do cliente, considerando o contexto da conversa."*                                  |
| **Resumir conversa**    | Veja um resumo rápido           | *"Resuma em poucas linhas o que já foi tratado nesta conversa até agora."*                                                                               |

{% hint style="warning" %}
São só exemplos de ponto de partida. Escreva o **prompt** pensando em quem vai usar o botão: quanto mais claro o comando, mais previsível é a resposta do Agente de IA.
{% endhint %}

***

#### 4️⃣ Segurança

| Campo                                 | O que é                                                                                                                      |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Hosts permitidos**                  | Lista dos domínios autorizados a exibir esse Copilot (ex.: `minhaempresa.com.br`). Obrigatório ter pelo menos um             |
| **Token público**                     | Identificador usado no código de instalação. Pode ser exposto no HTML do site sem risco                                      |
| **Chave JWT (JWT secret)**            | Opcional. Usada pelo seu próprio backend para assinar um token e identificar quem já está logado no seu site para o Copilot  |
| **Hash do ID do usuário autenticado** | Se ativo, o identificador da pessoa logada (vindo do JWT) é transformado em um código (hash) antes de ser usado internamente |

**📷 Inserir print:** aba Segurança com os campos Hosts permitidos, Token público e Chave JWT

{% hint style="warning" %}
Se nenhum **host** for cadastrado, o widget fica bloqueado e não carrega em nenhum site, mesmo com o token correto.
{% endhint %}

***

#### 5️⃣ Instalar

Mostra o código pronto para colar no seu site.

**✅ Como fazer na tela**

1. Na aba **Instalar**, clique em **Copiar código**.
2. Cole o código antes do fechamento da tag `</body>` de cada página onde o Copilot deve aparecer.
3. Publique a página no seu site.
4. Volte à aba Instalar e confira, na lista de **hosts permitidos**, se o domínio publicado está na lista.

**📌 Resultado esperado**

Ao abrir o site, o botão flutuante do Copilot aparece no canto da tela configurado na aba Apresentação.

**📷 Inserir print:** aba Instalar com o código de instalação e a lista de hosts permitidos

***

### 📌 Regras e comportamentos importantes

* O campo **Agente Principal** é obrigatório: sem um agente selecionado, a conexão não pode ser salva.
* No máximo **4 icebreakers** podem ser cadastrados por canal.
* O texto do **prompt** de um icebreaker nunca aparece para quem está conversando — só o **Título** e o **Subtítulo** são visíveis.
* Sem pelo menos um **host permitido** cadastrado na aba Segurança, o widget não carrega em nenhum site.
* O **limite de tokens** igual a 0 significa uso ilimitado por pessoa.
* As **ferramentas de frontend** só têm efeito prático quando o Copilot está instalado dentro de uma página web (elas dependem do navegador de quem está usando).
* É possível cadastrar mais de uma conexão de Copilot na mesma conta, cada uma com seu próprio agente, aparência e icebreakers.

***

### 💡 Casos de uso

**Cenário 1 — assistente para visitantes do site**

Uma empresa quer um assistente de IA no próprio site institucional para tirar dúvidas de quem está navegando.

1. Cria um agente de IA no fluxo com instruções sobre produtos e políticas da empresa.
2. Conecta um canal Copilot, seleciona esse agente como **Agente Principal** e define o **Nome**, **Avatar** e **Cor primária** de acordo com a marca.
3. Cadastra os icebreakers **"Ver planos"**, **"Falar com um humano"** e **"Rastrear pedido"**.
4. Copia o código na aba **Instalar** e cola no site.

**Resultado:** os visitantes clicam no botão flutuante e já encontram atalhos prontos, sem precisar digitar a primeira mensagem.

**Cenário 2 — apoio ao atendente dentro do próprio atendimento**

Uma empresa quer que os atendentes tenham um atalho de IA para revisar mensagens antes de enviar, direto na tela de atendimento.

1. Cria um agente de IA com instruções de revisão de texto e suporte a dúvidas internas.
2. Conecta um canal Copilot apontando para esse agente.
3. Cadastra os icebreakers **"Corrigir ortografia"** e **"Tira-dúvidas"**, com os prompts correspondentes.
4. O código de instalação desse canal é o mesmo usado dentro da tela de atendimento, exibindo os botões de comando rápido junto ao campo de digitação do atendente.

**Resultado:** o atendente clica em **"Corrigir ortografia"** e recebe o texto revisado, sem precisar sair da conversa ou reescrever a mensagem do zero.

***

### 📝 Resumo

* O **Copilot** é um canal de assistente de IA embarcável, ligado a um **Agente de IA** já configurado em um fluxo.
* A configuração tem **5 abas**: **Apresentação** (identidade, aparência, agente e limites), **Ferramentas de Frontend** (ações no navegador de quem conversa), **Icebreakers** (comandos rápidos), **Segurança** (hosts e tokens) e **Instalar** (código de instalação).
* **Icebreakers** são botões de atalho — a pessoa vê um **Título**/**Subtítulo**, mas quem realmente chega ao agente é o **Prompt**, oculto. Podem ser cadastrados até **4** por canal.
* Exemplos de icebreakers: **Corrigir ortografia**, **Tira-dúvidas**, **Auxílio suporte**, **Resumir conversa**.
* É obrigatório definir um **Agente Principal** e pelo menos um **host permitido** para o canal funcionar.
* O mesmo tipo de canal serve tanto para um assistente público em um site quanto para um atalho de apoio ao atendente dentro da própria tela de atendimento.