- 11 May 2023
- 10 Minutes to read
- Print
- DarkLight
Custom Widget Integration
- Updated on 11 May 2023
- 10 Minutes to read
- Print
- DarkLight
Tegsoft widely supports industry-standard technologies and infrastructures to develop software for integrations, one of which is Tegsoft Widget.
Tegsoft widget is a component of the Tegsoft interface, that enables users to access certain Tegsoft services by adding this widget to their CRM.
After adding the Tegsoft widget to the CRM, along with many useful features, users will be able to receive inbound and web chat calls, make outbound and campaign calls as the agent, track the agents’ states, and so on.
And besides, if users need todevelop advanced widget integration to simplify agents' tasks such as calling a customer, getting information about the calling customer, then actions and events come into play. Users are able to set up widgets in their CRM to incorporate various external services and make them work in CRM with Action-Oriented and Event-Driven integration.
This article covers the comprehensive methods of how to develop Tegsoft Widget integration.
1. Importing Tegsoft Widget into CRM Software
There are various ways to import Tegsoft Widget into CRM software, two of them are detailed below.
1.1. Embedding Widget as Javascript
Tegsoft provides you with a small snippet of HTML code for Widget. To add script data, go to your site editor and select the page where you want to display the widget. Paste the copied script before the closing </ body> tag in the relevant HTML file. This way you will get a widget on your site.
You can access this HTML code snippet and sample widget test page by customizing the link below.
❗ Please be aware that the widget script must be placed in the BODY tag to make it work.
https://YOUR_TEGSOFT_URL/Tobe/forms/tegsoftwidgettest.html
➤ Auto Login for Javascript
The following parameters are available for auto login.
- session_type
- usercode
- clearpassword
- token
From the above parameters, either the usercode and the clearpassword should be used together or the token should be used alone. (Using the token parameter is a better method for security and stability.)
To generate tokens, please go to APIdocs.
➤ Layout Options for Javascript
The following parameters are available for layout.
- autoMaximize ➔ If the parameter value is true, the widget window will be maximized automatically when the call is received.
- style :
padding ➔ The paddingproperty is used to create space around widget content, inside of any defined borders.
borderRadius➔ The borderRadius property defines the radius of the widget's corners.
height➔ The height property sets the height of the widget. The height of the widget does not include padding, borders, or margins! Default value is 100vh. Values should be entered in units (vh, %, or px).
width➔ The width property sets the width of the widget. The width of the widget does not include padding, borders, or margins!Default value is 100vw. Values should be entered in units (vw, %, or px). - minimize➔ The Minimize button is among the four buttons at the right end of the title bar. This button has a small dash (or minus sign). The Minimize button shrinks the widget window and places it on the task bar while leaving the widget running.
By default the Minimize button is hidden. Minimize property is enabled by setting the "enable" parameter value as "true". - hideToSide➔ The Hide/Display to Side button is among the four buttons at the right end of the title bar. This button has a quillemet (or quotation marks). The Hide/Displayto Side button hides the widget window to either left/right.
By default theHide/Display to Side button is hidden.Hide/Display to Side property is enabled by setting the enable parameter value as true. - hideInIcon ➔ TheHide/Display in Icon button is among the four buttons at the right end of the title bar. This button has a small square inside a large square. TheHide/Display in Icon button close or open the widget window and places it on the widget icon while leavingthe widget running.
By default theHide/Display in Icon button is hidden.Hide/Display in Icon property is enabled by setting the enable parameter value as true. - movable➔ The Move button is among the four buttons at the right end of the title bar. This button has a vertical ellipsis (or tree vertical dots). TheMove button places the widget windowto either left/right of the screen.
By default theMove button is hidden.Move property is enabled by setting the enable parameter value as true.
The default position parameter values are left and right.
The example usage of these style parameters are given below.
<script type='text/javascript' >
window.tegsoft_widget_options = {
tegsoft_hostname: "Your_Tegsoft_URL",
layout : {
autoMaximize: true,
style : {
padding : "0px",
borderRadius : "0px",
height: "100vh",
width: "100vw"
},
minimize : {
enable : true,
},
hideToSide : {
enable : true,
},
hideInIcon : {
enable : true,
},
movable : {
enable : true,
position : "right",
},
},
};
</script>
1.2. Importing Widget with IFrame
You can import the Tegsoft widget in an IFrame with the following URL.
https://YOUR_TEGSOFT_URL/Tobe/forms/TegsoftVue/?fileName=forms/TegsoftTelecom/tegsoftWidget
Once the widget is added to the CRM it will start functioning automatically.
➤ Auto Login for IFrame
The following URL is available for auto login with Token parameter.
https://TEGSOFT_URL/Tobe/forms/TegsoftVue/?fileName=forms/TegsoftTelecom/tegsoftWidget&sessiontype=agent&token=XXXXXX
The following URL is available for auto login with Usercode and Clearpassword parameters.
https://TEGSOFT_URL/Tobe/forms/TegsoftVue/?fileName=forms/TegsoftTelecom/tegsoftWidget&sessiontype=agent&usercode=XXXXXX&clearpassword=XXXXXX
2. Initialization / Login session
Will be updated soon.
3. Events, Actions, and Data Exchange
Events and actions are occurrences that happen in the system, the system reported to you so that your code can react to them. To react to an event, an event handler is attached to it. This is a code block which runs when the event happens. When such a code block is defined to run in response to an event, it means that an event handler is registered. (Event handlers are sometimes called event listeners.)
Some data will need to be transmitted during events and actions occurring. The payload function is used to transmit these data. In telecommunications, the payload is the essential part of transmitted data.
Use following Syntax to register for receiving events:
if (window.addEventListener) {
window.addEventListener("message", onMessage, false);
} else {
window.attachEvent("onmessage", onMessage, this);
}
function onMessage(payload) {
if(!payload) {
return;
}
if(payload.type!= "message") {
return;
}
if(!payload.data) {
return;
}
if(payload.data.type != "event") {
return;
}
if(payload.data.type == "agent") {
// Handle Agent Event
}
}
After the above process is completed, the following integration parameter (Login URL) needs to be added by the relevant user account on the Tegsoft server.
clientSideCTI://parentWindowEvent|eventList=all
Use following Syntax to send actions to widget:
function sendAction(payload) {
if (!payload) {
return;
}
if (!document.getElementById("tegsoftWidgetFrame")) {
return;
}
if (!document.getElementById("tegsoftWidgetFrame").contentWindow) {
return;
}
document
.getElementById("tegsoftWidgetFrame")
.contentWindow.postMessage(payload, "*");
}
function queryStatus() {
sendAction({
type: "action",
group: "agent",
name: "queryStatus",
});
}
3.1. Actions from CRM to Widget
When you need the Widget to perform some actions (like logout, hangup, etc.) from CRM you need to post messages to the widget. In this section, protocol and examples will be described.
Payload format for actions (CRM → Widget) is given below.
{
type: "action",
group: "agent/report/message",
name: "Action Name"
data: { // Optional data for the action
}
}
For sending actions from CRM to the Widget you need to call.
The list of actions and usage examples are given below.
List of Actions
logout
ready
notReady
dial
answer
mute
unmute
hold
unhold
hangUp
sendDTMF
blindTransfer
attendedTransfer
changeActiveLine
cancelAttendedTransfer
completeAttendedTransfer
turnOnCamera
turnOfCamera
toggleCamera
➤ User Logout Action
{
"type": "action",
"group": "agent",
"name": "logout",
}
➤ Click to Call Action
{
"type": "action",
"group": "agent",
"name": "dial",
"data": {
"numberToDial": "1234567890"
}
}
}
➤ Click to Call with CTI Data Action
{
"type": "action",
"group": "agent",
"name": "dial",
"data": {
"numberToDial": "1234567890",
"ctiData": {
"variables": {
"sample1": "value1",
"sample2": "value2",
"sample3": "value3",
"CONTID": "sampleCONTID"
},
"ctiVariableNames": ["sample1", "sample2"],
"logDTMF": ["OPTION1: valueOPT1", "OPTION2: valueOPT2"]
}
}
}
➤ Set CTI Data Action
{
"type": "action",
"group": "agent",
"name": "setCtiData",
"data": {
"ctiData": {
"variables": {
"sample1": "value1",
"sample2": "value2",
"sample3": "value3",
"CONTID": "sampleCONTID"
},
"ctiVariableNames": ["sample1", "sample2"],
"logDTMF": ["OPTION1: valueOPT1", "OPTION2: valueOPT2"]
}
}
}
➤ Remove CTI Data Action
{
"type": "action",
"group": "agent",
"name": "removeCtiData"
}
➤ Get CTI Data Action
{
"type": "action",
"group": "agent",
"name": "getCtiData"
}
➤ Change Agent Status to Ready Action
{
"type": "action",
"group": "agent",
"name": "ready",
}
➤ Change Agent Status to Not Ready with Reason Action
{
"type": "action",
"group": "agent",
"name": "notReady",
"data": {
"reason": "CUSTOM_REASON"
}
}
➤ Answer the Call Action
{
"type": "action",
"group": "agent",
"name": "answer"
}
➤ Mute the Microphone Action
{
"type": "action",
"group": "agent",
"name": "mute"
}
➤ Unmute the Microphone Action
{
"type": "action",
"group": "agent",
"name": "unmute"
}
➤ Put the Call on Hold Action
{
"type": "action",
"group": "agent",
"name": "hold"
}
➤ Stop Holding the Call Action
{
"type": "action",
"group": "agent",
"name": "unhold"
}
➤ Hangup the Call Action
{
"type": "action",
"group": "agent",
"name": "hangUp"
}
➤ DTMF Action
{
"type": "action",
"group": "agent",
"name": "sendDTMF",
"data": {
"dtmf": "2"
}
}
➤ Blind Transfer Action
{
"type": "action",
"group": "agent",
"name": "blindTransfer",
"data": {
"extension": "1003"
}
}
➤ Attended Transfer Action
{
"type": "action",
"group": "agent",
"name": "attendedTransfer",
"data": {
"extension": "1003"
}
}
➤ Complete Attended Transfer Action
{
"type": "action",
"group": "agent",
"name": "completeAttendedTransfer"
}
➤ Cancel Attended Transfer Action
{
"type": "action",
"group": "agent",
"name": "cancelAttendedTransfer"
}
➤ Change Active Line Action
{
"type": "action",
"group": "agent",
"name": "changeActiveLine"
}
➤ Turn on Camera Action
{
"type": "action",
"group": "agent",
"name": "turnOnCamera"
}
➤ Turn off Camera Action
{
"type": "action",
"group": "agent",
"name": "turnOfCamera"
}
➤ Toggle Camera Action
{
"type": "action",
"group": "agent",
"name": "toggleCamera"
}
3.2. Events from Widget to CRM
When some events occur (like Hangup, Agent called, et.c) the Widget transmits these events to the parent window which is the CRM to handle with business logic. In this section protocol and examples will be described.
Payload format for events ( Widget → CRM) is given below.
{
type: "event",
group: "agent",
name: "Event Name",
data: { // Optional data for the event
}
}
The list of events and usage examples are given below.
List of Events
status
OnLogin
OnReady
OnNotready
OnAgentCalled
OnAgentRingNoAnswer
OnBlindTransferInitialized
OnBlindTransferCompleted
OnAttendedTransferInitialized
OnAttendedTransferConnected
OnAttendedTransferCompleted
OnAttendedTransferCancelled
OnAttendedTransferSwitchToPrimarySession
OnAttendedTransferSwitchToSecondarySession
OnHold
OnUnhold
OnMute
OnUnmute
OnAttendedTransferInitialized
OnAttendedTransferConnected
OnAttendedTransferCancelled
OnAttendedTransferCompleted
OnAttendedTransferSwitchToPrimarySession
OnAttendedTransferSwitchToSecondarySession
OnBlindTransferInitialized
OnBlindTransferCompleted
OnIncomingCallAnswered
OnIncomingCallRinging
OnIncomingCallHangup
OnOutgoingCallInitialized
OnOutgoingCallRinging
OnOutgoingCallAnswered
OnOutgoingCallCancelled
OnOutgoingCallHangup
OnWebchatAgentCalled
OnWebchatAgentConnect
OnWebchatAgentComplete
OnInboundAgentCalled
OnInboundAgentConnect
OnInboundAgentComplete
OnCampAgentWaitContact
OnCampAgentWaitConnect
OnCampAgentWaitAcw
OnCampAgentComplete
OnCampAgentWaitComplete
➤ Status Event
{
"type": "event",
"group": "agent",
"name": "status",
"data": {
"agent": {
"ready": false,
"busy": 25,
"notReadyReason": "AFTERLOGIN",
"lastStateChange": "01:01",
"lastStateChangeDuration": 55,
"phoneAccess": false,
"popup_mode": "both",
"dialoutpopup": true,
"EXTEN": "6003",
"INTERFACE": "PJSIP/6003",
"REMOTEINTERFACE": "PJSIP/ebd37af5-260a-436f-9bdf-44bcc9b1b946/6003",
"EXTID": "6003",
"PHONETYPE": "WebRTCPhone",
"seatType": "Extension",
"UID": "57bcaee3-d33b-48ea-89af-877fdb5d649b",
"USERCODE": "test.agent",
"USERNAME": "Test",
"SURNAME": "Agent",
"DISPLAYNAME": "Test Agent",
"PHOTOURL": "/Tobe/image/themes/flat2/tegsoft_user_default.png",
"isActivityMandatory": false,
"isActivityMandatoryAfterAnswer": false,
"autoAnswerActive": false,
"STATEDURATION": 55,
"LOGINDURATION": 56,
"NOTREADYDURATION": 55,
"TOTALLOGINDURATION": 33567,
"TOTALNOTREADYDURATION": 31594,
"TALKDURATION": 0,
"INBOUND": 0,
"OUTBOUND": 0,
"TOTALCALLCOUNT": 0,
"ANSWERED": 0,
"AVGTALK": 0,
"WEBCHAT": 0,
"CAMPAIGN": 0
},
"primarySession": {
"answerDate": "2022-10-12T07:20:58.990Z",
"sessionStartDate": "2022-10-12T07:20:58.309Z",
"endDate": null,
"isMuted": false,
"isOnHold": false,
"remoteNumber": "859995",
"isRinging": false,
"isAnswered": true,
"duration": 12,
"formattedDuration": "00:00:12",
"statusMessage": "message_lastmessage10"
}
}
}
➤ Inbound Event
{
"primarySession": {
"answerDate": null,
"sessionStartDate": "2022-10-26T13:45:12.339Z",
"endDate": null,
"isMuted": false,
"isOnHold": false,
"remoteNumber": "1234567890",
"isRinging": false,
"isAnswered": false,
"duration": 0,
"formattedDuration": "00:00:00",
"statusMessage": "message_lastmessage04"
},
"UID": "5df34f9d-d91f-4e43-be33-f805fc8d84f2",
"EXTEN": "1001",
"activeCallProperties": {
"incomingCallModalVisible": true,
"SKILL": "7000",
"DIRECTION": "INBOUND",
"SKILLNAME": "Technical Support",
"dstUniqueId": "1666791910.1981",
"INTERFACE": "PJSIP/1001",
"agentUID": "5df34f9d-d91f-4e43-be33-f805fc8d84f2",
"channelName": "PJSIP/1001-00000311",
"callerId": "1234567890",
"callerIdName": "",
"REASON": "DEFAULT",
"uniqueId": "1666791896.1980",
"CONTID": "a219063a-4f04-4fe1-9789-36b8a044056d",
"SRCEVENT": "AgentCalled-1666791896.1980",
"callStatusLine1": "",
"callStatusLine2": "",
"isInCall": true,
"PHOTOURL": "/Tobe/contactImages/a219063a-4f04-4fe1-9789-36b8a044056d.png",
"CALLID": "1666791896.1980",
"answered": false
}
}
➤ Outbound (Campaign) Event
{
"primarySession": {
"answerDate": "2022-10-26T13:43:43.310Z",
"sessionStartDate": "2022-10-26T13:43:42.647Z",
"endDate": null,
"isMuted": false,
"isOnHold": false,
"remoteNumber": "859995",
"isRinging": false,
"isAnswered": true,
"duration": 5,
"formattedDuration": "00:00:05",
"statusMessage": "message_lastmessage10"
},
"UID": "5df34f9d-d91f-4e43-be33-f805fc8d84f2",
"EXTEN": "1001",
"activeCallProperties": {
"incomingCallModalVisible": false,
"agentUID": "5df34f9d-d91f-4e43-be33-f805fc8d84f2",
"REASON": "DEFAULT",
"CALLID": "1666791820.1967",
"CAMPAIGNID": "2e321272-cace-442e-b89f-e581b137e38a",
"PHONE": "123456789",
"DIRECTION": "OUTBOUND",
"callStatusLine1": "",
"callStatusLine2": "",
"isInCall": true,
"PHOTOURL": "/Tobe/image/themes/flat2//tegsoft_user_default.png",
"campaignName": "test",
"eventName": "campAgentConnect",
"CONTID": "a219063a-4f04-4fe1-9789-36b8a044056d",
"answered": true
}
}
➤ Webchat Event
{
"UID": "5df34f9d-d91f-4e43-be33-f805fc8d84f2",
"EXTEN": "1001",
"activeCallProperties": {
"incomingCallModalVisible": true,
"ENGINETYPE": "WEBUI",
"CHATID": "52537aa6-e599-48a7-8ab8-6f1f3614f550",
"REASON": "DEFAULT",
"PHONE": "1234567890",
"CONTID": "7b7828fd-755b-4e2a-a3c5-9fd793a72d93",
"DIRECTION": "CHAT",
"callStatusLine1": "",
"callStatusLine2": "",
"isInCall": true,
"PHOTOURL": "data:image/png;base64,iVBORw0gAAABIC==",
"CALLID": "52537aa6-e599-48a7-8ab8-6f1f3614f550",
"skillName": "Test_Skill",
"callerIdName": "Jane Poe",
"SKILLNAME": "Test",
"answered": false
}
}
Tegsoft makes no representations or warranties, either express or implied, by or with respect to anything in this document, and shall not be liable for any implied warranties of merchantability or fitness for a particular purpose or for any indirect, special or consequential damages.
Copyright © 2022, Tegsoft. All rights reserved.
"Tegsoft" and Tegsoft’s products are trademarks of Tegsoft. References to other companies and their products use trademarks owned by the respective companies and are for reference purpose only.