Integraciones - Conector CTI¶

El Conector CTI de VoIPstudio permite la integración del sistema de telefonía del cliente dentro de los portales web o las aplicaciones de este.

Tanto para CMS, apps de e-commerce o CRM avanzados; el conector puede ser usado como un componente independiente en casi cualquier tipo de entorno que soporte JavaScript. El connector soporta tanto llamadas salientes (click to call también conocido como c2c) como entrantes - tal como se describe más abajo:

1) Llamadas salientes - Hacer clic para llamar permite realizar llamadas haciendo clic en un número de teléfono que aparezca dentro de una página web o aplicación. Esto produce un evento en la red de VoIPstudio que generará una llamada al terminal SIP (teléfono IP o Softphone) del usuario. Una vez el usuario ha respondido a esta llamada se le conectará automáticamente con el número que había marcado.

2) Las llamadas entrantes recibidas desde la red pública (Red de telefonía tradicional) generan notificaciones de su estado en tiempo real (por ejemplo algunas notificaciones pueden ser: si la llamada está sonando, conectada, en espera, desconectada, etc) estos eventos o notificaciones pueden ser monitorizados y gestionados desde la aplicación del cliente.

En los dos escenarios descritos anteriormente, y una vez la llamada está establecida, el usuario puede controlar el estado de la llamada mediante la CTI Connector API de VoIPstudio. Por ejemplo, las llamadas en curso pueden ser transferidas a otros usuarios a números externos o desconectadas.

Figura 61.1 VoIPstudio Diagrama de conexión.

Requerimientos¶

Cti.Connector requiere que la librería - SIP para JavaScript - sip.js sea incluida antes que el código del conector. Utiliza WebSockets para mantener conexión bi-direccional permanente al servidor SIP que hace de puente entre JavaScript y la red de telefonía SIP.

Eventos del conector¶

Para integrar el Connector en su aplicación, es necesario responder a los eventos del Cti.Connector. Para poder recibir y responder a estos eventos, es necesario pasar una función como parámetro onMessage del Connector.

Nota: En el ejemplo de integración también se describe el flujo de eventos.

Tipos de eventos¶

El Connector envía (lanza) los siguientes eventos:

LOOGED_IN - después de una autenticación correcta en VoIPstudio;
TWO_FACTOR_AUTH - emitido cuando se requiere autenticación ed doble factor;
LOGGED_OUT - después de una des-autenticación correcta en VoIPstudio;
INITIAL - cuando la terminación SIP del llamante empieza a sonar - solo en llamadas salientes;
ACCEPTED - cuando la terminación SIP del llamante acepta la llamada (descuelga el teléfono) - solo en llamadas salientes;
READY - después de que la conexión con el servidor SIP haya sido establecida;
RINGING - Cuando el servidor está tratando de establecer una llamada, tanto ENTRANTE como SALIENTE;
CONNECTED - Después de que una llamada ENTRANTE o SALIENTE haya sido establecida;
ON_HOLD - cuando el llamante o el llamado ponen en espera la llamada;
HANGUP - cuando el llamante o el llamado terminan la llamada;
CANCEL - cuando la llamada no ha podido ser conectada por algún error;
INFO - cuando la acción no se ha podido ejecutar por algún motivo pero no ha habido ningún error;
SUBSCRIBED - cuando hay un evento SIP tipo subscribe - sirve para monitorizar el estado de los objetos;
ERROR - cuando aparece cualquier tipo de error, por ejemplo: nombre de usuario o contraseña incorrectas durante la autenticación, formato del número de teléfono incorrecto, o acción no permitida durante la llamada, etc.

Secuencia de eventos¶

A continuación se muestran algunos escenarios comunes:

Llamadas SALIENTES:

INITIAL - La terminación SIP del llamante está sonando
ACCEPTED - La terminación SIP del llamante ha descolgado
RINGING - el número marcado está sonando
CONNECTED - se ha establecido la conexión con el número marcado
HANGUP - la llamada ha terminado, uno de los dos extremos ha colgado

