TwiML™ Voice: <Client>
O substantivo <Client> do verbo <Dial> especifica um identificador de cliente para discar.
Você pode usar até dez substantivos <Client> em um verbo <Dial> para tentar simultaneamente uma conexão com muitos clientes ao mesmo tempo. O primeiro cliente a aceitar a conexão de entrada é conectado à chamada e as outras tentativas de conexão são canceladas. Se pretende se conectar com vários outros clientes simultaneamente, leia sobre o substantivo <Conference>.
O identificador do cliente não deve conter caracteres de controle, espaço, delimitadores ou imprudentes. Os SDKs para dispositivos móveis não podem incluir caracteres especiais e devem usar apenas caracteres alfanuméricos e sublinhado.
Atributos do substantivo
O substantivo <Client> dá suporte aos seguintes atributos que modificam seu comportamento:
| Nome do atributo | Valores permitidos | Valor padrão |
|---|---|---|
url |
Qualquer URL | nenhuma |
method |
GET, POST |
POST |
statusCallbackEvent |
initiated, ringing, answered, completed |
none |
statusCallback |
Any URL | none |
statusCallbackMethod |
GET, POST |
POST |
url
O atributo url permite que você especifique um URL para um documento TwiML que será
executado no terminal da parte chamada, depois que ela responder, mas antes que as partes estejam
conectadas. Você pode usar este TwiML para reproduzir ou dizer informações privadamente à
parte 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 no atributo url. O padrão é POST.
statusCallbackEvent
Ao discar para um Cliente 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 chamar 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 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 |
Este evento é acionado quando a Twilio começa a discar a chamada. |
ringing |
Este evento é acionado quando a chamada começa a tocar. |
answered |
Este evento é acionado quando a chamada é atendida. |
completed |
Este evento é 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).
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.
Parâmetros HTTP de retorno de chamada de status
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 |
O 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 de gravação precisa após qualquer corte de silêncio, use recordingStatusCallback. |
Timestamp |
O carimbo de data/hora em que o evento foi acionado, 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. |
Parâmetros personalizados
É possível incluir pares de valores-chave adicionais que serão passados para o Cliente (Web ou Mobile). Você pode fazer isso usando o substantivo do TwiML <Parameter> aninhado.
Esses parâmetros personalizados podem ser recuperados usando os SDKs. Para Cliente JS, consulte Connection.customParameters, para iOS, consulte TVOConnectOption.params e para Android, consulte ConnectOptions.getParams()
Exemplos
Exemplo 1: Discar para um cliente
Neste exemplo, queremos conectar a chamada atual a um cliente chamado joey.
Para conectar a chamada a joey, use um verbo <Dial>
com um substantivo <Client> aninhado dentro.
Exemplo 2: Discagem simultânea
Você pode usar até dez substantivos <Number> e <Client> no total
dentro de um verbo <Dial> para discar vários números de
telefone e clientes ao mesmo tempo. A primeira pessoa a atender a chamada
será conectada ao autor da chamada, enquanto o restante das tentativas de chamada será desligada.
Exemplo 3: Eventos de progresso de chamada
Neste caso, queremos receber um webhook para cada evento de progresso de chamada ao
discar para um Cliente usando <Dial>.
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.
