Configurando a transferência de chamada

O comportamento de transferência de chamada é definido por meio da API e da configuração do Voice Gateway ou de propriedades de configuração avançada de JSON.

Iniciando transferências de chamada

Na Versão 1.0.0.2 e mais recente, a transferência de chamada é iniciada no serviço Watson Assistant definindo a tag de ação vgwActTransfer na definição do nó JSON.

{
  "output": {
    "vgwAction": {
      "command": "vgwActTransfer", "parameters": {
        "transferHeader": "User-to-User",
        "transferHeaderVal": "12a345b6c7d8901234e5;encoding=hex;purpose=foo;content=bar",
        "transferTarget": "tel:+18883334444"
      }
    }
  }
}

Ao definir uma URI do SIP como o destino de transferência, certifique-se de escapar o caractere @ no URI, para que o valor não seja processado pelo Watson Assistant.

  ...
  {
    "transferHeader": "User-to-User",
    "transferHeaderVal": "12a345b6c7d8901234e5;encoding=hex;purpose=foo;content=bar",
    "transferTarget": "sip:12345556789\\@myhost.com"
  }
...

As versões anteriores do Voice Gateway usavam a variável de estado vgwTransfer para iniciar a transferência de chamada. Embora essa variável de estado continue a funcionar, seu uso foi descontinuado em favor da tag de ação vgwActTransfer. Para obter mais informações, veja Variáveis de estado descontinuadas.

Determinando se uma transferência é bem-sucedida ou com falha

Quando um processo de transferência é bem-sucedido, o Watson Assistant recebe uma atualização de texto com a palavra "vgwCallTransferred" e a variável de estado vgwCallTransferred configurada como Yes.

Quando uma transferência falha e a variável de estado vgwDisconnectCallOnTransferFailure é configurada como No, o Watson Assistant recebe uma atualização de texto do Voice Gateway com a sequência "vgwCallTransferFailed". Essa sequência indica que uma transferência falhou. Veja Transferindo em caso de falha para configurar sua instância de serviço do Watson Assistant e a implementação do Voice Gateway para responder às falhas de transferência.

Transferência em desligamento

Por padrão, o Voice Gateway executa uma chamada de transferência usando uma solicitação SIP REFER. Dependendo do provedor de serviços IVR, você pode precisar configurar a transferência de chamada para usar um método SIP BYE no lugar. Veja Integrando o Voice Gateway com IVRs e centrais de contato para localizar mais informações sobre os provedores de serviços IVR.

Na ação vgwActTransfer, use o atributo transferMethod para especificar como transferir a chamada, REFERIR ou HANGUP. Quando configurado para HANGUP, o comportamento da ação de transferência muda. Em vez de enviar uma solicitação SIP REFER, o Voice Gateway reproduz qualquer texto associado e, em seguida, desliga a chamada enviando uma solicitação SIP BYE.

Após o desligamento, o Voice Gateway passa o destino de transferência que é especificado no atributo transferTarget para a âncora de chamada na mensagem BYE. O campo de cabeçalho que contém o destino de transferência é determinado pelo atributo transferTargetHeader. Se o atributo transferTargetHeader não for especificado, o Voice Gateway utilizará Transfer-Target. Se o atributo transferMethod não for incluído ao configurar a ação de transferência de chamada, o vgwActTransfer utilizará o método REFER por padrão.

{
  "output": {
     "vgwAction": {
      "command": "vgwActTransfer", "parameters": {
        "transferTarget": "tel:18883334444",
        "transferTargetHeader": "Transfer-Target",
        "transferMethod": "HANGUP"
      }
    }
  }
}

Transferência em uma falha

Será possível configurar o voice gateway para transferir automaticamente uma chamada para um terminal estático se ocorrer uma falha. As falhas poderão ocorrer, por exemplo, se o voice gateway perder a conectividade com um dos serviços Watson configurados.

As variáveis de estado a seguir podem ser configuradas no primeiro turno da conversa e serão usadas se ocorrer uma falha durante a chamada. Consulte Definindo ações e estados.

