Ir para o conteúdo

Envio e recebimento de arquivos

Como o usuário pode enviar um arquivo para o chatbot?

No canal Whatsapp é possível que o usuário do app envie anexos.

No canal Web é possível ativar a opção Exibir botão de anexar arquivo no grupo de configurações Caixa de Entrada. Isso vai permitir anexar um arquivo junto de uma pergunta ao chatbot, ou mesmo enviar a pergunta vazia somente com o anexo.

Nos demais canais o recurso ainda não é suportado.

Como um sistema externo poderá ter acesso aos arquivos enviados pelos usuários nas conversas?

Quando uma mensagem do usuário carrega um anexo, o arquivo fica armazenado temporariamente na plataforma durante 24 horas. A mensagem com anexo também define algumas variáveis de contexto que vão permitir, por exemplo, acionar um Sistema Externo por webhook (vide Integrações) para que o arquivo recebido seja abordado.

Para que o sistema externo acesse os arquivos enviados pelos usuários, os seguintes endpoints estão disponíveis:

  • Baixar o arquivo GET https://serprobots.estaleiro.serpro.gov.br/web/<id do chatbot>/api/files/<id da conversa>/user/<chave do arquivo>

  • Listar arquivos enviados em uma conversa de um chatbot: GET https://serprobots.estaleiro.serpro.gov.br/web/<id do chatbot>/api/files/<id da conversa>/user

Esses endpoints exigem a presença do cabeçalho Authorizaton: Bearer <token> informando o token de sessão autenticada configurado no Serprobots para aquele chatbot naquele ambiente (vide Sessão Autenticada). Dessa forma, somente o sistema externo devidamente autorizado terá o acesso.

Todas as informação necessárias para que o sistema externo consiga fazer os acessos estão disponíveis como variáveis de contexto nos motores que dão suporte à chamadas de webhook (Rivescript e Watson). São elas:

  • sb_uploaded_file_key: chave de arquivo que foi recebido e deve ser usada para baixá-lo.
  • sb_chatbot_id: identificador do chatbot (ex: bot-arquivos-d).
  • sb_conversation_id: identificador da conversa.

Outros metadados do arquivo recebido também ficam disponíveis, para ajudar na programação dos tratametnos desejados. São eles:

  • sb_uploaded_file_name: nome original do arquivo.
  • sb_uploaded_file_size: tamanho do arquivo em bytes.
  • sb_uploaded_file_type: tipo MIME do arquivo.

Warning

As variáveis de contexto com informações do anexo só existem no recebimento daquela mensagem com anexo. Na próxima mensagem recebida, já sem anexo, elas estarão vazias para o motor.

Uma sugestão é criar um loop de espera por anexo que verifica se variável sb_uploaded_file_key está presente ou não. Veja o exemplo do Rivescript abaixo:

+ *  
* <get sb_uploaded_file_key> == undefined => Favor enviar o arquivo.
- Recebi o seu arquivo!

Se for preciso preservar o chave do arquivo recebido e usar num ponto futuro da conversa, basta atribuir seu valor a uma variável de sua escolha. Veja o exemplo do Rivescript abaixo, que cria a variável arquivo_enviado:

+ *  
* <get sb_uploaded_file_key> == undefined => Favor enviar o arquivo.
- <set arquivo_enviado=<get sb_uploaded_file_key>>
^ Recebi o seu arquivo!

Alguns cases podem solicitar um único anexo e já despachar o tratamento específico dele. Ex:

  1. Chatbot diz: "Envie a cópia do seu documento para que seja aberta a solicitação".
  2. Usuário envia anexo.
  3. Chatbot aciona Sistema Externo por meio de webhook já informando o ID da conversa (sb_conversation_id) e a chave do arquivo recebido (sb_uploaded_file_key).
  4. De poss das informações, o Sistema Externo baixa aquele arquivo através do respectivo endpoint, valida seu conteúdo e abre a solicitação.

Outros cases podem preferir que vários anexos sejam enviados e que seja feito um tratamento que aborde todos eles em conjunto. Ex:

  1. Chatbot diz: "Envie todos os documentos listados acima e ao final digite 'Acabei' para que sua solicitação seja aberta".
  2. Usuário envia vários anexos.
  3. Usuário envia o texto 'Acabei'.
  4. Chatbot aciona Sistema Externo por meio de webhook e informa apenas o ID da conversa (sb_conversation_id).
  5. De posse dessa informação, o Sistema Externo lista todos os arquivos enviados naquela conversa através do respectivo endpoint e abre a solicitação.

