Retorno vinculado à Suri

Por padrão, ao executar uma ação de Requisição HTTP, a Suri não espera uma resposta específica, apenas continua o fluxo executando as demais ações, se existirem. Porém existem algumas situações que desejamos utilizar o retorno de tal chamada HTTP de forma mais inteligente dentro do próprio Flow. Abaixo temos um exemplo para ilustrar:

Quero utilizar o Suri Flow para enviar um boleto de segunda via da fatura para meus clientes. Estou utilizando a ação de Requisição HTTP em meu Flow, onde envio os dados do contato para a API e lá consigo saber o último boleto em aberto, mas como faço para enviar de volta para o contato?

É uma situação interessante e bem comum: você deseja que o retorno da sua chamada HTTP seja uma resposta para seu contato - nesse caso, o boleto em PDF que o mesmo solicitou no fluxo. Para isso, basta marcar a opção "O retorno da requisição insere uma ação" na configuração da ação HTTP, como ilustrado abaixo:

Isso indicará à Suri que ela pode esperar um retorno do tipo FlowAction, que é uma ação executada pelo Flow de envio de mensagem ao contato. Retornando uma ação, ela é inserida no fluxo atual sem comprometer a experiência do fluxo e permitindo um leque de opções.

Existem diversos tipos de ação que podemos usar como resposta e iremos falar mais sobre elas mais abaixo, mas já adiantando, ainda utilizando o exemplo do boleto em PDF, sua API deve retornar um objeto do tipo FlowActionSendMediacontendo a url do boleto em questão., que será enviado ao contato que o solicitou.

Note que assim que marcamos a opção, aparece um banner amarelo indicando que as ações posteriores podem sofrer alterações. Isso é apenas um alerta indicando que, dependendo do tipo de FlowAction retornado, as demais ações do fluxo podem não ser executadas. Por exemplo, se sua API retornar com um FlowActiondo tipo "Envio de texto", tudo ok, as ações posteriores irão ser executadas normalmente após a ação de texto inserida ser executada. Mas se sua API retornar um FlowActiondo tipo "Transferir para atendimento humano", aí não faria sentido executar ações posteriores, pois a ação de transferir é uma ação de redirecionamento, que encerra o fluxo atual. Portanto a Suri apenas ignora as próximas ações e transfere o contato para atendimento humano.

Caso sua API apresente falha e não consiga retornar nenhum dado ou retorne um FlowActioninválido, não se preocupe: isso não irá quebrar o fluxo da Suri. O flow irá continuar normalmente, enviando as demais ações, caso existam, e registrando o erro em nossos logs para fins de consulta.

Modelos de FlowAction

Atualmente temos suporte aos seguintes FlowAction 's como resposta de requisição HTTP:

• FlowActionSendText: Envio de texto

• FlowActionSendMedia: Envio de mídia (imagem, vídeo, áudio ou documento)

• FlowActionSendLocation: Envio de localização

• FlowActionCapture: Captura de dado

• FlowActionRequestAgent: Transferir para atendimento humano

• FlowActionGoToFlow: Transferir para outro fluxo

Segue abaixo uma definição de todos os modelos listados:

• FlowActionSendText: Envio de texto

{
    text: string, // Texto a ser enviado
    delay: number // Opcional, padrão 0. Tempo de espera em segundos antes de executar a ação
    type: 0, // 0 para tipo Texto. Não alterar
}

• FlowActionSendMedia: Envio de mídia (imagem, vídeo, áudio ou documento)

{
    mediaType: number, // 0 para áudio, 1 para documento, 2 para imagem, 3 para vídeo
    url: string, // URL do arquivo
    fileName: string, // Nome do arquivo
    caption: string, // Opcional. Descrição do arquivo (texto menor a ser enviado junto)
    delay: number, // Opcional, padrão 0. Tempo de espera em segundos antes de executar a ação
    type: 1 // 1 para tipo Mídia. Não alterar
}

• FlowActionSendLocation: Envio de localização

{
    latitude: number, // Latitude
    longitude: number, // Longitude
    name: string, // Obrigatório. Nome para a localização, exemplo: Trabalho
    address: string, // Opcional. Breve descrição do endereço, exemplo: Av. Dom Manuel, 1020
    delay: number, // Opcional, padrão 0. Tempo de espera em segundos antes de executar a ação
    type: 2 // 2 para tipo Localização. Não alterar
}

• FlowActionRequestAgent: Transferir para atendimento humano

{
    departmentId: string, // Opcional. ID do departamento para transferir
    agentId: string, // Opcional. ID do atendente para transferir
    delay: number, // Opcional, padrão 0. Tempo de espera em segundos antes de executar a ação
    type: 4 // 4 para tipo Transferência para atendimento humano. Não alterar
}

• FlowActionGoToFlow: Transferir para outro fluxo

{
    flowId: string, // ID do flow a ser transferido
    delay: number, // Opcional, padrão 0. Tempo de espera em segundos antes de executar a ação
    type: 3 // 3 para Transferência de fluxo. Não alterar
}