Tabela 1. Variáveis de estado para transferência em caso de falha
Nome da variável de estado	Valor esperado	Valor padrão	Descrição
vgwTransferFailedMessage	Cadeia de texto	-	Se `vgwDisconnectCallOnTransferFailure` estiver configurado como `Yes`, a mensagem será transmitida para o responsável pela chamada se a transferência de chamada falhar. Deve ser configurado pelo Watson Assistant na primeira vez.
vgwConversationFailedMessage	Cadeia de texto	-	Mensagem transmitida para o responsável pela chamada caso o Watson Assistant falhe. Deve ser configurado pelo Watson Assistant na primeira vez.

Por exemplo, a variável de estado a seguir indica ao Voice Gateway que iniciar nessa resposta do nó, se uma transferência de chamada falhar, o vgwTransferFailedMessage será transmitido para o responsável pela chamada antes de terminar a chamada.

{
  "context": {
    "vgwDisconnectCallOnTransferFailure": "Yes",
    "vgwTransferFailedMessage": "Call transfer to an agent failed. Tente novamente mais tarde. Good bye. "
  }
}

Se o Voice Gateway não puder contatar o Watson Assistant, as variáveis de ambiente de configuração a seguir podem ser usadas para forçar uma transferência para um número de telefone estático.

Tabela 2. Variáveis de ambiente para transferência para um número de telefone estático
Variáveis de ambiente	Valor padrão	Descrição
CONVERSATION_FAILED_REPLY_MESSAGE	Chamada sendo transferida para um agente em razão de um problema técnico. Até logo.	Mensagem transmitida para o responsável pela chamada caso o Watson Assistant falhe
TRANSFER_DEFAULT_TARGET	Nenhum	Identifica a transferência de destino para o terminal. Deve ser um SIP válido ou um URI de tel. (por exemplo, sip:10.10.10.10). Esse é um destino de transferência padrão. Usado somente quando ocorre uma falha e o destino da transferência de chamada não pode ser obtido da API do Watson Assistant
TRANSFER_FAILED_REPLY_MESSAGE	A transferência de chamada para um agente falhou. Tente novamente mais tarde. Até logo.	Se `DISCONNECT_CALL_ON_TRANSFER_FAILURE` estiver configurado como `True`, a mensagem será transmitida para o responsável pela chamada se a transferência de chamada falhar.

Configurando o Voice Gateway para processar códigos de erro como respostas bem-sucedidas.

Quando o Voice Gateway processa uma solicitação SIP NOTIFY durante uma transferência de chamada, o processo de transferência falhará se o código de resposta especificado em uma solicitação NOTIFY não estiver no intervalo [200-299]. Alguns sistemas IVR podem enviar um código de erro em uma solicitação NOTIFY mesmo que a transferência tenha sido bem-sucedida. É possível configurar uma lista de códigos de erro que o Voice Gateway manipula como respostas bem-sucedidas, com o atributo de configuração ACCEPT_TRANSFER_REJECT_CODES ou com o atributo vgwActTransfer, acceptTransferRejectCodes.

No exemplo de atributo de configuração a seguir, se uma solicitação NOTIFY contiver códigos de erro 410 ou 500, o Voice Gateway processará a solicitação NOTIFY como uma solicitação bem-sucedida e continuará com o processo de transferência.

ACCEPT_TRANSFER_REJECT_CODES=410,500

É possível usar o atributo acceptTransferRejectCodes na ação vgwActTransfer para especificar a lista de códigos de erro que foram tratados como respostas bem-sucedidas ao processar solicitações NOTIFY. O exemplo a seguir mostra como usar a ação vgwActTransfer para configurar o Voice Gateway para processar uma solicitação NOTIFY, que contém códigos de erro 410 ou 500 como uma solicitação bem-sucedida.

{
"command": "vgwActTransfer", "parameters": {
"transferTarget": "tel:999",
"acceptTransferRejectCodes": "410,500"
}
}

Enviando dados de User-to-User Information (UUI) em transferências de chamada

