Integrando com telefone e Twilio Flex

Antes de iniciar

Para usar esse padrão de integração, você precisa:

• Construtor de assistentes de IA (necessário para integração com o celular)

• Uma conta do Twilio com os produtos a seguir:

  • Twilio Flex

  • Twilio Voice com a API Programmable Voice

  • Twilio Studio

Adicionar a integração do assistente de IA ao telefone

Você pode pular esta seção se já tiver adicionado a integração do telefone ao seu assistente.

Se você precisar adicionar a integração telefônica, siga estas etapas.

1. Na seção Integrações da página principal do seu assistente, em Canais essenciais, você verá um bloco para Telefone.

2. No bloco Phone, clique em Add.

3. Na janela pop-up, clique novamente em Add.

4. Selecione Usar um número de telefone existente com um provedor externo.

5. Conclua o processo de configuração de integração telefônica. Para obter mais informações, consulte Integrando com o telefone.

Por enquanto, isso é tudo que precisa ser feito. Para obter mais informações sobre a configuração da integração de telefone, consulte Integrando com o telefone.

Incluindo o projeto Twilio Flex

É necessário um projeto Twilio Flex novo ou existente.

Se precisar de um projeto Twilio Flex, você pode criar um usando estas etapas.

1. No menu suspenso do projeto, clique em Criar novo projeto. Especifique um nome para o projeto e verifique as informações de sua conta.

2. Na página de boas-vindas, selecione Flex como o produto Twilio para seu novo projeto. Preencha o questionário e, em seguida, clique em Comece a usar o Twilio.

Depois que seu projeto Flex estiver configurado, volte ao console do Twilio. Verifique se você selecionou o projeto correto na lista suspensa.

1. No menu de navegação, clique no ícone Todos os produtos e serviços.

2. Clique em Twilio Programmable Voice > Configurações > Geral.

3. Em Recursos do SIP programáveis aprimorados, alterne o comutador para Ativado.

Criando o fluxo de chamada

Depois que a integração telefônica e o projeto Twilio Flex estiverem configurados, você deverá criar um fluxo de chamadas com o Twilio Studio e provisionar (ou portar) o número de telefone com o qual deseja que o assistente trabalhe.

Para criar o fluxo de chamada:

1. No menu de navegação, clique no ícone Todos os produtos e serviços.

2. Clique em Studio.

3. Clique em + para criar um novo fluxo.

4. Nomeie o novo fluxo e clique em Next.

5. Selecione Start From Scratch e, em seguida, clique em Next. Um widget Trigger aparece em sua tela de fluxo.

6. Clique no widget Acionador.

7. Anote o valor do campo URL DO WEBHOOK. Você precisará desse valor em uma etapa posterior.

Configurando o número do telefone

1. No menu de navegação, clique no ícone Todos os produtos e serviços.

2. Clique em Números de telefone.

3. Em Gerenciar números, configure o número do telefone que você quer que o assistente use. Selecione Comprar um número para comprar um novo número ou em Porta e host para portar um número de telefone existente.

4. Na lista Números ativos, clique no novo número do telefone.

5. Em Voice and Fax, defina essas configurações.

   • Para o campo CONFIGURAR COM, selecione Webhook, Bins TwiML, Funções, Studio ou Proxy.

   • Para UMA CHAMADA RECEBIDA, selecione Fluxo do Studio. Selecione o fluxo na lista suspensa.

   • Para FALHA DO MANIPULADOR PRINCIPAL, selecione Fluxo do Studio. Selecione o fluxo na lista suspensa.

6. Acesse a interface do usuário do assistente de IA e abra as configurações de integração com o telefone do seu assistente.

7. No campo Número de telefone, digite o número de telefone que você configurou no Flex Studio.

8. Clique em Salvar e sair.

Teste o número de telefone

Agora é possível testar se o número de telefone está conectado ao fluxo acionando um widget Falar/Reproduzir no editor de fluxo do Twilio Flex.

1. Arraste um widget Falar/Reproduzir na tela de fluxo.

2. Configure o widget Say Falar/Reproduzir com uma frase simples como I'm alive..

3. Conecte o nó Chamada recebida no widget Acionador ao widget Falar/Reproduzir.

