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

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.

enableDebug

enableDebug(target?: string)

Enable the whole log. Taget is a log filter, default is *.

disableDebug

disableDebug()

Disable all logs and enable the log only on Widget.

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, callMeOnThisNumbe?: string, fields?: MultiChannelSessionCustomField[], formId?: string, widgetID?: 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.

Chat

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

newChatSession(service: string, fields?: MultiChannelSessionCustomField[], formId?: string, widgetID?: string, firstMessage?: 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.

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.

chatSendInteractiveOption

chatSendInteractiveOption(action: ChatChannelInteractiveOptionAction) : Promise<boolean>

Sends an interactive option selected by the user within a chat session.

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, fields?: MultiChannelSessionCustomField[], formId?: string, widgetID?: 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.

The optional "fields", "formId" and "widgetID" attributes are also available for forms with custom fields. To use these attributes it is necessary to configure a widget form on Tvox Configurator.

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

echoTestertSessionNew

echoTestertSessionNew(audio: boolean, video: boolean): Subject<EchoTestSessionOb>

Start an audio and/or video streaming test with TVox checking the devices and the connection. Returns a subject who notifies the duration of the test, details during the test, and finally the test results.

client.echoTestertSessionNew(true, true).subscribe(function(testResult) {
    $info.append(`Connection test: ${JSON.stringify(testResult)}\n`);
    if (testResult.state === "SUCCESS") {
        //Test OK
    } else if (testResult.state === "FAILED") {
        //test KO
        console.log(testResul.error)
    }
});

getLocalMediaAvailable

getLocalMediaAvailable(): Promise<MediaDeviceEnabled>

Get local media enabled devices. Returns a promise with an object specifying which devices are available.

client.getLocalMediaAvailable().then((mediaDeviceEnabled) => {
    console.log(`Devices enabled: ${JSON.stringify(mediaDeviceEnabled)}\n`);
});

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

WebrtDeviceManager

This class allows you to manage audio and video devices for real time sessions

getMediaDevice

getMediaDevice(startMedia: boolean, acquireAudio?: boolean, acquireVideo?: boolean): Promise<MediaDevice>

Get an enumeration of available device. If startMedia is true it request permission to usage devices (default was audio and video if available) to retrive description of every device, otherwise return only id

widget.client.webrtc.device.getMediaDevice(true).then((devices) => {
    .....
})

setMediaDevice

setMediaDevice(audio_input: SourceInput, video_input: SourceInput | null |boolean, audio_output: SinkOutput | null, audio_signal_output: SinkOutput | null): Promise<void>

Set the devices you have chosen

testMediaDevice

testMediaDevice(audio_input: SourceInput, video_input: SourceInput, audio_output: SinkOutput, videoContainer: HTMLElement): Promise<boolean>

Start a preview of the chosen devices. The devices that want to be tested must be passed as input to the method. The videocontainer is the html element in which you want to play the video stream

stopTestMediaDevice

stopTestMediaDevice(): Promise<boolean>

Stops the preview of devices

getLocalMediaTestAudioLevel

getLocalMediaTestAudioLevel(): Observable<number>

Returns an observable that notifies the instantaneous volume of the local device audio input.

SourceInput

SinkOutput

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"
        }
    ]
}

MultiChannelServiceMonitor

Channel configuration

ServiceConfiguration

Configurarion of services

CustomerInfo

Customer information

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

ServiceStatus

Service's status notified

ConnectionEvent

Loginprofile

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

ChatChannelInteractiveOptionAction

ChatChannelInteractiveOptionReply

VideoChannelSession

Extends MultiChannelSession

EchoTestSessionObj

MediaDeviceEnabled

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

ContactIdentifierWithDisplayName

Extends ContactIdentifier

ContactIdentifier

MediaDevice

MultiChannelSessionCustomField

Enum

MultiChannelType

Enum of channel type

ConfigurationStatus

Service or channel configuration

ServiceStatusValue

Service status

ChatChannelEventMessageStatus

ChatMessageType

Direction

MultiChannelState

MultiChannelStepType

TrickleIcePolicy

IceGatherPolicy

CallState

EchoSessionState

EchoSessionError

AddressBookContactType

LoginProfileStatus

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. In this directory there are 2 identical libraries, widget.js (not minimized) and widget.3cda6a6022627fa3ef5e.js (minimized).

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

Video Demo

The video demo shows how to instantiate a video session. The sources of this demo are:

• demo/video.html
• demo/lib/wtest.js

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

Before starting the demo you must configure a service with video channel on TVox and you must configure an agent in a skillset with this service associated.

When you start the demo you must set:

• the TVox url
• customer name
• service code

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

The service is a contact center service with video channel enabled. You have to configure it on the Tvox settings.

On the left of the screen there is an area dedicated to video layout and utility buttons, on the right there is an area with session log.

When the video service is available, the video button appears on the right. Clicking on it starts a video session.

Download

Download here the library pack with demo

Changes from 10.23

This section describes the differences between the 10.23 widget and the 10.26 widget (the 10.26 widget is now renamed v2.0)

• In widget object the old observable statusEvent of widget.client has been refactored to loginProfile. See the documentation and demo for usage examples.
• In video channel, attributes have been added to the videoChannelSessionNew method to manage the ability to request custom fields from the customer. These attributes are optional, so the old use of the method is kept.
• In call channel, attributes have been added to the callChannelSessionNew method to manage the ability to request custom fields from the customer. These attributes are optional, so the old use of the method is kept.
• In chat channel the method newChatSession has been totally changed because the server side chat has changed.