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:

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.

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