4. Ligue para o seu número de telefone. Você deverá ouvir o fluxo do Twilio responder com sua frase de teste.

5. Exclua o widget Falar/Reproduzir e continue na próxima etapa.

6. Se esse teste não funcionar como esperado, verifique novamente a configuração do seu número de telefone para garantir que ele esteja conectado ao seu fluxo.

Criando uma função Twilio para manipular chamadas recebidas

Agora você precisa configurar o fluxo de chamadas para direcionar as chamadas recebidas para o assistente usando uma função do Twilio. Siga estas etapas:

1. No menu de navegação, clique no ícone Todos os produtos e serviços.

2. Clique em Serviços.

3. Clique em Create Service. Especifique um nome de serviço e, em seguida, clique em Avançar.

4. Clique em Incluir > Incluir função para incluir uma nova função no serviço. Nomeie a nova função /receive-call.

5. Substitua o modelo em sua função /receive-call por este código:

    exports.handler = function(context, event, callback) {
      const VoiceResponse = require('twilio').twiml.VoiceResponse;  
      const response = new VoiceResponse();
      const dial = response.dial({
        answerOnBridge: "true",
        referUrl: "/refer-handler"
      });
      const calledPhoneNumber = event.Called;
      dial.sip(`sip:${calledPhoneNumber}@{sip_uri_hostname};secure=true`);  
      return callback(null, response);
    }

• Substitua {sip_uri_hostname} pela parte do nome do host do URI SIP de integração telefônica do seu assistente (tudo o que vem depois de sips:). Observação: o Twilio não oferece suporte a URIs SIPS, mas oferece suporte a entroncamento SIP seguro acrescentando ;secure=true ao URI SIP.

1. Clique em Salvar.

2. Clique em Implementar todos.

Redirecionando para o manipulador de chamadas recebidas

Use um widget TwiML Redirect no editor do Studio Flow para chamar a função /receive-call criada na seção anterior.

1. Inclua um widget Redirecionamento TwiML na tela Fluxo do Studio.

2. Conecte o acionador Chamada recebida ao widget Redirecionamento TwiML.

3. Configure o widget TwiML Redirect com o URL da função /receive-call que você criou na seção anterior.

4. Agora, seu fluxo deve redirecionar para o assistente de IA ao receber uma chamada.

5. Se o redirecionamento falhar, certifique-se de implementar a função /receive-call.

Criando uma função Twilio para manipular transferências do assistente

Você também precisa configurar o fluxo de chamadas para tratar as chamadas transferidas do assistente de volta para o Twilio Flex, para os casos em que os clientes pedem para falar com um agente. Use um widget “Say/Play” após o widget de redirecionamento “ TwiML ” para indicar que a chamada foi transferida de volta para o fluxo a partir do assistente de IA. Muitas opções são possíveis nesse momento, como enfileirar a chamada para um agente em tempo real, e são discutidas nesta seção.

1. Adicione um widget Say/Play à sua tela e configure-o com uma frase como Transfer from Watsom complete.

2. Conecte o nó Retorno no widget Redirecionamento TwiML ao widget Falar/Reproduzir.

3. Clique no widget Acionador.

4. Copie o valor do campo URL DO WEBHOOK. Você precisará desse valor em uma etapa posterior.

5. Na página Funções Twilio, clique em Incluir > Incluir função para incluir outra nova função no serviço. Nomeie essa nova função /refer-handler.