Como o chatbot pode enviar um arquivo público para o usuário?

No motor Perguntas e Respostas, há a opção de criar uma parte da resposta do tipo Arquivo, sendo possível informar visualmente o Endereço do arquivo e opcionalmente um Nome customizado e uma Descrição.

Nos demais motores, onde o envio do arquivo não é um recurso nativo, há a opção de usar a sintaxe de texto abaixo:

#file|public|<endereco do arquivo>|<nome customizado (opcional)>|<descrição (opcional)>

Exemplos: - #file|public|https://site.com/arquivo.pdf - #file|public|https://site.com/123456.pdf|documento.pdf - #file|public|https://site.com/123456.pdf|documento.pdf|Segue o documento desejado. - #file|public|https://site.com/manual.pdf||Aqui está o manual

!!! warning Escapar o símbolo # no Watson No motor Watson Assistant, ao escrever a sintaxe de forma literal num campo texto, utilize uma barra antes do símbolo # para escapá-lo. Ex: \#file|public|https://site.com/arquivo.pdf

Como o chatbot pode enviar um arquivo privado para o usuário?

O envio do arquivo ocorre através do endpoint POST https://serprobots.estaleiro.serpro.gov.br/web/<id do chatbot>/api/files/<id da conversa>/chatbot

A requisição deve ser do tipo multipart/form-data contendo as seguintes partes: file (os bytes do arquivo), fileName (nome do arquivo), fileMimeType (tipo MIME do arquivo) e um caption (texto opcional descrevendo a imagem). Vide exemplo abaixo em cURL:

curl -X POST 'https://d-serprobots.estaleiro.serpro.gov.br/web/dbot-arquivos-d/api/files/conversation/9441ef30-5da6-4c79-ac9b-e5b827b5b876/user' \
  --form 'caption="Estou te enviando meu documento";type=text/plain' \
  --form 'file=@"/home/usuario/documento.pdf"' \
  --form 'fileName="meetup.pdf";type=application/text' \
  --form 'fileMimeType="application/pdf"'

Esse endpoint também exige a presença do cabeçalho Authorizaton: Bearer <token> informando o token de sessão autenticada configurado no Serprobots para aquele chatbot naquele ambiente (vide Sessão Autenticada). Dessa forma, somente o sistema externo devidamente autorizado conseguirá acesso.

Para entregar o arquivo privado na conversa, basta criar uma resposta textual em algum diálogo do motor desejado, com a sintaxe abaixo:

#file|chatbot|<nome do arquivo privado>|<nome customizado (opcional)>|<descrição (opcional)>

Um case possível é: 1. Em determinado ponto da conversa, o chatbot aciona um Sistema Externo através de webhook. 2. O Sistema Externo gera um arquivo privado (Ex: um PDF com o extrato bancário chamado extrato.pdf). 3. O Sistema Externo faz o upload seguro desse arquivo no endpoint acima explicado. 4. O retorno do webhook acionado pelo chatbot é um texto simples seguindo a sintaxe acima explicada: #file|chatbot|extrato.pdf. 5. O arquivo do extrato será apresentado na janela de conversa para o usuário imediatamente após o retorno do webhook.

Um outro case possível é: 1. Em determinado ponto da conversa, o chatbot aciona um Sistema Externo através de webhook. 2. O Sistema Externo gera um arquivo privado (Ex: um recibo de uma compra recibo.pdf). 3. O Sistema Externo faz o upload seguro desse arquivo no endpoint acima explicado. 4. O retorno do webhook acionado pelo chatbot é um JSON que dentre outros campos, informa o nome do arquivo de recbibo: { "arquivo_recibo": "recibo.pdf" }. Isso irá criar a variável de contexto arquivo_recibo no motor de conversação. 5. A conversa continua até o ponto em que o chatbot pergunta Deseja baixar o recibo da sua compra?. 6. Quando o usuário responde que sim, o chatbot monta uma resposta de texto com o valor da variável arquivo_recibo produzindo a sintaxe #file|chatbot|recibo.pdf e o arquivo é apresentado na janela de conversa para ele.