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:

SDK do JS do Twilio Client: Twilio.Connection

Você está visualizando a versão 1.X do Voice JavaScript SDK (anteriormente chamado de Twilio Client). Clique aqui para obter informações sobre como migrar para a versão 2.X.

Um objeto Twilio.Connection representa uma chamada de ou para o Twilio. Você nunca o instanciará diretamente, mas ele será passado aos manipuladores de eventos e retornado quando você chamar Twilio.Device.connect().

// Explicitamente criar uma nova conexão de saída
var connection = Twilio.Device.connect();

// ou lidar com um evento de conexão de entrada
Twilio.Device.on('incoming', function(conn) {
  // conn é um objeto Twilio.Connection
});

Referência do método

.accept( [audioConstraints] )

Aceita uma conexão de entrada.

Isso começará a estabelecer a sessão de mídia para este dispositivo. O estado da conexão será definido como connecting enquanto a sessão de mídia para a chamada é configurada. O estado da conexão muda para open assim que a sessão mídia for estabelecida.

Twilio.Device.on('incoming', function(conn) {
  conn.accept();
});

Você pode, opcionalmente, especificar um objeto audioConstraints para alterar o comportamento do fluxo de mídia local durante esta chamada. Você pode usar isso para selecionar um microfone específico ou desativar recursos como controle de ganho automático. Cada navegador da Internet implementa um conjunto diferente de restrições MediaTrackConstraints que pode ser utilizado como audioConstraints. Por isso, consulte a implementação do seu navegador de getUserMedia para obter mais informações.

var audioConstraints = {
  optional: [{ sourceId: 'XXX' }]
};

Twilio.Device.on('incoming', function(conn) {
  conn.accept(audioConstraints);
});
Nota de melhores práticas

O método .accept( [audioConstraints] ) chama getUserMedia para obter um fluxo de áudio. A chamada será automaticamente desconectada se getUserMedia não for bem‐sucedido. Por exemplo, devido a problemas de hardware ou permissão. É recomendável lidar com erros getUserMedia antes de aceitar uma chamada. Consulte a nota de melhores práticas aqui.

.reject()

Rejeitar uma conexão pendente. Isso fará com que um desligamento seja emitido da sessão do cliente para a pessoa que está discando. Se várias sessões de cliente estiverem ativas , a conexão pendente será rejeitada para todas elas.

.ignore()

Ignorar uma conexão pendente. Isso impedirá que o dispositivo Cliente reproduza o som recebido e definirá o estado da conexão como fechado, mas não enviará uma mensagem de desligamento para o participante que está discando. A chamada recebida continuará tocando até que outro Cliente com o mesmo nome atenda a chamada ou a chamada atinja o tempo limite.

.disconnect()

Fechar esta conexão.

.mute(bool)

Deixa mudo ou ativa o som da conexão atual com base no parâmetro booleano que você fornece. verdadeiro silencia a conexão, encerrando o áudio coletado do microfone do usuário, falso ativa o som da conexão.

.isMuted()

Retorna um valor booleano que indica se a conexão está sem som.

.getLocalStream()

Obtém o MediaStream local que está sendo usado pela conexão. Contém a entrada de áudio do Cliente local.

.getRemoteStream()

Obtenha o MediaStream remoto. Contém o áudio do Cliente remoto, que está sendo recebido localmente e enviado pelos alto-falantes do Cliente local.

.sendDigits( digits )

Reproduzir tons DTMF. O parâmetro digits é uma cadeia de caracteres e pode conter os caracteres 0 - 9, *, # e w. Cada w causará uma pausa de 500 ms entre os dígitos enviados. Se você está familiarizado com o TwiML, você pode pensar no método sendDigits como o atributo sendDigits no substantivo <Number> . O SDK suporta apenas o envio de dígitos DTMF. Ele não aumenta os eventos se dígitos DTMF estiverem presentes no fluxo de áudio de entrada.

.status()

Retorna o status dessa conexão. O status será uma das seguintes strings:

Valor do status Descrição
"pending" A conexão é recebida e ainda não foi estabelecida.
"connecting" A conexão foi aceita ou iniciada pelo cliente local.
"ringing" O receptor foi notificado da chamada, mas ainda não respondeu.