Llamadas ENTRANTES:

RINGING - el teléfono del usuario esta sonando como resultado de una llamada entrante
CONNECTED - se ha establecido la conexión
HANGUP - la llamada ha terminado, uno de los dos extremos ha colgado

Estructura de los eventos¶

Existen dos tipos de evento:

activity eventos de actividad: LOOGED_IN, LOGGED_OUT, READY, INFO, ERROR;
call eventos de llamada: INITIAL, ACCEPTED, RINGING, CONNECTED, ON_HOLD, HANGUP, CANCEL;

cada evento tipo activity mandado por el conector Connector contiene dos atributos:

name - nombre del evento;
message - mensaje del evento con una descripción/motivo;

Ejemplo de eventos:

{
    name: "READY",
    message: "Connection with SIP server has been successfully established."
}

Cada evento tipo call contiene también dos atributos:

name - nombre del evento;
call - los detalles de la llamada, tal como se describen a continuación;

{
    name: "CONNECTED",                      // nombre del evento
    call: {
        id: "1432310571129"                 // identificador único de la llamada
        cid: "100"                          // identificador de la llamada dentro del conector (interno)
        cause: ""                           // motivo o detalles del evento: CANCEL o HANGUP
        destination: "+123456789"           // número llamado
        destinationName: "John Smith"       // nombre del llamado, si está disponible
        direction: "OUTBOUND"               // Dirección de la llamada: INBOUND(entrante) / OUTBOUND(saliente)
        source: "anonymous"                 // Numero de presentación del origen, si está disponible
        sourceName: "anonymous <anonymous>" // Nombre del origen, si está disponible
        status: "CONNECTED"                 // Estado de la llamada
    }
}

Posibles estados de la llamada (igual que los eventos):

INITIAL - cuando el teléfono del llamante está sonando - solo para llamadas salientes;
ACCEPTED - cuando el teléfono del llamante acepta la llamada (descuelga el teléfono) - solo para llamadas salientes;
RINGING - cuando esta sonando la llamada en el llamado;
CONNECTED - cuando el llamado acepta la llamada (descuelga el teléfono)
ON_HOLD - cuando el llamante o el llamado ponen en espera la llamada;
HANGUP - cuando el llamante o el llamado terminan la llamada;

Posibles direcciones de la llamada

OUTBOUND - para llamadas salientes;
INBOUND - para llamadas entrantes;

API del Conector¶

El Connector ofrece las siguiente llamadas de la API:

login - utilizado para autenticar al usuario en la aplicación de VoIPstudio y para abrir nuevas conexiones con el servidor SIP;
twoFactorAuth - se utiliza para pasar el código de autenticación de doble factor;
logout - utilizado para des-autenticar al usuario y cerrar la conexión;
isConnected - utilizado para indicar si el usuario ya está autenticado y conectado a VoIPstudio;
answer - utilizado para responder a una llamada entrante en estado de timbre. Nota: este método funciona a partir de la versión 3.0.50 del softphone de escritorio de VoIPstudio.
call - utilizado para lanzar una nueva conexión con un número de destino;
terminate - utilizado para terminar una llamada en curso;
transfer - utilizado para transferir una llamada en curso a otra extensión;
subscribe - permite crear una suscripción para recibir eventos de llamada para objetos distintos del usuario con el que se esta conectado.

A continuación se describen todos estos métodos.

Creando el conector¶

Para crear una instancia/variable de Connector es necesario definir la función y pasarla dentro de la variable:

// Función que será llamada cada vez que el conector envía un evento
var onMessageCallback = function(event) {
    console.info("Event received" + event.name);
    if (event.name === Cti.EVENT.READY) {
        document.title = "Connector is ready";
        // ...
    }
    // incluir su código aquí
}
var connector = new Cti.Connector({
    // callback
    onMessage: onMessageCallback
});

Después de configurar el Connector, podemos comenzar a usar la API del conector.

Parámetros necesarios:

username - es la dirección e correo proporcionada durante el registro en voipstudio.es
password - contraseña del usuario

o:

