You are viewing the Spanish (Mexico) site, but your language preference is set to English. Switch to English site →

Menu

Expand
Calificar esta página:

SDK de Twilio Client para JS: Twilio.Connection

Estás viendo la versión 1.X del SDK de Voice para JavaScript (antes llamado Twilio Client). Haz clic aquí para obtener información sobre cómo migrar a la versión 2.X.

Un objeto Twilio.Connection representa una llamada hacia o desde Twilio. Nunca se crea una instancia directamente, sino que se pasa a los controladores de eventos y se devuelve cuando se llama a Twilio.Device.connect().

// Crear explícitamente una nueva conexión saliente
var connection = Twilio.Device.connect();

// o manejar un evento de conexión entrante
Twilio.Device.on('incoming', function(conn) {
  // conn es un objeto Twilio.Connection
});

Referencia del método

.accept( [audioConstraints] )

Acepta una conexión entrante.

Con esto se comenzará a establecer la sesión multimedia en este dispositivo. El estado de conexión se establecerá en connecting mientras se configura la sesión multimedia de la llamada. El estado de la conexión cambiará a open una vez que se establezca la sesión multimedia.

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

Si lo deseas, puedes especificar un objeto audioConstraints para modificar el comportamiento de la secuencia multimedia local durante la llamada. Puedes utilizarlo para seleccionar un micrófono específico o para desactivar funciones como el control automático de ganancia. Cada navegador web implementa un conjunto diferente de MediaTrackConstraints que se pueden utilizar como audioConstraints, por lo que debes consultar la implementación de getUserMedia de tu navegador para obtener más información.

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

Twilio.Device.on('incoming', function(conn) {
  conn.accept(audioConstraints);
});
Nota sobre las prácticas recomendadas

El método .accept( [audioConstraints] ) llama a getUserMedia para obtener una secuencia de audio. La llamada se desconectará automáticamente si getUserMedia no tiene éxito. Por ejemplo, debido a problemas de hardware o permisos. Se recomienda manejar los errores de getUserMedia antes de aceptar una llamada. Consulta la nota sobre prácticas recomendadas aquí.

.reject()

Rechaza una conexión pendiente. Esto hará que se emita la acción de colgar desde la sesión del client (cliente) a la parte que llama. Si hay varias sesiones de client (cliente) activas, se rechazará la conexión pendiente para todas ellas.

.ignore()

Ignora una conexión pendiente. Esto impedirá que el dispositivo cliente reproduzca el sonido de llamada entrante y establecerá el estado de conexión en closed (cerrada), pero no enviará un mensaje de colgar llamada a la parte que llama. La llamada entrante seguirá sonando hasta que otro client (cliente) con el mismo nombre responda a la llamada o la llamada supere el tiempo de espera.

.disconnect()

Cierra la conexión.

.mute(bool)

Silencia o activa el sonido de la conexión actual según el parámetro booleano que proporciones. true silencia la conexión mediante la finalización del audio recopilado del micrófono del usuario, mientras que false activa el sonido de la conexión.

.isMuted()

Devuelve un booleano que indica si la conexión está silenciada.

.getLocalStream()

Obtiene el MediaStream local que utiliza la conexión. Contiene la entrada de audio del client (cliente) local.

.getRemoteStream()

Obtiene el MediaStream remoto. Contiene el audio del client (cliente) remoto, que se recibe a nivel local y se emite a través de los altavoces del client (cliente) local.

.sendDigits( digits )

Reproduce tonos DTMF. El parámetro digits es una cadena y puede contener los caracteres 0-9, *, # y w. Cada w causará una pausa de 500 ms entre los dígitos enviados. Si estás familiarizado con TwiML, puedes pensar en el método sendDigits como el atributo sendDigits en el sustantivo <Number> . El SDK solo admite el envío de dígitos DTMF. No genera eventos si los dígitos DTMF están presentes en la secuencia de audio entrante.

