TwiML™ Voice: <Sip>

O substantivo <Sip> do verbo <Dial> permite que você configure sessões VoIP usando SIP -- Protocolo de iniciação de sessão. Com esse recurso, você pode enviar uma chamada para qualquer endpoint SIP. Configure seu TwiML para usar o substantivo <Sip> no verbo <Dial> sempre que qualquer um de seus números de telefone da Twilio for chamado. Se você não conhecer o SIP ou quiser mais informações sobre como a Twilio funciona com seu endpoint SIP, consulte a visão geral do SIP.

A sessão SIP

A mensagem SIP INVITE inclui a versão da API, o AccountSid e o CallSid para a chamada. Opcionalmente, você também pode fornecer um conjunto de parâmetros para gerenciar o transporte de sinalização e a autenticação ou configurar o Twilio para passar cabeçalhos SIP personalizados na mensagem INVITE: esse método inclui cabeçalhos como UUI (User-to-user Information, informações de usuário para usuário).

Quando a sessão SIP é concluída, a Twilio solicita a <Dial> URL de ação, passando o cabeçalho SIP CallID, o código de resposta da tentativa de convite, quaisquer cabeçalhos X retornados na resposta SIP final, bem como os parâmetros padrão do <Dial> da Twilio.

Se Enhanced Programmable SIP Features (Recursos SIP programáveis ​​aprimorados) não estiver ativado em sua conta, apenas um substantivo <Sip> pode ser especificado por <Dial>, e a mensagem INVITE pode ser enviada para apenas um endpoint SIP. Além disso, você não pode adicionar nenhum outro substantivo (por exemplo, <Number>, <Client>) no mesmo <Dial> do SIP. Se você quiser usar outro substantivo, configure um retorno de chamada no <Dial> para usar métodos alternativos.

O parâmetro region

Para especificar a região geográfica da qual a Twilio enviará tráfego de saída SIP para sua infraestrutura de comunicação, você deve incluir o parâmetro region em seu URI SIP. Por exemplo, se o parâmetro region=ie1 estiver incluído em seu URI SIP, o Twilio enviará o tráfego SIP da região Europa Irlanda:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:alice@example.com;region=ie1</Sip>
    </Dial>
</Response>

Se o parâmetro region não for especificado, a Twilio enviará tráfego de saída SIP da região da América do Norte, Virgínia.

Use o substantivo Sip

Todos os parâmetros existentes <Dial> funcionam com o substantivo <Sip> (record, timeout, hangupOnStar, etc). Para chamadas SIP, o atributo callerId não precisa ser um número de telefone validado. Insira qualquer string alfanumérica. Opcionalmente, inclua os seguintes caracteres: +-_., mas sem espaço em branco.

Dentro do substantivo <Sip>, você deve especificar um URI para a Twilio se conectar. O URI deve ser um URI SIP válido com menos de 255 caracteres. Por exemplo:

Autenticação

Envie atributos de nome de usuário e senha para autenticação em sua infraestrutura SIP como atributos no substantivo <Sip>.

Por exemplo:

Cabeçalhos personalizados

Envie cabeçalhos personalizados anexando-os ao URI SIP, exatamente como você passaria cabeçalhos em um URI sobre HTTP. Por exemplo:

Enquanto o próprio URI do SIP deva ter menos de 255 caracteres, os cabeçalhos devem ter menos de 1024 caracteres. Quaisquer cabeçalhos que comecem com o prefixo x- podem ser enviados desta forma.

Você também pode enviar vários parâmetros e valores como parte do cabeçalho x-

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:jack@example.com?x-customname=Madhu%2CMathiyalagan%3BTitle%3DManager&amp;x-myotherheader=bar</Sip>
    </Dial>
</Response>

O cabeçalho UUI (User-to-user Information, informações de usuário para usuário) pode ser enviado sem preceder x-

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Sip>sip:jack@example.com?User-to-User=123456789%3Bencoding%3Dhex&amp;x-myotherheader=bar</Sip>
    </Dial>