apip_key - Clave REST API asignada a la cuenta del usuario;

Para verificar que el usuario ya ha sido autenticado y que el conector está conectado, utilizaremos el método isConnected.

connector.isConnected(); // de momento devolverá falso

Si el usuario aún no está conectado, el primer paso es entrar en la aplicación de VoIPstudio:

var email = "user@example.com",
    password = "secretpass";
connector.login(email, pass);

o:

var apiKey = "%%rest_api-key%%";
connector.login(apiKey);

Después del intento de acceso el Connector puede enviar los siguientes eventos:

LOGGED_IN - si el acceso es correcto;
TWO_FACTOR_AUTH - si se requiere un código de autenticación de dos factores - proceda a twoFactorAuth descrito a continuación
READY - tan pronto como la conexión con el servidor SIP este establecida;
ERROR - si ocurre un error;

Autenticación doble factor¶

Parámetros necesarios:

authCode - código válido de autenticación de dos factores
nonce - cadena nonce devuelta por la llamada anterior al método login

Tras el intento de autenticación, Connector enviará los siguientes eventos:

LOGGED_IN - si el acceso es correcto;
READY - tan pronto como la conexión con el servidor SIP este establecida;
ERROR - si ocurre un error;

Des-autenticación (logout)¶

Si el usuario esta autenticado y conectado, podemos desconectarlo con el método de logout:

connector.logout();

Después de esto el Connector puede devolver los siguientes eventos:

LOGGED_OUT - si se ha podido des-autenticar correctamente al usuario;
ERROR - si ha ocurrido un error;

llamada¶

Parámetros necesarios:

destination - número de teléfono destino en formato E164 o una extensión interna sin caracteres especiales;

Para hacer una llamada al método call debemos incluir el número de destino como parámetro:

var destination = "+123456789";
connector.call(destination);

Después de esto el Connector puede devolver los siguientes eventos:

INITIAL - Cuando el teléfono SIP llamante recibe la llamada - solo para llamadas salientes;
ACCEPTED - Cuando el teléfono SIP llamante acepta la llamada (descuelga el teléfono) - solo para llamadas salientes;
RINGING - para informar a la aplicación que la llamada saliente se está estableciendo. En llamadas salientes el evento RINGING aparece después de que el llamante acepte la llamada.
CONNECTED - cuando el llamado responde a la llamada;
INFO - si no se ha podido ejecutar la acción;
ERROR - si ha ocurrido un error;

Colgar¶

Parámetros necesarios:

callId - identificador único de la llamada que ha sido generado/recibido durante los eventos de RINGING / CONNECTED; Este identificador debe ser almacenado para identificar la llamada y los eventos relacionados con esta;

Para terminar una determinada llamada, el método terminate debe ser llamado con el parámetro callId:

var callId = "1432549154470";
connector.terminate(callId);

Después de esto el Connector puede devolver los siguientes eventos:

HANGUP - cuando la llamada ha sido colgada de manera satisfactoria;
INFO - si la acción no se ha podido ejecutar;
ERROR - si ha ocurrido un error;

transferencia¶

Parámetros necesarios:

callId - identificador único de la llamada que ha sido generado/recibido durante los eventos de RINGING / CONNECTED; Este identificador debe ser almacenado para identificar la llamada y los eventos relacionados con esta;
destination - número de teléfono de destino de la llamada en E164 formato o una extensión interna sin caracteres especiales;

Para transferir una llamada a un número dado, el método transfer debe ser llamado con los parámetros callId y destination:

var callId = "1432549154470",
    destination = "+987654321";
connector.transfer(callId, destination);

Después de esto el Connector puede devolver los siguientes eventos:

HANGUP - cuando la llamada ha sido transferida de manera satisfactoria;
INFO - si la acción no se ha podido ejecutar;
ERROR - si ha ocurrido un error;

Parámetros necesarios:

node - cadena en formato node_type:node_id que describe el objeto al que queremos suscribirnos para llamar a eventos.

Los valores validos para node_type son:

* `user`
* `ivr`
* `queue`
* `conf`

