TwiML™ Voice: <Dial>
Durante uma chamada ativa, você pode usar o verbo <Dial> do TwiML para conectar o autor da chamada atual a outra pessoa.
O exemplo a seguir mostra o uso mais básico do <Dial>:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial>415-123-4567</Dial>
</Response>Se a pessoa em 415-123-4567 atender a chamada, as duas partes poderão se comunicar até que uma desligue.
O verbo <Dial> encerrará a nova chamada se:
- A pessoa chamada não atende.
- A Twilio recebe um sinal de ocupado.
- O número não existe.
O <Dial> não consegue iniciar uma chamada diretamente da Twilio; ele só discará para uma nova pessoa a partir de uma chamada ativa em andamento. Para iniciar uma nova chamada outbound na Twilio, você deve fazer uma solicitação na API para o endpoint da chamada.
Para obter um guia passo a passo sobre como fazer sua primeira chamada outbound com a Twilio, experimente um de nossos inícios rápidos que mostram como fazer uma chamada usando as bibliotecas auxiliares da Twilio.
A Twilio fará uma solicitação GET ou POST para o URL action (se fornecido) quando a chamada <Dial> terminar. O fluxo de chamadas continuará, usando o TwiML que você enviar em resposta a essa solicitação.
Se um URL action não for fornecido no <Dial> e o autor da chamada original ainda estiver na linha, a Twilio continuará a renderizar o documento TwiML original.
Com este código, a Twilio conecta a chamada original a uma nova pessoa discando 415-123-4567. Várias coisas podem acontecer:
- Se alguém atender, a Twilio conecta o autor da chamada com a pessoa chamada.
- Se o autor da chamada original desligar, a sessão da Twilio é encerrada e o
<Say>não é executado. - Se a linha estiver ocupada, se não houver resposta ou se a pessoa chamada desligar, o
<Dial>é encerrado e o autor da chamada inicial ouve o texto<Say>(“Goodbye”) antes de o fluxo da chamada ser encerrado.
Atributos do <Dial>
O <Dial> é compatível com os seguintes atributos que alteram seu comportamento:
| Atributo | Valores permitidos | Valor padrão |
|---|---|---|
| action | URL relativo ou absoluto | Nenhum |
| answerOnBridge | true, false |
false |
| callerId | Um número de telefone válido ou um identificador de cliente se estiver chamando um <Client>. |
Caller's callerId |
| callReason | String (máximo de 50 caracteres) | Nenhum |
| hangupOnStar | true, false |
false |
| method | GET, POST |
POST |
| record | do-not-record, record-from-answer, record-from-ringing, record-from-answer-dual, record-from-ringing-dual. Para a compatibilidade com versões anteriores, true é um alias para record-from-answer e false é um alias para do-not-record. |
do-not-record |
| recordingStatusCallback | URL relativo ou absoluto URL | Nenhum |
| recordingStatusCallbackMethod | GET, POST |
POST. Este atributo indica qual método HTTP a Twilio deve usar ao solicitar 'recordingStatusCallback'. |
| recordingStatusCallbackEvent | in-progress, completed, absent |
completed |
| recordingTrack | inbound, outbound, both |
both |
| referUrl | URL relativo ou absoluto | Nenhum |
| referMethod | GET, POST |
POST |
| ringTone | ISO 3166-1 alpha-2 country code | O padrão é o toque da operadora |
| timeLimit | Número inteiro positivo (segundos) | 14.400 segundos (4 horas) |
| timeout | Número inteiro positivo (segundos) | 30 segundos |
| trim | trim-silence, do-not-trim |
do-not-trim |
Use um ou mais desses atributos em um verbo <Dial>, desta forma:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial timeout="10" record="true">415-123-4567</Dial>
</Response>
action (ação)
O atributo action aceita um URL como seu argumento. Este URL informa a Twilio onde fazer uma solicitação POST ou GET após o término da chamada discada.
A solicitação da Twilio para este URL incluirá os seguintes parâmetros:
| Parâmetro | Descrição |
|---|---|
| DialCallStatus | O resultado da tentativa do <Dial>. Para obter detalhes, consulte a seção DialCallStatus abaixo. |
| DialCallSid | O SID de chamada do trecho de chamada. Este parâmetro não é enviado após discar para uma conferência. |
| DialCallDuration | A duração, em segundos, da chamada discada. Este parâmetro não é enviado após discar para uma conferência ou se uma chamada secundária for redirecionada para um novo URL do TwiML antes de ser desconectada. |
| DialBriged | Indicador booleano que indica se a chamada de discagem foi ou não conectada ao destino discado. |
| RecordingUrl | O URL do áudio gravado. Este parâmetro só é incluído se a gravação estiver definida em <Dial> e não incluir gravações iniciadas de outras maneiras. O arquivo de gravação pode ainda não estar acessível quando o callback da ação é enviado. Use recordingStatusCallback para receber uma notificação confiável de quando a gravação estiver disponível para acesso. |
Se você usar o <Dial> em <Queue>, a Twilio passará parâmetros adicionais para seu URL action. Leia a documentação <Queue> detalhada para saber mais.
Se um URL action for especificado para <Dial>, a Twilio continuará a chamada inicial depois que a pessoa discada desligar.
Quaisquer verbos TwiML incluídos após este <Dial> não poderão ser alcançados, pois sua resposta à Twilio assume o controle total da chamada inicial. Se deseja tomar mais ações nessa chamada inicial, você deve responder à solicitação da Twilio com as instruções TwiML sobre como lidar com a chamada.
Se nenhum URL action for fornecido, o <Dial> será concluído e a Twilio passará para o próximo verbo TwiML do documento. Se não houver mais verbos, a Twilio encerrará a chamada telefônica. Observe que isso é diferente do comportamento de <Record> e <Gather>.
DialCallStatus
Se você especificar um URL action, a Twilio sempre passará o status da tentativa de <Dial>.
Os valores possíveis para DialCallStatus são:
| Valor | Descrição |
|---|---|
| completed | A pessoa chamada atendeu a chamada e foi conectada ao autor da chamada. |
| answered | Ao chamar uma conferência, a pessoa chamada atendeu e foi conectada ao autor da chamada. |
| busy | A Twilio recebeu um sinal de ocupado ao tentar se conectar à parte chamada. |
| no-answer | A parte chamada não atendeu antes do tempo limite decorrido. |
| failed | A Twilio não conseguiu rotear para o número de telefone fornecido. Isso frequentemente é causado ao discar um número de telefone correto, mas não existente. |
| canceled | A chamada foi cancelada por meio da API REST antes de ser atendida. |
Voltar para a lista de atributos
answerOnBridge
Se <Dial> for o primeiro verbo TwiML no seu documento TwiML, answerOnBridge="true" fará com que a chamada inbound toque até que o número dicado atenda.
Se a chamada inbound for uma chamada SIP, a Twilio enviará 180 ou 183 ao servidor SIP assim que ele se conetar à Twilio. Ela aguardará até que a chamada <Dial> se conecte para um retorno de 200.
callerId
Ao usar <Dial> em resposta à solicitação de chamada inbound da Twilio, a parte discada vê o número do autor da chamada inbound como o ID do autor da chamada.
Por exemplo:
- Alguém com ID do autor da chamada
1-415-123-4567liga para o seu número da Twilio. - Você diz para a Twilio executar o verbo
<Dial>para1-858-987-6543para lidar com a chamada inbound. - A pessoa chamada (
1-858-987-6543) verá1-415-123-4567como o ID do autor da chamada na chamada recebida.
Ao usar o substantivo <Number> e especificar um callerId no <Dial>, é possível definir um ID do autor da chamada diferente do padrão. Você pode alterar o número de telefone que a pessoa chamada vê para um dos seguintes:
- O número
ToouFromfornecido na solicitação do TwiML da Twilio para seu app. - Qualquer número de telefone de entrada que você tenha adquirido da Twilio.
- Qualquer número de telefone verificado com a Twilio.
No caso de uma chamada SIP inbound, o callerId o não pode ser o número To ou From, pois existe o risco de falsificação de ID do autor da chamada. Ele pode ser apenas um número da Twilio ou um número de telefone verificado com a Twilio.
Se você estiver discando um <Client>, também pode definir um identificador de cliente válido como o atributo callerId. Por exemplo, se você configurou um cliente para as chamadas recebidas e estiver discando para esse cliente, poderá definir o atributo callerId como client:joey.
Se você estiver discando um endpoint <Sip>, insira qualquer string alfanumérica como o callerId. Opcionalmente, inclua os seguintes caracteres: +, -, _, e ., mas sem espaço em branco.
No exemplo a seguir, usamos <Dial> para ligar para um número de telefone a partir de um dispositivo Twilio Client:
Voltar para a lista de atributos
hangupOnStar
O atributo hangupOnStar permite que o autor da chamada inicial desligue a chamada da pessoa chamada pressionando a tecla '*' no telefone.
Quando as duas pessoas são conectadas usando o <Dial>, a Twilio bloqueia a execução de outros verbos até que o autor da chamada ou a pessoa chamada desligue. O recurso hangupOnStar permite que o autor da chamada inicial desligue na pessoa que recebeu a chamada sem ter que desligar o telefone (o que encerra a sessão de processamento do TwiML).
Quando o autor da chamada pressiona '*', a Twilio desliga a chamada para a pessoa chamada. Se um URL action foi fornecido, a Twilio envia um DialCallStatus para esse URL e processa a resposta. Ao ligar para uma conferência, o DialCallStatus será answered. Todos os outros tipos de chamada terão um DialCallStatus completed.
Se nenhum action foi fornecido, a Twilio continua para o próximo verbo no documento TwiML atual.
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.
No exemplo a seguir, fornecemos um URL action e especificamos GET como o method:
Esse código fará com que <Dial> conecte o autor da chamada iniciar ao número de telefone 415-123-4567.
Quando a chamada <Dial> termina, a Twilio envia uma solicitação GET ao URL action. Essa solicitação incluirá o parâmetro DialCallStatus que nos informa sobre o status da chamada <Dial>.
Nosso aplicativo da Web hospedado neste URL action agora pode analisar o DialCallStatus e enviar uma resposta à Twilio informando o que fazer em seguida.
Neste exemplo, o verbo <Say> nunca será executado, pois o código em /handleDialCallStatus assume o controle total da chamada.
Voltar para a lista de atributos
record
O atributo record permite que você grave os dois trechos de uma chamada dentro do verbo <Dial> associado. As gravações estão disponíveis em duas opções: monocanal ou canal duplo.
Nas gravações monocanal, ambos os trechos da chamada são combinados em um único canal dentro de um arquivo de gravação.
Entre as opções de record monocanal temos:
record-from-answer, que inicia a gravação assim que a chamada é atendida.record-from-ringing, que inicia a gravação assim que o toque começa (antes que o destinatário atenda a chamada).
Com as gravações de canal duplo, ambos trechos usam canais separados em um único arquivo de gravação.
Entre as opções de record de canal duplo temos:
record-from-answer-dual, que inicia a gravação assim que a chamada é atendida.record-from-ringing-dual, que inicia a gravação assim que o toque começa (antes que o destinatário atenda a chamada).
A chamada principal estará sempre no primeiro canal e a chamada secundária estará sempre no segundo canal de uma gravação de canal duplo.
Se a opção de gravação de canal duplo for usada para um <Dial> com um <Conference> aninhado, o arquivo de gravação resultante terá dois canais. O trecho principal (chamada inbound) é representado no primeiro canal. O segundo canal inclui o áudio que vem da conferência.
recordingStatusCallback
O atributo recordingStatusCallback usa um URL relativo ou absoluto como argumento. Se você solicitou a gravação do <Dial>, o URL informa a Twilio onde fazer sua solicitação GET ou POST quando a gravação estiver disponível para acesso.
A Twilio passará os seguintes parâmetros com sua solicitação para o URL recordingStatusCallback:
| Parâmetro | Descrição |
|---|---|
| AccountSid | O identificador exclusivo da conta responsável pela gravação. |
| CallSid | Um identificador exclusivo para a chamada associada à gravação. Isso sempre se refere ao trecho principal de uma chamada de dois trechos. |
| RecordingSid | O identificador exclusivo da gravação. |
| RecordingUrl | O URL do áudio gravado. |
| RecordingStatus | O status da gravação. Os valores possíveis são: in-progress, completed, absent. |
| RecordingDuration | A duração da gravação, em segundos. |
| RecordingChannels | O número de canais no arquivo de gravação final como um número inteiro. Os valores possíveis são 1 e 2. |
| RecordingStartTime | O carimbo de data/hora de quando a gravação foi iniciada. |
| RecordingSource | O método de início usado para criar a gravação. Em gravações iniciadas quando a gravação é definida para <Dial>, o DialVerb é retornado. |
Voltar para a lista de atributos
recordingStatusCallbackEvent
O recordingStatusCallbackEvent permite especificar quais alterações de status de gravação devem gerar um webhook para o URL especificado no atributo recordingStatusCallback. Os valores disponíveis são:
in-progress: a gravação foi iniciada.completed: a gravação foi concluída e está disponível.absent:a gravação está ausente e inacessível.
Para especificar mais de um valor, separe cada um com um espaço. O valor padrão é: completed.
Para pausar, retomar ou pararas gravações, consulte os documentos da API de gravação.
O exemplo a seguir especifica que queremos que cada participante na chamada <Dial> seja representado em seu próprio canal da gravação final e que a gravação comece quando a chamada começar a tocar.
Voltar para a lista de atributos
recordingTrack
O atributo recordingTrack permite selecionar se as faixas de áudio inbound, outbound ou both da chamada devem ser gravadas. A faixa inbound representa o áudio recebido pela Twilio e a faixa outbound representa o áudio que a Twilio gera na chamada. O valor padrão é both e grava o áudio recebido e gerado pela Twilio.
Quando a faixa da áudio inbound ou outbound for gravada, o arquivo de gravação resultante será sempre monocanal. Quando o áudio é gravado usando both, o arquivo resultante pode estar em canais separados (duplo) ou mistos (mono).
Voltar para a lista de atributos
referUrl
Para usar o recurso SIP REFER de entrada da Twilio, você deve ativar os "recursos SIP programáveis aprimorados" em suas configurações do Voice no console.
Se a pessoa chamada enviar uma solicitação SIP REFER, uma solicitação da Twilio será enviada para o referUrl. Seu aplicativo deve responder sobre como lidar com a transferência. Saiba mais sobre o SIP REFER de entrada para Twilio.
Os seguintes parâmetros são adicionados ao padrão Twilio Voice Webhook Request (solicitação de webhook do Twilio Voice):
| Parâmetro | Descrição |
|---|---|
| ReferTransferTarget | O número de telefone ou endpoint SIP para o qual transferir. |
Voltar para a lista de atributos
referMethod
O atributo referMethod 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.
Voltar para a lista de atributos
ringTone
O toque permite substituir o toque de retorno de chamada que a Twilio reproduz para o autor da chamada durante a execução de um <Dial>.
Se não for especificado, a Twilio reproduzirá o toque de retorno de chamada ou passará o toque de retorno de chamada da operadora (se fornecido). Isso funciona automaticamente, mas pode haver casos em que uma substituição é desejada.
Os valores aceitos são: at, au, bg, br, be, ch, cl, cn, cz, de, dk, ee, es, fi, fr, gr, hu, il, in, it, lt, jp, mx, my, nl, no, nz, ph, pl, pt, ru, se, sg, th, uk, us, us-old, tw, ve, za.
Observação: se você estiver discando um endpoint <Sip>, o ringTone só funcionará como esperado se você tiver habilitado os recursos SIP programáveis aprimorados na Twilio.
timeLimit
O atributo timeLimit define a duração máxima do <Dial> em segundos.
Por exemplo, ao definir um limite de tempo de 120 segundos, o <Dial> desligará automaticamente a parte chamada após dois minutos da chamada telefônica.
O limite de tempo padrão em chamadas é de 4 horas, que também é a duração máxima de uma chamada. Para aumentar a duração máxima para 24 horas, ative o recurso "24-Hour Maximum Call Duration" (duração máxima da chamada de 24 horas) em General settings (Configurações gerais) do Programmable Voice.
timeout (tempo limite)
Especificar um timeout define o limite em segundos que o <Dial> aguardará até que a pessoa discada atenda a chamada. Isso informa a Twilio quanto tempo deve deixar a chamada tocar antes de desistir e configurar no-answer como o DialCallStatus.
O valor padrão do timeout é 30 segundos. O valor mínimo permitido é 5 segundos e o valor máximo é 600 segundos.
A Twilio sempre adiciona um buffer de tempo limite de 5 segundos ao <Dial>; portanto, se você inserir um valor de tempo limite de 10 segundos, verá um tempo limite real mais próximo de 15 segundos.
Voltar para a lista de atributos
trim
Definir o atributo trim para trim-silence cortará o silêncio inicial e final de seus arquivos de áudio.
Cortar um arquivo pode fazer com que a duração da gravação seja ligeiramente inferior à duração da chamada. O atributo trim tem do-not-trim como padrão.
callReason
O motivo da chamada realizada. Use‐o para especificar a finalidade da chamada que é apresentada no telefone da pessoa chamada. (Branded Calls Beta, Chamadas sinalizadas versão Beta)
Para obter mais informações, visite a página Branded Calls (chamadas sinalizadas).
substantivos <Dial>
Você sempre pode optar por aninhar um texto sem formatação (uma string representando um número de telefone válido) em <Dial> para informar um número de telefone para a Twilio chamar:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Dial>415-123-4567</Dial>
</Response>Você também pode optar por aninhar substantivos no <Dial> para criar conexões com outros tipos de dispositivos, chamadas em conferência e filas de chamadas.
O substantivo de um verbo TwiML descreve os números de telefone, endpoints e recursos de API sobre os quais você deseja agir. Os substantivos TwiML substantivos são qualquer coisa sobre a qual o verbo (<Dial>, neste caso) age sobre.
Você pode usar os substantivos a seguir com o <Dial>. Cada um é um elemento XML aninhado:
| Substantivo | Descrição |
|---|---|
| <Client> |
Descreve uma conexão do Twilio Client. A discagem simultânea também é possível usando vários substantivos do Leia a documentação detalhada do <Client> para obter informações detalhadas e uso. |
| <Conference> |
Descreve uma conferência que permite que duas ou mais pessoas falem. Conecta a parte ativa a uma chamada em conferência. Consulte a documentação detalhada de <Conference> para obter o passo a passo sobre como usar a funcionalidade de conferência da Twilio. |
| <Number> |
Descreve um número de telefone com atributos mais complexos. Esse substantivo permite que você use Leia a documentação detalhada do <Number> para obter mais informações e uso. |
| <Sim> |
Descreve uma conexão do chip/SIM do Programmable Wireless. Consulte a documentação detalhada do <Sim> para obter mais informações. |
| <Sip> |
Descreve uma conexão SIP. Consulte a documentação detalhada do <Sip> para obter mais informações. |
| <Queue> |
Identifica uma fila à qual esta chamada deve se conectar. Permite conectar a chamada atual à chamada em espera na frente de uma fila específica. Leia a documentação sobre <Queue> para obter o passo a passo detalhado sobre como usar a funcionalidade de enfileiramento da Twilio. |
Aninhe um desses substantivos dentro de um verbo <Dial> desta maneira:
Funcionalmente, o exemplo acima se comporta exatamente como o exemplo básico, no qual aninhamos um número de telefone de texto sem formatação no <Dial>. Vamos levar esse aninhamento de substantivos TwiML mais adiante.
No exemplo a seguir, especificaremos que queremos uma gravação de canal duplo para um <Dial> com um <Conference> aninhado.
Este código encaminhará o autor da chamada ativo para uma conferência chamada myteamroom. Uma gravação de canal duplo da chamada iniciará quando o toque começar. Depois que a chamada terminar e a gravação estiver pronta, a Twilio enviará as informações de gravação de volta para example.com:
Como usar Twimlets
Twimlets são URLs hospedados pela Twilio que fornecem pequenos pedaços de funcionalidade comumente usadas.
- O twimlet Foward (encaminhar) encaminha todas as chamadas de um número da Twilio para outro número de sua escolha.
- O twimlet Simulring (toque simultâneo) disca vários números ao mesmo tempo e conecta o autor da chamada à primeira pessoa que atender.
- Para discar números por vez até que um deles pegue, use o twimlet Find me (encontrar).
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.
