Intenção de IA (legado)
Fluxos de conversa que redirecionam para serviço externo
Last updated
Fluxos de conversa que redirecionam para serviço externo
Last updated
Se você não possui acesso à tela de Intenções de IA pelo Portal Suri significa que seu chatbot já está na nova experiência conversacional: o Suri Flow. Para integrar com a Suri utilizando essa nova experiência ou migrar sua integração, acesse a página anterior.
Intenções de IA já são bem conhecidas do atendimento utilizando a Suri, pois são elas que permitem criar fluxos de conversa de forma inteligente. Utilizar um tipo específico de ação ao criar uma intenção de IA permite redirecionar o controle da conversa para um serviço externo, seja para realizar uma integração, seja para trocar mensagens de forma customizada.
Para você que prefere algo mais resumido, nesta seção traremos as principais informações necessárias para realizar a integração. Mas logo abaixo trazemos exemplos práticos com casos de uso da vida real que podem ajudar a compreender os conceitos aqui tratados.
A ação do tipo "Redirecionar para API" espera receber no campo Conteúdo a url do endpoint de sua API.
Este endpoint não deve possuir regra de autorização via header. Se desejar limitar o acesso por questões de segurança, você pode autorizar somente a url do seu chatbot como origin da requisição (para ver a url do seu chatbot, basta acessar a página Configurações > aba Geral, no Portal Suri).
Este endpoint deve estar preparado para receber uma requisição POST com body contendo o contato (User) que falou com seu bot a caiu na intenção de IA em questão. O objeto do contato (User) está definido em nossa documentação no Postman, bem como outros modelos importantes.
Após enviar e receber uma resposta de código 200 (sucesso), a Suri entra em "modo espectador" na conversa, isto é, ela não interage mais com aquele contato, pois entende que o domínio da conversa é de seu serviço externo.
Para identificar de qual intenção de IA seu contato chegou até sua API, você pode utilizar um dos atributos do objeto User enviado pela Suri à sua API: CurrentDialog.Data["source"], que estará preenchido com o nome da Intenção de IA que o redirecionou para seu serviço externo.
Seu serviço externo pode enviar mensagens através da API de envio de mensagens e receber as mensagens enviadas pelo contato através do webhook de mensagem recebida.
Para dar novamente acesso da conversa à Suri, basta chamar o endpoint Voltar para o fluxo Suri na API. Na chamada, você pode especificar uma intenção de IA para que o contato já entre em um novo fluxo.
Muitas vezes a melhor maneira de explicar algo é exemplificando, então considere a seguinte situação: você possui uma Suri com um fluxo específico para enviar segunda via de boleto. Uma vez que o contato solicite a segunda via através do chatbot, o mesmo deve chamar a API do financeiro, que gerará o arquivo do boleto e deverá ser enviado de volta para o contato. Por mootivos de simplicidade, suponha que para consultar o boleto na API do financeiro seja necessário apenas o documento da pessoa e que este dado está salvo no contato no Portal de atendimento da Suri.
Para que isso seja possível, você deve, na intenção de segunda via, configurar a ação de Redirecionar para API informando o endpoint que realiza tal ação. A Suri envia uma requisição POST para o endpoint com o body contendo o contato em questão. Com isso sua API pode verificar o documento do contato em sua base de dados e buscar o boleto. Para finalizar, o arquivo é enviado em caso de sucesso ou uma mensagem de texto informando o erro em caso negativo. A figura abaixo ilustra esse fluxo:
Ainda meio confuso? Vamos por partes:
1) Contato manda mensagem informando que quer receber a segunda via. A Suri, utilizando inteligência artificial, relaciona tal frase à uma Intenção previamente criada, chamada "Segunda Via";
2) Tal Intencão foi configurada como comentamos anteriormente: utilizando uma acão de Redirecionar para API. Com isso, a SURI realiza uma requisição POST com o body contendo o contato em questão e todos os seus dados (id único, nome, telefone, etc.) e como isso transfere o controle de mensagens da Suri para o serviço externo. Guarde essa informação que iremos comentar sobre mais adiante;
3) O serviço externo recebe tal requisição e então comeca o processamento para obtenção da segunda via. Note que no diagrama retornamos o código 200 (de sucesso) antes de processar tal requisicão. Esta etapa não é obrigatória, mas recomendada, para que a Suri não fique "esperando" e haja risco de timeout (em caso de processamento longo demais). É uma abordagem interessante caso utilize Jobs para realizacão de tarefas em seu servico;
4) e 5) Ao termos o arquivo pronto, enviamos para o contato em questão utilizando nossa API de envio de mensagens;
6) Como o Servico Externo já fez o seu papel gerando o arquivo e enviando para o contato, o controle da conversa deve ser retornado à Suri, caso contrário qualquer outra mensagem enviada pelo contato não irá ser respondida pelo chatbot. Tal acão é realizada através da API, no endpoint Voltar para fluxo Suri.
7) Opcionalmente, ao transferir o controle da conversa à Suri, podemos escolher uma IA específica para que o contato continue um determinado fluxo. É comum criarmos uma Ia de agradecimento ou perguntando "Ajudo em algo mais?', mas caso não seja de seu desejo basta deixar o parâmetro em branco que a Suri não mandará mais nenhuma mensagem, mas ficará pronta para tratar qualquer nova mensagem do contato.
Como citado nos pontos 2) e 6) do exemplo de uso, separamos os conceitos de fluxo Suri e fluxo externo. Isso é importante para impedir que a Suri responda mensagens quando há uma tarefa externa em processamento - imagine só um contato que pediu a segunda via do boleto, está esperando a resposta de sua API e manda mais uma mensagem solicitando outra coisa, o fluxo iria para outro caminho e, ao ter o boleto processado, seria enviado no meio da conversa, resultando em uma má experiência.
Quando um contato está falando com a Suri ou com um atendente humano, consideramos que ele está no fluxo Suri. Isso significa que o chatbot pode enviar mensagens para o contato e direcioná-lo através dos fluxos de IA. Quando um contato cai em uma IA que redireciona para uma API e esta responde com um status de sucesso (código 200), o contato vai para o fluxo externo.
Por isso sempre que não precisamos mais tratar a conversa a nível de API, deve-se chamar o endpoint de voltar para fluxo Suri para que o controle passe para o chatbot novamente.
Para que um contato entre em um fluxo externo é necessário que a resposta da API para a qual o contato foi direcionado seja de código 200. Isso evita que, caso a API esteja indisponível, contatos fiquem presos no fluxo externo sem resposta da Suri.
Por isso indicamos que toda tarefa seja realizada de forma assíncrona pelo serviço externo, como no exemplo de uso, que a API retornou código 200 antes de processar o arquivo da segunda via, evitando possíveis problemas com timeout.
Existem situações que um único dado não é o suficiente para realizar uma determinada ação em seu serviço externo. Por exemplo, quando você precisa que o contato responda a uma espécie de formulário com várias perguntas.
Vamos supor agora outra situação, onde você possui uma clínica e deseja, através da Suri, realizar um agendamento em seu sistema interno de agendamentos de consulta. Você necessita que o contato informe seu nome completo, CPF e o horário desejado.
No exemplo de uso 1 vimos como redirecionar para API sem necessitar de um dado específico (pois o próprio contato enviado no POST conteria o documento de identificação necessário), mas e se o dado depender de uma resposta do contato à uma pergunta? Utilizamos a dobradinha API + Webhook. Detalhamos o fluxo abaixo:
Para coletar essas três informações do contato iremos precisar de 3 Intenções de IA, chamaremos de "Coleta - Nome", "Coleta - CPF" e "Coleta - Horário", respectivamente. Adicionalmente mais uma chamada "Finalização" para dar um feedback ao contato após o processamento;
A primeira intenção envia uma mensagem perguntando o nome e logo em seguida redireciona para a API;
Na API, a partir desse momento monitoramos o webhook de mensagem recebida esperando a resposta do contato;
Quando recebemos a resposta, armazenamos tal informação (em memória, em um banco de dados, etc.) e chamamos a API de Voltar para fluxo Suri enviando para a intenção Coleta - CPF;
A intenção de CPF por sua vez envia uma mensagem perguntando o CPF e redireciona para a API, repetindo o processo novamente até chegar na última Intenção, a de horário.
Abaixo ilustramos esse fluxo em um diagrama para melhor compreensão:
Deu para notar que tal integração consiste em utilizar a IA como forma da Suri indicar que tal contato está em um fluxo e utilizar o webhook para mapear a resposta do contato referente à esse fluxo.
Note também que há muitas idas e vindas e requisições entre Suri e seu serviço externo. Nada impede que você, ao invés de retornar ao fluxo Suri para fazer a próxima pergunta, faça uma chamada de API para enviar mensagem contendo a pergunta em si.
O fluxo seria praticamente o mesmo, observando a resposta via webhook e passando ao próximo passo. Porém, indicamos que deixe toda a parte de envio de mensagens pelo fluxo Suri, pois isso gera uma maior flexibilidade (caso precise alterar um texto, não precisa fazer um novo deploy em sua aplicação, basta utilizar o Portal da Suri).
É natural que surja uma nova dúvida nesse momento:
Como irei saber em qual parte do fluxo o Contato está - nome, CPF ou horário?
Como você pode observar em nossa documentação de webhooks, o evento de nova mensagem é composto pelo contato que mandou tal mensagem e o corpo da mensagem de fato. Obviamente utilizamos o corpo da mensagem para pegar as informações necessárias (nesse caso, nome, CPF e horário) e utilizamos uma propriedade específica do contato para saber qual a última IA acessada por ele, ou seja, de qual fluxo o contato veio:
A propriedade acima contém exatamente o nome da IA que levou o contato para o serviço externo, podendo assim, ser utilizada como mapeamento das respostas. Aplicando ao nosso exemplo:
Se source é "Coleta - Nome", contato está informando nome
Se source é "Coleta - CPF", contato está informando CPF
Se source é "Coleta - Horário", contato está informando horário
Sabemos que na vida real nem tudo é perfeito, então precisamos estar preparados para o caso de contatos não responderem o que esperamos. Por exemplo, um número como sendo o nome ou um CPF mal formatado ou inválido.
É importante haver um tratamento das respostas em seu serviço externo para verificar a validade dos mesmos. Em caso de falha, você pode utilizar nossa API de envio de mensagem para solicitar o dado correto. Enviar uma mensagem via API durante fluxo Suri ou fluxo externo não afeta o caminho esperado.
Em nosso exemplo poderíamos utilizar mensagens como "Por favor, informe seu nome completo" quando contatos informarem somente seu primeiro nome ou "Por favor, informe um CPF válido" quando a mensagem conter um CPF não aceito de acordo com as diversas regras de validação de CPF.
