---
title: "Solicitar arquivo"
slug: "solicitar-arquivo"
updated: 2026-10-20T17:59:18Z
published: 2026-10-20T17:59:18Z
canonical: "docs.omnisiga.ai/solicitar-arquivo"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnisiga.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Solicitar arquivo

Use esta caixa quando o fluxo precisar pedir que a pessoa envie uma imagem, um documento, um áudio ou um vídeo durante a conversa.

A caixa **Solicitar arquivo** envia uma orientação ao usuário e aguarda o envio de uma mídia. Quando o arquivo é recebido e passa pela validação do tipo escolhido, o OmniSIGA guarda o **identificador da mídia** na variável configurada e permite que o fluxo continue.

A variável não contém o arquivo inteiro. Ela contém a referência que identifica a mídia recebida na sessão. Essa referência pode ser usada em etapas posteriores, como uma análise de imagem, uma caixa de código ou uma integração que precise trabalhar com o arquivo.

Use a caixa, por exemplo, para:

- solicitar um comprovante de residência;
- receber a foto de um documento de identificação;
- pedir um áudio ou um vídeo para análise;
- receber um anexo antes de encaminhar a conversa para um atendente;
- coletar mais de um documento, usando uma variável diferente para cada arquivo.

> **Não confunda:** a caixa **Solicitar arquivo** recebe uma mídia enviada pelo usuário. A caixa **Webhook de Upload** configura um destino externo para os arquivos e não substitui a etapa que pede o envio na conversa.

## Onde encontrar

1. Acesse **Configuração > Fluxos**.
2. Crie um fluxo ou abra uma versão existente no editor.
3. Na barra de ferramentas, abra o grupo **Entrada de dados**.
4. Adicione a caixa **Solicitar arquivo** ao diagrama.
5. Selecione a caixa para abrir o painel de configuração.
6. Preencha os campos e clique em **Aplicar**.
7. Salve a versão do fluxo e publique ou ative a versão conforme o processo da organização.

## Como a caixa funciona

O fluxo básico é:

```
Solicitar arquivo
      │
      ├── envia a mensagem de orientação
      │
      └── aguarda o usuário enviar a mídia escolhida
                │
                ├── arquivo válido → guarda o identificador e segue pelo caminho de sucesso
                └── arquivo não validado → segue pelo caminho de erro, quando configurado
```

A caixa executa estas etapas:

1. exibe as mensagens configuradas em **Mensagem para solicitar o arquivo**;
2. aguarda o envio do usuário;
3. verifica se a mídia corresponde ao **Tipo do arquivo** selecionado;
4. em caso de sucesso, grava o identificador na **Variável de destino**;
5. encaminha a conversa para a caixa de sucesso ou de erro configurada.

Enquanto o usuário não envia uma mídia válida, a etapa de solicitação ainda não foi concluída. Por isso, sempre informe na mensagem o que deve ser enviado e teste o comportamento no canal em que o fluxo será utilizado.

## Campos da caixa

### Nome do elemento

Identifica a caixa no diagrama. Use um nome que explique o que está sendo solicitado, por exemplo:

- `Solicitar comprovante de residência`;
- `Receber foto do documento`;
- `Pedir vídeo do produto`.

Um nome descritivo facilita a manutenção do fluxo e a escolha das caixas nos campos de navegação.

### Variável de destino

Informe o nome da variável que receberá o identificador da mídia enviada. Este campo é necessário para que o arquivo possa ser utilizado depois no fluxo.

Exemplos de nomes:

- `comprovanteResidencia`;
- `fotoDocumento`;
- `audioCliente`;
- `videoProduto`.

Use um nome de variável válido, sem espaços ou caracteres que o editor não aceite. O nome deve ser exatamente o mesmo quando a variável for usada em outra caixa ou em uma caixa de código.

> **Atenção:** se este campo ficar vazio ou tiver um nome inválido, a caixa não poderá ser aplicada. A mensagem exibida pelo editor é semelhante a **“O nome da variável não foi informado ou é inválido”**.

### Tipo do arquivo

Define a categoria de mídia que o usuário deverá enviar. As opções disponíveis são:

| Opção | Quando usar |
| --- | --- |
| **Imagem** | Para fotos, capturas ou outras imagens. |
| **Documento** | Para arquivos que representam documentos, como comprovantes ou contratos. |
| **Áudio** | Para gravações de voz ou outros arquivos de áudio. |
| **Vídeo** | Para vídeos enviados pelo usuário. |
| **Imagem ou Documento** | Quando o fluxo aceita tanto uma imagem quanto um documento. |

