TwiML™ Voice: <Refer>

Durante uma chamada SIP programável, o verbo <Refer> do TwiML instrui a Twilio a iniciar um SIP Refer (ou seja, transferências) em direção a uma infraestrutura SIP e lida com qualquer mensagem de NOTIFY (NOTIFICAR). Você também pode invocar o verbo usando a API REST.

O verbo <Refer> pode ser invocado em chamadas SIP inbound e outbound. Por exemplo, em uma chamada SIP inbound para um Domínio SIP da Twilio, você pode desejar transferir o autor da chamada de volta para sua infraestrutura SIP interna ou legada. Ao iniciar o verbo <Refer>, a Twilio instrui seu dispositivo SIP a iniciar uma nova chamada para o sistema externo e a substituir o trecho da Twilio por essa nova chamada.

Você pode inciar um <Refer> em qualquer ponto da duração de uma chamada. Por exemplo, com uma chamada SIP outbound criada pelo <Sip> substantivo ou pela API REST da Twilio para um Domínio SIP, pode ser usada a qualquer momento para transferir o autor da chamada de volta para sua infraestrutura SIP interna ou herdada. Ao iniciar o verbo <Refer>, a Twilio instrui seu dispositivo SIP a iniciar uma nova chamada para o sistema externo e a substituir o trecho da Twilio por essa nova chamada.

O exemplo abaixo mostra <Refer> estabelecido em um segmento de chamada inbound:

Uma vez iniciado, o verbo <Refer> gerará uma mensagem REFER (ENCAMINHAR) do SIP com o URI SIP de destino especificado usando o substantivo <Sip>. Se o endpoint SIP aceitar a solicitação de REFER (ENCAMINHAR), a Twilio ouvirá as mensagens NOTIFY (NOTIFICAR) do SIP do endpoint para monitorar o estado da nova chamada iniciada em resposta ao REFER (ENCAMINHAR). A Twilio relatará esses parâmetros de volta ao seu aplicativo como parâmetros para o URL de ação, se especificado.

O exemplo a seguir mostra o uso mais básico do <Refer>.

Atributos do <Refer>:

action (ação)

O atributo action aceita um URL como seu argumento. Esse URL informa à Twilio onde fazer uma solicitação POST ou GET depois que o verbo <Refer> termina a execução.

A solicitação da Twilio para esse URL pode incluir os seguintes parâmetros adicionais:

Observe que apenas parâmetros específicos do <Refer> são listados aqui. A Twilio também enviará os parâmetros padrão do TwiML Voice na solicitação.

Para ilustrar ainda mais como os parâmetros <Refer> funcionam, fornecemos alguns exemplos de cenários:

1. A Twilio emite um REFER (ENCAMINHAR) e o endpoint do SIP inicia com sucesso uma nova chamada para o destino da transferência:
   
   • ReferCallStatus: "in-progress"
   • ReferSipResponseCode: "202"
   • NotifySipResponseCode: "200"
2. A Twilio emite um REFER (ENCAMINHAR), e o endpoint do SIP inicia uma nova chamada para o destino da transferência. No entanto, a nova chamada falha com um erro:
   
   • ReferCallStatus: "busy" (ou "failed" dependendo do valor de NotifySipResponseCode)
   • ReferSipResponseCode: "202"
   • NotifySipResponseCode: "486"
3. A Twilio emite um REFER (ENCAMINHAR) e o endpoint do SIP responde ao REFER (ENCAMINHAR) com um erro:
   
   • ReferCallStatus: "failed"
   • ReferSipResponseCode: "405"
4. O autor da chamada desliga antes que a transação <Refer> seja concluída:
   • ReferCallStatus: "canceled"
   • ReferSipResponseCode: "202"
   • NotifySipResponseCode: "180"

método

O atributo method aceita GET ou POST. Isso informa a Twilio se deve solicitar o URL action por meio do HTTP GET ou POST, sendo POST o valor padrão.

Entendendo os trechos de chamada

Como <Refer> é um recurso específico do SIP, ele só pode ser usado em trechos de chamada SIP. No cenário típico de URA, haverá apenas um trecho de chamada único de/para a Twilio, como uma chamada inbound para um número de telefone Twilio ou domínio SIP, ou uma chamada outbound iniciada pela API REST da Twilio. Nesses casos, desde que a chamada seja entre a Twilio e um dispositivo SIP, <Refer> pode ser usado. Portanto, as chamadas com SIDs CAaaaa e CAbbbb são trechos de chamada SIP em que o verbo <Refer> é permitido.

Em um cenário de chamada em ponte, como ao usar o <Dial> verbo, pode haver dois trechos com a Twilio, conforme demonstrado no cenário abaixo:

No fluxo de chamadas acima, a chamada com SID CAdddd é um trecho de chamada SIP em que o verbo <Refer> é permitido. Invocar <Refer> em CAcccc resultaria em erro.

Contexto de aprovação via cabeçalhos SIP

Ao usar <Refer> para transferir um autor da chamada entre sistemas internos independentes, pode haver um desejo de transmitir informações contextuais sobre a chamada. Por exemplo, se você estiver criando uma URA na Twilio que coleta o número da conta de um cliente e o motivo para ligar antes de transferir a chamada para um call center, é provável que você queira passar as informações da conta capturadas pela URA para o sistema do call center. Essas informações contextuais geralmente são passadas em cabeçalhos SIP.

A Twilio permite especificar qualquer URI SIP válido no substantivo <Sip> para ser usado no alvo REFER (ENCAMINHAR). O mecanismo SIP padrão para especificar cabeçalhos em um URI SIP pode ser usado, presumindo que seu endpoint ou dispositivo respeite os cabeçalhos no URI de destino ao seguir o REFER (ENCAMINHAR).

Qualquer cabeçalho SIP permitido pode ser passado no URI, desde que seu endpoint ou dispositivo seja compatível com o carimbo do cabeçalho.

Monitoramento do status das chamadas encaminhadas usando o URL da ação

Quando os endpoints SIP recebem uma solicitação REFER (ENCAMINHAR), eles iniciam uma nova chamada para o URI SIP de destino especificado na solicitação. A transferência geralmente não é concluída até que a nova chamada seja totalmente estabelecida. A maioria dos endpoints SIP fornece feedback sobre o andamento da nova chamada para o transferidor por meio do mecanismo NOTIFY (NOTIFICAR) do SIP. Se a transferência falhar, o endpoint do SIP normalmente retomará a chamada original com o aplicativo da Twilio.

O verbo <Refer> inscreverá automaticamente e ouvirá as mensagens NOTIFY (NOTIFICAR) do SIP a partir do seu endpoint. O verbo aguardará uma mensagem de NOTIFY (NOTIFICAR) final indicando o sucesso ou a falha da chamada e continuará a chamada invocando o URL de ação especificado. Se o parâmetro de ação for omitido, a Twilio chamará o próximo verbo em seu documento TwiML. Se não houver mais verbos para processar, a chamada da Twilio será encerrada.

Com base nos parâmetros passados para o URL da ação, você pode retomar o tratamento da chamada de acordo se a transferência falhar (por exemplo, ReferCallStatus não está "in-progress").

O verbo <Refer> retornará quando ocorrer uma das seguintes circunstâncias:

1. A Twilio receber uma mensagem de NOTIFY (NOTIFICAR) do SIP indicando que a nova chamada recebeu um 200 OK ou uma resposta de erro
2. O endpoint do SIP termina ou atinge o tempo limite da inscrição de NOTIFY (NOTIFICAR)
3. A chamada para a Twilio está desligada