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. Esto es posible tanto en portales exclusivamente de contenido, aplicaciones de comercio electrónico o aplicaciones de gestión de relaciones con cliente (CRM); El conector se puede utilizar de manera independiente en cualquier entorno que soporte JavaScript. El conector de VoIPstudio permite gestionar tanto llamadas salientes (Hacer clic para llamar) como llamadas entrantes.

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.

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;
• 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;
• 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;
• 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;

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.

Autenticación (Login)

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;
• 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;

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.

La imagen superior muestra cinco pasos:

1. 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;
2. 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;
3. 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'';
4. 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'';
5. 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;
6. 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;
7. 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.