</Response>

Transporte

Defina um parâmetro em seu URI SIP para especificar qual protocolo de transporte você deseja usar. Atualmente, isso é limitado a UDP, TCP e TLS. Por padrão, a Twilio envia seu SIP INVITE por UDP. Altere isso usando o parâmetro de transporte:

Como alternativa, você pode personalizá‐lo para usar TLS para sinalização SIP. Ao usar o TLS, a porta padrão é a 5061. No entanto, uma porta diferente pode ser especificada.

Parâmetros de chamada <Sip>

Quando uma chamada SIP é atendida, a Twilio passa os seguintes parâmetros com sua solicitação, além do TwiML padrão [Parâmetros de solicitação de voz][parâmetros de solicitação]:

Parâmetros adicionais

Quando você invoca o atributo ação de discagem e <Sip>, a Twilio passa os seguintes parâmetros com sua solicitação, além dos parâmetros padrão ação de discagem. Use os parâmetros de retorno de chamada de ação para modificar seu aplicativo com base nos resultados da tentativa de discagem SIP:

<Sip> Atributos

O substantivo <Sip> dá suporte aos seguintes atributos que modificam seu comportamento:

url

O atributo url permite que você especifique uma url para um documento TwiML que é executado no terminal da parte chamada, depois de responder, mas antes que as duas partes estejam conectadas. Você pode usar este TwiML para <Play> ou <Say> informações privadamente à pessoa chamada, ou fornecer a chance de recusar a chamada telefônica usando <Gather> e <Hangup>. Se o atributo answerOnBridge for usado em <Dial>, o autor da chamada atual continuará a ouvir o toque enquanto o documento TwiML é executado no outro lado. Os documentos TwiML executados desta maneira não podem conter o verbo <Dial>.

method

O atributo method permite que você especifique qual método HTTP a Twilio deve usar ao solicitar o URL especificado no atributo url. O padrão é POST.

statusCallbackEvent

Ao discar para número usando <Dial>, uma chamada outbound é iniciada. A chamada muda do estado initiated para o estado ringing quando o telefone começa a tocar. Ele muda para o estado answered quando a chamada é atendida e, finalmente, para o estado completed quando a chamada termina. Com statusCallbackEvent, você pode se inscrever para receber webhooks para os diferentes eventos de progresso de chamadas: initiated, ringing, answered ou completed para uma determinada chamada.

O atributo statusCallbackEvent permite especificar em quais eventos a Twilio deve fazer o webhook. Para especificar vários eventos, separe‐os com um espaço: initiated ringing answered completed. Se um statusCallback for fornecido e nenhum evento de retornos de chamada de status for especificado, o evento completed será enviado por padrão.

Em vez de criar uma chamada outbound por meio da API, as chamadas outbound criadas usando <Dial> são iniciadas imediatamente e nunca enfileiradas. A seguir, vemos uma linha do tempo de possíveis eventos de chamada que podem ser retornados e os diferentes status de chamada que um trecho <Dial> pode enfrentar:

statusCallback

O atributo statusCallback permite que você especifique um URL para a Twilio enviar solicitações de webhook para cada evento especificado no atributo statusCallbackEvent . URLs não relacionados devem conter um nome de host válido (sublinhados não são permitidos).

Os parâmetros que a Twilio passa para seu aplicativo em sua solicitação assíncrona para o URL StatusCallback incluem todos os parâmetros passados em uma solicitação síncrona para recuperar o TwiML quando o Twilio recebe uma chamada para um de seus números do Twilio. A lista completa de os parâmetros e as descrições de cada um estão na documentação TwiML Voice Request.

Quando os eventos de andamento da chamada são acionados, a solicitação de retorno de chamada de status também passa por esses parâmetros adicionais:

statusCallbackMethod

O atributo statusCallbackMethod permite especificar qual método HTTP a Twilio deve usar ao solicitar o URL no atributo statusCallback O padrão é POST.

Exemplos

Exemplo 1: Discando para um endpoint SIP