.status()

Devuelve el estado de la conexión. El estado será una de las siguientes cadenas:

Valor de estado Descripción
"pending" Se trata de una conexión entrante que aún no se establece.
"connecting" El cliente local aceptó o inició la conexión.
"ringing" Se notificó al agente de llamada de la llamada, pero aún no responde.

Nota: Hasta la versión 2.0, este estado solo se emite cuando el indicador enableRingingState está configurado como true en las opciones de Device.setup y la app TwiML está marcando con la propiedad answerOnBridge, por ejemplo: <Dial answerOnBridge=true></Dial>.
"open" Se estableció la conexión.
"closed" Se desconectó la conexión.

.postFeedback(score, issue)

Envía los comentarios recopilados de esta llamada a Twilio. Si no se pasa ningún parámetro, Twilio informará que no habían comentarios disponibles en relación con esta llamada. El envío de los comentarios mediante esta API te permitirá comprender exactamente qué factores contribuyen a los problemas de calidad de audio. Twilio podrá correlacionar las métricas con la calidad de llamada percibida y proporcionar una imagen precisa de los factores que afectan a la experiencia de llamada de tus usuarios.

Puntuaciones
Puntuación Interpretación sugerida
1 Calidad de llamada terrible, la llamada se cortó o hubo muchos problemas de comunicación.
2 Mala calidad de llamada, el audio se cortaba, cada cierto tiempo se producía audio unidireccional.
3 Calidad de llamada promedio, manejable, pero con cierto ruido o pequeñas pérdidas de paquetes.
4 Buena calidad de llamada, problemas menores.
5 Excelente calidad de llamada. Sin problemas.
Problemas
Nombre del problema Descripción
dropped-call En un principio la llamada se conectó, pero luego se cortó
audio-latency Los participantes se podían escuchar mutuamente, pero existía un retraso significativo
one-way-audio Un participante no pudo escuchar al otro
choppy-audio Cada cierto tiempo los participantes no se podían escuchar entre sí. Algunas palabras no llegaron al destinatario.
noisy-call Había alteraciones, ruido de fondo, poca claridad.
echo Había eco durante la llamada.
Ejemplos
.postFeedback(5); // Llamada perfecta
.postFeedback(2, 'dropped-call'); // No tan perfecta... La próxima vez será mejor.
.postFeedback(); // Le pedimos comentarios al cliente, pero no quiso brindar ninguno.

Referencia de eventos

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

Registra una función controladora que se llamará cuando el objeto de conexión haya finalizado el proceso de conexión y pase al estado open.

La función controladora recibe el objeto Twilio.Device como su único argumento.

.on('cancel', handler())

Registra una función controladora que se llamará cuando se cancele la conexión y Connection.status() retorne el estado closed (cerrada). Se ejecuta cuando se llama a Connection.ignore() o cuando se ha cancelado una invitación pendiente mientras se intentaba conectar con Twilio.

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

Registra una función controladora que se llamará cuando la conexión se cierre.

La función controladora recibe el objeto Twilio.Connection como su único argumento.

var connection = Twilio.Device.connect();

connection.on('disconnect', function(conn) {
  console.log("se finalizó la llamada");
});

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

Registra una función controladora que se llamará cuando se produzca un error de dispositivo durante el ciclo de vida de la conexión. Puede tratarse de errores en la solicitud, tu token de capacidad, errores de conexión u otros errores de la aplicación. Consulta la Referencia de códigos de error de Twilio Client para obtener más información. El uso del controlador de errores es una excelente forma de depurar la aplicación y detectar errores en el código.

La función controladora recibe un objeto de error como argumento. El objeto de error puede tener las siguientes propiedades:

