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

getConntectionEvent

getConntectionEvent(): BehaviorSubject

Returns a BehaviorSubject that emits events related to the GraphQL client's connection state.

getConfiguration

getConfiguration() : <WidgetConf>

Retrieves the current configuration of the widget.

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

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.

Custom

To send custom information, use one of the following methods:

Method 1: JavaScript Variable (window.teleniaCustomerInfo)

Add a global JavaScript object to your website under the window namespace.

window.teleniaCustomerInfo = {
  firstName: 'Mario',
  lastName: 'Rossi',
  id: '123456789',
  company: ''
};

This information will automatically be read by the widget when initialized.

Method 2: URL Parameters

Pass customer information directly in the widget URL by appending the relevant parameters.

https://cc.teleniasoftware.com/apps/widget-multichannel/multichannel?widgetId=widget_default&customerFirstName=Mario&customerLastName=Rossi&customerId=123456789

Data Available During the Call

When either method is used, the data will be available through the popupInfo object with the following properties:

Mail

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

mailChannelSessionNew

mailChannelSessionNew(): Promise<string>

Create a mail channel 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 it, we have access to all chat session methods. It's 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.

Note: The fields parameter is not available in this version.

chatChannelSessionNew

chatChannelSessionNew(action: ChatChannelSessionNewAction): Promise<string>

Send a request to TVox to start a chat session with an agent.

// Assuming `widgetConf` is an object of type `WidgetConfiguration`
const widget = new Widget(widgetConf);

widget
  .chatChannelSessionNew({
    force: false, 
    service: serviceCode, 
    firstMessage: message,
    widgetId: widgetId,
  })
  .then((sessionId: string) => {
    console.log('chatChannelSessionNew SUCCESS');
    console.log('chatChannelSessionNew sessionId:', sessionId);
  })
  .catch((err: any) => {
    console.error('chatChannelSessionNew ERROR', err);
  });

chatChannelSessionMonitor

chatChannelSessionMonitor(): Observable<ChatChannelSession>;

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

// Assuming `widgetConf` is an object of type `WidgetConfiguration`
const widget = new Widget(widgetConf);

widget
  .chatChannelSessionNew({
    force: false, 
    service: serviceCode, 
    firstMessage: message,
    widgetId: widgetId,
  })
  .then((sessionId: string) => {
    console.log('chatChannelSessionNew SUCCESS');
    console.log('chatChannelSessionNew sessionId:', sessionId);

    // subscribe to chatChannelSessionMonitor
    this.client.chatChannelSessionMonitor().subscribe({
      next: (session: any) => {
        console.log('chatChannelSessionMonitor session:', session);
      },
      error: (err: any) => {
        console.log('chatChannelSessionMonitor ERROR:', err);
      }
    });
  })
  .catch((err: any) => {
    console.error('chatChannelSessionNew ERROR', err);
  }); 

chatChannelSessionMonitorStop

chatChannelSessionMonitorStop(): void;

Use this method to stop notifications of session status.

chatChannelEventSubscription

chatChannelEventSubscription(sessionId: string): LiveResult<ChatChannelEventMessage>

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

See LiveResult documentation to learn this interface

// Assuming `widgetConf` is an object of type `WidgetConfiguration`
const widget = new Widget(widgetConf);

// Subscribe to the `chatChannelEventSubscription` method on `widget`
widget.chatChannelEventSubscription(this.sessionId).subscribe(
    (chatEvent: any) => {
      console.log('chatEvent received:', chatEvent);
    },
    (error : any) => {
      console.error('chatChannelEventSubscription ERROR:', error);
    }
  );

chatSendMessage

chatSendMessage(sessionId: string, 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".

// Assuming `widgetConf` is an object of type `WidgetConfiguration`
const widget = new Widget(widgetConf);

// Sending a chat message
widget.chatSendMessage(
  sessionId,     
  message,       
  'WROTE',      
  false          
)
  .then((response: boolean) => {
    console.log('chatSendMessage DONE', response); 
  })
  .catch((err: any) => {
    console.error('chatSendMessage ERROR', err);  
  });

chatChannelReceivedMessage

chatChannelReceivedMessage(sessionId: string, messageId: string): Promise<boolean>

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

chatChannelReadMessage

chatChannelReadMessage(sessionId: string, messageId: string): Promise<boolean>

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

chatSendRecapOfSession

chatSendRecapOfSession(sessionId: string, 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(sessionId: string): Promise<boolean>

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
    if (result.state) {
        console.log(`Session state is ${result.state}`)
    }
})

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

echoTestSessionStop

echoTestSessionStop(): Promise<boolean>

Stop an audio and/or video streaming test with TVox checking the devices and the connection.

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

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.

ChatChannelSessionNewAction

Extends MultiChannelSessionNew

ChatChannelEventMessage

Chat message interface

ChatChannelSession

Extends MultiChannelSession

VideoChannelSession

Extends MultiChannelSession

EchoTestSessionObj

MediaDeviceEnabled

CallChannelSession

Extends MultiChannelSession

MultiChannelSessionNew

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

Download

Download here the library pack with demo

Changes from v3.0

• Added feature to send custom information - documentation