Ir para o conteúdo

Trilha Avançada

Enviando e recebendo arquivos

É possível utilizar arquivos anexos em uma conversa com o chatbot das seguintes formas:

  • Receber um arquivo anexado pelo usuário na conversa: permite que os usuários enviem arquivos durante a conversa com o chatbot. Quando um usuário envia um arquivo, o chatbot receberá e poderá processá-lo de acordo com a lógica da sua programação. Além disso, os arquivos recebidos podem ser acessados por sistemas externos para realizar alguma tarefa.

  • Enviar arquivos para o usuário: permite que o chabot envie arquivos para os usuários diretamente na conversa. O arquivo pode estar disponível em uma URL pública na Internet ou o chatbot pode acessar um sistema externo para obter o arquivo e enviar para o usuário de forma privada.

Recepcionando arquivos enviados pelos usuários

1. Habilitando a opção de envio de anexo no Canal Web

É necessário habilitar a opção no canal Web para que o botão de anexo seja exibito na janela para o usuário. Para isso, faça:

  1. Acessar o chatbot que deseja editar.

  2. No menu lateral, acionar CANAIS.

  3. Selecionar o canal Web.

  4. Localizar o grupo de configurações CAIXA DE ENTRADA.

  5. Ativar a opção Exibir botão de anexar arquivo.

Atenção! No canal WhatsApp, o envio de anexo está sempre habilitado pois é nativo da ferramenta.

2. Tratar o arquivo anexado na conversa

Para tratar o arquivo recebido, é preciso utilizar ou o motor Watson Assistant ou Rivescript, que vão permitir o uso de variáveis de contexto. Uma mensagem de usuário que carrega um arquivo anexo vai possuir a variável sb_uploaded_file_key. Essa variável guarda a chave do arquivo que acabou de ser armazenado temporariamente na plataforma para posterior tratamento do chatbot desse upload feito pelo usuário.

Abaixo vamos exemplificar como criar um Rivescript que percebe que o arquivo foi recebido e dá uma resposta:

  1. No menu lateral de um chatbot, acionar MOTORES DE CONVERSAÇÃO.

  2. Na página Motores de conversação, acionar a opção NOVO MOTOR.

  3. Escolher o motor Rivescript e clicar em Criar.

  4. Escrever um nome para o motor, por exemplo, Receber anexo.

  5. Criar as regras no campo Regras, por exemplo:

    + anexo
- Por favor, envie o arquivo. {topic=esperaarquivo}

> topic esperaarquivo
+ *  
* <get sb_uploaded_file_key> == undefined => Por favor, envie o arquivo ou escreva "desistir".
- Recebi o seu arquivo! {topic=random}

+ desistir
- OK! {topic=random}

< esperaarquivo
3. Acessar arquivos recebidos

Quando uma mensagem do usuário contém um anexo, o arquivo fica armazenado temporariamente na plataforma durante 24 horas.

  1. Para acessar os arquivos enviados pelos usuários, o Serprobots disponibiliza os seguintes endpoints:

    Listar os arquivos da conversa:

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

    Baixar um arquivo da conversa:

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

    Esses endpoints exigem a presença do cabeçalho Authorizaton: Bearer <token> informando o token de sessão autenticada.

Atenção! As variáveis necessárias para a utilização dos endpoints estão descritas em Palavras reservadas

No exemplo abaixo, é acionada uma Integração no Rivescript que irá receber o nome do arquivo e o identificador da conversa para conseguir acionar a API.

5. Enviar arquivo público para o usuário

No motor Perguntas e Respostas:

  1. Selecionar a opção Gerenciar Conversas.

  2. Acionar a opção NOVA PERGUNTA ou selecionar Editar Pergunta em alguma pergunta já existente.

  3. No grupo de RESPOSTAS, incluir resposta tipo Arquivo.

  4. Informar o Endereço do arquivo e opcionalmente um Nome customizado e uma Descrição.

Nos demais motores:

  1. Utilizar a sintaxe:

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

    Exemplos:

    #file|public|https://site.com/123456.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/123456.pdf||Segue o documento desejado.

    Atenção! No motor Watson Assistant, ao escrever a sintaxe num campo texto, utilizar uma barra invertida \ antes do símbolo #.

    Por exemplo:

    \#file|public|https://site.com/arquivo.pdf
6. Enviar arquivo privado para o Serprobots

Em determinado ponto da conversa, o chatbot aciona um Sistema Externo através de webhook. O Sistema Externo pode realizar o upload seguro de arquivos para o Serprobots.

  1. Enviar o arquivo privado para o Serprobots por meio do endpoint do tipo multipart/form-data: 

    POST https://serprobots.estaleiro.serpro.gov.br/web/<id do chatbot>/api/files/<id da conversa>/chatbot

    Esse endpoint exige a presença do cabeçalho Authorizaton: Bearer <token> informando o token de sessão autenticada e possui as seguintes partes:

    • file: caminho para o arquivo.
    • fileName: nome do arquivo para o Serprobots.
    • fileMimeType: tipo MIME do arquivo.
    • caption: texto descrevendo o arquivo (opcional).

    Por exemplo, 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_123456.pdf"' \
--form 'fileName="documento_123456.pdf";type=application/text' \
--form 'fileMimeType="application/pdf"'

  2. Uma vez feito o upload do arquivo, você poderá criar uma resposta textual em algum diálogo do motor desejado com a seguinte sintaxe:

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

    Nessa sintaxe, a chave do arquivo privado é aquela definida no atributo fileName da API de upload descrita acima.

    Exemplo

    #file|chatbot|documento_123456.pdf|relatorio.pdf|Segue o relatório desejado.
6. Chamar uma integração que produz um arquivo

Em determinado ponto da conversa, o chatbot aciona um Sistema Externo através de webhook. Se o webhook devolver um arquivo, ele será exibido na conversa para download.

É importante que a integração ao retornar um arquivo informe o header Content-Disposition, que é o que permitirá perceber que se trata de um arquivo a ser baixado.