Retorno de lista
Nas páginas anteriores vimos sobre o comportamento de retorno vinculado à Suri, onde a API se adapta aos objetos do chatbot e consegue retornar diversos tipos de ação diferentes como resposta ao contato. Também vimos sobre retorno livre, onde a Suri se adapta ao retorno da API, capturando determinados valores retornados e utilizando como variáveis do contato. Nesta página iremos falar sobre uma junção desses dois conceitos, que iremos chamar de retorno de lista, para simplificar.
A grande motivação desse tipo de tratamento de retorno é poder retornar ao contato uma lista dinâmica de opções para que ele escolha uma e prossiga o fluxo. Um exemplo para ilustrar: listagem de notas fiscais.
Suponha que sua API receba o CNPJ da empresa e encontre uma lista de notas fiscais em nome dela. É natural que você queira mostrar essa lista para o contato escolher qual nota deseja receber. Até então isso só seria possível utilizando o comportamento de retorno vinculado à Suri, mas aí você teria que criar essa API unicamente para utilização do chatbot. Note que não seria possível usar o retorno livre pois a API pode retornar 1 nota, mas também pode retornar 2, 3.. Ou nenhuma, caso não sejam encontradas notas para aquele CNPJ. É por esse dinamismo que criamos o retorno de lista:
Ainda no exemplo do CNPJ vamos supor que nossa API tenha o seguinte formato de retorno:
Note que tenho duas informações importantes em meu retorno e que gostaria de retornar ao meu contato: a data de emissão da nota e a url da nota em si. Então a Suri deve mostrar uma lista de datas de emissão e, quando o contato escolher uma delas, deve enviar de volta para ele o PDF da nota (através do link). Também desejo tratar o caso de não haver nenhuma nota (ou seja, a lista vir vazia).
Para fazer tudo isso continuamos utilizando a ação de HTTP como vimos anteriormente, a única diferença é que devemos marcar a opção "Tratar retorno como botões ou lista". Marcar essa opção automaticamente invalida as duas anteriores, pois não podem coexistir.
Na imagem abaixo explicamos em detalhes o que significa cada um dos campos a serem configurados:
Se você já está acostumado em trabalhar com botões e listas em seu fluxo, irá perceber que a estrutura é bem semelhante, pois é o que de fato irá ser retornado ao contato. A única diferença é que, ao invés de colocarmos os valores de texto que irão nos botões, informamos o caminho do JSON que contém o valor a ser colocado nesse campo. Com isso a Suri irá ler o retorno da API, mapear esse caminho até o valor do mesmo e utilizá-lo em sua lista.
Importante: ao preencher os caminhos para título/valor da opção, você deve considerar como "raiz" o item da lista e não o JSON completo. No exemplo acima, note que a lista está dentro do caminho "Data", então consequentemente para preencher os caminhos de título e valor, considero um item dessa lista e utilizo as propriedades dele. No caso, "Emissao" e "Url".
Considerando o exemplo acima, suponha que eu armazenei o resultado da escolha do contato em uma variável chamada "notaUrl". Como eu armazenei a url da nota nesta variável, posso utilizá-la à vontade no fluxo, por exemplo, enviando uma ação de mídia por URL:
Veja abaixo o resultado dessa configuração:
E se não houverem resultador retornados? Como podemos tratar isso visto que não há uma forma de retornar uma lista vazia? Utilizamos a variável criada automaticamente "notaUrl_count", onde armazenamos o número de opções da lista. Utilizando a ação condicional conseguimos identificar se houveram resultados e tratar cada caso como um subfluxo:
Legal né? Esse tipo de retorno pode te ajudar muito a automatizar serviços dentro de sua empresa, principalmente em casos como retorno de informações, criação de formulários complexos, etc. O céu é o limite para o Suri Flow!
Last updated
