SDK do JS do Twilio Client: Twilio.Connection

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:

.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

Problemas

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:

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

Outgoing .parameters

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

Métodos descontinuados

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