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

Loading Code Sample...
        
        

        Use o substantivo <Sip>

        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:

        Loading Code Sample...
              
              

              Autenticação com seu <Sip>

              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:

              Loading Code Sample...
                    
                    

                    Cabeçalhos personalizados com <Sip>

                    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:

                    Loading Code Sample...
                          
                          

                          Transporte com <Sip>

                          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.

                          Loading Code Sample...
                                
                                

                                Transporte TLS com <Sip>

                                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:

                                Diagrama de eventos de discagem de chamada outbound

                                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.

                                Loading Code Sample...
                                      
                                      

                                      Dialing to a SIP endpoint

                                      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.

                                      Loading Code Sample...
                                            
                                            

                                            Dial a SIP endpoint, protected by authentication

                                            Exemplo 3: Passar cabeçalhos

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

                                            Loading Code Sample...
                                                  
                                                  

                                                  Passing headers

                                                  Exemplo 4: Discagem com vários atributos

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

                                                  Loading Code Sample...
                                                        
                                                        

                                                        Dial with several attributes

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

                                                        Loading Code Sample...
                                                              
                                                              

                                                              Call Progress Events

                                                              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.

                                                              Loading Code Sample...
                                                                    
                                                                    

                                                                    Parallel calling

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

                                                                    Loading Code Sample...
                                                                          
                                                                          

                                                                          Serial calling

                                                                          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