• FlowActionCapture: Captura de dado. Deixamos ele por último pois é o mais extenso. Lembrando que em caso de captura de Variável ele possui 3 subtipos: Texto livre, Botões e Lista.

  • Nome, E-mail, Telefone, Documento, Observação ou Variável de Texto Livre

  {
      property: number, // Propriedade a ser capturada. 0 para Nome, 1 para E-mail, 2 para Telefone, 3 para Documento de identificação, 4 para Observação, 100 para Variável
      alwaysCapture: boolean, // Padrão true. Se a Suri sempre deve tentar capturar o dado ou somente em caso de não capturado
      variableType: 0, // Não alterar. Forma de captura. 0 para Texto livre, 1 para Botões, 2 para Lista
      variableName?: string, // Opcional. Obrigatório se property = 4. Nome da variável a ser capturada
      messageQuestion: string, // Mensagem de pergunta para capturar o dado
      messageIfCaptured?: null, // Opcional. Mensagem para caso de campo já capturado
      messageAfterCapture?: string, // Opcional. Mensagem para enviar após captura
      delay: number, // Opcional, padrão 0. Tempo de espera em segundos antes de executar a ação
      type: 7 // 7 para Captura. Não alterar
  }

  • Variável com botões: lembrando que o máximo de botões é 3

  {
      property: 100, // Não alterar. Propriedade a ser capturada. 0 para Nome, 1 para E-mail, 2 para Telefone, 3 para Documento de identificação, 100 para Variável
      alwaysCapture: boolean, // Padrão true. Se a Suri sempre deve tentar capturar o dado ou somente em caso de não capturado
      variableType: 1, // Não alterar. Forma de captura. 0 para Texto livre, 1 para Botões, 2 para Lista
      variableTypeButtons: {
          ContentType: number, // Tipo de conteúdo do botão. 0 para Texto, 1 para Imagem, 2 para Vídeo, 3 para Arquivo
          Header: string, // Opcional. Texto a ser enviado acima do texto principal de pergunta
          Text: string, // Texto principal do botão, que geralmente é a pergunta.
          Caption: string, // Opcional. Texto a ser enviado após o texto principal de pergunta
          Url: string, // Opcional. URL da mídia a ser enviada, caso o ContentType seja diferente de Text
          FileName: string, // Opcional. Nome da mídia a ser enviada
          Buttons: { Title: string }[] // Botões a serem mostrados (máximo 3). O título do botão é também o valor a ser capturado na variável
      },
      variableName: string, // Nome da variável
      messageIfCaptured?: null, // Opcional. Mensagem para caso de campo já capturado
      messageIfNoOptionSelected?: string, // Opcional. Mensagem para enviar em caso de nenhuma opção selecionada
      messageAfterCapture?: string, // Opcional. Mensagem para enviar após captura
      delay: number, // Opcional, padrão 0. Tempo de espera em segundos antes de executar a ação
      type: 7 // 7 para Captura. Não alterar
  }

  • Variável com lista: lembrando que o máximo de opções em uma lista é 10, podendo ser divididas em no máximo 3 seções (divisões visuais no WhatsApp)

  {
      property: 100, // Não alterar. Propriedade a ser capturada. 0 para Nome, 1 para E-mail, 2 para Telefone, 3 para Documento de identificação, 100 para Variável
      alwaysCapture: boolean, // Padrão true. Se a Suri sempre deve tentar capturar o dado ou somente em caso de não capturado
      variableType: 2, // Não alterar. Forma de captura. 0 para Texto livre, 1 para Botões, 2 para Lista
      variableTypeList: {
          title: string, // Título da lista
          body: string, // Pergunta de captura
          buttonTitle: string, // Título do botão que abre a lista
          sections: {
              title: string, // Título da lista
              subtitle: string, // Opcional. Pequena descrição da seção
              options: {
                  title: string, // Título da opção da lista e valor a ser capturado após seleção
                  description: string // Opcional. Descrição do item da lista
              }[] // Opções da lista, no máximo 10 contando todas as seções, isto é, a soma de options de cada section não deve ultrapassar 10
          }[] // Seções da lista, no máximo 3
      },
      variableName: string, // Nome da variável
      messageIfCaptured?: null, // Opcional. Mensagem para caso de campo já capturado
      messageIfNoOptionSelected?: string, // Opcional. Mensagem para enviar em caso de nenhuma opção selecionada
      messageAfterCapture?: string, // Opcional. Mensagem para enviar após captura
      delay: number, // Opcional, padrão 0. Tempo de espera em segundos antes de executar a ação
      type: 7 // 7 para Captura. Não alterar
  }

Agora que você entendeu como funciona o tratamento de Retorno vinculado à Suri, te convidamos a conhecer um pouco mais sobre a maneira mais no-code de integrar: o tratamento de Retorno livre, onde a própria Suri consegue capturar os dados proveninentes de sua API, independente do formato em que estiverem.