Escolha a opção mais específica possível. Se a pessoa puder enviar uma foto do documento ou o documento digitalizado, use **Imagem ou Documento**. Os formatos e limites efetivamente disponíveis podem variar conforme o canal; valide a configuração com um teste no canal de destino.

### Mensagem para solicitar o arquivo

É a orientação exibida antes de o OmniSIGA aguardar o envio. Explique claramente:

- qual arquivo deve ser enviado;
- para que ele será usado, quando isso for relevante;
- se é necessário enviar uma foto legível ou um documento completo;
- o que fazer caso o arquivo não esteja disponível.

O editor permite formatar a mensagem e adicionar emoji. Também é possível clicar em **Nova mensagem** para incluir mais de uma mensagem de orientação.

Exemplos:

```
Envie uma foto legível do seu documento de identificação.
```

```
Para continuar, anexe o comprovante de residência.
Aceitamos uma imagem ou um documento digitalizado.
```

### Em caso de sucesso no upload, vai para

Escolha a caixa que deverá ser executada depois que o arquivo for recebido e validado. Normalmente, ela é uma confirmação, uma análise do arquivo ou a próxima coleta.

Exemplos de destino:

- `Confirmar recebimento`;
- `Analisar documento`;
- `Solicitar segundo documento`.

A opção **Nenhum** deixa a caixa sem um destino de sucesso explícito nesse campo. Para evitar que a conversa fique sem continuidade, configure uma próxima etapa ou uma conexão clara no diagrama.

### Em caso de erro na validação, vai para

Escolha a caixa que deverá tratar o caso em que a mídia não passa pela validação da solicitação, por exemplo, quando o tipo enviado não corresponde ao tipo escolhido.

Um bom destino de erro costuma:

- explicar o que foi aceito;
- pedir o envio novamente;
- oferecer uma alternativa de atendimento, quando necessário.

Exemplo: `Solicitar comprovante novamente`.

Se ficar como **Nenhum**, não haverá um tratamento de erro indicado neste campo. Em fluxos que dependem do arquivo, é recomendável configurar uma rota de erro explícita.

## Como configurar passo a passo

### 1. Prepare as caixas de destino

Antes de configurar a solicitação, adicione ao diagrama as etapas que serão executadas depois do envio. Por exemplo:

- uma mensagem de confirmação;
- uma caixa **Análise de imagem**;
- outra caixa **Solicitar arquivo** para pedir um segundo documento;
- uma mensagem de orientação quando o arquivo não for aceito.

### 2. Configure a solicitação

1. Adicione **Solicitar arquivo** no ponto em que o fluxo deve pedir a mídia.
2. Informe um **Nome do elemento** descritivo.
3. Em **Variável de destino**, informe o nome que guardará o identificador, como `comprovante`.
4. Escolha o **Tipo do arquivo**.
5. Escreva uma **Mensagem para solicitar o arquivo**.
6. Selecione o destino de sucesso.
7. Selecione o destino de erro, se o fluxo precisar tratar uma mídia inválida.
8. Clique em **Aplicar**.
9. Salve a versão do fluxo.

### 3. Teste a conversa

1. Inicie uma nova conversa no canal correto.
2. Confirme se a mensagem de solicitação é clara.
3. Envie uma mídia do tipo esperado.
4. Verifique se o fluxo segue para o destino de sucesso.
5. Teste também um tipo de arquivo diferente para confirmar o caminho de erro.
6. Confira se a etapa seguinte consegue utilizar a mídia recebida.

Faça o teste em uma nova sessão depois de publicar ou atualizar a versão do fluxo. Uma conversa já iniciada pode estar executando uma versão anterior ou permanecer em uma etapa que já foi processada.

## Exemplos de configuração

### Solicitar um comprovante

**Objetivo:** receber o comprovante de residência e confirmar o recebimento.

| Campo | Valor de exemplo |
| --- | --- |
| **Nome do elemento** | `Solicitar comprovante de residência` |
| **Variável de destino** | `comprovanteResidencia` |
| **Tipo do arquivo** | `Documento` |
| **Mensagem para solicitar o arquivo** | `Envie seu comprovante de residência.` |
| **Em caso de sucesso no upload, vai para** | `Confirmar comprovante` |
| **Em caso de erro na validação, vai para** | `Solicitar comprovante novamente` |

```
Perguntar dados do cliente
          │
          ▼
Solicitar comprovante de residência
          ├── sucesso ──► Confirmar comprovante
          └── erro ─────► Solicitar comprovante novamente
```

O identificador da mídia fica disponível na variável `comprovanteResidencia` para as etapas seguintes.