O Voice Gateway pode enviar dados de User-to-User Information (UUI) em uma mensagem SIP REFER, uma solicitação SIP BYE ou uma solicitação SIP INFO.

Quando o Voice Gateway transfere uma chamada, ele pode enviar dados de UUI na mensagem SIP REFER. Na Versão 1.0.0.4c e mais recente, o Voice Gateway suporta os campos de cabeçalho a seguir para enviar dados de UUI em uma solicitação REFER:

Usuário para Usuário
Contato
Consulte

Se você transferir uma chamada usando uma solicitação SIP BYE, os dados de UUI serão enviados em um campo de cabeçalho User-to-User na Versão 1.0.0.7 e mais recente.

Enviando dados de UUI em uma solicitação SIP BYE ou SIP REFER

É possível customizar o cabeçalho que o Voice Gateway usa para enviar os dados de UUI usando os atributos uuiData e uuiSendMethod na ação vgwActTransfer para solicitações SIP BYE ou SIP REFER. Para configurar o campo de cabeçalho, configure o atributo uuiSendMethod para uuiHeader, contactHeader ou referToURL. Se nenhum valor for fornecido para o atributo uuiSendMethod, os dados serão enviados no campo de cabeçalho User-to-User por padrão. Veja Tags de ação.

{
  "output": {
    "vgwAction": {
      "command": "vgwActTransfer", "parameters": {
        "transferTarget": "sip:+18883334444@example.com",
        "uuiData": "59a390f3d2b7310023a2;encoding=hex;purpose=abc;content=123",
        "uuiSendMethod": "contactHeader"
      }
    }
  }
}

Enviando dados de UUI em uma solicitação SIP INFO

Ao transferir uma chamada, o Voice Gateway pode enviar dados de UUI em solicitações SIP REFER ou BYE. Alguns Controladores de borda de sessão não suportam essas opções e esperam que os dados de UUI sejam fornecidos em uma solicitação SIP INFO. É possível usar o vgwActSendSIPInfo para enviar uma solicitação SIP INFO com dados de UUI e conteúdo customizado antes de transferir ou desconectar uma chamada. Versões 1.0.0.8 e mais recente.

Configure o atributo sipHeaders com pares de nomes e valores do cabeçalho SIP para incluir na solicitação SIP INFO. Não inclua os campos de cabeçalho do sistema na lista, como De, Para, Contato, etc. Forneça campos de cabeçalho bem conhecidos no formato correto para evitar problemas de análise. Os cabeçalhos malformados não são incluídos na mensagem.

É possível, opcionalmente, configurar o atributo messageBody para incluir quaisquer informações adicionais. O messageBody é um corpo anexado à solicitação SIP INFO. Para incluir um messageBody, inclua o cabeçalho obrigatório, Content-Type, na lista sipHeaders. Se Content-Type não for incluído, um valor padrão de application/text será inserido.

{
  "output": {
    "command": "vgwActSendSIPInfo",
    "parameters": {
            "sipHeaders": {
              "Content-Type": "multipart/mixed;boundary=unique-boundary-1"
            },
            "messageBody": "--unique-boundary-1\r\nContent-Type: application/dtmf-relay\r\nSignal=999#\r\nDuration=250\r\n--unique-boundary-1--"
          }
        }
}

Depois de enviar a solicitação SIP INFO, o Voice Gateway aguarda a parte remota responder na solicitação SIP INFO antes de continuar com as ações restantes na lista. Se ocorre uma falha quando o Voice Gateway envia a solicitação SIP INFO, o Voice Gateway inicia imediatamente um turno para o SOE com o texto vgwSIPInfoFailed. A variável de estado vgwSIPFailureReason contém a razão da falha.

O exemplo a seguir mostra o formato da variável de estado vgwSIPFailureReason depois que a parte remota não respondeu a uma solicitação SIP INFO, incluindo o motivo pelo qual a solicitação falhou.

{
  "vgwSIPFailureReason": {
    "sipMessage": "INFO",
    "failureReason": "A 400 Bad Request error response message was received"
  }
}

