TwiML™ Voice: <Number>
<Number> é um substantivo para o verbo do TwiML <Dial> e especifica um número de telefone para discar. Usando os atributos do substantivo, você pode especificar comportamentos específicos que a Twilio deve aplicar ao discar o número.
Você pode usar até dez substantivos <Number> dentro de um verbo <Dial> para chamar todos eles simultaneamente de uma só vez. A primeira chamada a ser atendida é conectada à chamada atual e o restante é desligado. Para cada substantivo <Number>, você pode especificar para quais eventos de progresso de chamada deseja receber webhooks.
Atributos do substantivo
O substantivo <Number> dá suporte aos seguintes atributos que modificam seu comportamento:
| Nome do atributo | Valores permitidos | Valor padrão |
|---|---|---|
| sendDigits | Qualquer dígito | Nenhum |
| url | URL absoluto ou relativo | Nenhum |
| method | GET, POST |
POST |
| byoc | BYOC Trunk SID | Nenhum |
| statusCallbackEvent | initiated, ringing, answered, completed |
completed |
| statusCallback | Qualquer URL | Nenhum |
| statusCallbackMethod | GET, POST |
POST |
Os números de telefone devem ser formatados com um + e o código do país, por exemplo: +16175551212 (E.164 format). A Twilio também aceitará números dos EUA não formatados; por exemplo, (415) 555-1212 ou 415-555-1212.
sendDigits
O atributo sendDigits diz à Twilio para reproduzir tons DTMF quando a chamada for atendida. Isso é útil ao discar um número de telefone e um ramal. A Twilio discará o número e, quando o sistema automatizado atender, enviará os tons DTMF para se conectar ao ramal.
url
O atributo url permite especificar um URL que retornará uma resposta do TwiML a ser executada no final da parte chamada, depois que ela responder, mas antes que as partes estejam conectadas.
Você pode usar este TwiML para obter informações privadas sobre <Play> ou <Say> do destinatário chamado. Você também pode dar a chance de recusar a chamada telefônica usando <Gather> e <Hangup>. O atributo url não suporta nenhum outro verbo do TwiML.
Se o atributo answerOnBridge for usado em <Dial>, o autor da chamada atual continuará a ouvir o toque enquanto o documento do TwiML é executado na outra extremidade. Os documentos TwiML executados desta maneira não podem conter o verbo <Dial>.
method
O atributo method permite especificar qual método HTTP a Twilio deve utilizar ao solicitar o URL no atributo url. O padrão é POST.
byoc
O atributo byoc permite especificar qual cliente configurado BYOC Trunk a Twilio deve usar para encaminhar a chamada para a RPTC. O padrão é nenhum, caso em que a chamada será roteada por meio do Twilio Super Network.
statusCallbackEvent
Ao discar para número usando <Dial>, uma chamada outbound é iniciada. A chamada passa 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 para uma determinada chamada: initiated, ringing, answered ou completed. URLs não relacionados devem conter um nome de host válido (sublinhados não são permitidos).
O atributo statusCallbackEvent permite especificar em quais eventos a Twilio deve acionar um 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 retorno 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.
statusCallbackMethod
O atributo statusCallbackMethod permite que você especifique qual método HTTP a Twilio deve usar ao solicitar o URL no atributo statusCallback. O padrão é POST.
Status dos parâmetros HTTP de retorno de chamada
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 a Twilio recebe uma chamada para um dos seus números da Twilio. A lista completa de parâmetros e descrições de cada um está na documentação [Solicitação do TwiML Voice][solicitação de voz].
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 de gravação precisa final após qualquer corte de silêncio, use recordingStatusCallback. |
| Carimbo de data/hora | O carimbo de data/hora em que o evento foi disparado, fornecido 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. |
Exemplos
Exemplo 1: Uso do sendDigits
Nesse caso, queremos discar a extensão 1928 em 415-123-4567. Utilizamos um substantivo <Number> para descrever o número de telefone e dar a ele o atributo
sendDigits. Queremos esperar antes de enviar a extensão; por isso, acrescentamos alguns caracteres w à esquerda. Cada w diz à Twilio que aguarde meio segundo em vez de tocar um dígito. Isso permite ajustar o tempo de quando os dígitos começam a ser reproduzidos de acordo com o sistema telefônico que você está discando.
Exemplo 2: Discagem simultânea
Nesse caso, usamos várias tags <Number> para discar três números de telefone ao mesmo tempo. A primeira dessas chamadas a serem atendidas será conectada ao autor da chamada atual, enquanto o restante das tentativas de conexão serão canceladas.
Exemplo 3: Eventos de progresso da chamada
Nesse caso, queremos receber um webhook para cada evento de progresso da chamada ao discar um número usando o comando <Dial>.
Exemplo 4: Discagem múltipla com eventos de progresso de chamada
Nesse caso, queremos receber um webhook para cada evento de progresso de chamada para cada número ao discar vários números usando o comando <Dial>.
Exemplo 5: Execução do TwiML antes que as partes estejam conectadas
Nesse caso, queremos conectar duas partes usando o comando <Dial>, mas também queremos que as instruções do TwiML sejam enviadas para a parte para a qual estamos ligando antes de serem conectadas à chamada. Ao definir o atributo url, podemos especificar um URL que retornará uma resposta do TwiML a ser executada no final da parte chamada. Este TwiML será executado após a resposta, mas antes que as partes estejam conectadas.
Dicas e usos avançados
- Você pode especificar até dez números dentro de um verbo
<Dial>para discar simultaneamente. - A discagem simultânea é útil quando você tem vários telefones (ou várias pessoas) que deseja que toquem ao receber uma chamada. Lembre‐se de que a primeira chamada conectada cancelará todas as outras tentativas. Se você discar um sistema de telefone do escritório ou um celular no modo avião, ele poderá atender após um único toque, evitando que os outros números de telefone toquem o suficiente para que um ser humano atenda. Portanto, você deve tomar cuidado para usar a discagem simultânea apenas em situações em que você conhece o comportamento das partes chamadas.
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.