```

Não reutilize a mesma variável quando precisar manter os dois arquivos para as etapas seguintes. Cada solicitação deve ter sua própria variável de destino.

## Como usar a mídia depois da solicitação

A caixa guarda uma referência à mídia, e não transforma automaticamente o arquivo em texto ou em campos estruturados. Para continuar o processamento, escolha uma etapa adequada ao objetivo:

- **Análise de imagem:** extrair ou verificar informações de uma foto;
- **Caixa de código:** ler a variável e chamar uma ação compatível com mídia;
- **Integração:** enviar a referência ou o arquivo ao sistema externo conforme o contrato da integração;
- **Atendimento humano:** encaminhar a conversa depois que o documento for recebido.

Se a etapa seguinte precisar de um valor extraído do documento, a solicitação do arquivo deve ser seguida por uma etapa de análise ou validação. Apenas guardar a variável não lê o conteúdo do arquivo.

## Problemas comuns

### O editor não deixa aplicar a caixa

Confira o campo **Variável de destino**. Ele é obrigatório e deve conter um nome de variável válido. Evite espaços, acentos e caracteres especiais; use nomes como `fotoDocumento` ou `comprovante`.

### O usuário envia o arquivo, mas o fluxo não continua

Verifique:

1. se a versão do fluxo foi salva;
2. se a versão correta foi publicada ou ativada no canal;
3. se o campo **Em caso de sucesso no upload, vai para** aponta para a caixa esperada;
4. se o arquivo enviado corresponde ao **Tipo do arquivo** escolhido;
5. se o teste foi feito em uma nova sessão.

### O arquivo é recusado

Confirme se a categoria enviada corresponde à configuração. Por exemplo, uma caixa configurada como **Imagem** não deve ser usada para pedir um documento que só será enviado como arquivo. Quando os dois formatos forem aceitáveis, selecione **Imagem ou Documento**.

Também confirme se o canal utilizado oferece suporte ao tipo de mídia solicitado e se o arquivo atende aos limites apresentados pelo próprio canal.

### A etapa seguinte não encontra o arquivo

Confirme se:

- a variável foi preenchida na caixa **Solicitar arquivo**;
- o nome usado depois é exatamente igual ao nome configurado em **Variável de destino**;
- outra caixa não reutilizou a mesma variável e substituiu a referência;
- a etapa seguinte está ligada ao caminho de sucesso.

### Não há tratamento para o erro

Abra a caixa e selecione uma etapa em **Em caso de erro na validação, vai para**. Use uma mensagem que explique novamente o tipo de arquivo esperado e permita uma nova tentativa.

## Boas práticas

- Use nomes de variáveis descritivos e diferentes para cada mídia que precisar guardar.
- Escolha o tipo de arquivo mais específico que o canal e o processo permitirem.
- Explique na mensagem o que deve ser enviado e como deve estar legível.
- Configure caminhos explícitos de sucesso e erro.
- Coloque a solicitação somente depois de reunir os dados necessários para aquela etapa.
- Teste uma mídia válida e uma mídia incompatível antes de publicar o fluxo.
- Quando o arquivo contiver dados pessoais ou sensíveis, informe ao usuário por que ele está sendo solicitado e siga as regras de tratamento de dados da organização.
- Não use **Solicitar arquivo** para enviar um arquivo ao usuário. Para envio, use o recurso de mensagem ou integração apropriado.

## Diferença entre recursos relacionados

| Recurso | Função |
|---|---|
| **Solicitar arquivo** | Pede que o usuário envie uma mídia e guarda a referência na sessão. |
| **Webhook de Upload** | Configura uma URL e uma chave para o destino externo dos arquivos enviados. Não faz a pergunta ao usuário. |
| **Catálogo de Mídias** | Armazena mídias da organização para reutilização em configurações e fluxos; não representa um upload feito pelo usuário na conversa. |
| **Enviar arquivo por link** | Envia uma mídia para o usuário a partir de um endereço; é o sentido oposto de **Solicitar arquivo**. |

## Checklist antes de publicar

- [ ] A caixa tem um nome que explica o documento ou a mídia solicitada.
- [ ] A variável de destino foi preenchida com um nome válido.
- [ ] O tipo do arquivo corresponde ao que o canal aceitará.
- [ ] A mensagem explica claramente o que deve ser enviado.
- [ ] O caminho de sucesso aponta para a próxima etapa.
- [ ] O caminho de erro permite corrigir ou repetir a solicitação.
- [ ] O fluxo foi salvo e a versão correta foi publicada.
- [ ] O teste foi feito com uma mídia válida e uma mídia incompatível.
---
```