> 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/integracao/aws-s3.md).

# AWS S3

## ☁️ Módulo AWS S3

O módulo **AWS S3** permite que o seu chatbot faça upload de arquivos para um bucket do Amazon S3 durante uma conversa. Com ele, você pode publicar arquivos coletados no fluxo (documentos, imagens, áudios) diretamente em um bucket S3, com opção de gerar uma URL assinada e privada para acesso controlado — tudo de forma automática, enquanto o atendimento acontece.

**📷 Inserir print:** visão geral do nó AWS S3 no canvas do Builder

***

### 🗂️ Como acessar

1. No menu lateral, clique em **Aplicativo**.
2. Em seguida, clique em **Fluxos**.
3. Abra o fluxo desejado ou crie um novo.
4. No canvas do Builder, clique no botão **+** para adicionar um novo nó.
5. Localize e selecione **AWS - S3** na lista de módulos disponíveis.

**📷 Inserir print:** lista de módulos com o item "AWS - S3" destacado

{% hint style="warning" %}
**Pré-requisito:** Para usar este módulo, é necessário ter uma integração com a AWS configurada na plataforma com permissão de publicação no S3. Caso não exista nenhuma integração disponível no campo **Nome da integração**, acesse as configurações de integrações, cadastre as credenciais da AWS e retorne para configurar o módulo.
{% endhint %}

***

### 🧩 Conhecendo o módulo

Ao adicionar o módulo ao fluxo, um painel de configuração é aberto. Nele, você define qual bucket S3 receberá o arquivo, qual arquivo será enviado e como ele ficará acessível após o upload.

**📷 Inserir print:** painel de configuração do módulo AWS S3 aberto

***

### 🔧 Configurações do módulo

#### Campos obrigatórios

| Campo                  | O que preencher                                                                                                                                                              |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome da integração** | Selecione a integração AWS cadastrada que o bot deve usar para se conectar ao S3. A integração precisa ter permissão de publicação (`s3:PutObject`). Campo obrigatório.      |
| **S3 Bucket**          | Informe o nome do bucket de destino (ex.: `minha-empresa-arquivos`). Aceita variáveis do fluxo (ex.: `{{config.bucket}}`).                                                   |
| **S3 Region**          | Informe a região AWS onde o bucket está hospedado (ex.: `us-east-1`, `sa-east-1`). Aceita variáveis do fluxo.                                                                |
| **File**               | Informe o conteúdo ou a referência do arquivo a ser enviado. Aceita variáveis do fluxo que apontem para o arquivo coletado durante a conversa (ex.: `{{input.arquivo}}`).    |
| **File name**          | Informe o nome (e caminho, se necessário) que o arquivo terá dentro do bucket (ex.: `uploads/2024/documento.pdf`). Aceita variáveis do fluxo (ex.: `{{input.nomeArquivo}}`). |

**📷 Inserir print:** painel com os campos obrigatórios preenchidos

***

#### Opções avançadas

Clique em **Advanced options** para exibir configurações adicionais de controle de acesso e metadados.

**ACL — Sign Private URL**

| Opção                   | Comportamento                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Desativado** (padrão) | O arquivo é enviado com as permissões padrão do bucket. O acesso segue as políticas de ACL definidas no bucket S3. |
| **Ativado**             | O arquivo é enviado como **privado** e o módulo gera automaticamente uma **URL assinada** para acesso temporário.  |

Quando a opção **ACL - Sign Private URL** está ativada, um campo adicional é exibido:

| Campo                | O que preencher                                                                                                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tempo (segundos)** | Informe por quantos segundos a URL assinada ficará válida após a geração. Padrão sugerido: `30`. Após esse prazo, o link expira e o arquivo não poderá mais ser acessado pela URL gerada. |

{% hint style="info" %}
Use a URL assinada quando o arquivo contiver dados sensíveis (ex.: documentos pessoais, comprovantes) e você não quiser que ele fique publicamente acessível no S3. A URL gerada fica disponível como variável nos próximos nós do fluxo.
{% endhint %}

**Headers**

Campo de editor JSON para enviar metadados ou cabeçalhos HTTP personalizados junto com o upload. Útil para definir `Content-Type`, tags ou outros metadados aceitos pela API do S3.

Exemplo:

```json
{
  "Content-Type": "application/pdf",
  "x-amz-meta-origem": "chatbot-whatsapp"
}
```

Aceita variáveis do fluxo dentro dos valores.

**📷 Inserir print:** painel de opções avançadas com ACL ativado e campo de tempo preenchido

***

### 🔀 Saídas do módulo no fluxo

Após a execução, o módulo AWS S3 direciona o fluxo por dois caminhos:

