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>
Região | Localização |
---|---|
us1 | América do Norte Virgínia |
us2 | América do Norte Oregon |
ie1 | Europa Irlanda |
de1 | Europa Frankfurt |
sg1 | Ásia-Pacífico Cingapura |
jp1 | Ásia-Pacífico Tóquio |
br1 | América do Sul São Paulo |
au1 | Ásia-Pacífico Sydney |
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>
.
Nome do atributo | Valores |
---|---|
nome de usuário | Nome de usuário para autenticação SIP |
senha | Senha para autenticação 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&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&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âmetro | Valores |
---|---|
Chamado | Para o cabeçalho da mensagem de convite SIP. O identificador SIP da parte chamada. |
Autor da chamada | Do cabeçalho da mensagem de convite SIP. O identificador SIP da parte que iniciou a chamada. |
SipCallId | O cabeçalho de identificação de chamada SIP da solicitação feita à infraestrutura SIP remota. |
SipDomain | A parte do host da solicitação SIP. |
SipDomainSid | Seu ID de domínio SIP. Tem 34 caracteres e sempre começa com as letras SD . |
SipHeader_ | O nome/valor de qualquer cabeçalho X retornado na resposta 200 à solicitação SIP INVITE. Isso é aplicável somente se você estiver usando SIP cabeçalhos personalizados. |
SipSourceIp | Endereço IP de origem para sinalização SIP. |
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:
Parâmetro | Valores |
---|---|
DialSipCallId | O cabeçalho de ID de chamada SIP da solicitação feita à infraestrutura SIP remota. |
DialSipResponseCode | O código de resposta SIP como resultado da tentativa de INVITE. |
DialSipHeader_ |
O nome/valor de qualquer cabeçalho X retornado na resposta final à solicitação SIP INVITE. |
<Sip>
Atributos
O substantivo <Sip>
dá suporte aos seguintes atributos que modificam seu comportamento:
Nome do atributo | Valores permitidos | Valor padrão |
---|---|---|
método | GET , POST |
POST |
[senha][autenticação] | Senha para autenticação SIP | |
statusCallbackEvent | initiated , ringing , answered , completed |
nenhum |
statusCallback | qualquer URL | nenhum |
statusCallbackMethod | GET , POST |
POST |
url | url de triagem de chamada | nenhum |
[nome de usuário][autenticação] | Nome de usuário para autenticação SIP |
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:
Evento | Descrição |
---|---|
initiated | O evento initiated é acionado quando a Twilio começa a discar a chamada. |
ringing | O evento ringing é acionado quando a chamada começa a tocar. |
answered | O evento answered é acionado quando a chamada é atendida. |
completed | O evento completed é acionado quando a chamada é concluída, independentemente do status de encerramento: busy , canceled , completed , failed ou no-answer . Se nenhum StatusCallbackEvent for especificado, completed será acionado por padrão. |
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:
Parâmetro | Descrição |
---|---|
CallSid | Um identificador exclusivo para esta chamada, gerado pela Twilio. Você pode usar o CallSid para modificar a chamada secundária POSTing to Calls/{CallSid} com um novo URL TwiML. |
ParentCallSid | Um identificador exclusivo para a chamada principal. |
CallStatus | Um status descritivo para a chamada. O valor pode ser um desses: queued , initiated , ringing , in-progress , busy , failed ou no-answer . Consulte a seção CallStatus para mais detalhes. |
CallDuration | A duração em segundos da chamada recém‐concluída. Presente apenas no evento completed . |
RecordingUrl | A URL do áudio gravado da chamada telefônica. Este parâmetro só é incluído se a gravação estiver definida em <Dial> e não incluir as gravações iniciadas de outras maneiras. RecordingUrl está presente apenas no evento completed . |
RecordingSid | A ID exclusiva da [Gravação][gravações] desta chamada. RecordingSid está presente apenas no evento completed . |
RecordingDuration | A duração do áudio gravado (em segundos). RecordingDuration está presente apenas no evento completed . Para obter uma duração final da gravação precisa após qualquer corte de silêncio, use recordingStatusCallback. |
Carimbo de data e hora | O carimbo de data/hora quando o evento foi acionado, dado como UTC no formato RFC 2822. |
CallbackSource | Uma string que descreve a origem do webhook. Isso é fornecido para ajudar a desambiguar por que o webhook foi criado. Em retornos de chamada de status, esse valor é sempre call-progress-events . |
SequenceNumber | A ordem em que os eventos foram acionados, começando em '0'. Embora os eventos sejam disparados em ordem, eles são feitos como solicitações HTTP separadas e não há garantia de que eles chegarão na mesma ordem. |
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>
.
Para usar o recurso SIP Chamada paralela da Twilio, você deve ativar "Enhanced Programmable SIP Features" em suas configurações do Voice no console.
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.
Para usar o recurso SIP Chamada em série Twilio, você deve ativar "Enhanced Programmable SIP Features" em suas configurações do Voice no console.
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á.
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.