Login
    Contents x
    Custom Widget Integration
    • 11 May 2023
    • 10 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Custom Widget Integration

    • Updated on 11 May 2023
    • 10 Minutes to read
    • Print
    • Dark
      Light
    Article Summary

    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 do not forget to replace YOUR_TEGSOFT_URL in the URL with your server.

    ❗ 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

    If the value of the eventList parameter is all, all events are enabled. 
    Please check the list of events at the end of the article to give a specific event value.


    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. 

    Because the postMessage() method is asynchronous, it returns instantly. Response will be received as event, if needed.


    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"]
		}
    }
}
    ℹ️ Custom value according to Tegsoft Database Schema can be given to the variables.

    ➤  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"
 }
}
    ℹ️  As the value of reason parameter, default values such as Meeting, Technical Issue, Medical, Back Office Activity, Coaching and Other can be set or not ready reason can be customized according to the needs.


    ➤  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.

    Was this article helpful?
    What's Next
    Change password!
    Changing your password will log you out immediately. Use the new password to log back in.
    Change profile
    Success!
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.
    Logout