Enviando dados de User-to-User Information com variáveis de estado

Também é possível configurar as variáveis de estado a seguir no diálogo do Watson Assistant. Se você definir essas variáveis de estado e, em seguida, definir valores diferentes para os atributos da ação de transferência, os valores na ação terão precedência.

Tabela 3. Variáveis de estado para envio de dados de UUI em mensagens REFER de saída
Nome da variável de estado	Valor esperado	Valor padrão	Descrição
`vgwUUIData`	Definido pelo usuário	-	Define os dados de User-to-User Information (UUI) a serem enviados em uma mensagem SIP REFER de saída durante uma transferência. Versão 1.0.0.4c e mais recente.
`vgwUUISendMethod`	`uuiHeader` / `contactHeader` / `referToURL`	-	O método pelo qual os dados de User-to-User Information (UUI) são enviados. Por padrão, os dados de UUI são enviados no campo de cabeçalho `User-to-User`. Versão 1.0.0.4c e mais recente.

O Voice Gateway codifica os dados de UUI de acordo com o valor e o método de envio. Se você enviar os dados de UUI nos campos de cabeçalho Contato ou Consulte, os dados serão codificados como um cabeçalho de URI. Se o cabeçalho Consulte for uma URL tel, os dados de UUI serão enviados como um parâmetro de URL. Por exemplo, os dados de UUI no exemplo anterior são enviados no cabeçalho Contato e codificados conforme mostrado:

Contact: <sip:+18883334444@example.com?User-to-User=59a390f3d2b7310023a2%3Bencoding%3Dhex%3Bpurpose%3Dabc%3Bcontent%3D123>

Problema conhecido: os dados de UUI não podem ser codificados em uma URL tel. Como solução alternativa, forneça o valor já codificado para os dados de UUI.

Em versões anteriores à 1.0.0.4c, é possível configurar as variáveis de estado a seguir no diálogo do Watson Assistant para informar o voice gateway do cabeçalho customizado para configurar na mensagem REFER de saída. Observe que, ao usar essas variáveis, os dados de UUI especificados na propriedade vgwTransferHeaderVal não serão codificados.

Tabela 4. Variáveis de estado para cabeçalhos customizados em mensagens REFER de saída
Nome da variável de estado	Valor esperado	Valor padrão	Descrição
`vgwTransferHeader`	Definido pelo usuário	-	Define um campo de cabeçalho customizado em uma mensagem SIP REFER de saída durante uma transferência. O valor do cabeçalho customizado é definido pela variável de estado `vgwSIPTransferHeaderVal`.
`vgwTransferHeaderVal`	Definido pelo usuário	-	Define o valor de um cabeçalho customizado em uma mensagem SIP REFER de saída durante uma transferência. O campo de cabeçalho customizado é definido pela variável de estado `vgwTransferHeader`.

Chamadas de rastreamento passando GUIDs

Os sistemas de telefonia corporativos podem ser configurados para incluir um ID globalmente exclusivo (GUID) como um cabeçalho Usuário para Usuário em chamadas SIP recebidas. O GUID é usado para rastrear uma chamada durante seu tempo de vida na rede corporativa. O voice gateway pode ser configurado para extrair o GUID do convite SIP inicial e passar o mesmo GUID como um cabeçalho em uma mensagem REFER subsequente. A passagem do GUID assegura que uma chamada possa ser adequadamente rastreada à medida que é propagada para um agente da central de contato.

A variável de ambiente de configuração CUSTOM_SIP_INVITE_HEADER identifica o cabeçalho customizado que é retirado da mensagem SIP INVITE inicial que estabelece a chamada. Quando você especifica essa variável de ambiente, o cabeçalho SIP especificado é passado para o Watson Assistant na variável de estado vgwSIPCustomInviteHeader.

Para configurar o cabeçalho customizado na mensagem REFER de saída, você pode utilizar as tags de ação e variáveis de estado de dados de UUI ou as variáveis de estado do cabeçalho de transferência customizado, conforme descrito na seção anterior.