You are viewing the Portuguese (Brazil) site, but your language preference is set to English. Switch to English site →

Menu

Expand
Classifique esta página:

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 <Refer> é compatível somente com trechos de chamada SIP porque o método REFER (ENCAMINHAR) é um recurso específico do SIP. Tipos de trechos diferentes de SIP, como RPTC e chamadas do Twilio Client não são compatíveis e resultarão em um erro. Para obter mais informações sobre o que constitui um trecho de chamada SIP, consulte Understanding Call Legs (Entendendo os trechos de chamada) abaixo.

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

PV SIP Call Transfer - SIP REFER Example

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>.

Loading Code Sample...
        
        

        Basic Refer example

        Atributos do <Refer>:

        Nome do atributo Valores permitidos Valor padrão
        action (ação) URL relativo ou absoluto Nenhum
        method GET, POST POST

        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.

        Loading Code Sample...
              
              

              Refer with action URL

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

              Parâmetro Descrição

              ReferCallStatus

              Semelhante ao parâmetro CallStatus, ele fornece ao aplicativo nossa compreensão (com base nas mensagens NOTIFY (NOTIFICAR) do SIP) do status da nova chamada criada em resposta a REFER (ENCAMINHAR). Se REFER (ENCAMINHAR) falha ou o endpoint não envia nenhuma solicitação NOTIFY (NOTIFICAR), esse parâmetro será omitido.

              ReferSipResponseCode

              O código de resposta do SIP recebido em resposta à solicitação REFER (ENCAMINHAR) da Twilio é enviado ao endpoint do SIP.

              NotifySipResponseCode

              Esse é o último código de resposta do SIP recebido no trecho encaminhado, conforme determinado pela análise das mensagens NOTIFY (NOTIFICAR) do SIP. Por exemplo, se o endpoint do SIP iniciou uma nova chamada, mas recebeu uma resposta SIP 404 devido ao destino não ter sido encontrado, esse parâmetro seria definido como "404". Se REFER (ENCAMINHAR) falha ou o endpoint não envia nenhuma solicitação NOTIFY (NOTIFICAR), esse parâmetro será omitido.

              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.

              Pic1

              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:

              Pic2

              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).

              Loading Code Sample...
                    
                    

                    Refer with SIP Headers

                    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.

                    Loading Code Sample...
                          
                          
                          Passagem do cabeçalho padrão usuário a usuário SIP, que é compatível com alguns equipamentos de call center

                          Refer with SIP User-to-User Header

                          Passagem do cabeçalho padrão usuário a usuário SIP, que é compatível com alguns equipamentos de call center

                          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
                          Classifique esta página:

                          Precisa de ajuda?

                          Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.

                          Loading Code Sample...
                                
                                
                                

                                Obrigado pelo seu feedback!

                                Selecione o(s) motivo(s) para seu feedback. As informações adicionais que você fornece nos ajudam a melhorar nossa documentação:

                                Enviando seu feedback...
                                🎉 Obrigado pelo seu feedback!
                                Algo deu errado. Tente novamente.

                                Obrigado pelo seu feedback!

                                thanks-feedback-gif