Nota: Até 2.0, este estado só é confrontado quando a bandeira do "enableRingingState" é definida como verdadeira nas opções "Device.setup" e a aplicação TwiML está discando com a propriedade "answerOnBridge", por exemplo: <Dial answerOnBridge=true></Dial>.
"open" A conexão foi estabelecida.
"closed" A conexão foi desativada.

.postFeedback(score, issue)

Posta o feedback coletado para esta chamada para Twilio. Se nenhum parâmetro for aprovado, o Twilio informará que o feedback não estava disponível para esta chamada. Publicar o feedback usando esta API permitirá que você entenda exatamente quais fatores contribuem para problemas de qualidade de áudio. A Twilio poderá correlacionar as métricas com a qualidade percebida da chamada e fornecer uma imagem precisa dos fatores que afetam a experiência de chamada dos usuários.

Pontuações
Pontuação Interpretação sugerida
"1" Terrível qualidade das chamadas, as chamadas diminuíram ou provocaram grandes dificuldades de comunicação.
"2" Qualidade de chamada ruim, como áudio instável, áudio unidirecional periódico.
"3" Qualidade média das chamadas, gerenciável com alguma perda de ruído/pacote menor.
"4" Boa qualidade das chamadas, pequenos problemas.
"5" Excelente qualidade de chamada. Sem problemas.
Problemas
Nome do problema Descrição
dropped-call Chamada inicialmente conectada, mas caiu
audio-latency Os participantes podem ouvir uns aos outros, mas com um atraso significativo
one-way-audio Um participante não podia ouvir o outro
choppy-audio Periodicamente, os participantes não podiam ouvir uns aos outros. Algumas palavras foram perdidas.
"Noisy-call" Houve distúrbio, ruído de fundo, pouca clareza.
Echo Houve eco durante a chamada.
Examples
.postFeedback(5); // Perfect call!
.postFeedback(2, 'dropped-call'); // Não tão perfeito... Faremos melhor da próxima vez!
.postFeedback(); // Pedimos feedback ao cliente, mas ele se recusou a fornecer feedback.

Referência do evento

.on('accept', handler(connection))

Registre uma função de manipulador a ser chamada quando este objeto de conexão terminar de se conectar e alterar o estado para "open" (aberto).

A função de manipulador recebe o objeto "Twilio.Connection" como seu único argumento.

.on('cancel', handler())

Registrar uma função de manipulador a chamar quando a conexão é cancelada e a conexão "Connection.status()" passa para "closed". Isto é levantado quando se chama "Connection.ignore()" ou quando é cancelado um convite pendente enquanto se tenta conectar ao Twilio.

.on('disconnect', handler(connection))

Registra uma função de manipulador a ser chamada quando essa conexão é fechada.

A função de manipulador recebe o objeto "Twilio.Connection" como único argumento.

var connection = Twilio.Device.connect();

connection.on('disconnect', function(conn) {
  console.log("the call has ended");
});

.on('error', handler(error))

Registra uma função de manipulador a ser chamada quando ocorrer qualquer erro de dispositivo durante a vida útil da conexão. Podem ser erros na solicitação, token de recursos, erros de conexão ou outros erros do aplicativo . Consulte a Referência de códigos de erro do Twilio Client para obter mais informações. Usar o manipulador de erros é uma ótima maneira de depurar o aplicativo e ajudar a detectar erros no código!

A função de manipulador recebe um objeto como argumento. O objeto de erro pode incluir as seguintes propriedades:

Propriedade Descrição
message Uma string que descreve o erro.
code Um código de erro numérico descrito na Referência de códigos de erro do Twilio Client.
Conexão Uma referência ao objeto "Twilio.Connection" que estava ativo quando o erro ocorreu.
twilioError Quando aplicável, os erros emitidos contêm este campo twilioError, que fornece mais informações sobre o erro. Este twilioError representa o novo formato do TwilioError que se tornará o formato de erro padrão na próxima versão principal. Para obter uma lista de possíveis twilioErrors, visite esta página.