Propiedad Descripción
message Una cadena que describe el error.
code Un código de error numérico descrito en la Referencia de códigos de error de Twilio Client.
connection Una referencia al objeto Twilio.Connection que estaba activo cuando se produjo el error.
twilioError Cuando corresponda, desde ahora los errores emitidos contienen el campo twilioError que brinda más información sobre el error. Este twilioError representa el nuevo formato de TwilioError que se convertirá en el formato de error predeterminado en la siguiente versión de cambios importantes. Para obtener una lista de posibles twilioErrors, visita esta página.

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

Registra una función controladora a la que se deba llamar cuando se silencie o se active el sonido de una conexión.

La función controladora recibe un booleano que indica si la conexión está silenciada actualmente (true) o no (false), y el objeto Twilio.Connection que se silenció o respecto al cual se activó el sonido.

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

Nota: Esta función se activa mediante un indicador que se pasa a Device.setup: enableIceRestart. De forma predeterminada, este evento no se activará.

Se emite cuando la conexión multimedia falla y se ha iniciado la reconexión automática mediante la emisión de reinicios de ICE. Durante este período, Connection.status() se establecerá en reconnecting (reconectando).

  • error - Objeto Error { code: 53405, message: 'Media connection failed' (Error de conexión multimedia). }
  • Disparadores de reconexión multimedia
    • El estado de conexión ICE avanza a disconnect y hay cero bytes enviados y recibidos en los últimos tres segundos.
    • El estado de conexión ICE o estado de PeerConnection avanza a failed. Solo el navegador Chrome intentará reiniciar ICE con este disparador. Otros navegadores desconectan de inmediato la llamada y generan un error 31003. Esto se debe a que los navegadores no admiten completamente los estados de conexión durante un reinicio de ICE.
    • El estado de recopilación de ICE avanza a completado sin que se haya recopilado ningún candidato ICE.
    • La recopilación de candidatos ICE excede los 15 segundos sin que se haya recopilado ningún candidato ICE
  • Reintentos: los reinicios de ICE se volverán a realizar en caso de que los reinicios anteriores no hayan tenido éxito. Los reintentos se producirán cuando el estado de conexión ICE o el estado de PeerConnection pase a failed. Si han transcurrido más de 30 segundos durante esta transición, la llamada se desconectará y se generará un error 31003.

.on('reconnected', handler())

Nota: Esta función se activa mediante un indicador que se pasa a Device.setup: enableIceRestart. De forma predeterminada, este evento no se activará.

Se emite cuando la conexión multimedia se restablece, lo que se detecta cuando se inicia el flujo multimedia. Una vez reconectado, Connection.status() cambiará a open.

.on('reject', handler())

Registra una función controladora a la que se llama cuando se rechaza la conexión y Connection.status() retorna el estado closed. Se emite cuando se llama a Connection.reject().

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

Nota: Esta función se activa mediante un indicador que se pasa a Device.setup: enableRingingState. De forma predeterminada, este evento no se activará.

Se emite cuando la conexión avanza al estado ringing. Por defecto, el verbo Dial de TwiML se conectará de inmediato y este estado será breve o se omitirá por completo. Cuando se utiliza el verbo Dial con el indicador answerOnBridge=true, el estado ringing comenzará cuando el destinatario de la llamada reciba la notificación de llamada y avanzará a open después de que la acepte o avanzará a closed si rechaza la llamada o esta se cancela.

El argumento hasEarlyMedia es un booleano que indica si hay recursos multimedia disponibles enviados de forma temprana por el destinatario de la llamada. Si es true, el SDK de Client reproducirá automáticamente el recurso multimedia anticipado, que a veces será un tono de llamada y otras veces será un mensaje importante sobre la llamada. Si es false, significa que no hay recursos multimedia remotos para reproducir, por lo que la aplicación podría reproducir su propio sonido de llamada saliente.

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