Neste exemplo, queremos nos conectar a kate@example.com. Para ligar a chamada a Kate, , use um verbo <Dial> com um substantivo <Sip> aninhado dentro.

Exemplo 2: Discagem com um endpoint SIP, protegido por autenticação

Neste exemplo, você ainda está discando para Kate, mas precisa passar credenciais de autenticação para entrar em contato.

Exemplo 3: Passar cabeçalhos

Neste exemplo, passe cabeçalhos personalizados junto com o endereço SIP.

Exemplo 4: Discagem com vários atributos

Uma Discagem mais complexa, especificando configurações personalizadas como atributos em <Dial>, incluindo triagem de chamadas.

Exemplo 5: Eventos de progresso de chamada

Neste exemplo, queremos receber um webhook para cada evento de progresso de chamada ao discar para um endpoint SIP usando <Dial>.

Exemplo 6: Chamada paralela ou Discagem simultânea

A chamada paralela, também conhecida como discagem simultânea, é útil quando você desejar gerenciar vários telefones (ou várias pessoas) ao receber uma chamada. Digamos que você tenha vários endpoints diferentes nos quais pode atender uma chamada, como um telefone celular, telefone residencial, telefone do escritório e/ou softphone de PC. Este recurso permite que você chame até dez endpoints ao mesmo tempo, especificando um verbo <Dial> com vários destinos. Além disso, para cada endpoint, você pode especificar quais eventos de retorno de chamada de status para os quais deseja receber solicitações de webhook.

Além dos números de telefone e/ou identificadores do Twilio Client, agora você pode especificar URIs SIP para chamadas paralelas usando o substantivo <Sip> do verbo <Dial>.

Você pode misturar até dez substantivos <Sip>, <Number> ou <Client> diferentes dentro de um verbo de discagem para chamar simultaneamente.

Lembre‐se de que a primeira chamada conectada cancelará todas as outras tentativas. Se você discar para um sistema telefônico de escritório ou um telefone celular no modo avião, etc., esse endpoint pode atender após um único toque, impedindo que os demais endpoints toquem por tempo suficiente para que uma pessoa atenda. Portanto, você deve tomar cuidado para usar a discagem simultânea em situações em que você conhece o comportamento das partes chamadas.

Por exemplo, Alice tem três maneiras diferentes de contatá‐la usando SIP. Ela quer que você ligue para ela em seu softphone SIP, telefone de mesa SIP e Cliente Móvel SIP ao mesmo tempo, e ela atenderá um dependendo de onde ela estiver no momento da chamada.

Exemplo 7: Chamada em série ou discagem sequencial

A chamada em série, também conhecida como discagem sequencial, é útil quando você desejar gerenciar vários telefones (ou várias pessoas) ao receber uma chamada. Digamos que você tenha um grupo de agentes em um call center e desejar tentar cada um deles na ordem até que um atenda. Este recurso permite que você ligue para até dez agentes sequencialmente especificando um verbo <Dial> com vários destinos e configurando o atributo sequential para true. A prioridade das chamadas é baseada na ordem dentro do verbo <Dial>. Além disso, para cada endpoint, você pode especificar quais eventos de retorno de chamada de status deseja receber por meio de Webhooks.

Você pode misturar até dez substantivos <Sip>, <Number> ou <Client> diferentes dentro de um verbo <Dial> para chamar sequencialmente.

Lembre‐se de que a primeira chamada conectada cancelará todas as tentativas restantes na sequência. Se você discar para um sistema telefônico de escritório ou um telefone celular no modo avião, etc., esse endpoint pode atender após um único toque, impedindo que os endpoints restantes sejam chamados. Portanto, você deve tomar cuidado para usar a discagem sequencial em situações em que você conhece o comportamento das partes chamadas.

Para o exemplo abaixo, se Alice rejeitar ou não atender, a chamada irá para Bob. Da mesma forma, se Bob rejeitar ou não atender, a chamada irá para Charlie. Se Charlie não atender, a chamada falhará.