.on('mute', handler(boolean, connection))

Registre uma função de manipulador a ser chamada quando uma conexão estiver sem áudio ou sem som.

A função de manipulador recebe um booleano que indica se a conexão está agora silenciada ("true") ou não ("false") e o objeto "Twilio.Connection" que foi silenciado ou não.

.on('reconnecting', handler(error))

Observação: Este recurso está atrás de uma marcação no Device.setup: "enableIceRestart". Por padrão, esse evento não será acionado.

Surge quando a conexão de mídia falha e a reconexão automática foi iniciada emitindo reinicializações ICE. Durante este período, "Connection.status()" será definido como "reconnecting".

  • error - Objeto de erro { code: 53405, message: 'Media connection failed.' }
  • Gatilhos de reconexão de mídia
    • Estado da conexão ICE faz transição para "disconnect" e os bytes enviados e recebidos nos últimos 3 segundos são zero.
    • Estado da conexão ICE ou Estado PeerConnection faz transição para "failed". Somente o navegador Chrome tentará uma reinicialização ICE com este gatilho. Outros navegadores desconectam imediatamente a chamada e geram um erro "31003". Isso ocorre porque os navegadores não suportam totalmente os estados de conexão durante uma reinicialização ICE.
    • Estado de coleta ICE faz transição para completo e nenhum candidato ICE é coletado.
    • A coleta GELO excede 15 segundos e nenhum candidato ICE foi coletado
  • Novas tentativas - as reinicializações ICE serão repetidas caso as reinicializações anteriores de ICE não sejam bem‐sucedidas. As tentativas de repetição ocorrerão quando Estado de conexão ICE ou Estado PeerConnection fizer transição para "failed". Se tiverem decorrido mais de 30 segundos durante esta transição, a chamada será desconectada e gerará um erro "31003".

.on('reconnected', handler())

Observação: Este recurso está atrás de uma marcação no Device.setup: "enableIceRestart". Por padrão, esse evento não será acionado.

Gerado quando a conexão de mídia foi restaurada, que é detectada quando a mídia começa a fluir. Uma vez reconectada, a "Connection.status()" será definida como "open".

.on('cancel', handler())

Registrar uma função de manipulador a chamar quando a conexão é rejeitada e a conexão "Connection.status()" passa para "closed". Isso é gerado quando se chama "Connection.reject()".

.on('ringing', handler(hasEarlyMedia))

Observação: Este recurso está atrás de uma marcação no Device.setup: "enableRingingState". Por padrão, esse evento não será acionado.

Gerado quando a conexão entra no estado "ringing". Por padrão, o verbo Dial do TwizML se conectará imediatamente e esse estado será breve ou totalmente ignorado. Ao utilizar o verbo Dial com "answerOnBridge=true", o estado "ringing" começará quando o receptor for notificado da chamada e passará para "open" após o receptor aceitar a chamada, ou "closed" se a chamada for rejeitada ou cancelada.

O argumento "hasEarlyMedia" é um booleano que denota se há mídias disponíveis a partir do receptor. Se "true", o Client SDK reproduzirá automaticamente a mídia inicial. Às vezes isso é tocar, outras vezes pode ser uma mensagem importante sobre a chamada. Se "false", não há mídia remota para reproduzir, então o aplicativo pode querer reproduzir o próprio toque de saída.

Exemplo
connection.on('ringing', function(hasEarlyMedia) {
  showRingingIndicator();
  if (!hasEarlyMedia) { playOutgoingRinging(); }
});