Por ejemplo, para suscribirse a los eventos de llamada del ID de usuario 12345:

connector.subscribe('user:12345');

Después de la suscripción exitosa los siguientes eventos serán enviados por Connector:

SUBSCRIBED - si se ha podido suscribir correctamente al objeto;
ERROR - si ha ocurrido un error;

getSubscriptionURIs¶

Devuelve una matriz de URI de suscripciones a eventos de llamada activos, por ejemplo:

var subscriptions = connector.getSubscriptionURIs();
console.log(subscriptions);
$ [ '10002@eu.sip.ssl7.net', 'conf:123456@eu.sip.ssl7.net' ]

Ejemplo de implementación - Cti.Platform¶

Para una mejor compresión hemos creado un ejemplo de implementación que utiliza el conector Cti.Connector para crear una interfaz Hacer clic para llamar. Con esto pretendemos ilustrar lo fácil que que es de integrar. Puede encontrar el ejemplo en el repositorio Connector CTI.

Figura 61.2 VoIPstudio Ejemplo de integración del Connector.

La imagen superior muestra cinco pasos:

Puesta a punto de la plataforma: El Connector y los otros archivos JavaScript han sido cargados, el usuario aún no está autenticado; El primer paso es conectarse a la aplicación de VoIPstudio con el Cti.Connector. Para ello hace falta proporcionar un e-mail y una contraseña válidos de su VoIPstudio; Introducir datos inválidos hará aparecer el evento de ERROR con el mensaje correspondiente;
El conector está READY: después de una autenticación correcta recibiremos el evento LOGGED_IN, y posteriormente, cuando la conexión haya sido establecida recibiremos el evento READY - En este punto ya podemos recibir y realizar llamadas;
Realizar llamadas salientes: después de introducir un número de teléfono y hacer clic en el botón Outbound call, el Connector enviará el evento INITIAL. Esto implica que el llamante está recibiendo la llamada, para aceptar la llamada. Esto solo pasa en llamadas salientes;
Después de que el llamante (haya descolgado el teléfono), el Connector enviará el evento de ACCEPTED. Ahora empezará a sonar la llamada en destino. Si el llamado no acepta la llamada, por ocupación o no respuesta, el Connector devolverá un evento de CANCEL especificando la causa en el campo cause. Esto solo pasa en llamadas salientes;
El Connector enviará en evento de RINGING para notificar a nuestra app que está intentando establecer una conexión - El teléfono del llamado está sonando; si no se ha podido establecer la conexión, aparecerá un evento de ERROR especificando la causa;
Recibir llamadas entrantes: cuando se esté estableciendo la conexión, el connector enviará el evento de RINGING con la información del llamante. Esta información puede ser utilizada para identificar al llamante, abra el histórico de llamada para ver los detalles del llamante;
La llamada está ahora conectada CONNECTED: cuando el llamado responde nuestra llamada saliente o después de atender una llamada entrante, en conector enviará el evento de CONNECTED lo que significa que la llamada ha sido establecida. Con una llamada en curso podemos terminarla o transferirla a otro número de teléfono. Después de terminar o transferir la llamada volveremos al paso 1.

Recomendamos familiarizarse con esta integración. La hemos llamado Cti.Platform ya que contiene el código necesario para integrar el Cti.Connector con una app de ejemplo creada con Bootstrap.

Con el código de ejemplo usted puede autenticarse en VoIPstudio y realizar, recibir o transferir llamadas. Estas funciones básicas pueden ser ampliadas de manera sencilla en base a las necesidades del cliente.

Integraciones - Conector CTI¶

Requerimientos¶

Eventos del conector¶

Tipos de eventos¶

Secuencia de eventos¶

Estructura de los eventos¶

API del Conector¶

Creando el conector¶

Autenticación (Login)¶

Autenticación doble factor¶

Des-autenticación (logout)¶

llamada¶

Colgar¶

transferencia¶

subscribe¶

getSubscriptionURIs¶

Ejemplo de implementación - Cti.Platform¶