.on('sample', handler(rtcSample)

Registra una función controladora que se llamará cuando la conexión obtenga un objeto de muestra WebRTC. Este evento se publica cada segundo.

Datos de ejemplo
{
  "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))

Registra una función controladora que se llamará con el actual volumen de entrada y salida de la conexión en cada fotograma de animación. El controlador se llamará hasta 60 veces por segundo y dicha frecuencia se reducirá dinámicamente en los dispositivos más lentos para mantener el rendimiento. El controlador recibe inputVolume y outputVolume como un porcentaje del volumen máximo representado por un número decimal entre 0,0 y 1,0, inclusive. Este valor representa un rango de valores de decibelios relativos entre -100 dB y -30 dB.

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

Se emite cuando una métrica de calidad de llamada supera un límite.

Twilio.js emite los eventos warning cuando detecta un empeoramiento de la calidad de llamada u otras condiciones que podrían indicar que el usuario está teniendo dificultades con la llamada. Puedes implementar devoluciones de llamadas en estos eventos para alertar al usuario de un problema.

Para ver una lista completa de los eventos warning, consulta la referencia de eventos de Voice Insights Revisa los siguientes ejemplos para aprender a detectar los eventos warning y warning-cleared.

Ejemplo
connection.on('warning', function(warningName, warningData) {
  if (warningName === 'low-mos') {
    showQualityWarningModal('Hemos detectado una mala calidad de llamada. Puede que experimentes una calidad de llamada deficiente.');
    console.log(warningData);
    /* Imprime lo siguiente
      {
        // Nombre de la estadística
        "name": "mos",

        // Arreglo de valores mos en las últimas cinco muestras que provocaron la advertencia
        "values": [2, 2, 2, 2, 2],

        // Arreglo de las muestras recopiladas que provocaron la advertencia.
        // Revisa el formato del objeto de muestra aquí https://www.twilio.com/docs/voice/client/javascript/connection#sample
        "samples": [...],

        // La configuración del umbral.
        // En este ejemplo, se generará una advertencia de puntuación mos baja si el valor es menor que tres
        "threshold": {
          "name": "min",
          "value": 3
        }
      }
     */
  }
});

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

Se emite cuando una métrica de calidad de llamada vuelve a su estado normal.

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

Referencia de propiedades

.callerInfo

.callerInfo devuelve la información de verificación del agente de llamada. Si no hay disponible ninguna información de verificación del agente de llamada, se devolverá null. El objeto callerInfo contiene los siguientes atributos:

  • isVerified: indica si Twilio ha verificado o no el número de teléfono del agente de llamada utilizando la validación SHAKEN/STIR. Devuelve true si el agente de llamada fue verificado con el nivel 'A', y devuelve false si el agente de llamada fue verificado con cualquier otro nivel inferior o si falló la verificación.

Ejemplo

device.on('incoming', connection => {
  if (connection.callerInfo && connection.callerInfo.isVerified) {
    console.log('Este agente de llamada fue verificado por el operador móvil mediante el marco de autenticación de llamada SHAKEN and STIR');
  }
});

Revisa esta página para obtener más información sobre cómo realizar y recibir llamadas verificadas mediante SHAKEN/STIR hacia y desde la red telefónica pública.

.customParameters

.customParameters en un Map<string, string> que incluye todos los parámetros en TwiML enviados a la app TwiML a la que este objeto Connection se está conectado, o desde ella. Se trata de una excelente manera de pasar datos de contexto entre tu app TwiML y el SDK de Client para JS.

Ante conexiones entrantes

El mapa .customParameters de la conexión entrante contiene todos los datos enviados usando los sustantivos <Parameter> en la app TwiML.

Ante conexiones salientes

El mapa .customParameters de una conexión saliente contiene todos los datos de los parámetros en TwiML pasados a Device.connect(twimlParams). Es importante tener en cuenta que el mapa .customParameters de un agente de llamada y el mapa .customParameters del destinatario de la llamada pueden no contener los mismos datos, ya que depende de tu app TwiML elegir cuál de los datos que recibe del agente de llamada pasará al destinatario, si es que decide pasar alguno.

.parameters

.parameters contiene detalles sobre la llamada, como quién está llamando y qué marcó. El significado de estos parámetros coincide con los de los parámetros de la solicitud de Twilio Voice.

.parameters entrantes

Ante conexiones entrantes, se incluyen los siguientes parámetros:

Parámetro Descripción
CallSid Un identificador único de la llamada generado por Twilio.
AccountSid El ID de tu cuenta de Twilio. Tiene 34 caracteres y siempre comienza con las letras AC.
From El número de teléfono o identificador de cliente de la persona que inició la llamada. Los números de teléfono tienen el formato '+' y el código de país, por ejemplo +16175551212 (formato [E.164][e164]). Los identificadores de cliente comienzan con el esquema URI client:; por ejemplo, en el caso de una llamada desde un cliente llamado 'tommy', el parámetro From será client:tommy.
To El número de teléfono o identificador de cliente de la persona a la que se llama. Los números de teléfono tienen el formato '+' y el código de país, por ejemplo +16175551212 (formato [E.164][e164]). Los identificadores de cliente comienzan con el esquema URI client:; por ejemplo, en el caso de una llamada a un cliente llamado 'joey', el parámetro To será client:joey.
ApiVersion La versión de la API de Twilio utilizada para gestionar la llamada. En el caso de las llamadas entrantes, esto está determinado por la versión de la API establecida en el número al que se llama. En el caso de las llamadas salientes, se trata de la versión de la API utilizada por la solicitud API REST de la llamada saliente.
.parameters salientes

Ante conexiones salientes, se incluyen los siguientes parámetros:

Parámetro Descripción
CallSid Un identificador único de la llamada generado por Twilio.

Métodos obsoletos

Los siguientes métodos han quedado obsoletos y se eliminarán en una futura versión de twilio.js. Llamar a estos métodos generará una advertencia de obsolescencia a menos que el parámetro warnings se establezca en false al llamar a Twilio.Device.setup().

.mute()

Dejar de capturar audio del micrófono para esta conexión. Este método fue reemplazado por .mute(bool).

.unmute()

Continuar capturando audio del micrófono para esta conexión. Este método fue reemplazado por .mute(bool).

Métodos controladores

De forma adicional, Twilio Client está adoptando la interfaz estándar de EventEmitter, por lo que los eventos deben ser controlados con .on(eventName, handler) y .removeListener(eventName, handler). Con esto se reemplazan nuestros controladores heredados (como .accept(handler), .error(handler), etc.). Los siguientes métodos están obsoletos:

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

Fueron reemplazados con los siguientes eventos de 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)

Ten en cuenta que ya no hay un evento ignore. El método .ignore(handler) es en realidad un detector compatible con versiones anteriores que se utiliza con el evento .on('cancel', handler).

Calificar esta página:

¿Necesitas ayuda?

Todos la necesitamos a veces; la programación es difícil. Obtén ayuda ahora de nuestro equipo de soporte, o recurre a la sabiduría de la multitud visitando Stack Overflow Collective de Twilio o navegando por la etiqueta de Twilio en Stack Overflow.

        
        
        

        Gracias por tus comentarios.

        Selecciona los motivos de tus comentarios. La información adicional que nos brindas nos ayuda a mejorar nuestra documentación:

        Enviando tus comentarios…
        🎉 Gracias por tus comentarios.
        Se produjo un error. Inténtalo de nuevo.

        Gracias por tus comentarios.

        ¡Recomiéndanos y gana USD 10 en 3 pasos sencillos!

        Paso 1

        Obtén un enlace

        Obtén un enlace gratuito de referencia personal aquí

        Paso 2

        Regala USD 10

        Tu usuario se registra y actualiza mediante el enlace

        Paso 3

        Obtén USD 10

        1250 SMS gratuitos
        O 1000 minutos gratuitos de voz
        O 12 000 chats
        O más