.on('sample', handler(rtcSample)

Registre uma função de manipulador a ser chamada quando a conexão obtiver um objeto de amostra de WebRTC. Este evento é publicado a cada segundo.

Dados de exemplo
{
  "audioInputLevel": 11122,
  "audioOutputLevel": 2138,
  "bytesReceived": 8600,
  "bytesSent": 8600,
  "codecName": "opus",
  "jitter": 0,
  "mos": 4.397229249317001,
  "packetsLost": 0,
  "packetsLostFraction": 0,
  "packetsReceived": 50,
  "packetsSent": 50,
  "rtt": 77,
  "timestamp": 1572301567032.327,
  "totals": {
    "bytesReceived": 63640,
    "bytesSent": 83936,
    "packetsLost": 0,
    "packetsLostFraction": 0,
    "packetsReceived": 370,
    "packetsSent": 488
  }
}

.on('volume', handler(inputVolume, outputVolume))

Registre uma função de manipulador a ser chamada com o volume de entrada atual da conexão e o volume de saída em cada quadro de animação. O manipulador será chamado até 60 vezes por segundo e será diminuído gradualmente de forma dinâmica em dispositivos mais lentos para preservar o desempenho. O manipulador recebe "inputVolume" e "outputVolume" como uma porcentagem do volume máximo representado por um número de ponto flutuante entre 0.0 e 1.0, inclusive. Esse valor representa uma faixa de valores de decibéis relativos de -100dB a -30dB.

.on('warning', handler(warningName, warningData))

Gerado quando uma métrica de qualidade de chamada ultrapassou um limite.

Twilio.js gera eventos de advertência quando detecta uma queda na qualidade da chamada ou outras condições que podem indicar que o usuário está tendo problemas com a chamada. Você pode implementar retornos de chamada sobre esses eventos para alertar o usuário sobre um problema.

Para uma lista completa de eventos "warning", consulte a Referência de eventos do Voice Insights. Verifique os exemplos abaixo para saber como ouvir os eventos "warning" e "warning-cleared".

Exemplo
connection.on('warning', function(warningName, warningData) {
  if (warningName === 'low-mos') {
    showQualityWarningModal('We have detected poor call quality conditions. Você pode ter uma qualidade de chamada degradada.');
    console.log(warningData);
    /* Imprime o seguinte
      {
        // Stat name
        "name": "mos",

        // Matriz de valores mos nas últimas 5 amostras que acionaram o aviso
        "values": [2, 2, 2, 2, 2],

        // Conjunto de amostras coletadas que acionaram o aviso.
        // Veja o formato de objeto de amostra aqui https://www.twilio.com/docs/voice/client/javascript/connection#sample
        "samples": [...],

        // A configuração do limite.
        // Neste exemplo, o aviso de low‐mos será gerado se o valor estiver abaixo de 3
        "threshold": {
          "name": "min",
          "value": 3
        }
      }
     */
  }
});

.on('warning-cleared', handler(warningName))

Gerado quando uma métrica de qualidade de chamada retorna ao normal.

Exemplo
connection.on('warning-cleared', function(warningName) {
  if (warningName === 'low-mos') {
    hideQualityWarningModal();
  }
});

Referência de propriedade

.callerInfo

.callerInfo retorna informações de verificação do autor da chamada sobre o autor da chamada. Se nenhuma informação de verificação do autor da chamada estiver disponível, ela retornará "nulo". O objeto "callerInfo" contém os seguintes atributos:

  • "isVerified" - Indica se o número de telefone do autor da chamada foi verificado ou não pelo Twilio usando SHAKEN/STIR. Verdadeiro se o autor da chamada tiver sido verificado no nível "A", falso se o autor da chamada tiver sido verificado em qualquer nível inferior ou tiver falhado na verificação.

Exemplo

device.on('incoming', connection => {
  if (connection.callerInfo && connection.callerInfo.isVerified) {
    console.log('This caller is verified by a carrier under the SHAKEN and STIR call authentication framework');
  }
});

Confira esta página para saber mais sobre fazer e receber chamadas SHAKEN/STIR para/de redes de telefone públicas.

".customParameters"

".customParameters" é uma string "Map<, string>" que inclui todos os parâmetros do TwiML enviados ou recebidos do aplicativo TwiML esta conexão está sendo realizada com. Esse recurso é uma ótima maneira de transmitir dados de contexto entre seu aplicativo TwizML e o JS Client SDK.

Em conexões de entrada

Um parâmetro de conexão de entrada ".customParameters" contém todos os dados enviados usando substantivos "" no aplicativo TwizML.

Em conexões de saída

Um parâmetro de conexão de saída ".customParameters" contém todos os dados de parâmetro do TwiML aprovados para "Device.connect(twimlParams)". É importante observar que o mapa ".customParameters" de um autor da chamada e o mapa ".customParameters" de um receptor podem não conter os mesmos dados, pois cabe ao seu aplicativo TwML escolher quais, se houver, dos dados que ele recebe do autor da chamada para passar para o receptor.

.parameters

.parameters contém detalhes sobre a chamada, como quem está chamando e o que foi discado. O significado desses parâmetros corresponde àqueles nos [parâmetros de solicitação do Twilio Voice] (/docs/api/twiml/twilio_request#synchronous).

Incoming .parameters

Nas conexões de entrada, incluem‐se os seguintes parâmetros:

Parâmetro Descrição
CallSid Um identificador exclusivo para esta chamada, gerado pelo Twilio.
AccountSid Seu ID da conta da Twilio. Ele tem 34 caracteres e sempre começa com as letras AC.
De O número de telefone ou identificador do cliente da pessoa que iniciou a chamada. Os números de telefone são formatados com um código de país e ''+'', por exemplo, "+16175551212" (formato [E.164][e164]). Os identificadores dos clientes começam pelo regime URI "client:"; Por exemplo, para uma chamada de um cliente chamado "tommy", o parâmetro "From" será "client:tommy".
Para O número de telefone ou identificador do cliente da parte chamada. Os números de telefone são formatados com um código de país e ''+'', por exemplo, "+16175551212" (formato [E.164][e164]). Os identificadores de clientes começam pelo regime de URI "client:"; por exemplo, para uma chamada para um cliente chamado "joey", o parâmetro "To" será "client:joey".
ApiVersion A versão da API Twilio usada para lidar com esta chamada. Para chamadas recebidas, isso é determinado pela versão da API definida no número chamado. Para chamadas de saída, esta é a versão da API usada pela solicitação da API REST da chamada de saída.
Outgoing .parameters

Nas conexões de saída, incluem‐se os seguintes parâmetros:

Parâmetro Descrição
CallSid Um identificador exclusivo para esta chamada, gerado pelo Twilio.

Métodos descontinuados

Os métodos a seguir foram desaprovados e serão removidos em uma versão futura do twilio.js. Chamar esses métodos gerará um aviso de substituição, a menos que o parâmetro de avisos seja definido como falso ao chamar Twilio.Device.setup().

.mute()

Interrompe a captura de áudio do microfone para esta conexão. Este método foi substituído por .mute(bool).

.unmute()

Retoma a captura de áudio do microfone para esta conexão. Este método foi substituído por .mute(bool).

Métodos do manipulador

Além disso, o Twilio Client está avançando para a interface padrão do EventEmitter, o que significa que os eventos devem ser gerenciados com o ".on(eventName, handler)" e ".removeListener(eventName, handler)", substituindo os nossos manipuladores legado (como ".accept(handler)", ".error(handler)" etc...). Os seguintes métodos foram desaprovados:

Connection.accept(handler)
Connection.cancel(handler)
Connection.disconnect(handler)
Connection.error(handler)
Connection.ignore(handler)
Connection.mute(handler)
Connection.reject(handler)
Connection.volume(handler)

Estes foram substituídos pelos seguintes eventos do EventEmitter:

Connection.on('accept', handler)
Connection.on('cancel', handler)
Connection.on('disconnect', handler)
Connection.on('error', handler)
Connection.on('mute', handler)
Connection.on('reject', handler)
Connection.on('volume', handler)

Observe que não há evento "ignore". O método ".ignore(handler)" é, na verdade, um ouvinte retrocompatível para o evento ".on('cancel', handler)".

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.

        
        
        

        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!

        Indique‑nos e obtenha USD10 em 3 etapas simples!

        Etapa 1

        Obtenha o link

        Obtenha um link de indicação pessoal gratuito aqui

        Etapa 2

        Dê USD10

        Seu usuário se inscreve e faz a atualização usando o link

        Etapa 3

        Obtenha USD10

        1.250 mensagens SMS grátis
        OU 1.000 min de voz grátis
        OU 12.000 chats
        OU mais