Introduction

The Telenia widget library permits to connect your customer with operator logged on your TVox server using all licensed comunication channels.

The Telenia widget library delivers 2 functions:

• server connection interface.
• draw graphic elements to use server connection interface.

You can init server connection interface without use the graphic component.

Network

The server connection is initialized via https on port 443.

For video comunication WebRTC protocol is used. Ice server port comunication is 3478. Audio/video data is on DTLS through ports between 10000 and 20000.

External library used

This library and our demo need external library:

• RxJS - 5.5.8
• JQuery - 1.12.4 - this is necessary for IE11 compatibility
• Promise Polyfill - 7.1.2 - this is necessary for IE11 compatibility

For WebRTC on IE11 we check to load an Active-X powered by Frozen Mountain, as default this file is load from your server installation.

Widget

To use widget in your code you need to define a Widget object.

constructor(configuration: WidgetConfiguration)

In the constructor we need to pass the widget configuration.

var widget = new Widget(widgetConf)

In this section are described the main methods of widget.

onLoadClientComplete

onLoadClientComplete(action: function): void

This method requires a function that will be called after the creation of the widget object and when the client is ready to work.

var widget = new Widget(widgetConf)

widget.onLoadClientComplete(function() {

    console.log("I'm ready to work!")

    //for example we can log connection status
    widget.client.connectionEvent.subscribe(function (connectionEvent) {
        if(connectionEvent.connected) {
            console.log("Connected")
        } else {
            console.log("Not connected")
        }
    })
}

getServiceStatusForChannel

getServiceStatusForChannel(service: string, channel: MultiChannelType): Observable<ServiceStatus>

Get observable of service status by channel. After the subscription, all changes in the service status will be notified. Throw Error if service on channel is unmonitored as defined in configuration.

var widget = new Widget(widgetConf)

widget.onLoadClientComplete(function() {

    //for example we can log service status
    widget.client.getServiceStatusForChannel("service0001", "VIDEO").subscribe(function (statusForChannel) {
        if(statusForChannel && statusForChannel.service && statusForChannel.channelId && statusForChannel.status){
            console.log(`In channel ${statusForChannel.channelId} the status of service ${statusForChannel.service} is  ${statusForChannel.status}`)
        }
    })
}

widgetVisitUri

widgetVisitUri(linkableUri?: string, uri?: string, uriDisplay?: string): Promise

If the widget is displayed on many pages of the company site, the widget can send information to the server about the page of the site visited by the customer. The agent who answers a chat, phone call or video call with the customer can view this information in Tvox Web Client

document.location.href

var widget = new Widget(widgetConf)

widget.onLoadClientComplete(function() {
    widget.widgetVisitUri(document.location.href, document.location.pathname, document.title)
})

sendCustomerIdentifier

sendCustomerIdentifier(channel: MultiChannelType, service: string): void

When the customer decides which channel and service to use to communicate with contact center, the widget must inform the server of this decision.

Service is a string of service id.

var widget = new Widget(widgetConf)

widget.onLoadClientComplete(function() {
    widget.sendCustomerIdentifier("CHAT", "service0001");
})

disconnect

disconnect() :void

Disconnect widget from server

getChannelsEnabled

getChannelsEnabled(): { [key: string]: boolean }

were key is string of MultichannelType and boolean specify if channel is enabled or not on server

Chat

To use chat in your code you need to define a ChatSession object.

newChatSession(service: string, fields?: MultiChannelSessionCustomField[], chatCustomerDisplayName?: string, chatCustomerValue?: string): ChatSession

This object is the basis for a chat session and with this object we have access to all chat session methods. It is necessary to pass the chosen service and, optionally, the customer's name and e-mail. If you have already set up customer information in the configuration, there is no need to pass it now. If you don't pass any names and emails and have not set up customer information in the configuration, the agent on the web client will receive an anonymous chat request.

Param fields is not available in this version.

var chatSession = widget.newChatSession("support0001", null, "Mario Rossi", "rossimario@example.com");

createChatChannelSession

createChatChannelSession(): Promise<ChatChannelSession>

Send a request to TVox to start a chat session with an agent. javascript var chatSession = widget.newChatSession("support0001", null, "Mario Rossi", "rossimario@example.com"); chatSession.createChatChannelSession() .then((result) => { console.log(`Result of chat session creation: ${JSON.stringify(result)}`) }).catch((err) => { console.log(`Error of chat session creation: ${JSON.stringify(err)}`) })

getChatChannelSessionMonitor

getChatChannelSessionMonitor(): Observable<ChatChannelSession>;

Use this method to get notifications of session status. Subscribe on this method after createChatChannelSession

var chatSession = widget.newChatSession("support0001", null, "Mario Rossi", "rossimario@example.com");

var sessionMonior = chatSession.getChatChannelSessionMonitor()

chatSession.createChatChannelSession()
    .then((result) => {
        sessionMonior.subscribe((sessionMonitor) => {
            //for example we can log session state
            if (sessionMonitor.sessionState) {
                console.log(`Session state notified: ${sessionMonitor.sessionState}`)
            }
        })
    })

getChatChannelEventMonitor

getChatChannelEventMonitor(): LiveResult<ChatChannelEventMessage,ChatChannelEventMessage>

Use this method to get notifications of all messages of chat channel session. Subscribe on this method after createChatChannelSession

See LiveResult documentation to learn this interface

var chatSession = widget.newChatSession("support0001", null, "Mario Rossi", "rossimario@example.com");

var sessionMonior = chatSession.getChatChannelSessionMonitor()
var eventMonitor = chatSession.getChatChannelEventMonitor()

chatSession.createChatChannelSession()
    .then((result) => {
        sessionMonior.subscribe((sessionMonitor) => {

            //if session is close stop notification on event monitor
            if (sessionMonitor.sessionState && result.sessionState == "CLOSED") {
                eventMonitor.stopNotification();
            }
        })

        eventMonitor.result.subscribe((eventMonitorResult) => {
            console.log(`Event monitor result is: ${JSON.stringify(eventMonitorResult)}`);
        });

        eventMonitor.notification.subscribe((eventMonitorNotification) => {
            switch (notification.status) {
                case "WROTE":
                    // The message is wrote, check the direction and show the sent / received message
                    break
                case "COMPOSING":
                    // Someone is composing a message, check direction and show composing icon
                    break;
                case "IDLE":
                    // Nobody is composing a message, hide the composing icon
                    break;
            }
        })
    })

chatSendMessage

chatSendMessage(message: string, status: ChatChannelEventMessageStatus, notifyGreetingMessage: boolean): Promise<boolean>

Send a message to this chat session. You must pass the message, the status and notifyGreetingMessage. If notificationGreetingMessage is true, this message will be displayed as a message sent by the agent and not by the customer. Use this function to send a personalized welcome message from the widget to Tvox or to send the history of a previous chat with an external bot.

You can send message only when sessioMonitor.step.type is "CONNECTED".

var chatSession = widget.newChatSession("support0001", null, "Mario Rossi", "rossimario@example.com");

var sessionMonior = chatSession.getChatChannelSessionMonitor()

chatSession.createChatChannelSession()
    .then((result) => {
        sessionMonior.subscribe((sessionMonitor) => {
            if (sessionMonitor.sessionState && result.sessionState === "ACTIVE") {
                if(sessionMonitor.step && sessionMonitor.step.type && sessionMonitor.step.type === "CONNECTED" ) {
                    chatSession.chatSendMessage("Can I get some help, please?", "WROTE", false);
                }
            }
        })
    })

chatChannelReceivedMessage

chatChannelReceivedMessage(messageId: string): void

Inform the server that the widget received the message, messageId is the id of the message received.

chatChannelReadMessage

chatChannelReadMessage(messageId: string): void

Inform the server that the widget has read the message, messageId is the id of the message read.

chatSendRecapOfSession

chatSendRecapOfSession(mail: string): Promise<boolean>

Send a copy of chat session to customer by e-mail. To use this method, TVox must have MAIL channel enabled and configured for manage tickets.

chatChannelSessionClose

chatChannelSessionClose(): void

Close chat channel session and stop session notification

Video

To use the video channel on your code, you must be sure that the "webrtc" parameter is present in the server parameter of the widget configuration.

When a real-time session is established, use the WebrtcManager class to manage the devices.

videoChannelSessionMonitor

videoChannelSessionMonitor(): Observable<VideoChannelSession>

Get monitor of video channel session

var monitor = widget.videoChannelSessionMonitor()
monitor.subscribe(function (result) {
    //for example, we can log the state of the session and if the session is IDLE, we stop monitoring the session
    if (result.state) {
        console.log(`Session state is ${result.state}`)
        if(result.state === 'IDLE') {
            widget.videoChannelSessionMonitorStop()
        }
    }
})

videoChannelSessionMonitorStop

videoChannelSessionMonitorStop(): void

Stop notification of video channel session

videoChannelSessionNew

videoChannelSessionNew(service: string, customerName?: string, customerMail?: string): Promise<string>

Create a video channel session. The service id must be specified. The customer's name and email are optional. If you have not already configured customer information in the widget configuration and do not set the customer name in this method, the agent in the TVox client will receive an anonymous video call

This method return a promise with session id.

videoChannelSessionClose

videoChannelSessionClose(sessionId: string): Promise<boolean>

close a video channel session. You must pass the session id of the active video session.

var sessionId = ''
widget.videoChannelSessionNew("support0001").then(function(result) {
    sessionId = result
})

...
...

widget.videoChannelSessionClose(sessionId).then(function(result){
    if(result) {
        console.log("Session closed")
    }
})

Call

To use the Call channel on your code, you must be sure that the "webrtc" parameter is present in the server parameter of the widget configuration.

When a real-time session is established, use the WebrtcManager class to manage the devices.

callChannelSessionMonitor

public callChannelSessionMonitor(): Observable<CallChannelSession>

Get monitor of call channel session

callChannelSessionMonitorStop

Stop notification of call channel session

callChannelSessionNew

callChannelSessionNew(service: string, customerName?: string, customerMail?: string): Promise<string>

Create a call channel session. The service id must be specified. The customer's name and email are optional. If you have not already configured customer information in the widget configuration and do not set the customer name in this method, the agent in the TVox client will receive an anonymous call session.

This method return a promise with session id.

callChannelSessionClose

callChannelSessionClose(sessionId: string): Promise<boolean>

close a call channel session. You must pass the session id of the active call session.

WebRTCManager

This class manages webrtc sessions. With methods of this class it is possible to manage all the communication functions in real time.

toggleAudioMute

toggleAudioMute(sessionId: string): Promise<boolean>;

Enable / disable microphone. The session starts with audio enabled, the microphone is deactivated the first time you use this method, and then it is restored at the second use. You have to pass the sessionId.

widget.client.webrtc.toggleAudioMute(sessionId);

toggleVideoMute

toggleVideoMute(sessionId: string): Promise<boolean>;

Enable / disable webcam. The session starts with video enabled, the webcam is deactivated the first time you use this method, and then it is restored at the second use. You have to pass the sessionId.

widget.client.webrtc.toggleVideoMute(sessionId);

Interfaces

WidgetClient

WidgetConf

var widgetConf = {
    server: {
      url: "https://contact.teleniasoftware.com"
    },
    servicesConfiguration: [
        {
            type: "CHAT",
            services: [
                {
                    code: "service0001",
                    descritpion: "Commercial service"
                },
                {
                    code: "service0002",
                    descritpion: "Support service"
                }
            ]
        }
    ],
    customerInfo: {
        customerDisplayName: "Mario Rossi",
        customerValue: "rossimario@example.com"
    }
  };

ServerInterface

var server = {
    url: "https://contact.teleniasoftware.com"
}

ChannelServicesConfiguration

Configurarion of single channel

var channelServiceConfiguration = {
    type: "CHAT",
    services: [
        {
            code: "service0001",
            descritpion: "Servizio commerciale"
        },
        {
            code: "service0002",
            descritpion: "Servizio assistenza"
        }
    ]
}

ServiceConfiguration

Configurarion of services

CustomerInfo

Customer information

var customerInfo = {
    customerDisplayName: "Mario Rossi",
    customerValue: "rossimario@example.com"
}

ServiceStatus

Service's status notified

ConnectionEvent

LiveResult

LiveResult

LiveResult is an interface used in sessions for notification subscribes. It is composed by two observables, one for the result of notification request and one for future notifications. When notifications aren't needed yet, the method stopNotification stops them.

ChatChannelEventMessage

Chat message interface

ChatChannelSession

Extends MultiChannelSession

VideoChannelSession

Extends MultiChannelSession

CallChannelSession

Extends MultiChannelSession

MultiChannelSession

MultiChannelStepUnion

Step for channel session, this interface is generic for all channel session.

MultiChannelStepQueue | MultiChannelStepPlay | MultiChannelStep | MultiChannelStepToUrl | MultiChannelStepInactivityTimeout

MultiChannelStepQueue

Queue step, when session is on queue. Extends MultiChannelStep

MultiChannelStepPlay

Play step, when session is play something to customer. Extends MultiChannelStep

MultiChannelStepToUrl

Session's action that say to change page uri. Please redirect to uri. Extends MultiChannelStep

MultiChannelStepInactivityTimeout

Connection is expiring for inactivity timeout. Extends MultiChannelStep

MultiChannelStep

WebrtcConfig

Webrtc configuration

Enum

MultiChannelType

Enum of channel type

ConfigurationStatus

Service or channel configuration

ServiceStatusValue

Service status

ChatChannelEventMessageStatus

ChatMessageType

Direction

MultiChannelState

MultiChannelStepType

TrickleIcePolicy

IceGatherPolicy

CallState

Use and Demo

The widget directory is made up of 3 directories

• cross-storage
• dist
• demo

cross-storage use is not available in this version.

The javascript library to be imported into your project is in dist/bundle.

To show an example of using the widget library, a demo per channel is available in the source code.

Chat & Bot integration

The chat demo shows how to instantiate a chat session and how to integrate an external chat bot with the widget. The sources of this demo are:

• demo/chat.html
• demo/lib/wtest_chat.js

wtest_chat.js have a lot of comments for show how to use the library.

Before starting the demo you must configure 3 services with chat channel on TVox and you must configure an agent in a skillset with which these 3 services are associated.

When you start the demo you must set:

• the TVox url
• 3 services configured previously on your TVox

The TVox url is the TVox address like "test.teleniasoftware.com" or static IP like "X.X.X.X".

The 3 services, in this case "Assistenza","Commerciale","Amministrazione", are 3 contact center services with chat channel enabled. You have to configure them on the Tvox settings.

On the left of the screen there is an area with chat session, on the right there is an area with session log.

Send Bot History to TVox

To send the chat history about customer and bot conversation, you have to use chatSendMessage method. This method has a Boolean notifyGreetingMessage parameter. If notificationGreetingMessage is true, this message will be displayed as a message sent by the agent and not by the customer. Therefore, if you use this parameter, when the agent replies to the chat session, you can send in cronologiacl order all the messages previously written by the customer with notificationGreetingMessage set to false and send the questions asked by the bot by setting notificationGreetingMessage to true.

In the demo example the method sendBotMessages in demo/lib/wtest_chat.js shows how to send the history to agent on TVox.

Download the library pack to start demo now

Video

Available soon...

Download

Download here the library pack with demo