> 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/acao/executar-codigo.md).

# Executar código

O módulo **Executar Código** permite adicionar funções JavaScript personalizadas diretamente no seu fluxo. Use-o para aplicar regras de negócio, formatar dados, fazer cálculos ou transformar informações antes de enviá-las para o próximo passo do atendimento.

![Video 1 - Utilização do módulo Executar código.](https://content.gitbook.com/content/RWteFkm020DS5IbXoSgj/blobs/o3V36pUnIOCsLXkq0DyX/image)

***

### 📍 Como acessar

1. No menu lateral, clique em **Gerenciamento de aplicativos**.
2. Clique em **Fluxos** e abra o fluxo que deseja editar.
3. No painel lateral esquerdo, localize a categoria **Ação**.
4. Arraste o módulo **Executar Código** para o canvas do fluxo.

***

### 🧩 Conhecendo o módulo

#### 1️⃣ Editor de código

Ao clicar no módulo no canvas, um painel de configuração será exibido. Nele você encontra um editor de código onde escreve a função JavaScript que será executada quando o fluxo chegar a esse passo.

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FvvofQOAGvMGnACKmlFcB%2Fimage.png?alt=media&amp;token=33bd240c-62db-43dc-9732-80816945ad97" alt=""><figcaption><p>Imagem 1 - Editor do texto de Executar código aberto.</p></figcaption></figure>

O editor oferece:

* Realce de sintaxe para facilitar a leitura do código
* Identação automática ao pressionar Enter
* Salvamento automático das alterações

O código deve seguir o seguinte formato:

```javascript
(input, user, flow, env) => {
  // escreva sua lógica aqui
  return resultado;
}
```

{% hint style="info" %}
O comando `return` é obrigatório. O valor retornado pela função é o que será enviado para o próximo módulo do fluxo. Sem ele, nenhum dado seguirá adiante.
{% endhint %}

***

#### 2️⃣ Variáveis disponíveis no código

Dentro do código, você tem acesso a quatro variáveis que o fluxo passa automaticamente para a função:

![Video 2 - Painel de configuração do módulo aberto com o editor de código em evidência.](https://content.gitbook.com/content/RWteFkm020DS5IbXoSgj/blobs/ihpMGzRtqY27wPZGTPwY/image)

| Variável | O que contém                                                                         |
| -------- | ------------------------------------------------------------------------------------ |
| `input`  | Dados de entrada que chegaram ao módulo neste passo do fluxo                         |
| `user`   | Informações do usuário em atendimento: nome, identificador, dados extras cadastrados |
| `flow`   | Variáveis e contexto do fluxo em andamento                                           |
| `env`    | Variáveis de ambiente configuradas na plataforma                                     |

{% hint style="warning" %}
Essas variáveis são **somente leitura** — você não pode alterá-las diretamente. Para transformar os dados, crie novas variáveis locais dentro do código e retorne o resultado com `return`.
{% endhint %}

***

#### 3️⃣ Ferramentas disponíveis no código

Você pode usar as seguintes ferramentas diretamente no código, sem precisar instalar ou importar nada:

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FvRGLyTUmMfA01q4J7TIS%2Fimage.png?alt=media&amp;token=cd7e23cc-23ae-4e0f-9c4d-ebf310094aea" alt=""><figcaption><p>Imagem 2 - Editor com exemplo de uso de ferramentas disponíveis (formatação de data com moment).</p></figcaption></figure>

| Ferramenta                   | Para que serve                                                  |
| ---------------------------- | --------------------------------------------------------------- |
| `moment` e `moment-timezone` | Trabalhar com datas e horários, incluindo fusos horários        |
| `_` (Lodash)                 | Manipular listas, objetos e textos de forma simplificada        |
| `uuid`                       | Gerar identificadores únicos para registros                     |
| `Intl`                       | Formatar números, datas e valores monetários por região         |
| `console.log()`              | Registrar mensagens para facilitar a identificação de problemas |

***

#### 4️⃣ Saídas do módulo

O módulo possui duas saídas que direcionam o fluxo dependendo do resultado da execução:

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2Fu4CPaeSxl7gbeWgUX9vZ%2F07-canvas-sucesso-erro.png?alt=media&amp;token=9f404b84-c92c-4615-92d6-ced930af51c2" alt=""><figcaption><p>Imagem 3 - Módulo no canvas com as duas conexões de saída (Sucesso e Erro) visíveis e conectadas a outros módulos.</p></figcaption></figure>

**🎯 Propósito**

Definir o caminho que o fluxo vai seguir dependendo se o código foi executado com sucesso ou se ocorreu um problema.

**✅ Como fazer na tela**

Conecte cada saída ao próximo módulo de acordo com o cenário desejado:

1. Arraste a conexão da saída **Sucesso** para o módulo que deve continuar o fluxo quando tudo correr bem.
2. Arraste a conexão da saída **Erro** para o módulo responsável por tratar falhas ou informar o usuário sobre o problema.

**📌 Resultado esperado**

| Saída       | Quando é ativada                       | O que é enviado ao próximo módulo        |
| ----------- | -------------------------------------- | ---------------------------------------- |
| **Sucesso** | O código foi executado sem erros       | O valor retornado pela função (`return`) |
| **Erro**    | Ocorreu um problema durante a execução | Um objeto com a descrição do erro        |

{% hint style="warning" %}
O módulo tem um limite de **30 segundos** de execução. Se o código demorar mais do que isso, a saída **Erro** será ativada automaticamente.
{% endhint %}

***

### 💡 Dicas úteis

* **Sempre use `return`:** sem esse comando, o fluxo não receberá nenhum dado e a execução pode falhar.
* **Trate erros com `try/catch`:** para situações previsíveis de falha, use `try/catch` dentro do código. Assim você decide o que enviar ao próximo módulo em vez de cair automaticamente na saída de **Erro**.
* **Use `console.log()` para identificar problemas:** as mensagens aparecem nos registros de execução do fluxo e ajudam a localizar erros rapidamente.
* **Não modifique as variáveis diretamente:** `input`, `user`, `flow` e `env` são somente leitura. Copie os dados que você precisa e trabalhe com as cópias.
* **Atenção ao tempo limite:** operações lentas podem ultrapassar o limite de 30 segundos. Para chamadas a serviços externos, prefira usar o módulo de **Requisição** (HTTP).

***

### 🧪 Caso de uso

**Objetivo:** personalizar a saudação de abertura do atendimento exibindo apenas o primeiro nome do usuário.

**Configuração no módulo:**

```javascript
(input, user, flow, env) => {
  const nomeCompleto = user.name || '';
  const primeiroNome = nomeCompleto.split(' ')[0];
  return { primeiroNome };
}
```

<figure><img src="https://3829578295-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRWteFkm020DS5IbXoSgj%2Fuploads%2FWnWseGhoKl8OM1XPTMwA%2Fimage.png?alt=media&amp;token=a3aca3b4-7706-4074-b675-adad7ac99585" alt=""><figcaption><p>Imagem 4 - Editor com o código do caso de uso digitado e a saída Sucesso conectada ao módulo de mensagem seguinte.</p></figcaption></figure>

**Resultado esperado no fluxo:** a saída **Sucesso** é ativada e o próximo módulo recebe o objeto `{ primeiroNome: "Rafael" }`. Esse valor pode ser usado em uma mensagem de texto como *"Olá, {{primeiroNome}}! Como posso te ajudar hoje?"*, tornando o atendimento mais personalizado e humanizado.

***

### 📋 Resumo

* O módulo **Executar Código** permite rodar funções JavaScript personalizadas dentro do fluxo de atendimento.
* As variáveis `input`, `user`, `flow` e `env` estão disponíveis automaticamente com os dados do contexto atual do fluxo — todas somente leitura.
* As ferramentas `moment`, `_` (Lodash), `uuid` e `Intl` já estão disponíveis sem necessidade de importação.
* O módulo possui duas saídas: **Sucesso** (execução sem erros) e **Erro** (falha ou tempo limite excedido).
* O limite de execução é de **30 segundos** — códigos mais lentos ativam a saída de Erro automaticamente.