| Saída   | Quando acontece                                                                                                                                                 |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OK**  | O upload foi realizado com sucesso. Os resultados da operação (incluindo a URL assinada, se configurada) ficam disponíveis como variáveis para os próximos nós. |
| **ERR** | Ocorreu um erro ao executar o upload (ex.: credenciais inválidas, bucket inexistente, arquivo não encontrado, permissão negada).                                |

Conecte cada saída ao próximo nó conforme a lógica do seu fluxo — por exemplo, enviar a URL do arquivo no caminho **OK** ou exibir uma mensagem de erro no caminho **ERR**.

**📷 Inserir print:** nó AWS S3 no canvas com as saídas OK e ERR conectadas a nós diferentes

***

### 💡 Dicas úteis

* **Variáveis do fluxo:** A maioria dos campos aceita variáveis dinâmicas com a sintaxe `{{nome.da.variavel}}`. Use isso para preencher o nome do arquivo, o bucket e o conteúdo do arquivo com dados coletados durante a conversa.
* **Caminho no bucket:** O campo **File name** aceita subdiretórios usando `/` como separador (ex.: `documentos/cpf/{{input.cpf}}.pdf`). Use isso para organizar os arquivos dentro do bucket.
* **URL assinada:** Quando **ACL - Sign Private URL** está ativado, o módulo retorna uma URL temporária de acesso ao arquivo. Essa URL fica disponível como variável e pode ser enviada ao cliente via mensagem.
* **Tempo de expiração:** O campo **Tempo (segundos)** define por quantos segundos a URL assinada será válida. Calcule o tempo necessário para o cliente usar a URL antes de configurar esse valor (ex.: `3600` para 1 hora, `86400` para 24 horas).
* **Permissões da integração:** A integração AWS usada precisa ter pelo menos a permissão `s3:PutObject` no bucket de destino. Para gerar URLs assinadas, a permissão `s3:GetObject` também é necessária.
* **Headers e Content-Type:** Se o arquivo enviado for de um tipo específico (PDF, imagem, áudio), defina o `Content-Type` correto no campo **Headers** para garantir que o navegador interprete o arquivo corretamente ao acessar a URL.

***

### 📋 Caso de uso

**Cenário:** Uma empresa de seguros usa um chatbot no WhatsApp para coletar documentos de clientes durante o processo de abertura de sinistro. O bot recebe fotos e documentos enviados pelo cliente e os armazena com segurança em um bucket S3, gerando uma URL assinada para que o time interno possa acessá-los no sistema de gestão.

**Configuração principal:**

1. Adicione o módulo **AWS S3** ao fluxo, após o nó que recebe o arquivo enviado pelo cliente.
2. Selecione a **integração AWS** com as credenciais do ambiente de produção.
3. No campo **S3 Bucket**, informe `seguros-sinistros-docs`.
4. No campo **S3 Region**, informe `sa-east-1`.
5. No campo **File**, use a variável do arquivo recebido: `{{input.arquivo}}`.
6. No campo **File name**, use um caminho dinâmico: `sinistros/{{input.protocolo}}/{{input.nomeArquivo}}`.
7. Em **Opções avançadas**, ative **ACL - Sign Private URL** e defina o tempo de expiração como `3600` (1 hora).
8. No campo **Headers**, adicione:

   ```json
   { "Content-Type": "{{input.tipoArquivo}}" }
   ```
9. Conecte a saída **OK** a um nó que registra a URL gerada no CRM e envia uma confirmação ao cliente.
10. Conecte a saída **ERR** a um nó que informa ao cliente que não foi possível receber o documento e solicita o reenvio.

**Resultado esperado no fluxo:** O chatbot recebe o documento do cliente, faz o upload seguro no S3 organizando por número de protocolo, gera uma URL temporária de acesso e disponibiliza essa URL para o sistema de gestão, sem intervenção humana.

***

### ✅ Resumo

* O módulo **AWS S3** conecta o chatbot ao Amazon S3 para fazer upload de arquivos durante o atendimento.
* A operação é sempre de **publicação (upload)** — o módulo envia um arquivo para o bucket especificado.
* Os campos **Bucket**, **Region**, **File** e **File name** são obrigatórios e aceitam **variáveis dinâmicas** do fluxo.
* Em **Opções avançadas**, é possível ativar o **ACL - Sign Private URL** para tornar o arquivo privado e gerar uma URL assinada com tempo de expiração configurável em segundos.
* O campo **Headers** permite adicionar metadados e cabeçalhos HTTP customizados ao upload, no formato JSON.
* O módulo possui duas saídas: **OK** (upload com sucesso, URL disponível como variável) e **ERR** (falha no upload), que devem ser conectadas a nós diferentes conforme a lógica do fluxo.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.hyperflow.global/docs/builder-hyperflow/gerenciamento-de-aplicativos/fluxos/integracao/aws-s3.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.