6. Substitua o modelo na função /refer-handler pelo código a seguir:

    exports.handler = function(context, event, callback) {
      // This function handler will handle the SIP REFER back from the Phone Integration.
      // Before handing the call back to Twilio, it will extract the session history key from the
      // User-to-User header that's part of the SIP REFER Refer-To header. This session history key
      // is a string that is used to load the agent application in order to share the transcripts of the caller
      // with the agent.
      // See https://github.com/watson-developer-cloud/assistant-web-chat-service-desk-starter/blob/main/docs/AGENT_APP.md
      const VoiceResponse = require('twilio').twiml.VoiceResponse;
      
      const STUDIO_WEBHOOK_URL = '{webhook_url}';
      
      let studioWebhookReturnUrl = `${STUDIO_WEBHOOK_URL}?FlowEvent=return`;
      
      const response = new VoiceResponse();
      console.log("ReferTransferTarget: " + event.ReferTransferTarget);
      
      const referToSipUriHeaders = event.ReferTransferTarget.split("?")[1];
      console.log(referToSipUriHeaders);
      if (referToSipUriHeaders) {
        const sanitizedReferToSipUriHeaders = referToSipUriHeaders.replace(">", "");
        console.log("Custom Headers: " + sanitizedReferToSipUriHeaders);
        
        const sipHeadersList = sanitizedReferToSipUriHeaders.split("&");
        
        const sipHeaders = {};
        for (const sipHeaderSet of sipHeadersList) {
          const [name, value] = sipHeaderSet.split('=');
          sipHeaders[name] = value;
        }

        const USER_TO_USER_HEADER = 'User-to-User';
        
        // Extracts the User-to-User header value
        const uuiData = sipHeaders[USER_TO_USER_HEADER];
        
        if (uuiData) {
          const decodedUUIData = decodeURIComponent(uuiData);
          const sessionHistoryKey = decodedUUIData.split(';')[0];
          // Passes the session history key back to Twilio Studio through a query parameter.
          studioWebhookReturnUrl = `${studioWebhookReturnUrl}&SessionHistoryKey=${sessionHistoryKey}`;
        }    
      }

      response.redirect(
        { method: 'POST' },
        studioWebhookReturnUrl
      );

      // This callback is what is returned in response to this function being invoked.
      // It's really important! E.g. you might respond with TWiML here for a voice or SMS response.
      // Or you might return JSON data to a studio flow. Don't forget it!
      return callback(null, response);
    }

Substitua {webhook_url} pelo valor URL WEBHOOK que você copiou do widget Trigger em seu Studio Flow.

1. Clique em Salvar.

2. Clique em Implementar todos.

3. Depois de criar esse manipulador de referência, copie a URL da função de volta para o campo referUrl do manipulador /receive-call.

Configurando o assistente para transferir chamadas para Twilio Flex

Agora é preciso configurar o assistente para transferir chamadas para o Twilio Flex quando um cliente pede para falar com um agente. Siga estas etapas:

1. Na interface do usuário do assistente de IA, abra a habilidade de diálogo do seu assistente.

2. Adicione um nó com a condição que aciona seu assistente para transferir clientes para um agente.

3. Adicione uma resposta de texto ao nó e especifique o texto que você deseja que o assistente diga antes de transferir os clientes para um agente.

4. Abra o editor JSON para a resposta.

5. No editor JSON, inclua uma resposta connect_to_agent especificando seu número de telefone como sip.uri (substitua {phone_number} pelo número de telefone do tronco SIP):

{
  "generic": [
    {
        "response_type": "connect_to_agent",
        "transfer_info": {
          "target": {
            "service_desk": {
              "sip": {
                "uri": "sip:+{phone_number}@flex.twilio.com",
                "transfer_headers_send_method": "refer_to_header"
              }
            }
          }
        },
        "agent_available": {
          "message": "Ok, I'm transferring you to an agent"
        },
        "agent_unavailable": {
          "message": ""
        }
    }
  ]
}

Este exemplo não mostra como usar o contexto que é passado do assistente de IA para o Twilio Flex. Você pode fazer referência às informações de usuário para usuário no fluxo do Twilio Flex:

{
  "context": {
    "widgets": {
      "redirect_1": {
        "User-to-User": "value",
      }
    }
  }
}

em que redirect_1 é o nome do widget de redirecionamento. Por exemplo, se várias filas forem configuradas, talvez você queira usar um widget Divisão do Twilio para escolher uma fila com base no contexto retornado.

Teste seu assistente

Seu assistente agora deve poder atender chamadas para seu número de telefone e transferir chamadas de volta para seu fluxo Twilio Flex. Para testar o assistente:

1. Ligue para o seu número de telefone. Quando o assistente responder, solicite um agente.

2. Você deverá ouvir a frase configurada no widget Say/Play (como, por exemplo, "Transfer from Watson complete").

3. Se a transferência falhar, use o log do console para acompanhar o fluxo da chamada à medida que ela passa do fluxo para o /receive-call manipulador, para o assistente de IA, para o manipulador de encaminhamento e, em seguida, de volta ao seu fluxo do Twilio Flex.