Retorno livre

Na página anterior, entendemos como funciona uma API com retorno vinculado à Suri, ou seja, APIs desenvolvidas especificamente para intergrar com o chatbot. Apesar de ser uma maneira super prática, não deixa de ser um fator limitante, pois muitas vezes você já possui uma API modelada para suas necessidades ou utiliza uma API externa, a qual não possui controle. Para esses casos, a Suri conta com uma abordagem que aqui chamaremos de Retorno livre.

Como o nome sugere, a API é livre para retornar qualquer tipo de dado, ficando a cargo da Suri entender tal retorno e poder fazer algo com ele. Ela faz isso utilizando o mesmo conceito de variáveis de contato, que já vimos neste tutorial. Em outras palavras: você pode utilizar dados do retorno de sua API como sendo variáveis do contato. Para isto, basta marcar mais um checkbox na configuração da ação HTTP:

Note que, após marcar o checkbox, uma opção aparece mais abaixo com dois campos: "Caminho" e "Nome da variável". Isto ocorre porque, para que a Suri saiba a estrutura do retorno, você precisa informar o "caminho" até o atributo que deseja armazenar, bem como o nome da variável a ser utilizada para guardar tal valor. Para entender melhor, observe o exemplo de retorno abaixo:

{
    "success": true,
    "data": {
        "ticket": {
            "id": "202403152107446473"
        }
    }
}

Para armazenar o id do ticket retornado, basta colocar o "caminho" para a propriedade correspondente, como se fosse acessar o objeto JSON:

data.ticket.id

E o nome da variável, por exemplo, "TicketId", é o nome desejado para utilizar tal valor em outros pontos do fluxo, utilizando @User.Variables.TicketId. Para rever como utilizar variáveis e outros dados do contato em seu fluxo, veja a página "Utilizando dados do contato". Veja abaixo como ficaria a configuração final:

Você pode armazenar quantos campos julgar necessário para sua integração. Observe abaixo uma configuração com mais variáveis:

Note que você também pode utilizar caminhos para atributos dentro de arrays/listas, utilizando o índice do mesmo, como no exemplo acima com a propriedade data.history[0].id

E, logicamente, você poderá utilizar as variáveis capturadas a partir desse momento, seja nesse ou em fluxos futuros:

Você deve estar se perguntando: por que não armazenar todo o retorno da API como variável de contato? De fato seria muito mais cômodo, porém, abriria precedentes para uma possível queda de performance de seu chatbot, visto que muitas APIs, principalmente as que não temos controle, retornam dados muito grandes e, por serem armazenados no banco de dados vinculados ao seu contato, poderia deixar o fluxo muito pesado.

Tipos de dados aceitos

As regras para captura de campos seguem a mesma regra de variáveis de contato, aceitamos apenas tipos primitivos, que são:

• String (texto)

• Date (data)

• Double, Int ou Float (numérico)

• Bool (verdadeiro/falso)

Portanto, utilizando o exemplo acima, caso você tente armazenar o caminho data.ticket (que é um objeto complexo), a Suri irá ignorar tal informação, salvando apenas uma variável vazia (com null).