Client API

WhosOn Client API

Introduction

The Client API is designed to create desktop, product embedded or browser-based WhosOn Operator Client applications or to add WhosOn Operator functionality to existing applications. Using Client API, it is possible to create your own WhosOn Operator Client applications using any developer platform that supports WebSockets.

The WebSocket Client interface uses port 8013 by default. The port can be changed using the WhosOn Service Manager. The WebSocket interface only accepts connections from IP addresses in the WhosOn Server Whitelist, since it is designed to be used via a secure Web Server proxy to the WhosOn Server.

Use Cases

• Create WhosOn Operator Client applications with a much or as little functionality as you need, on any platform using any development tool.
• Embed WhosOn Operator functionality into existing in house applications.
• Create real-time dashboard views of visitor & chat activity.

Regardless of how you use the Client API, the standard WhosOn Operator Client can still be used. You can use the WhosOn Client in combination with any custom client applications you create or use your own exclusively.

API Key

An API key must be supplied with the Login command. Please contact Parker Software to obtain your API key before you start development against the Client API.

Connecting

Connect a WebSocket on URL ws://{server}:{port} (or wss://{server}:{port} for a secure connection). Replace {server} with the IP address of the WhosOn Server or the Web Server if connecting via a proxy.

Important: WebSocket connections should always be secure (wss://). If you are connecting via a proxy then the web server will need a SSL Certificate. The WhosOn Server does not - since traffic between the proxy and WhosOn will be internal. If connecting to WhosOn directly then the WhosOn Server must be assigned a certificate and the 'Secure' setting of the Client WebSocket must be enabled.

Once a WebSocket connection is established it should remain open for the duration of the Client session.

UTF8 encoding should be used for sending & receiving.

Sending Commands

JSON text is used for all messages.

All commands sent to the WhosOn Server have the following format:

{
    "Command": "commandname",
    "Parameters": [
        "param1",
        "param2"
    ]
}

Copy

The commandname is the name of the command to send to the WhosOn Server. Command names are not case sensitive. Parameters contains a list of parameters (if any) associated with the command. All parameters are case sensitive strings. If there are no parameters for a command send "Parameters": null

The Parameters list must be ordered correctly for the specific command.

Example:

{
    "Command": "Login",
    "Parameters": [
        "",
        "",
        "",
        "",
        "19.1.1",
        "0",
        "en",
        "thomas@mycompany.com",
        "test123",
        "WebClient",
        "abcdefgh223456"
    ]
}

Copy

Any numeric parameters should still be passed as strings. Any date parameters should be passed as strings in yyyy-mm-dd format.

Receiving Data

The WhosOn Server will send data to the client as events occur. This will not only be in response to commands sent, but also when events happen (Eg: A chat request or another user changing their status). Your client application should monitor for events received and process each one accordingly.

All events received are in the following format:

{
    "EventName": "eventname",
    "Header": "headerdata",
    "Data": "data"
}

Copy

Where eventname is the name of the WhosOn Server Event. The header property headerdata may contain additional parameters associated with the event, or it will be null.

The data property will either be a single string, null or an object (or list of objects).

Example:

{
    "EventName": "connected",
    "Header": "3",
    "Data": {
        "AppTitle": "WhosOn",
        "ServerBuild": "19.1.410.800",
        "RegisteredUser": "Parker Software",
        "MaxUsers": 999,
        "EvaluationVersion": false,
        "WebChartsUrl": "https://chat.mycompany.com/whosoncharts/",
        "ChatUrl": "https://chat.mycompany.com/newchat/",
        "PortalUrl": "https://chat.mycompany.com/settings/",
        "ServerUid": "8vmvcu0bfs"
    }
}

Copy

All event data sent by the WhosOn Server to your client connection will only contain data relevant to your connected user - based on the user's access rights & assigned sites. It is not possible to request or receive data outside of the connected user's scope.

Logging In

Your client must login before it can send other commands or receive events. Send the Login command:

Login (Command)

{
    "Command": "Login",
    "Parameters": [
        "authenticationstring",
        "fullname",
        "department",
        "phone",
        "version",
        "status",
        "lang",
        "username",
        "password",
        "platform",
        "apikey"
    ]
}

Copy

The authenticationstring is the WhosOn Server authentication string. It must match the server authentication string setting.

The fullname is the users' full name. This is optional. If blank or the 'Can Change Own Name On Login' user right is false then the users full name from their user record will be used. This also applies to dept and phone.

version can be a version indicator of your client app.

status is the initial status the client user should be set to (0=Online, 1=Busy, 2=BRB, 3=Away).

lang is the user's two letter language code - if blank the language assigned to the user record is used.

platform is a string showing the client platform (e.g.: 'WebClient').

apikey is your API key. You must obtain your API key from Parker Software. The supplied API key must be valid. Client IP addresses will be blacklisted on repeated login attempts with an invalid API key.

If the login in accepted, you will receive the connected event. Header will contain your Connection ID.

If the login is not accepted, your client will receive:

{
    "EventName": "msg",
    "Header": null,
    "Data": "Invalid credentials entered. Please check your login details."
}

Copy

Data will contain the reason for the login failure.

Once logged in you should not send the Login command again for the current session.

Client IP Pass Through

Normally clients using the WebSocket interface would connect using a secure WebSocket via IIS on port 443 (rather than a direct connection to the WhosOn Server). The 'X-Forward-For' header value will override the WebSocket Client IP if it exists. Client IP addresses are recorded in the UserLog table for auditing.

Security

The Client IP is checked against the global blacklist and temporary backlist on connection. Clients that send invalid commands or have multiple failed login attempts will be temporarily blacklisted. The temporary blacklist settings are configured using the WhosOn Service Manager. The Service Manager can also be used to clear the temporary blacklist.

WebSocket connection attempts from blacklisted Client IP's will be immediately refused.

Events Received After Login

Following a successful login your client will receive the following events:

• connected - the connected header.
• user - user properties for your connected user.
• sites - a list of sites that the connected user has access to.
• clients - list of connected users.
• chatting - list of current active chats.
• missedchats - list of pending missed chats (only if the user can respond to missed chats).
• clientiniserver - the server-side client custom settings (only sent if it exists).

Connected (Event)

{
    "EventName": "connected",
    "Header": "3",
    "Data": {
        "AppTitle": "WhosOn",
        "ServerBuild": "19.1.327.800",
        "RegisteredUser": "My Company",
        "MaxUsers": 999,
        "EvaluationVersion": false,
        "WebChartsUrl": "https://chat.mycompany.com/whosoncharts/",
        "ChatUrl": "https://chat.mycompany.com/newchat/",
        "PortalUrl": "https://chat.mycompany.com/settings/",
        "ServerUid": "8vmvcu0bfs"
    }
}

Copy

This is the first event your client will receive after a successful login. Header will contain your client Connection ID. The Connection ID is an integer number that is unique for your client's current connection. Data contains information about the WhosOn Server.

The PortalUrl contains a link to the WhosOn Settings Portal for the WhosOn Server you have connected to. This can be used to provide a link for client users to add or edit WhosOn Sites.

User (Event)

{
    "EventName": "user",
    "Header": null,
    "Data": {
        "User": {
            "Name": "Thomas",
            "Dept": "",
            "Email": "thomas@mycompany.com",
            "Phone": "",
            "Mobile": "",
            "Title": "",
            "MaxChats": 0,
            "Rights": "NYYYYYYYNNNYYNYYN0",
            "Admin": false,
            "Supervisor": false,
            "TeamLeader": false,
            "RequirePasswordReset": true,
            "AutoAccept": false,
            "Bot": false,
            "MinPasswordLength": 8,
            "ClientOptions": "Theme=Dark;AutoLogout=True;"
        }
    }
}

Copy

Data contains the User object which contains information about your connected user.

If the RequirePasswordReset is true in the user event, then your client should offer the user the option of changing their password. To change the password, send the ChangePassword command.

The MaxChats property contains the maximum concurrent chats that your client user can take (or zero for no limit). The WhosOn Server will stop sending new chat requests when this limit is reached (unless queuing overrides are setup).

The ClientOptions property contains any client options/settings. Client options can be set using the ClientOptions command. You can use this to store any arbitrary settings for your client application.

User Rights

The Rights string contains the users access rights as follows (Y or N characters in the following positions):

1. Can Edit Properties (allowed to login to Settings Portal)
2. Can View Reports
3. Can View Daily Summary (Site visitor totals)
4. Can Edit Local Settings
5. Can Take Chats
6. Can Send Chat Invites
7. Can Respond To Missed Chats
8. Can Chat To Other Users (User-To-User Chat)
9. Can Monitor Other Users Chats
10. Can Change Own Name On Login
11. Can Delete Chats
12. Can See Users Outside Of Own Department
13. Can Transfer Chats To Users Outside Of Own Department
14. Can Create Tickets
15. Can Start Video Chats
16. User-To-User Chats Are Stored In Database
17. Can Start Remote Control Sessions
18. Can Send Single Use Files To Visitors (0=Ask,1=Always,2=Never)

If the Rights property contains a 'S' character, then the user is the System Administrator.

If the Rights property contains an 'I' character, then the user is marked as invisible and will not show to other users.

The WhosOn Server will allow/block access depending on the rights - however your client should also observe the rights and adjust the UI accordingly.

Sites (Event)

{
    "EventName": "sites",
    "Header": null,
    "Data": {
        "Sites": [
            {
                "SiteKey": 1,
                "Name": "My Company",
                "Domain": "www.mycompany.com",
                "Paused": false,
                "UTCBias": 3600,
                "SLAWarnSeconds1": 20,
                "SLAWarnSeconds2": 40,
                "AllowEmoji": true,
                "AllowFileUpload": 2,
                "DisableFileSend": false,
                "TranslationEnabled": false,
                "CustomChatTab": true,
                "CustomChatTabTitle": "Search Google",
                "CustomChatTabURL": "https://www.google.co.uk",
                "OnDemandFields": [
                    {
                        "FieldName": "Email",
                        "FieldType": "email",
                        "Prompt": "What is your email address?"
                    },
                    {
                        "FieldName": "Reference",
                        "FieldType": "text",
                        "Prompt": "What is your reference"
                    }
                ],
                "Invites": [
                    {
                        "Number": 1,
                        "Enabled": true,
                        "Name": "Default",
                        "Desc": "Default invite after 10 seconds"
                    },
                    {
                        "Number": 2,
                        "Enabled": true,
                        "Name": "Sales",
                        "Desc": "Sales invite"
                    }
                ],
                "ProspectTypes": [
                    {
                        "Name": "Default prospect after 5 page views or 5 minutes"
                    },
                    {
                        "Name": "Looked at pricing page"
                    }
                ],
                "Alerts": [
                    {
                        "Number": 1,
                        "Name": "Google Adwords"
                    },
                    {
                        "Number": 2,
                        "Name": "Google Free"
                    },
                    {
                        "Number": 3,
                        "Name": "Default (All Other Visitors)"
                    }
                ],
                "WrapUp": {
                    "Enabled": true,
                    "Message": "Please select one of",
                    "Type": "Buttons",
                    "Options": "Option 1|Option 2",
                    "IsList": false,
                    "Required": false,
                    "Show": "Session End"
                },
                "CRM": {
                    "Enabled": true,
                    "AutoPosting": true,
                    "ShowClientForm": false,
                    "ShowClientButton": false,
                    "PostOnFormSubmit": false
                },
                "Tags": [
                    "Sales",
                    "Order Placed",
                    "Complaint"
                ]
            }
        ]
    }
}

Copy

The Sites list contains a site item for each monitored site that the connected user has access to.

The WhosOn Server will also send a site event if a site is changed via the Settings Portal.

Site Properties

The following site properties are sent for each site in the sites event. Many more properties can be configured for sites using the WhosOn Settings Portal. The properties sent in the sites event are those that are useful for operator client applications.

Property	Details
SiteKey	The unique number for the site.
Name	The name of the site as configured in WhosOn.
Domain	The domain name of the site as configured in WhosOn.
Paused	True if the site has been paused in WhosOn.
UTCBias	The UTC bias in seconds according to the timezone assigned to the site.
SLAWarnSeconds1	The number of seconds after a chat request starts (before a user picks it up) before the first 'waiting' message is sent to the visitor.
SLAWarnSeconds2	The number of seconds after a chat request starts (before a user picks it up) before the second 'waiting' message is sent to the visitor.
AllowEmoji	True if the user is allowed to send Emoji's during chat sessions.
AllowFileUpload	For visitor file uploads during chats: 0=No file upload allowed, 1=Allowed, 2=Allowed but only if user sends file upload request (FileRequest).
DisableFileSend	If True users should not be allowed to send files during chat sessions.
TranslationEnabled	True if Translation is active for the site.
CustomChatTab	True of a custom tab has been defined. If True you should add a Tab or view to chat session views and display the CustomChatTabUrl page in it.
CustomChatTabTitle	The title of the custom tab.
CustomChatTabUrl	The Url of the web page to display in the custom tab.
OnDemandFields	A list of On Demand Survey fields defined against the site. On demand fields can be requested during chat sessions. See: FieldRequest.
Invites	A list of Dynamic chat invites that can be sent to visitors. See: Invite.
ProspectTypes	A list of visitor prospect detection names defined for the site. The WhosOn Server flags visitors as 'Prospects' based on site defined Prospect Detection rules. The ProspectTypes property on VisitDetail objects gives the prospect number. If the ProspectTypes number on a visitor visitdetail is 1 then the prospect type name would be the 1st item in this list.
Alerts	A list of Site Entry Alerts defined for the site. Site entry alerts are used by the WhosOn Server to categorize visitors based on how they entered the site. The AlertNo property of *visitor events shows the Alert Number.
WrapUp	The chat 'wrapup' settings defined for the site. If Enabled is true you should offer then user the option selecting a Wrap Up value. If the Show property is 'Session End' then the wrapup should be shown when the chat closes. See: Chat Wrapup in the WhosOn Settings Portal. See Also: ChatWrapUpComplete.
CRM	The CRM Integration settings defined for the site.
Tags	Any chat tags defined for the site. See: ChatAddTags.

Clients (Event)

{
    "EventName": "clients",
    "Header": null,
    "Data": {
        "Clients": [
            {
                "Connection": 3,
                "Username": "thomas@mycompany.com",
                "Name": "Thomas",
                "Dept": "",
                "Email": "thomas@mycompany.com",
                "Status": 0,
                "StatusMessage": "",
                "Lang": "en",
                "Chats": 0,
                "MaxChats": 0,
                "Skills": "1,2,3",
                "Rights": "NYYYYYYYNNNYYNYYN0",
                "Supervisor": false,
                "TeamLeader": false,
                "Admin": false,
                "Platform": "Web Client",
                "Version": "19.1.1",
                "IPAddress": "192.168.10.43"
            },
            {
                "Connection": 4,
                "Username": "daniel@mycompany.com",
                "Name": "Daniel",
                "Dept": "",
                "Email": "daniel@mycompany.com",
                "Status": 0,
                "StatusMessage": "",
                "Lang": "en",
                "Chats": 1,
                "MaxChats": 0,
                "Skills": "2,3,4",
                "Rights": "YYYYYYYYYYNYYNYYY0",
                "Supervisor": false,
                "TeamLeader": false,
                "Admin": true,
                "Platform": ".NET Client",
                "Version": "18.0.0.492",
                "IPAddress": "192.168.10.21"
            }
        ]
    }
}

Copy

Data contains a Clients list. The list has an item for each user currently connected to the WhosOn Server that the logged in user has access to. The Connection property is the Connection ID for that user session.

Normally your client will only receive a full list of connected users after login. From then on you will receive single clientevent events, as users login or change, and clientremove events as users disconnect.

Chatting (Event)

{
    "EventName": "chatting",
    "Header": null,
    "Data": [
        {
            "SiteKey": 1,
            "Number": 2,
            "ChatUID": "19idvkff33",
            "VisitorIPAddress": "195.62.193.194",
            "VisitorSessionID": "",
            "VisitorName": "Melina",
            "WaitedSecs": 13,
            "QueuePos": 0,
            "TalkingToClientNo": 4,
            "Dept": "",
            "Lang": "en",
            "Translation": false,
            "Monitoredby": null,
            "WantsSkills": "2,3",
            "Location": "United Kingdom - Stoke on Trent",
            "Channel": ""
        }
    ]
}

Copy

Data contains a list of current chat sessions.

Your client will normally only receive a full list after login. From then on, your client will receive single chatchanged events as chats change (new chats, chat picked up by a user etc.) and chatclosed events as chats are removed.

Your client will receive all chats (that the logged in user has access to) in the chatting,chatchanged & chatclosed events. The TalkingToClientNo property contains the Connection ID of the client user that has picked up the chat. If this is zero, then the chat is available to pick up.

MissedChats (Event)

{
    "EventName": "missedchats",
    "Header": null,
    "Data": {
        "MissedChats": [
            {
                "SiteKey": 1,
                "Domain": "www.mycompany.com",
                "ChatUID": "5nb58re1u5",
                "VisitorIPAddress": "195.62.193.194",
                "VisitorSessionID": "",
                "VisitorVisitNo": 11,
                "VisitorName": "Howard Williams",
                "DNS": "1234567890.test.com",
                "Location": "United Kingdom - Stoke on Trent",
                "Dept": "",
                "Lang": "en",
                "Translation": false,
                "WantsSkills": "",
                "Started": "2019-09-15T11:25:04.543",
                "WaitedSecs": 67,
                "Email": "howard@test.com",
                "Phone": "01782822577",
                "Message": "I need some support.. Could someone contact me.",
                "MissedResponseStarted": false,
                "MissedResponseStartedBy": "",
                "MissedWantsCallback": true,
                "MissedWantsCallbackOn": "2019-09-15T11:26:33.877",
                "State": 50,
                "Channel": null
            }
        ]
    }
}

Copy

Data contains a list of pending Missed Chats (Missed chats that have not yet been responded and have not expired). Your client will not receive this event if the 'Can Respond To Missed Chats' user right is false.

The full list is only sent after login. After this individual missedchat events are sent when new missed chats are added, or existing ones responded to. A missedchatclosed event will be sent when a missed chat is removed (by another user responding to it or the missed chat expired).

You can request the detail of any missed chat by sending the GetPrevChat command.

Note: The WhosOn Server will mark any chat request as 'missed' where the visitor has started a chat (and completed the pre-chat survey) but no user picked up (even though users were available) and where the visitor leaves a message or callback request because no users were available.

ClientINIServer (Event)

{
    "EventName": "clientiniserver",
    "Header": null,
    "Data": "{clientini}"
}

Copy

Data will contain the INI string if a server-side client settings file has been created. This event will only be sent if the Client INI string exists. This Client INI is used to send custom settings to clients.

Change Password

If the RequirePasswordReset property of the user event is true, then your client should offer the user the option of changing their password. To change the password, send the ChangePassword command.

ChangePassword (Command)

{
    "Command": "changepassword",
    "Parameters": [
        "username",
        "oldpassword",
        "newpassword"
    ]
}

Copy

The WhosOn Server will respond with either with a error event or a passwordchanged event.

Note: Passwords cannot contain characters with ASCII codes less than 32, quote or : (colon) characters. Passwords must meet the Minimum Password Length setting defined in WhosOn.

PasswordChanged (Event)

{
    "EventName": "passwordchanged",
    "Header": null,
    "Data": "newpassword"
}

Copy

The ChangePassword command can be sent at any time once logged in.

Client Options

The User event contains a ClientOptions property. This is a string value that you can use to store any arbitrary options/settings for your client application. The value is stored against the user record in the WhosOn Database. You can use any format for the string, for example:

Theme=Dark;AutoLogout=True;

To save/update the options string, use the ClientOptions command.

ClientOptions (Command)

{
    "Command": "ClientOptions",
    "Parameters": [
        "Theme=Dark;AutoLogout=True;"
    ]
}

Copy

A single parameter is passed containing a string value holding the client options. You can use any formatting for the string. Once updated the value will be passed in subsequent User events for the user.

General Message Events

The WhosOn Server will send a msg event for any message that should be displayed to the client user. These are system/user related and designed to be shown to the client user.

Msg (Event)

{
    "EventName": "msg",
    "Header": null,
    "Data": "Visitor Melina has already started chatting to Daniel"
}

Copy

Error (Event)

The WhosOn Server may also send error messages. These should be displayed to the client user.

{
    "EventName": "error",
    "Header": null,
    "Data": "Access denied"
}

Copy

msg and error events could be received at any time during the client session.

'Access Denied' error messages can result in requesting data outside of the currently connected user's scope (eg: Requesting chat data for a chat belonging to a site that the user does not have access to). Too many 'Access Denied' errors will eventually result in the client being temporarily blacklisted.

Requesting Other Data After Login

After logging in you can request additional data from the WhosOn Server:

• GetSkills - gets a list of skills.
• GetFiles - gets a list of available uploaded files.
• GetCannedResponses - gets a list of canned responses.
• GetUsers - gets a list of all users.
• GetUserGroups - gets all of user groups.
• GetWorkPeriods - gets all work periods.
• GetMonthSummary - gets site traffic summary data for the last 3 months.
• GetDS - gets site traffic summary data for the current day.
• GetUserPhotos - gets avatars for users.
• GetVisitors - gets a list of live visitors.
• GetNewsFeed - gets the current news feed.

All of these are optional, however you should send the GetSkills,GetFiles & GetCannedResponses commands after login.

GetSkills (Command)

The GetSkills command can be used to get a list of all Skills (available to the connected user). The WhosOn Server will send the skills event.

{
    "Command": "GetSkills",
    "Parameters": null
}

Copy

Skills (Event)

{
    "EventName": "skills",
    "Header": null,
    "Data": {
        "1": {
            "ID": 1,
            "ParentID": 0,
            "Name": "Sales",
            "Description": "Sales skills",
            "SiteKeys": "1"
        },
        "2": {
            "ID": 2,
            "ParentID": 0,
            "Name": "Support",
            "Description": "Technical support skills",
            "SiteKeys": "1"
        }
    }
}

Copy

Data contains a sorted list of skills available for all users and sites that the connected user has access to.

GetFiles (Command)

The GetFiles command can be used to get a list of all uploaded files (available to the connected user). The WhosOn Server will send the uploadedfiles event.

{
    "Command": "GetFiles",
    "Parameters": null
}

Copy

UploadedFiles (Event)

{
    "EventName": "uploadedfiles",
    "Header": null,
    "Data": [
        {
            "FileName": "WhosOn - Brochure.pdf",
            "HashedFileName": "dfc3ffd72bb9416194aaea7c6f14b449f4629aafd2830e0b4716.pdf",
            "URL": "https://chat.mycompany.com/whosoncharts/document.aspx?f=dfc3ffd72bb9416194aaea7c6f14b449f4629aafd2830e0b4716.pdf",
            "Dated": "2019-09-21T07:41:03.59",
            "LastAccessed": "2019-09-21T07:41:03.59",
            "Size": 5165980,
            "CreatedByUser": "thomas@mycompany.com",
            "VisitorName": "",
            "VisitorUploaded": false,
            "SiteKey": 0,
            "Pinned": false,
            "SingleUse": false
        },
        {
            "FileName": "WhosOn Introduction.pdf",
            "HashedFileName": "7da1795eb8154a6ea75a2b858d5df252cc0f5c8efb219a608866.pdf",
            "URL": "https://chat.mycompany.com/whosoncharts/document.aspx?f=7da1795eb8154a6ea75a2b858d5df252cc0f5c8efb219a608866.pdf",
            "Dated": "2019-09-21T07:40:58.95",
            "LastAccessed": "2019-09-21T07:40:58.95",
            "Size": 5164359,
            "CreatedByUser": "thomas@mycompany.com",
            "VisitorName": "",
            "VisitorUploaded": false,
            "SiteKey": 0,
            "Pinned": false,
            "SingleUse": false
        }
    ]
}

Copy

Data contains a list of uploaded files that are available for the connected user.

The HashedFileName property is unique to each file (even if multiple files have the same FileName). The URL contains a link to download the file - this is the URL sent to visitors during chat sessions.

If CreatedByUser is not blank, then the file was added by a user. The SiteKey will be zero for user uploaded files - since the file is available for all sites (that the CreatedByUser has access to).

If VisitorName is not blank, then the file was uploaded by a visitor during a chat session (and the VisitorUploaded property will be True). The SiteKey will contain the SiteKey of the Site.

The Size property is the file size in bytes.

GetCannedResponses (Command)

The GetCannedResponses command can be used to get a list of all pre-defined Canned Responses (available to the connected user). The WhosOn Server will send the cannedresponses event.

{
    "Command": "GetCannedResponses",
    "Parameters": null
}

Copy

CannedResponses (Event)

{
    "EventName": "cannedresponses",
    "Header": null,
    "Data": {
        "154": {
            "ID": 154,
            "ParentID": 0,
            "SkillID": 0,
            "Attachments": "",
            "SiteKeys": "1",
            "Keywords": "general,responses",
            "Subject": "General",
            "Content": "General responses"
        },
        "155": {
            "ID": 155,
            "ParentID": 154,
            "SkillID": 0,
            "Attachments": "7da1795eb8154a6ea75a2b858d5df252cc0f5c8efb219a608866.pdf",
            "SiteKeys": "1",
            "Keywords": "address,parker,software,victoria,business,park,prospect,way",
            "Subject": "What is your address",
            "Content": "Our address is:\\r\\nParker Software\\r\\nVictoria Business Park\\r\\nProspect Way\\r\\nST8 7PL"
        }
    }

Copy

Data contains a list of Canned Responses setup on the WhosOn Server that are available to the user. If SkillID = -1 then the response is available to the connected user only (My Canned Response). If SkillID <> -1 then the response is global (for all users that can see the sites in SiteKeys). SkillID is not used otherwise. The SiteKeys is a comma separated list of SiteKeys that the canned response can be used on.

Each Canned Response has an ID and ParentID allowing Canned Responses to be displayed in a tree structure. The Keywords property will contain the user entered keywords assigned to the response along with keywords automatically extracted from the response by WhosOn. You can use the keywords to aid in canned response searching during chat sessions.

The Attachments property will contain files attached to the response (separated by commas). These will correspond to the HashedFileName property of the files returned in the uploadedfiles event.

GetUsers (Command)

The GetUsers command can be used to get a list of all users (available to the connected user), regardless of if the users are logged in or not. The WhosOn Server will send the users event.

{
    "Command": "GetUsers",
    "Parameters": null
}

Copy

Users (Event)

{
    "EventName": "users",
    "Header": null,
    "Data": {
        "Users": [
            {
                "Username": "thomas@mycompany.com",
                "Name": "Thomas",
                "Dept": "",
                "Email": "thomas@mycompany.com",
                "Phone": "",
                "Title": "",
                "MaxChats": 0,
                "SiteKeys": "1",
                "Skills": "",
                "Rights": "YYYYYYYYYYNYYYYYY2",
                "IsAdmin": true,
                "IsSupervisor": false,
                "IsTeamLeader": false,
                "IsBot": false,
                "KeepLog": false,
                "WorkPeriodID": 1,
                "GroupID": 1,
                "HasPhoto": false
            },
            {
                "Username": "millie@mycompany.com",
                "Name": "Millie",
                "Dept": "",
                "Email": "",
                "Phone": "",
                "Title": "Support Bot",
                "MaxChats": 0,
                "SiteKeys": "1",
                "Skills": "1,2,3,4",
                "Rights": "NNNNYNYYNNNYYNNNN0",
                "IsAdmin": false,
                "IsSupervisor": false,
                "IsTeamLeader": false,
                "IsBot": true,
                "KeepLog": false,
                "WorkPeriodID": 0,
                "GroupID": 0,
                "HasPhoto": true
            }
        ]
    }
}

Copy

The GetUsers command is optional and only required if you wish to list all available users in your client rather than just currently connected users.

The Rights property contains the user access rights as described in User Rights.

GetUserGroups (Command)

The GetUserGroups command can be used to get a list of user groups (available to the connected user). The WhosOn Server will send the usergroups event.

{
    "Command": "GetUserGroups",
    "Parameters": null
}

Copy

UserGroups (Event)

{
  "EventName": "usergroups",
  "Header": null,
  "Data": {
    "UserGroups": [
      {
        "ID": 1,
        "Name": "Sales",
        "Dept": "",
        "MaxChats": 0,
        "AutoAccept": false,
        "SiteKeys": "1",
        "Skills": "",
        "Rights": "NNYNYYYYNNNYYNNYN0",
        "IsAdmin": false,
        "IsSupervisor": false,
        "WorkPeriodID": 0,
        "Lang": "Lang",
        "INI": ""
      }
    ]
  }
}

Copy

The GetUserGroups command is optional and only required if you wish to show user group detail in your client.

The Rights property contains the user access rights as described in User Rights.

Users that are members of a group will have the GroupID property in the users event set to the Group ID.

GetWorkPeriods (Command)

The GetWorkPeriods command can be used to get a list of user work periods (available to the connected user). The WhosOn Server will send the workperiods event.

{
    "Command": "GetWorkPeriods",
    "Parameters": null
}

Copy

WorkPeriods (Event)

{
  "EventName": "workperiods",
  "Header": null,
  "Data": {
    "WorkPeriods": [
      {
        "ID": 1,
        "Description": "Default Working Day",
        "CreatedByUser": "admin@mycompany.com",
        "Day1": "09:00:00,12:30:00,13:00:00,17:30:00",
        "Day2": "09:00:00,12:30:00,13:00:00,17:30:00",
        "Day3": "09:00:00,12:30:00,13:00:00,17:30:00",
        "Day4": "09:00:00,12:30:00,13:00:00,17:30:00",
        "Day5": "09:00:00,12:30:00,13:00:00,17:30:00",
        "Day6": ",,,",
        "Day7": ",,,"
      }
    ]
  }
}

Copy

The GetWorkPeriods command is optional and only required if you wish to show user work period detail in your client.

Users that are members of a work period will have the WorkPeriodID property in the users event set to the Work Period ID.

User To User Chat

You can send a message to any user in the Clients list. Send the SendToClient command:

SendToClient (Command)

{
    "Command": "SendToClient",
    "Parameters": [
        "12",
        "Hello"
    ]
}

Copy

The first parameter in the Connection ID of the client you want to send a message. The second in the message text. The message text can be a maximum 4000 characters. The other user will receive the fromclient event.

Showing Typing Status

During a user-to-user chat you can send your client typing status. This will show in the other users chat window as an 'is typing' indicator.

To enable typing indicator, send the C1 command:

C1 (Command)

{
    "Command": "C1",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: Chat Number.

The other user will receive the C1 event.

To disable the typing indicator, send the C0 command:

C0 (Command)

{
    "Command": "C0",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: Chat Number.

The other user will receive the C0 event.

In your client application you need to enable a timer when the user presses a key in the chat message text box during user-to-user chats. If the timer was not already enabled – send the C1 command and enable the timer. If the timer is already enabled – record the time of the last keypress. In the timer event compare the last key press time with the current time and if a period of (say) 2 seconds has elapsed – send the C0 command and disable the timer.

Note: You do not need to send the C0 command before the SendToClient command. The WhosOn Server assumes the user has stopped typing when it receives a SendToClient command.

FromClient (Event)

When another client user sends you a message you will receive the fromclient event:

{
    "EventName": "fromclient",
    "Header": "12",
    "Data": "hello back"
}

Copy

Header contains the Connection ID of the sending client and Data contains the message text.

User To User Chat Typing Status

C1,C0 (Event)

When another user that you are chatting to starts typing you will receive:

{
    "EventName": "c1",
    "Header": null,
    "Data": "12"
}

Copy

Data contains the Connection ID of the client user you are chatting to.

When the other user stops typing you will receive:

{
    "EventName": "c0",
    "Header": null,
    "Data": "12"
}

Copy

Loading Previous User To User Chat Lines

The WhosOn Server stores user-to-user chats in the database. This can be enabled/disabled for each user.

If your connected user has 'User-To-User Chats Are Stored In Database' user right, you can read previous chat lines for any user-to-user chat using the GetClientChat command:

GetClientChat (Command)

{
    "Command": "GetClientChat",
    "Parameters": [
        "daniel@mycompany.com",
        "0",
        ""
    ]
}

Copy

Parameters:

• Username of the other user
• Start at lowest ID
• Search text (optional - pass a blank string for all lines)

The WhosOn Server will send the clientchat event. The other user will also need the 'User-To-User Chats Are Stored In Database' user right.

The lowest id parameter is used for paging. For each GetClientChat command the server will send a maximum of 100 lines. If the lowest id parameter is zero, then the most recent 100 lines will be sent. Each line sent contains an ID. To retrieve more lines, send the GetClientChat command again but with the lowest ID that you last received.

You can use the GetClientChat command for any user that your connected user has access to - the other user does not need to be logged in at the time.

ClientChat (Event)

{
    "EventName": "clientchat",
    "Header": "daniel@mycompany.com",
    "Data": [
        {
            "ID": 11047,
            "Dated": "2019-10-05T22:59:07.553",
            "MyLine": true,
            "Text": "hello"
        },
        {
            "ID": 11046,
            "Dated": "2019-10-05T19:05:49.707",
            "MyLine": true,
            "Text": "Hi.. this is a test"
        }
    ]
}

Copy

Header will contain the other username.

Data will contain a list of chat lines. Lines are returned in reverse order - starting with the newest.

The Dated property is the date/time of the line in UTC.

The MyLine property will be True if the line was sent by your connected user to the other user and False for the other way around.

If the 'Search Text' parameter of the GetClientChat command was specified, then only lines containing the search text will be returned.

Sending A Message To All Connected Users

If your connected user has 'Admin' user right you can send a message to all connected users (that the logged in user has access to), using the BroadCast command:

Broadcast (Command)

{
    "Command": "Broadcast",
    "Parameters": [
        "Please logout, we are updating the server."
    ]
}

Copy

Parameters: Message to send.

All users that the logged in user has access to will receive a msg event.

Changing Status

To change the current status of the connected user, send the Status command:

Status (Command)

{
    "Command": "status",
    "Parameters": [
        "1",
        "some message"
    ]
}

Copy

The first parameter is the status number: 0=Online, 1=Busy, 2=Be right back, 3=Away

The second parameter the optional and can be set to a string status message.

Whenever any user status changes (either manually or by the server) all connected users that have access to the user will receive a clientevent.

ClientEvent (Event)

{
    "EventName": "clientevent",
    "Header": null,
    "Data": {
        "Connection": 3,
        "Username": "thomas@mycompany.com",
        "Name": "Thomas",
        "Dept": "",
        "Email": "thomas@mycompany.com",
        "Status": 1,
        "StatusMessage": "some message",
        "Lang": "en",
        "Chats": 0,
        "MaxChats": 0,
        "Skills": "",
        "Rights": "NYYYYYYYNNNYYNYYN0",
        "Supervisor": false,
        "TeamLeader": false,
        "Admin": false,
        "Platform": "Web",
        "Version": "19.1.1",
        "IPAddress": "192.168.10.123"
    }
}

Copy

The clientevent will also be received when another user takes or closes a chat (IE: the Chats property changes).

Status (Event)

If your connected user's status is changed by the WhosOn Server (for example: by the users Work Period start or end time being reached), or by another user, your client will receive a status event.

{
    "EventName": "status",
    "Header": null,
    "Data": "1"
}

Copy

Data will contain your new Status number (0=Online, 1=Busy, 2=Be Right Back, 4=Away).

Changing The Status For Another User

If your connected user has 'Team Leader', 'Supervisor' or 'Administrator' user rights, you can change the current status of another connected user (that the logged in user has access to). Send the SetStatus command:

SetStatus (Command)

{
    "Command": "SetStatus",
    "Parameters": [
        "13",
        "2"
    ]
}

Copy

Parameters: Connection ID of the user you want to change, Status number:

1. Online
2. Busy
3. Be Right Back
4. Away

The other user will receive a status event.

All users will receive a clientevent indicating that the user's status has changed.

Team Leaders can only change the status of users in their own user group.

Users Disconnecting

Whenever any user logs out all other users that have access to that user will receive a clientremove event.

ClientRemove (Event)

{
    "EventName": "clientremove",
    "Header": null,
    "Data": "3"
}

Copy

Data contains the Connection ID of the user logging out.

You would use the clients, clientevent & clientremoved events to maintain a list of other connected users that you can display in your client and to do user-to-userchat.

Logging Out

When the user logs out you should send a Close command:

Close (Command)

{
    "Command": "Close",
    "Parameters": null
}

Copy

You should then disconnect the WebSocket connection.

You can just disconnect the WebSocket connection without sending close beforehand and the WhosOn Server will handle it - however it is recommended to send close first.

When The WhosOn Server Closes Your Connection

The WhosOn Server may close your connection for some reason (server shutting down or the user's properties have changed requiring a re-login). In these cases, the server will send a close event. And then disconnect the WebSocket.

{
    "EventName": "close",
    "Header": null,
    "Data": null
}

Copy

Chatting Visitors

After you have logged in your client will receive the chatting event containing a list of all current chatting visitors. After this, individual chatchanged and chatclosed events will be received for each chatting visitor.

All chatting visitors are sent to your client - for all sites that the logged in user has access to. Including chatting visitors that are chatting to other users.

ChatChanged (Event)

{
    "EventName": "chatchanged",
    "Header": null,
    "Data": {
        "SiteKey": 1,
        "Number": 1,
        "ChatUID": "5pdwevpab0",
        "VisitorIPAddress": "195.62.193.194",
        "VisitorSessionID": "",
        "VisitorName": "Howard Williams",
        "WaitedSecs": 0,
        "QueuePos": 0,
        "TalkingToClientNo": 0,
        "Dept": "",
        "Lang": "en",
        "Translation": false,
        "Monitoredby": null,
        "WantsSkills": "2,3",
        "Location": "United Kingdom - Stoke on Trent",
        "Channel": ""
    }
}

Copy

The chatchanged event will be sent for any new chat and when an existing chat changes (eg: It is picked up by a user).

The WantsSkills of the chatting and chatchanged events contains a comma-separated list of Skill ID's assigned to the chat. The WhosOn Server assigns skills to each chat based on the chat routing rules defined for the site. If the WantsSkills for a chat is blank then the chat has no specific skills and can be taken by anyone.

Once a chat is picked up by a user the TalkingToClientNo property will contain the Connection ID of the user that has taken the chat:

{
    "EventName": "chatchanged",
    "Header": null,
    "Data": {
        "SiteKey": 1,
        "Number": 1,
        "ChatUID": "5pdwevpab0",
        "VisitorIPAddress": "195.62.193.194",
        "VisitorSessionID": "",
        "VisitorName": "Howard Williams",
        "WaitedSecs": 5,
        "QueuePos": 0,
        "TalkingToClientNo": 3,
        "Dept": "",
        "Lang": "en",
        "Translation": false,
        "Monitoredby": "Daniel",
        "WantsSkills": "2,3",
        "Location": "United Kingdom - Stoke on Trent",
        "Channel": ""
    }
}

Copy

The MonitoredBy property will contain the users name if it is being monitored.

ChatClosed (Event)

{
    "EventName": "chatclosed",
    "Header": null,
    "Data": "5pdwevpab0"
}

Copy

When a chatting visitor is removed the chatclosed event will be sent. Data contains the ChatUID.

You would use the chatting, chatchanged & chatclosed events to maintain a list of current chatting visitors to display in your client.

You should update a list of chatting visitors in your client. Chats with TalkingToClientNo = 0 should be displayed separately - showing that these are waiting to be picked up.

Chat Requests

When a visitor requests a chat a chat event is sent to all connected users who can take the chat.

The WhosOn Server will handle chat routing and only send the chat event to users who are able to take the chat based on current status, skill assignments, chat routing rules, chat queuing, maximum chat settings, user rights, opening hours etc. Therefore, if your client user receives a chat event it should display a notification and offer the user the option to take it - since the WhosOn Server has already decided your user is able to do so.

Chat (Event)

{
    "EventName": "chat",
    "Header": null,
    "Data": "1:www.mycompany.com:Daniel:"
}

Copy

Header will be null.

Data contains colon separated fields:

1. Chat number
2. Domain
3. Visitor name
4. Department

You can use this event to show a new chat notification message.

A chatchanged event will also be sent (to your client and all others).

To take the chat send a Chat command:

Chat (Command)

{
    "Command": "Chat",
    "Parameters": [
        "1"
    ]
}

Copy

The first parameter is the Chat Number.

If the WhosOn Server accepts the chat take request it will send a chataccepted event:

ChatAccepted (Event)

{
    "EventName": "chataccepted",
    "Header": null,
    "Data": "3k2xq46019:2,3:https://chat.mycompany.com/newchat/"
}

Copy

Header will be null.

Data contains a colon separated fields:

1. ChatUID
2. WhatsSkillIDs (comma separated list of skill ids assigned to that chat).
3. ChatURL - not used

A chatchanged event will also be sent (to your client and all others).

If the WhosOn Server does not accept the chat take request it will send a msg event:

{
    "EventName": "msg",
    "Header": null,
    "Data": "Visitor Test Visitor has already started talking to Daniel"
}

Copy

Auto Accept Chats

The WhosOn Server may require your client to auto accept a chat instead of giving the user the option. In these cases, the acceptchat event is sent:

AcceptChat (Event)

{
    "EventName": "acceptchat",
    "Header": null,
    "Data": "1:www.mycompany.com:Test Visitor:"
}

Copy

The parameters are the same as the chat event. Your client should accept the chat by sending the Chat command as above without giving the user the option.

PreChatSurvey (Event)

After the chataccepted event has been sent the WhosOn Server will send the prechatsurvey event.

{
    "EventName": "prechatsurvey",
    "Header": "1:195.62.193.194::2:3k2xq46019",
    "Data": [
        {
            "Name": "VisitorName",
            "Value": "Howard Williams",
            "BuiltInField": "visitor name"
        },
        {
            "Name": "Company",
            "Value": "Microsoft",
            "BuiltInField": "company name"
        }
    ]
}

Copy

Header will be a colon separated list of fields:

1. Sitekey
2. Visitor IP Address
3. Visitor Session ID
4. Chat Number
5. ChatUID

Data will contain a list of pre-chat survey fields completed by the visitor.

CurrentChat (Event)

If the picked-up chat already has chat lines (for example: it was picked up by another user and has been transferred, or the visitor has sent some chat lines before the chat has been picked up), then a currentchat event will be sent. This contains all survey data & previous chat lines.

Header will be a colon separated list of fields:

1. Sitekey
2. VisitorIpAddress
3. VisitorSessionId
4. ChatUID
5. Chat Number

{
    "EventName": "currentchat",
    "Header": "1:195.62.193.194::8b2j6yur8q:1",
    "Data": {
        "SiteKey": 1,
        "VisitorIPAddress": "195.62.193.194",
        "VisitorSessionID": "",
        "VisitNumber": 15,
        "ChatUID": "8b2j6yur8q",
        "VisitorName": "Howard Williams",
        "TakenByUser": "Thomas,Daniel",
        "StartTime": "2019-09-15T14:04:57.193",
        "Email": "",
        "Phone": "",
        "LeftMessage": "",
        "FinishTime": "2019-09-15T14:06:55.27",
        "PreChatSurvey": [
            {
                "FieldName": "Company",
                "FieldValue": "Microsoft"
            }
        ],
        "Lines": [
            {
                "Dated": "2019-09-15T14:04:51.363",
                "OperatorIndex": 99,
                "Message": "Please wait. An operator will be with you shortly."
            },
            {
                "Dated": "2019-09-15T14:05:01.673",
                "OperatorIndex": 1,
                "Message": "Good Afternoon Test Visitor. My name is Stephen how can I help you?"
            },
            {
                "Dated": "2019-09-15T14:05:10.803",
                "OperatorIndex": 0,
                "Message": "Can I chat to support"
            },
            {
                "Dated": "2019-09-15T14:05:20.87",
                "OperatorIndex": 1,
                "Message": "One moment I will transfer you"
            }
        ],
        "PostChatSurvey": null,
        "WrapUpMessage": "",
        "WrapUpValues": null,
        "VisitDetail": null,
        "Key": "1:195.62.193.194::15"
    }
}

Copy

The TakenByUser property contains a comma separated list of operator names that have chatted to the visitor (there could be more than one if the chat has been transferred). The OperatorIndex property of each chat line contains the index to this list (1 based). For example if TakenByUser is set to 'Thomas,Daniel' and the OperatorIndex for a line = 2 then the line was sent by 'Daniel'.

OperatorIndex = 99 refers to lines created server-side.

If OperatorIndex = 0 then the line was sent by the visitor.

The VisitDetail property will contain the VisitDetail object (see the GetVisit command).

Transfer (Event)

{
    "EventName": "transfer",
    "Header": null,
    "Data": "1:3:Please pick up the chat session for visitor Test Visitor."
}

Copy

When another user transfers a chat, the WhosOn Server will send a transfer event to all users selected for the transfer.

Header will be null. Data will be a colon separated list:

1. Chat Number
2. Client Connection ID - of the client user sending the transfer.
3. Message - optional chat transfer message.

Note: Since 'message' could contain colons you should split the first 2 fields and assume the remaining is the message. This message can be used to show a popup, or you can create your own.

To accept the transfer, send the Chat command as with regular chats.

ChatClosed (Event)

{
    "EventName": "chatclosed",
    "Header": null,
    "Data": "8b2j6yur8q"
}

Copy

The WhosOn Server will send a chatclosed event whenever any chat is closed (including your users own chats). Chats can be closed either by the visitor or user. Data will contain the ChatUID.

Chatting

Once a chat has been accepted you can send and receive messages and perform other operations.

Sending A Message

To send a message send the SendTo command:

SendTo (Command)

{
    "Command": "SendTo",
    "Parameters": [
        "1",
        "Hello. How can I help?"
    ]
}

Copy

Parameters: Chat Number, Message Text.

The WhosOn Server will then forward the message to the visitor's chat session. The message text can be up to 4000 characters.

Handling Translation

If Translation is enabled for the Site (as indicated by the TranslationEnabled property in the Sites event) and the visitor has requested translation for their chat session (as indicated by the Translation property of the chatting visitor in the Chatting and ChatChanged events) then the WhosOn server will automatically translate messages sent by client users to visitors before forwarding the message and the translation to the visitor's chat session.

If the WhosOn server has translated the message text in the SendTo command it will send a SendToTranslated event back to the client:

SendToTranslated (Event)

{
    "EventName": "SendToTranslated",
    "Header": "1",
    "Data": "Hello. How can I help?<translated>Salut. Comment puis-je aider?</Translated>"
}

Copy

Header will contain the chat number.

You can use this event to update your chat view if you wish to show the translated text.

If you prefer to handle translation in your client using your own or 3rd party translation service, rather than the WhosOn server performing the translation, add <Translated> translated text </Translated> to the end of the message. The Lang property of the chatting visitor will be set to their 2 character language code.

If the message sent with the SendTo command already contains a <Translated> tag the server will skip translation and the SendToTranslated event will not be sent. If you are providing your own translation then the <Translated> tag can be added to messages regardless of if Translation is enabled on the Site.

Markdown

Messages sent to visitors using the SendTo command can contain 'Markdown'. Markdown is a lightweight markup language with plain text formatting syntax. See: Markdown Guide

If messages are sent containing Markdown the WhosOn Server will automatically convert the message to equivalent HTML before forwarding it to the chat session.

For example:

{
    "Command": "SendTo",
    "Parameters": [
        "1",
        "# Markdown Operator Line

        Markdown can be **bold** *italics* ~~strikethru~~

        1. List item1
        2. List item2

        | Tables        | Are           | Cool  |
        | ------------- |:-------------:| -----:|
        | col 3 is      | right-aligned | $1600 |
        | col 2 is      | centered      |   $12 |
        | zebra stripes | are neat      |    $1 |

        > This is a note"
    ]
}

Copy

Note: \n newline marks have been removed from the above message for readability.

Sending A File

To send a file send the SendFileTo command:

SendFileTo (Command)

{
    "Command": "SendFileTo",
    "Parameters": [
        "1",
        "myfile.pdf",
        "https://myserver.whoson.com/whosoncharts/document.aspx?f=fa77436dbdae4696aeee7a4b44ac86ce36bff95b0ff7ba137ed5.pdf"
    ]
}

Copy

Parameters: Chat Number, File Name, URL.

The URL should be the URL to one of the files in the uploaded files list sent with the UploadedFiles event.

Showing Typing Status

During a chat you can send your client typing status. This will show in the visitor's chat window as an 'Operator is typing' indicator.

To enable typing indicator, send the StartTyping command:

StartTyping (Command)

{
    "Command": "StartTyping",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: Chat Number.

To disable the typing indicator, send the StopTyping command:

StopTyping (Command)

{
    "Command": "StopTyping",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: Chat Number

In your client application you need to enable a timer when the user presses a key in the chat message text box. If the timer was not already enabled – send the StartTyping command and enable the timer. If the timer is already enabled – record the time of the last keypress. In the timer event compare the last key press time with the current time and if a period of (say) 2 seconds has elapsed – send the StopTyping command and disable the timer.

Note: You do not need to send the StopTyping command before the SendTo command. The WhosOn Server assumes the user has stopped typing when it receives a SendTo command.

Requesting A File

To request a file from the visitor, send the FileRequest command:

FileRequest (Command)

{
    "Command": "FileRequest",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: Chat Number.

Requesting A Dynamic Field

Dynamic Fields are pre-defined input requests with their own prompt, field type & validation rules. A list of available Dynamic Fields is sent in the Sites event. To request the visitor to complete a dynamic survey field send the FieldRequest command:

FieldRequest (Command)

{
    "Command": "FieldRequest",
    "Parameters": [
        "1",
        "Reference",
        "Please enter your reference code"
    ]
}

Copy

Parameters: Chat Number, Dynamic Field Name, Prompt Text.

The Dynamic Field Name must be one of the defined Dynamic Fieldname names.

If the prompt text is blank, then the default prompt of the selected field will be used.

The visitor must then complete the field input in the correct format in their chat session. The result of the completed field will be sent as a regular Message event.

Request Monitoring

To request that another supervisor user monitor your chat session send the RequestMonitor command:

RequestMonitor (Command)

{
    "Command": "RequestMonitor",
    "Parameters": [
        "1",
        "message"
    ]
}

Copy

Parameters: Chat Number, Request Message.

The message text is optional.

A RequestMonitor event will then be sent to all other users who are able to monitor the chat.

Block A Visitor

To block a visitor's IP address and prevent chats from that IP from starting another chat for the next 24 hours send the Block command:

Block (Command)

{
    "Command": "Block",
    "Parameters": [
        "123.456.789.101",
        "message"
    ]
}

Copy

Parameters: IP address to block. You cannot block IP's that are in the whitelist.

Mark Chat For CRM Update

If the CRM settings allow client update, you can flag a chat to be sent to the CRM when the chat ends by sending the CRMPost command:

CRMPost (Command)

{
    "Command": "CRMPost",
    "Parameters": [
        "1",
        "6y0r04w2fq",
        ""
    ]
}

Copy

Parameters: SiteKey, ChatUID, optional 'disable'.

If the last parameter is equal to 'disable' then the CRM update will be switched off if it was previously enabled.

Send Transcript

You can request that the WhosOn Server send an email transcript of the chat. This can be done at any time - during a current chat or for a previous chat. Send the SendTranscript command.

SendTranscript (Command)

{
    "Command": "SendTranscript",
    "Parameters": [
        "1",
        "6y0r04w2fq",
        "from@myserver.com",
        "tovisitor@test.com",
        "subject",
        "false",
        "message"
    ]
}

Copy

Parameters:

1. SiteKey
2. ChatUID
3. From email address
4. To email address
5. Subject
6. True/false - set to true to send a link to the transcript via SMS. If true, then the from address should be a phone number.
7. Message text - this text is shown in the message body of the email before the transcript.

Transfers

Chats can be transferred to other users, departments or skills.

To transfer a chat to another user, send the Transfer command:

Transfer (Command)

{
    "Command": "Transfer",
    "Parameters": [
        "1",
        "3,4",
        "message"
    ]
}

Copy

Parameters: Chat Number, Comma Separated list of client Connection IDs to send the transfer request to. Optional message. The WhosOn Server will send the transfer event to the client users specified.

You should check the Status of each of the other clients - and only include clients that are available (Status=0).

TransferDept (Command)

To transfer the chat to another department, send the TransferDept command:

{
    "Command": "TransferDept",
    "Parameters": [
        "1",
        "department",
        "message"
    ]
}

Copy

Parameters: Chat Number, Department name, optional message. The WhosOn Server will send the transfer event to only those client users that have a matching department.

TransferSkills (Command)

To transfer the chat to another skill, send the TransferSkill command:

{
    "Command": "TransferSkills",
    "Parameters": [
        "1",
        "skillid",
        "message"
    ]
}

Copy

Parameters: Chat Number, Comma Separated list of Skill Id's, optional message. The WhosOn Server will send the transfer event to only those client users that have all the skills specified.

Client users that receive the transfer request will receive a transfer event:

{
    "EventName": "transfer",
    "Header": null,
    "Data": "1:3"
}

Copy

Data contains the Chat Number and the client Connection ID of the client user making the transfer request.

Clients that receive this event should display a message saying that "User {name} would like to transfer a chat with {visitorname}".

The client user that wishes to take the transfer should then send a Chat command to join the chat session.

Leaving The Chat After Transfer

After sending any of the Transfer commands your client user should leave the chat, allowing other users to pick it up. Send the Leave command.

Requesting Visitor Detail

After accepting a chat, you can request additional visitor detail from the WhosOn Server by sending the GetChatVisit command. This can be displayed in a 'Visit Detail' section of the chat session view. This is optional.

GetChatVisit (Command)

{
    "Command": "GetChatVisit",
    "Parameters": [
        "1",
        "195.62.193.194",
        "123-4567890123",
        "6y0r04w2fq"
    ]
}

Copy

Parameters: SiteKey, Visitor IP Address, Visitor Session Id, ChatUID.

The WhosOn Server will respond with a visitdetailchat event.

Header will contain SiteKey:IPAddress:VisitorSessionID:ChatUID

Data will contain the visit detail.

VisitDetailChat (Event)

{
    "EventName": "visitdetailchat",
    "Header": "1:195.62.193.194:123-4567890123:6y0r04w2fq",
    "Data": {
        "SiteKey": 1,
        "SiteName": "My Company",
        "IP": "195.62.193.194",
        "DNS": "(Test) 1234567890.test.com",
        "SessionID": "123-4567890123",
        "VisitNumber": 1,
        "AlertNumber": 3,
        "TotalVisits": 15,
        "Browser": "Chrome 76",
        "OS": "Windows 10",
        "Spider": false,
        "SearchEngine": "",
        "Referer": "https://chat.mycompany.com/newchat/chat.aspx",
        "RefererQuery": "?domain=www.mycompany.com",
        "SessionStarted": "2019-09-10T14:44:47.263",
        "Cost": 0,
        "Revenue": 0,
        "Prospect": false,
        "Chatting": true,
        "Customer": false,
        "Invited": false,
        "ProspectTypes": 0,
        "FirstVisit": "2019-09-10T14:44:47.263",
        "FirstReferer": "https://www.google.com",
        "FirstAlert": 3,
        "TotalCost": 0,
        "TotalRevenue": 0,
        "ContactName": "Howard Williams",
        "ContactEmail": "howard@test.com",
        "ContactCompany": "Microsoft",
        "ContactTelephone": "01782822577",
        "ContactNotes": "",
        "ChattingLanguage": "",
        "ChattingTranslate": false,
        "OrgIsOwn": false,
        "ContactFax": "",
        "ContactStreet": "",
        "ContactCity": "",
        "ContactPostCode": "",
        "ContactCountry": "",
        "ContactWebAddress": "",
        "ContactOrganization": "",
        "ContactDated": "2019-09-10T14:45:00",
        "CRMId": "",
        "Pages": [
            {
                "Dated": "2019-09-10T14:44:01.321",
                "Name": "index.aspx",
                "Status": 200
            },
            {
                "Dated": "2019-09-10T14:44:47.263",
                "Name": "chat.aspx",
                "Status": 200
            }
        ],
        "FormFields": [],
        "GeoIP": {
          "IPAddress": "195.62.193.194",
          "IsProxy": false,
          "IsSatellite": false,
          "PostCode": "ST1",
          "Latitude": 53.0278,
          "Longitude": -2.1658,
          "Radius": 20,
          "ISP": "Internet Central Limited",
          "CountryISO": "GB",
          "CountryName": "United Kingdom",
          "City": "Stoke-on-Trent",
          "MetroCode": "",
          "Organization": "Parker Software",
          "RegionName": "",
          "RegionISO": ""
      }
    }
}

Copy

Receiving Messages

The WhosOn Server will send a message event whenever a chat message from a visitor is received.

Message (Event)

{
    "EventName": "message",
    "Header": "1",
    "Data": "Do you offer an on-premises version?"
}

Copy

Header will contain the chat number. Data will contain the message text.

Note: The message event will be sent for your own current chats and for chats that have not yet been picked up. For example: A visitor starts a chat and sends some chat lines before anyone has picked up the chat. If the Chat for the Chat Number TalkingToConnection property is zero, then you should display a notification with the message text - indicating a visitor has said something but no user has yet picked up.

Translated Text

If the message contains a translation the <Translation> text </Translation> will be appended to the message text. You should extract the translated text from the message and display this in the chat session view (along with the untranslated text).

Server Response Suggestion

The WhosOn Server will attempt to match the visitor message to a Canned Response and/or a recent previously sent message. If a match is found, then a <Suggest> tag will be appended to the message text. Eg:

{
    "EventName": "message",
    "Header": "1",
    "Data": "Do you offer an on-premises version?<Suggest>Yes, we offer an on-premises version.</Suggest>"
}

Copy

You can use this to optionally show the suggestion to the user or pre-fill the user chat text with the suggestion.

If the suggestion contains an attachment, then the <Suggest> tag will include it:

<Suggest>Yes, we offer an on-premises version
    <Attachment>dfc3ffd72bb9416194aaea7c6f14b449f4629aafd2830e0b4716.pdf</Attachment>
</Suggest>

Copy

Note: You need to remove the <Suggest> tag from the message text before showing the message in the chat view.

The WhosOn Server searches Canned Responses first. If no matching Canned Response is found it searches previous chats for responses to similar visitor messages (for recent user chats with matching skills).

MessageServer (Event)

The WhosOn Server may send messages to the visitor for chat inactivity messages or if a visitor message has been filtered due to Chat Text Rules. These messages are also forwarded to the client.

{
    "EventName": "messageserver",
    "Header": "1",
    "Data": "You havent said anything for 1 minute. Are you still there?"
}

Copy

You can show these messages in your current chat view or ignore them.

Visitor Typing Indicator

When a visitor starts or stops typing the WhosOn Server will send 1 and 0 events:

1 (Event)

{
    "EventName": "1",
    "Header": null,
    "Data": "1"
}

Copy

0 (Event)

{
    "EventName": "0",
    "Header": null,
    "Data": "1"
}

Copy

Data will contain the Chat Number. You would use this to show a 'Visitor is typing' indicator in the selected chat session. Your client will only receive these events for currently active chats.

Note: A StopTyping event will not be sent prior to a Message event. You should assume that when a visitor sends a message that they have stopped typing (for the current message).

Visitor Preview

If typing preview is enabled for the site, then the WhosOn Server will send the preview event periodically whilst the visitor is typing. This enables the user to see what the visitor has typed before the visitor sends the text:

Preview (Event)

{
    "EventName": "preview",
    "Header": "1",
    "Data": "Do you offer a on-pr"
}

Copy

Header will contain the chat number.

Data will be the text typed so far by the visitor.

File Uploads

When a visitor uploads a file during a chat the WhosOn Server will send the fileupload event:

FileUpload (Event)

{
    "EventName": "fileupload",
    "Header": "1",
    "Data": "myfile.pdf TAB url"
}

Copy

Header will contain the chat number.

Data will the file name and URL separated by a TAB character.

The URL will be the URL to the document.aspx page pointer in the WhosOn web services.

The fileupload event will be sent only to your client's active chats. However, all other clients (including yours) will also receive a fileuploaded event:

FileUploaded (Event)

{
    "EventName": "fileuploaded",
    "Header": "myfile.pdf",
    "Data": "url"
}

Copy

All client users that have access to an uploaded file will receive a fileuploaded event when a visitor uploads a file (that is not marked as single use).

This is so that other clients can update their lists of uploaded files.

Two Factor Email Validation

If a visitor supplies an email address during a chat or as part of a pre-chat survey you can request that the visitor validates it using the SendTwoFactorAuth command.

SendTwoFactorAuth (Command)

{
    "Command": "SendTwoFactorAuth",
    "Parameters": [
        "1",
        "6y0r04w2fq",
        "howard@test.com",
        "123456",
        "Please enter the code below into your chat session to verify:"
    ]
}

Copy

Parameters:

• SiteKey
• ChatUid
• Email address to validate
• Validation code to send
• Message

The WhosOn Server will then send an email to the email address given. The visitor can then enter the code into their chat session - indicating to the user that their email address is valid and that they have access to it.

If the Message parameter is blank it will default to: 'Please enter the code below into your chat session to verify:'.

The Validation code parameter should be a random code.

Once the SendTwoFactorAuth command has been sent you should wait for the Validation code to be sent back in the message events. Receiving the code back indicates that the visitor has received the email and therefore the email address must be valid.

Closing A Chat

To close a chat, send the CloseChat command:

CloseChat (Command)

{
    "Command": "CloseChat",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: Chat Number

This command should be used where the user closes the chat. The Visitor can also close a chat - in which case the chatclosed event will be sent. Your client will also receive the chatclosed event for user closed chats.

SoftCloseChat (Command)

{
    "Command": "SoftCloseChat",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: Chat Number

This command should be used when the user closes an asynchronous chat, but wants to leave open the possibility for the resumption of the chat at a later date. This marks the chat as "Soft Closed".

UncloseChat (Command)

{
    "Command": "UncloseChat",
    "Parameters": [
        "a6223a23",
        "1",
        "Y"
    ]
}

Copy

Parameters: Chat Uid, Sitekey and Y/N for assign to me.

If assign to me is Y then the server will assign it to you. If it is N then the chat will go into the waiting chat list for the next available operator.

Leaving A Chat

Your client user can leave a chat instead of closing it. Leaving a chat keeps the chat session open on the WhosOn Server - for other users to pickup.

Leave (Command)

{
    "Command": "Leave",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: Chat Number

You should send the Leave command after any Transfer commands.

Wrap Up

To add wrap up information for a chat send the ChatWrapUpComplete command.

ChatWrapUpComplete (Command)

{
    "Command": "ChatWrapUpComplete",
    "Parameters": [
        "1",
        "68739dj38jf",
        "wrap up value"
    ]
}

Copy

Parameters: SiteKey, ChatUID, Value

The chatwrapupcomplete can be sent at any time during a chat or after it has been closed.

Chat Tags

Chats can be assigned any number of tag values. Tags available for a site are returned with the Site data in the sites events. These can be overridden with any arbitrary value.

To assign tags to a chat send the ChatAddTags command.

ChatAddTags (Command)

{
    "Command": "ChatAddTags",
    "Parameters": [
        "1",
        "68739dj38jf",
        "Sales"
    ]
}

Copy

Parameters: SiteKey, ChatUID, Tags (single string with tags separated by TAB).

The chataddtags can be sent at any time during a chat or after it has been closed. Any existing tags assigned to a chat will be replaced.

Chat tags allow chats to be reported on by tag value and 'Tag Cloud' style reports to be created. Tags will show in the modern client in the Previous Chat view.

Post Chat Survey

When a visitor completes a post-chat survey the WhosOn Server will send a postchatsurvey event to all connected users who have access to the chat.

PostChatSurvey (Event)

{
    "EventName": "postchatsurvey",
    "Header": "1:127.0.0.1::2:3k2xq46019",
    "Data": [
        {
            "Name": "Rating",
            "Value": "5",
            "BuiltInField": "chat rating"
        },
        {
            "Name": "FoundBy",
            "Value": "Google",
            "BuiltInField": ""
        }
    ]
}

Copy

Header will be a colon separated list of fields:

1. Sitekey
2. Visitor IP Address
3. Visitor Session ID
4. Chat Number
5. ChatUID

Data will contain a list of post-chat survey fields completed by the visitor.

You can use this to update a list of closed chats if you are showing these or ignore the event. Your client would have already received a chatclosed event.

Setting Contact Information

You can assign contact information to any visitor. This can be done during a chat or against any previous chat or visitor. These fields are in addition to any pre-chat survey fields. Contact information stays with a visitor across multiple visits and shows in the VisitDetail and VisitList.

To add/update contact information send the Contact command:

Contact (Command)

{
    "Command": "Contact",
    "Parameters": [
        "1",
        "195.34.21.32",
        "123-78729473872",
        "{name}",
        "{company}",
        "{phone}",
        "{email}",
        "{notes}",
        "{fax}",
        "{street}",
        "{city}",
        "{postcode}",
        "{country}",
        "{webaddress}",
        "{organization}",
        "{crmid}"
    ]
}

Copy

Parameters: SiteKey, IPAddress, Visitor Session Id, Contact fields.

All fields should be sent. If a field is a blank string, then the existing value will not be overwritten. So, to just update an email address you would send:

{
    "Command": "contact",
    "Parameters": [
        "1",
        "195.34.21.32",
        "123-78729473872",
        "",
        "",
        "",
        "howard@test.com",
        "",
        "",
        "",
        "",
        "",
        "",
        "",
        "",
        ""
    ]
}

Copy

Once contact information is assigned to a visitor it will show in the Visit Detail for against subsequent visits for the same SiteKey, IPAddress, Visitor Session ID.

Note: Contact information is automatically added to visitors by the WhosOn Server for name, email, company & phone when a visitor starts a chat and provides any of these fields in the pre or post chat survey.

When the contact update has been accepted by the WhosOn Server it will send an accepted event:

Accepted (Event)

{
    "EventName": "accepted",
    "Header": null,
    "Data": null
}

Copy

The accepted event will also be sent in response to Invite, Block & ClearBlacklist commands.

Monitoring

If your connected user has 'Can Monitor Other Users Chats' user right then they can monitor other users active chats and can receive requestmonitor events from other users.

To start monitoring a chat send the Monitor command:

Monitor (Command)

{
    "Command": "Monitor",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: Chat Number

You can only monitor chats that are not already being monitored and have been taken by another user (the TalkingToClientID is not zero).

If the WhosOn Server accepts the monitor request it will send the monitoring event:

Monitoring (Event)

{
    "EventName": "monitoring",
    "Header": null,
    "Data": "1:3"
}

Copy

Header will be null. Data will contain the Chat Number and the Client Connection ID separated by a colon. The Client Connection ID is the ID of the client user that is currently chatting to the visitor.

After this event the WhosOn Server will send a monitoredchat event.

MonitoredChat (Event)

{
    "EventName": "monitoredchat",
    "Header": "1:195.62.193.194::8b2j6yur8q:1",
    "Data": {
        "SiteKey": 1,
        "VisitorIPAddress": "195.62.193.194",
        "VisitorSessionID": "",
        "VisitNumber": 15,
        "ChatUID": "8b2j6yur8q",
        "VisitorName": "Howard Williams",
        "TakenByUser": "Thomas,Daniel",
        "StartTime": "2019-09-15T14:04:57.193",
        "Email": "",
        "Phone": "",
        "LeftMessage": "",
        "FinishTime": "2019-09-15T14:06:55.27",
        "PreChatSurvey": [
            {
                "FieldName": "Company",
                "FieldValue": "Microsoft"
            }
        ],
        "Lines": [
            {
                "Dated": "2019-09-15T14:04:51.363",
                "OperatorIndex": 99,
                "Message": "Please wait. An operator will be with you shortly."
            },
            {
                "Dated": "2019-09-15T14:05:01.673",
                "OperatorIndex": 1,
                "Message": "Good Afternoon Test Visitor. My name is Stephen how can I help you?"
            },
            {
                "Dated": "2019-09-15T14:05:10.803",
                "OperatorIndex": 0,
                "Message": "Can i chat to support"
            },
            {
                "Dated": "2019-09-15T14:05:20.87",
                "OperatorIndex": 1,
                "Message": "One moment I will transfer you"
            }
        ],
        "PostChatSurvey": null,
        "WrapUpMessage": "",
        "WrapUpValues": null,
        "VisitDetail": null,
        "Key": "1:195.62.193.194::15"
    }
}

Copy

This event contains the same data as the currentchat event. It contains visitor information, survey fields and all chat lines so far.

The VisitDetail property will contain the VisitDetail object. See: GetVisit

MonitorC (Event)

When the client user that is chatting to the visitor sends a message the WhosOn Server will send a monitorc event to the client user that is monitoring the chat.

{
    "EventName": "monitorc",
    "Header": "1:Daniel",
    "Data": "message"
}

Copy

Header will contain the Chat Number and the other client name separated by a colon.

Data will contain the message text.

MonitorV (Event)

When the visitor sends a message to the client user that is chatting to the visitor the WhosOn Server will send a monitorv event to the client user that is monitoring the chat.

{
    "EventName": "monitorv",
    "Header": "1:Daniel",
    "Data": "message"
}

Copy

Header will contain the Chat Number and the other client name separated by a colon.

Data will contain the message text.

M1,M0,MC1,MC0 - Typing Status (Event)

When either the chatting user or chatting visitor typing status changes for a monitored chat the WhosOn Server will send m1,m0,mc1 or mc0 events.

Operator Started Typing

{
    "EventName": "mc1",
    "Header": null,
    "Data": "1:Daniel"
}

Copy

Data will contain the Chat Number and the chatting users name separated by a colon.

Operator Stopped Typing

{
    "EventName": "mc0",
    "Header": null,
    "Data": "1:Daniel"
}

Copy

Visitor Started Typing

{
    "EventName": "m1",
    "Header": null,
    "Data": "1 "
}

Copy

Data will contain the Chat Number

Visitor Stopped Typing

{
    "EventName": "m0",
    "Header": null,
    "Data": "1"
}

Copy

Whisper (Command)

Whilst monitoring another chat your client user can send private messages that only show to the other user (not the visitor). You can send a whisper message to a monitored chat by sending the Whisper command:

{
    "Command": "Whisper",
    "Parameters": [
        "243453",
        "3",
        "message"
    ]
}

Copy

Parameters: Client Connection ID (of other user), Chat Number, Message text.

The other client will receive a whisper event:

Whisper (Event)

{
    "EventName": "whisper",
    "Header": "1:Stephen",
    "Data": "message"
}

Copy

Header will contain the Chat Number and sending client name separated by a colon.

Data will contain the message text.

RequestMonitor (Event)

If another user that is chatting to a visitor has requested someone to monitor the chat, the WhosOn Server will send the requestmonitor event. This event will only be sent to users who can monitor the chat (based on their user rights).

{
    "EventName": "requestmonitor",
    "Header": "{header}",
    "Data": "message"
}

Copy

Header will contain a TAB separated list of fields:

• Domain
• Chat Number
• Visitor Name
• Talking To Client Name
• Talking To Client Connection ID

You would display a message to the user asking the user to monitor the chat.

StopMonitor (Command)

To stop monitoring a chat send the StopMonitor command.

{
    "Command": "StopMonitor",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: Chat Number

The WhosOn Server may also send a monitorstop event if you are monitoring a chat and the chat ends before you have sent the StopMonitor command.

MonitorStop (Event)

{
    "EventName": "monitorstop",
    "Header": null,
    "Data": "1:Daniel"
}

Copy

Header will be null, and Data will contain the Chat Number and the chatting users name separated by a colon.

Acquiring A Chat

Chats that you are currently monitoring can be Acquired (taken from the user currently chatting and transferred to your user).

To Acquire a chat, send the AquireChat command:

AquireChat (Command)

{
    "Command": "AquireChat",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: Chat Number

A chataquired event will be sent to the client user that is currently in the chat session:

ChatAquired (Event)

{
    "EventName": "chataquired",
    "Header": null,
    "Data": "1:Daniel"
}

Copy

Data will contain the Chat Number and the user's name that is acquiring the chat separated by a colon. The Client receiving this event should display a message saying the 'Chat has been acquired by {name}' and exit the chat (without closing it using the Leave command).

A monitorstop event will be sent to your client.

A transferconfirmed event will be sent to your client:

TransferConfirmed (Event)

{
    "EventName": "transferconfirmed",
    "Header": null,
    "Data": "1"
}

Copy

Data will contain the Chat Number. You should then send a Chat command to open the chat session.

Previous Chat Sessions

Clients can request information for previous chats that the current user they are chatting with has had.

To request a list of previous chats for this session, send the GetPrevChats command

When using a channel based chat session, use the GetPrevChatsChannel command

GetPrevChats (Command)

{
    "Command": "GetPrevChats",
    "Parameters": [
        "1",
        "195.62.193.194"
    ]
}

Copy

Parameters: Sitekey, IP Address, Optional Department

The server responds with the PrevChats event.

GetPrevChatsChannel (Command)

{
    "Command": "GetPrevChatsChannel",
    "Parameters": [
        "1",
        "Facebook",
        "1231222111"
    ]
}

Copy

Parameters: Sitekey, Channel Name, Channel User ID, Optional Department

The server responds with the PreChatsForChannel event.

PrevChats (Event)

{
    "EventName": "prevchats",
    "Header": "1:195.62.193.194",
    "Data": [
        {
            "ChatUID": "asdsd23a",
            "VisitorName": "Daniel",
            "StartDate": "2019-09-24T07:39:18.923",
            "TakenByUser": "paulc",
            "TakenByDept": "Customer Service",
            "ChattedSeconds": 231
        }
    ]
}

Copy

Header will contain the SiteKey and IP address separated by a colon.

You can then request the detail for any chat by sending the GetPrevChat command.

PrevChatsForChannel (Event)

{
    "EventName": "prevchatsforchannel",
    "Header": "1:Facebook:1231222111",
    "Data": [
        {
            "ChatUID": "asdsd23a",
            "VisitorName": "Daniel",
            "StartDate": "2019-09-24T07:39:18.923",
            "TakenByUser": "paulc",
            "TakenByDept": "Customer Service",
            "ChattedSeconds": 231
        }
    ]
}

Copy

Header will contain the SiteKey, channel name and channel user id separated by a colon.

You can then request the detail for any chat by sending the GetPrevChat command.

Previous Chat Lists

Clients can request list of previous chats for any site/day and request chat searches.

To request a list of previous chats for a site send the GetChats command:

GetChats (Command)

{
    "Command": "GetChats",
    "Parameters": [
        "1",
        "2019-09-24"
    ]
}

Copy

Parameters: SiteKey, Date.

The WhosOn Server will respond with a chats event.

Chats (Event)

{
    "EventName": "chats",
    "Header": "1:2019-09-24",
    "Data": [
        {
            "SiteKey": 1,
            "IP": "195.62.193.194",
            "UserName": "",
            "DNS": "1234567890.test.com",
            "Location": "United Kingdom - Stoke on Trent",
            "VisitorVisitNo": 44,
            "ChatUID": "m8mfjbrinv",
            "TakenByUsers": "Thomas",
            "TakenByDept": "",
            "StartTime": "2019-09-24T07:39:18.923",
            "FinishTime": "2019-09-24T07:40:10.333",
            "VisitorName": "Howard Williams",
            "WaitedForSecs": 0,
            "ChattedForSecs": 51,
            "Lang": "en",
            "Translation": false,
            "Invited": false,
            "Rating": 5,
            "Email": "howard@test.com",
            "Phone": "",
            "MessageText": "",
            "TakenByBot": false,
            "Missed": false,
            "MissedSeen": false,
            "MissedSeenByUserName": "",
            "MissedSeenOn": "0001-01-01T00:00:00",
            "MissedCallback": false,
            "MissedCallbackOn": "0001-01-01T00:00:00",
            "RequestedDept": "",
            "SentimentScore": 100,
            "WrapUpValue": "Option 1",
            "TagsValue": "Sales",
            "LinesCount": 0,
            "Summary": "I need some prices.",
            "SkillIds": ""
        }
    ]
}

Copy

Header will contain the SiteKey and date separated by a colon.

Data will contain a list of chats for the selected date.

You can then request the detail for any chat by sending the GetPrevChat command.

GetPrevChat (Command)

{
    "Command": "GetPrevChat",
    "Parameters": [
        "1",
        "m8mfjbrinv"
    ]
}

Copy

Parameters: SiteKey, ChatUID.

The WhosOn Server will respond with a prevchat event:

PrevChat (Event)

{
    "EventName": "prevchat",
    "Header": "1:m8mfjbrinv",
    "Data": {
        "SiteKey": 1,
        "VisitorIPAddress": "195.62.193.194",
        "VisitorSessionID": "123.4567890",
        "VisitNumber": 44,
        "ChatUID": "m8mfjbrinv",
        "VisitorName": "Howard Williams",
        "TakenByUser": "Thomas",
        "StartTime": "2019-09-24T07:39:18.923",
        "Email": "howard@test.com",
        "Phone": "",
        "LeftMessage": "",
        "FinishTime": "2019-09-24T07:40:10.333",
        "PreChatSurvey": [
            {
                "FieldName": "Company",
                "FieldValue": "Microsoft"
            }
        ],
        "Lines": [
            {
                "Dated": "2019-09-24T07:39:18.08",
                "OperatorIndex": 99,
                "Message": "Please wait. An operator will be with you shortly."
            },
            {
                "Dated": "2019-09-24T07:39:21.03",
                "OperatorIndex": 1,
                "Message": "Good Morning Howard. My name is Thomas how can I help you?"
            },
            {
                "Dated": "2019-09-24T07:39:27.363",
                "OperatorIndex": 1,
                "Message": "Hello"
            },
            {
                "Dated": "2019-09-24T07:39:35.127",
                "OperatorIndex": 0,
                "Message": "Hi.. I need some prices"
            },
            {
                "Dated": "2019-09-24T07:39:39.05",
                "OperatorIndex": 1,
                "Message": "which product"
            },
            {
                "Dated": "2019-09-24T07:39:42.127",
                "OperatorIndex": 0,
                "Message": "WhosOn"
            },
            {
                "Dated": "2019-09-24T07:39:53.96",
                "OperatorIndex": 1,
                "Message": "ok i will send a quote. What is your email address?"
            },
            {
                "Dated": "2019-09-24T07:40:01.937",
                "OperatorIndex": 0,
                "Message": "howard@test.com"
            },
            {
                "Dated": "2019-09-24T07:40:07.417",
                "OperatorIndex": 1,
                "Message": "Thanks"
            }
        ],
        "PostChatSurvey": [
            {
                "FieldName": "Rating",
                "FieldValue": "5"
            },
            {
                "FieldName": "transEmail",
                "FieldValue": ""
            }
        ],
        "WrapUpMessage": "Please select one of",
        "WrapUpValues": [
            {
                "FieldName": "Value",
                "FieldValue": "Option 1"
            },
            {
                "FieldName": "Username",
                "FieldValue": "thomas@mycompany.com"
            },
            {
                "FieldName": "Display Name",
                "FieldValue": "Thomas"
            },
            {
                "FieldName": "DateTime",
                "FieldValue": "2019-09-24 07:40:26"
            }
        ],
        "Tags": [
            "Sales"
        ],
        "VisitDetail": {
            "SiteKey": 1,
            "SiteName": "My Company",
            "IP": "195.62.193.194",
            "DNS": "(Test) 1234567890.test.com",
            "SessionID": "1234.4567890",
            "VisitNumber": 44,
            "AlertNumber": 3,
            "TotalVisits": 44,
            "Browser": "Chrome 76",
            "OS": "Windows 10",
            "Spider": false,
            "SearchEngine": "",
            "Referer": "https://chat.mycompany.com/newchat/chat.aspx",
            "RefererQuery": "?domain=www.mycompany.com",
            "SessionStarted": "2019-09-24T07:39:13.287",
            "Cost": 0,
            "Revenue": 0,
            "Prospect": false,
            "Chatting": true,
            "Customer": false,
            "Invited": false,
            "ProspectTypes": 0,
            "FirstVisit": "2019-09-10T14:44:47.263",
            "FirstReferer": "https://www.google.com",
            "FirstAlert": 3,
            "TotalCost": 0,
            "TotalRevenue": 0,
            "ContactName": "Howard Williams",
            "ContactEmail": "howard@test.com",
            "ContactCompany": "Microsoft",
            "ContactTelephone": "01782822577",
            "ContactNotes": "",
            "ChattingLanguage": "",
            "ChattingTranslate": false,
            "ContactFax": "",
            "ContactStreet": "",
            "ContactCity": "",
            "ContactPostCode": "",
            "ContactCountry": "",
            "ContactWebAddress": "",
            "ContactOrganization": "",
            "ContactDated": "2019-09-10T14:45:00",
            "CRMId": "",
            "Pages": [
                {
                    "Dated": "2019-09-24T07:39:00.117",
                    "Name": "index.aspx",
                    "Status": 200
                },
                {
                    "Dated": "2019-09-24T07:39:13.287",
                    "Name": "chat.aspx",
                    "Status": 200
                }
            ],
            "FormFields": [],
            "GeoIP": {
                "IPAddress": "195.62.193.194",
            "IsProxy": false,
            "IsSatellite": false,
            "PostCode": "ST1",
            "Latitude": 53.0278,
            "Longitude": -2.1658,
            "Radius": 20,
            "ISP": "Internet Central Limited",
            "CountryISO": "GB",
            "CountryName": "United Kingdom",
            "City": "Stoke-on-Trent",
            "MetroCode": "",
            "Organization": "Parker Software",
            "RegionName": "",
            "RegionISO": ""
            }
        },
        "Key": "1:195.62.193.194:123.4567890:44"
    }
}

Copy

Deleting Chats

If the connected user has the 'Can Delete Chats' user right, then previous chats can be deleted. To delete chats, send the DeleteChats command:

DeleteChats (Command)

{
    "Command": "DeleteChats",
    "Parameters": [
        "1",
        "m8mfjbrinv,usk4g3kf8d"
    ]
}

Copy

Parameters: SiteKey, Comma separated list of ChatUID's to delete.

When chats are deleted the WhosOn Server will send a deletedchats event to all connected users who have access to the deleted chats.

DeletedChats (Event)

{
    "EventName": "deletedchats",
    "Header": 1,
    "Data": "m8mfjbrinv,usk4g4kf8d"
}

Copy

Searching Chats

To perform a search, send the command GetChatSearch:

GetChatSearch (Command)

{
    "Command": "GetChatSearch",
    "Parameters": [
        "1",
        "2019-09-01",
        "2019-09-16",
        "thomas"
    ]
}

Copy

Parameters: SiteKey, From Date, To Date, Search Text.

Chats will be returned that contain the search text (not case sensitive). All chat lines are searched in addition to header information (visitor name, pre/post chat survey values, visitor location, email address, left message text).

The WhosOn Server will send a chatsearch event with the results of the search.

ChatSearch (Event)

{
    "EventName": "chatsearch",
    "Header": "1:2019-09-24:2019-09-24",
    "Data": [
        {
            "SiteKey": 1,
            "ChatUID": "m8mfjbrinv",
            "Dated": "2019-09-24T00:00:00",
            "TakenByUser": "Thomas",
            "TakenByDept": "",
            "RequestedSkillIDs": "",
            "RequestedDept": "",
            "StartTime": "2019-09-24T07:39:18.923",
            "FinishTime": "2019-09-24T07:40:10.333",
            "WaitedForSecs": 0,
            "Invited": false,
            "Rating": 5,
            "SentimentScore": 100,
            "Language": "en",
            "Translation": false,
            "VisitID": 9246,
            "VisitorName": "Howard Williams",
            "VisitorIP": "195.62.193.194",
            "VisitorSessionId": "",
            "VisitorVisitNumber": 44,
            "DNS": "1234567890.test.com",
            "Location": "United Kingdom - Stoke on Trent",
            "Email": "howard@test.com",
            "Phone": "",
            "LeftMessageText": "",
            "Missed": false,
            "MissedCallback": false,
            "MissedCallbackOn": "0001-01-01T00:00:00",
            "MissedSeen": false,
            "MissedSeenByUser": "",
            "TranscriptURL": "https://chat.mycompany.com/whosoncharts/chatview.aspx?k=ie9lAb%2ftKuWOwb%2bHOZCoI5si2EsTNrpqOZgSkChi2wE%3d",
            "Summary": "I need some prices.",
            "WrapUpValue": "Option 1",
            "TagsValue": "Sales"
        }
    ]
}

Copy

Header will contain the SiteKey, From Date and To Date separated by colons.

Data of this event is the same as the chats event.

Missed Chat Handling

After login your client will receive a missedchats event containing a list of pending missed chats that the connected user has access to. After login, individual missedchat events will be sent whenever a new missed chat is added. Missed chats can be responded to by the user. When a missed chat is responded to, the WhosOn Server will send the response to the visitor via email or if the visitor has provided a telephone number the missed chat can be responded to via a CallBack (if Callbacks are enabled for the Site).

MissedChat (Event)

{
    "EventName": "missedchat",
    "Header": null,
    "Data": {
        "SiteKey": 1,
        "Domain": "www.mycompany.com",
        "ChatUID": "5nb58re1u5",
        "VisitorIPAddress": "195.62.193.194",
        "VisitorSessionID": "",
        "VisitorVisitNo": 11,
        "VisitorName": "Howard Williams",
        "DNS": "1234567890.test.com",
        "Location": "United Kingdom - Stoke on Trent",
        "Dept": "",
        "Lang": "en",
        "Translation": false,
        "WantsSkills": "",
        "Started": "2019-09-15T11:25:04.543",
        "WaitedSecs": 0,
        "Email": "howard@test.com",
        "Phone": "01782822577",
        "Message": "I need some support.. Could someone contact me.",
        "MissedResponseStarted": false,
        "MissedResponseStartedBy": "",
        "MissedWantsCallback": true,
        "MissedWantsCallbackOn": "2019-09-15T11:26:33.877"
    }
}

Copy

To start a response, send the MissedChatResponding command. This command informs the WhosOn Server that a user has started a response to a missed chat. This prevents other users from also starting a response to the same chat at the same time. Only users who have the 'Can Respond To Missed Chats' are be allowed to do this.

MissedChatResponding (Command)

{
    "Command": "MissedChatResponding",
    "Parameters": [
        "jl8a91yj4c"
    ]
}

Copy

Parameters: ChatUID

If another user has already started responding to this missed chat a msg event will be sent:

{
    "EventName": "msg",
    "Header": null,
    "Data": "Missed chat with Melina is currently being responded to by Daniel"
}

Copy

MissedChatResponded (Command)

{
    "Command": "MissedChatResponded",
    "Parameters": [
        "jl8a91yj4c",
        "message text"
    ]
}

Copy

Send this command to send a response to a missed chat. The WhosOn Server will append the message text to the chat and send an email to the visitor with the response. The missed chat will be marked as completed and removed from the missed chats list. All users who can see the missed chat will receive a missedchatclosed event.

Note: The message text can contain Markdown.

MissedChatClosed (Event)

{
    "EventName": "MissedChatClosed",
    "Header": null,
    "Data": "jl8a91yj4c"
}

Copy

Data will contain the Chat UID.

The WhosOn Server will send the missedchatclosed event whenever a missed chat has been responded to (by any user) or has expired (missed chats can be set to expire after a number of days defined on the Site Properties).

MissedChatRespondingCancel (Command)

If the client has started a missed chat response by sending the MissedChatResponding command and wishes to cancel the response, send the MissedChatPespondingCancel command with the single parameter of ChatUID.

Callbacks

The client can initiate a Twilio callback for any chat (current, previous or missed).

To start a callback send the CallBackStart command:

CallBackStart (Command)

{
    "Command": "CallBackStart",
    "Parameters": [
        "1",
        "jl8a91yj4c",
        "07799123456"
    ]
}

Copy

Parameters: SiteKey, ChatUID, Phone Number.

The WhosOn Server will start the callback process.

During the call back the WhosOn Server will send progress events in the chatcallbackevent

ChatCallBackEvent (Event)

{
    "EventName": "chatcallbackevent",
    "Header": null,
    "Data": {
        "ID": 1,
        "SiteKey": 1,
        "ChatUID": "jl8a91yj4c",
        "FromNumber": "01782822577",
        "ToNumber": "07799123456",
        "UserName": "thomas@mycompany.com",
        "CallStarted": "2019-09-15T14:04:57.193",
        "CallStatus": "in-progress",
        "CallRecordingURL": "",
        "TranscriptLine": "Call connected."
    }
}

Copy

This event will be sent multiple times during a call as the call status changes. You should display the TranscriptLine property in your chat view.

Canned Responses

A list of Canned Responses can be requested by sending the GetCannedResponses command.

Canned Responses can also be added, updated & deleted by the client.

CannedResponseUpdate (Command)

Send the CannedResponseUpdate command to add or update a canned response:

{
    "Command": "CannedResponseUpdate",
    "Parameters": [
        "{xml}"
    ]
}

Copy

Where XML is in the following format:

<CannedResponse>
    <CannedID>0</CannedID>
    <ParentCannedID>179</ParentCannedID>
    <SkillID>0</SkillID>
    <CreatedByUser>thomas@mycompany.com</CreatedByUser>
    <Dated>2019-09-16 13:16:37</Dated>
    <Subject>Can I use a web client</Subject>
    <Content>Yes - WhosOn 2019 now supports websockets!</Content>
    <SiteKeys>1</SiteKeys>
</CannedResponse>

Copy

For new responses the <CannedID> should be zero. To update an existing response set its <CannedID> to an existing ID.

If the Canned Response should be added as a child of an existing response set the <ParentCannedID> to the parent id.

If the Canned Response is a 'My Canned Response' - IE only available to the user who created it, set the <SkillID> to -1

<Sitekeys> should be a comma separated list of sitekeys that this canned response is available for. If blank then the sitekeys of the user adding it will be used.

Whenever a canned response is added or updated the WhosOn Server will send a cannedresponseupdated event to all users who have access to it (including your client).

CannedResponseUpdated (Event)

{
    "EventName": "cannedresponseupdated",
    "Header": null,
    "Data": "{xml}"
}

Copy

Data will be the XML of the canned response. For new responses the <CannedID> will contain the new id. If Data does not contain XML it will contain an error message indicating why the canned response could not be updated.

CannedResponseDelete (Command)

To delete an existing response, send the CannedResponseDelete command:

{
    "Command": "CannedResponseDelete",
    "Parameters": [
        "132"
    ]
}

Copy

Parameters: The Canned ID to delete.

Whenever a canned response is deleted the WhosOn Server will send a cannedresponsedeleted event to all users who have access to it (including your client).

CannedResponseDeleted (Event)

{
    "EventName": "cannedresponsedeleted",
    "Header": null,
    "Data": "132"
}

Copy

Data will contain the Canned ID deleted. If not a number, then it will contain an error message indicating why the Canned Response could not be deleted.

Note: When deleting canned responses - if the canned response has child responses then all child responses will be deleted also - however your client will not receive events for all the children - only the parent.

You client should get the initial list of Canned Responses and then monitor the CannedResponseUpdated and CannedResponseDeleted events to maintain the list when other users are changing them.

Files

A list of Files can be requested by sending the GetFiles command.

Adding A New File

To add a new file, you must call the DocumentWrite web service. The web services URL is passed as part of the connected event. This web service returns a URL, or 'Error [message]'' if an error occurred. If a URL is returned you can then use this with the SendFileTo command if you have uploaded the file during a chat session and then want to send it to the visitor.

Deleting Files

Files can be deleted by the client by sending the DeleteFiles command:

{
    "Command": "DeleteFiles",
    "Parameters": [
        "hashedfilename.ext,hashedfilename2.pdf"
    ]
}

Copy

Parameters should contain a comma separated list of hashed filenames to delete.

A deletedfiles event will be sent to all clients that have access to the file(s) deleted. Clients can then remove the files from their files list.

Deleted Files (Event)

{
    "EventName": "deletedfiles",
    "Header": null,
    "Data": "hashedfilename.ext,hashedfilename2.pdf"
}

Copy

Data will contain a list of hashed file names deleted separated by a comma.

Pinning Files

Existing files can be marked as 'Pinned' by sending the PinFiles command:

PinFiles (Command)

{
    "Command": "PinFiles",
    "Parameters": [
        "hashedfilename.ext,hashedfilename2.pdf"
    ]
}

Copy

Parameters should contain a comma separated list of hashed filenames to pin. If files are already pinned, they will be marked as unpinned.

User Photos

The initial clients event that the WhosOn Server sends after login provides a list of other connected users.

The clientevent and clientremove events provide updates as users login, change status etc and logout.

Your client can also request avatars for any user by sending the GetUserPhotos command:

GetUserPhotos (Command)

{
    "Command": "GetUserPhotos",
    "Parameters": [
        "username"
    ]
}

Copy

Parameters: Tab separated list of usernames to request photos for.

The WhosOn Server will send a userphoto event for each user requested:

UserPhoto (Event)

{
    "EventName": "userphoto",
    "Header": "thomsas@mycompany.com",
    "Data": "{base64}"
}

Copy

Header will contain the username. Data will contain a base64 encoded string of the user image (or blank if no image).

Note: User images should be cached in some way by the client rather than requesting after each clients or clientevent events.

Traffic Summary Data

Your client can request traffic summary data for the current day and as a single request for the last 3 months.

GetMonthSummary (Command)

To request traffic summary for the last 3 months, send the GetMonthSummary command:

{
    "Command": "GetMonthSummary",
    "Parameters": [
        "1"
    ]
}

Copy

Parameters: SiteKey

The WhosOn Server will send a monthlysummary event containing:

MonthySummary (Event)

{
    "EventName": "monthsummary",
    "Header": null,
    "Data": {
        "SiteKey": "1",
        "Days": [
            {
                "Date": "2019-09-12",
                "Data": "1|1|0|0|0|0|0|0|0|0|1|1|15:36:43|0|0|0|0"
            },
            {
                "Date": "2019-09-11",
                "Data": "0|0|0|0|0|0|0|0|0|0|0|0|00:00:00|0|0|0|0"
            },
            {
                "Date": "2019-09-10",
                "Data": "1|1|0|1|0|0|0|0|1|1|1|1|14:44:47|0|0|0|0"
            },
            {
                "Date": "2019-09-15",
                "Data": "5|5|0|0|0|0|0|0|4|0|5|1|08:48:40|0|0|0|0"
            },
            {
                "Date": "2019-09-14",
                "Data": "0|0|0|0|0|0|0|0|0|0|0|0|00:00:00|0|0|0|0"
            },
            {
                "Date": "2019-09-13",
                "Data": "371|371|0|371|0|3|0|370|43|0|500|353|08:34:42|0|0|2|19"
            }
        ]
    }
}

Copy

Each Day in the Days list contains the Date and Data properties.

The Data property is a Pipe (|) delimited string of:

1. Visits
2. Site Entry Alerts Free
3. Site Entry Alerts Paid
4. New Visitors
5. Spiders
6. Prospects
7. Customers
8. Invites
9. Chats
10. Chats Missed
11. Page Views
12. Peak Time
13. Total Cost
14. Total Revenue
15. Average Chat Rating
16. Average Chat Sentiment

The monthly summary will not include the current day. For the current day use the GetDS command.

Monthly summary dates will be in date order and it is possible for there to be gaps in days (for instance if the server was not running on a particular day). When implementing a 'back', 'forward' view of dates in a client summary view you should maintain the current date in the view and then search for it in the list (and display zeros if no date found) - rather than going back/forward in the list itself.

GetDS (Command)

The GetDS command is used to get the current traffic summary for all sites (that the logged in user has access to).

{
    "Command": "GetDS",
    "Parameters": null
}

Copy

The WhosOn Server will send the ds event:

Ds (Event)

{
    "EventName": "ds",
    "Header": null,
    "Data": {
        "DaySummary": [
            {
                "SiteKey": 1,
                "Dated": "2019-09-16",
                "Current": 56,
                "Total": 132,
                "New": 75,
                "Prospects": 26,
                "Customers": 9,
                "Invites": 31,
                "ChatRequests": 45,
                "ChatsMissed": 3,
                "PageViews": 385,
                "Peak": 89,
                "PeakTime": "14:34:21",
                "AvgChatRating": 4,
                "AvgChatSentiment": 75
            }
        ]
    }
}

Copy

The DaySummary list will contain current totals for each site.

Your client can request an update of the current traffic summary at any time but should limit the requests to as needed (IE when the user clicks a 'summary' view - if the last update was less than 2 minutes ago).

Getting Current Visitor Totals Only

You can request to just get current visitor totals only. This provides a smaller event and is better for performance if you want to show current visitors for each site in your client.

Send the GetCT command:

GetCT (Command)

{
    "Command": "GetCT",
    "Parameters": null
}

Copy

The WhosOn Server will respond with the ct event:

Ct (Event)

{
    "EventName": "ct",
    "Header": null,
    "Data": {
        "Current": [
            {
                "SiteKey": 1,
                "Visitors": 23
            },
            {
                "SiteKey": 2,
                "Visitors": 45
            }
        ]
    }
}

Copy

The Current list will contain an entry for each site that the logged in user has access to. The Visitors property contains the current active visitors for the site. You can enable Current Visitor Totals events so that the ct events are sent automatically.

Enabling Current Visitor Totals Events

You can request that the server sends the ct event automatically whenever the visitor current totals change.

Send the StartCurrentVisitorTotalsEvents command:

tartCurrentVisitorTotalsEvents (Command)

{
    "Command": "StartCurrentVisitorTotalsEvents",
    "Parameters": null
}

Copy

Once enabled the server will automatically send a ct event when current visitor totals change. Events are sent approximately every 8 seconds (unless there has been no change, in which case an event is not sent).

To disable Current Visitor Totals events, send the StopCurrentVisitorTotalsEvents command:

StopCurrentVisitorTotalsEvents (Command)

{
    "Command": "StopCurrentVisitorTotalsEvents",
    "Parameters": null
}

Copy

Listen Mode

Listen mode can be enabled by users with Admin, Supervisor or Team Leader rights (and have the 'Can Monitor Other Users Chats' user right). Once enabled all active chat messages are sent to the listening client as they occur. This enables the creation of a 'supervisor view' to monitor the activity of all active chats for all users (that the logged in user has access to). Team Leaders can only see chats that are interacting with users in their own user groups.

To enable Listen Mode, send the StartListening command:

StartListening (Command)

{
    "Command": "StartListening",
    "Parameters": null
}

Copy

To disable Listen Mode, send the StopListening command:

StopListing (Command)

{
    "Command": "StopListening",
    "Parameters": null
}

Copy

These commands will be ignored by the WhosOn Server if the user does not have sufficient rights.

Listen Events

Once Listen Mode is enabled then your client will receive events for all chat sessions, for all users (the the logged in user has access to).

ListenC (Event)

When the client user that is chatting to a visitor sends a message the WhosOn Server will send a listenc event to all client users that have Listen Mode enabled.

{
    "EventName": "listenc",
    "Header": "1:eyh4h3ya85",
    "Data": "message from operator"
}

Copy

Header will contain the Chat Number and the Chat UID separated by a colon.

Data will contain the message text.

ListenV (Event)

When the visitor sends a message to a client user the WhosOn Server will send a listenv event to all client users that have Listen Mode enabled.

{
    "EventName": "listenv",
    "Header": "1:eyh4h3ya85",
    "Data": "message from visitor"
}

Copy

Header will contain the Chat Number and the Chat UID separated by a colon.

Data will contain the message text.

ListenTransfer (Event)

If a chat is transferred the WhosOn Server will send a listentransfer event to all client users that have Listen Mode enabled.

{
    "EventName": "listentransfer",
    "Header": "1:eyh4h3ya85:TransferTarget",
    "Data": "message"
}

Copy

Header will contain the Chat Number, Chat UID and Transfer target (Name, Department or Skill) separated by colons.

Supervisor View Design Notes

When creating a supervisor view to monitor all chats you should follow these tips:

• Switch on Listen Mode only when your 'monitor all' view is active.
• When Listen Mode is activated - use the GetPrevChat command to read the chat detail for all currently active chats.
• When a listenv or listenc event is received use the GetPrevChat command to get the chat detail for NEW chats (chats you don't already have the detail for).
• Add new lines from the listenv and listenc events to the chat lines as they come in.
• When a listentransfer event is received add a line to the chat to show it has been transferred.
• When a chatclosed event is received remove the chat from the view (or update its status to show it has closed).
• If the 'monitor all' view has been closed or not used for a period switch off Listen Mode.

Visitors

The WhosOn Server tracks all visitor activity for each monitored Site. By default, the WebSocket interface does not send individual visitor events unless visitor events are enabled.

The current visitors list can be requested by sending the GetVisitors command:

GetVisitors (Command)

{
    "Command": "GetVisitors",
    "Parameters": null
}

Copy

The WhosOn Server will respond with the visitors event:

Visitors (Event)

{
    "EventName": "visitors",
    "Header": null,
    "Data": {
        "Visitors": [
            {
                "SiteKey": 1,
                "Key": "1:212.45.112.80:301.6863295",
                "SessionId": "301.6863295",
                "StartTime": "10:06:47",
                "Time": "10:06:47",
                "No": 13,
                "VisitNo": 1,
                "AlertNo": 3,
                "Views": 1,
                "DNS": "212.45.112.80",
                "Page": "index.htm",
                "Flags": "NNNNNNNNNNNNNNN",
                "Browser": "IE 10",
                "OS": "Windows 7",
                "Ref": "",
                "Name": "",
                "Email": "",
                "Loc": "Denmark - WAOO A/S"
            },
            {
                "SiteKey": 1,
                "Key": "1:218.35.86.86:343.13095511",
                "SessionId": "343.13095511",
                "StartTime": "10:06:46",
                "Time": "10:06:47",
                "No": 12,
                "VisitNo": 1,
                "AlertNo": 3,
                "Views": 2,
                "DNS": "218.35.86.86",
                "Page": "parkersoft/page9.htm",
                "Flags": "NNNNNNNNNNNNNYN",
                "Browser": "Safari 4",
                "OS": "Android",
                "Ref": "",
                "Name": "",
                "Email": "",
                "Loc": "Taiwan - Asia Pacific On-line Service"
            }
        ]
    }
}

Copy

Data contains a list of active visitors for all monitored sites (that the client user has access to).

The GetVisitors command should be sent once after login if you want to monitor active visitors in your client.

Visitor Events

Visitor events can be enabled by sending the StartVisitorEvents command:

StartVisitorEvents (Command)

{
    "Command": "StartVisitorEvents",
    "Parameters": null
}

Copy

And disabled with StopVisitorEvents command.

Once Visitor Events are enabled the WhosOn Server will send a visitor event whenever a new visitor arrives at a site and when a visitor changes (for example, requests a new page or their IP address is resolved to a DNS name, or the visitor becomes a prospect etc). It will send a visitorremoved event whenever a visitor leaves a site.

Visitor (Event)

{
    "EventName": "visitor",
    "Header": null,
    "Data": {
        "SiteKey": 1,
        "Key": "1:196.15.109.60:991.61915693",
        "SessionId": "991.61915693",
        "StartTime": "10:16:19",
        "Time": "10:16:19",
        "No": 14,
        "VisitNo": 1,
        "AlertNo": 3,
        "Views": 1,
        "DNS": "196.15.109.60",
        "Page": "index.htm",
        "Flags": "NNNNNNNNNNNNNYN",
        "Browser": "Safari 7",
        "OS": "Mac OSX",
        "Ref": "https://www.google.com?q=test",
        "Name": "",
       "Email": "",
        "Loc": "South Africa - Cogent Communications"
    }
}

Copy

The Key property contains a string combining SiteKey:IPAddress:VisitorSessionID. This can be used as a unique key for the visitor. The No property is the visit number for the site for the current day. The VisitNo is the visit number for that visitor (IE: If it is the 2nd visit to the site for the same Key then VisitNo would be 2).

The Flags property is a string containing Y and N characters which indicate (Y or N by position):

1. Is marked as a Spider
2. (not used)
3. Not moving (hasn't change pages for a period of time)
4. Is currently chatting
5. Is marked as a Prospect
6. Is a new Prospect - became a prospect on the current visit
7. Is marked as a Customer
8. Is a new Customer - became a customer on the current visit
9. (not used)
10. Invited To Chat
11. Callback Requested
12. Polling - the WhosOn Tracking code for the site has updated the visitor
13. (not used)
14. Geo-IP organization is not an ISP
15. Requesting pages via SSL

VisitorRemoved (Event)

{
    "EventName": "visitorremove",
    "Header": null,
    "Data": "1:196.15.109.60:991.61915693"
}

Copy

The WhosOn Server will send this event when a visitor leaves the site. Data contains SiteKey: IP Address: Visitor Session ID (the Key property of the visitor event).

Requesting Visit Detail

You can request the visit detail for any active visitor. Use the GetVisit command:

GetVisit (Command)

{
    "Command": "GetVisit",
    "Parameters": [
        "1",
        "202.42.104.89",
        "589.14498921",
        "1"
    ]
}

Copy

Parameters: SiteKey, IP Address, Session ID, VisitNumber

The WhosOn Server will send a visitdetail event:

VisitDetail (Event)

{
  "EventName": "visitdetail",
  "Header": "1:202.42.104.89:589.14498921",
  "Data": {
    "SiteKey": 1,
    "SiteName": "My Company",
    "IP": "202.42.104.89",
    "DNS": "",
    "SessionID": "589.14498921",
    "VisitNumber": 1,
    "AlertNumber": 3,
    "TotalVisits": 1,
    "Browser": "Edge 13",
    "OS": "Windows 10",
    "Spider": false,
    "SearchEngine": "Google",
    "Referer": "https://www.google.com",
    "RefererQuery": "",
    "SessionStarted": "2019-11-18T07:22:23.133",
    "Cost": 0.0,
    "Revenue": 0.0,
    "Prospect": false,
    "Chatting": false,
    "Customer": false,
    "Invited": false,
    "ProspectTypes": 0,
    "FirstVisit": "2019-11-18T07:22:23.133",
    "FirstReferer": "",
    "FirstAlert": 3,
    "TotalCost": 0.0,
    "TotalRevenue": 0.0,
    "ContactName": "",
    "ContactEmail": "",
    "ContactCompany": "",
    "ContactTelephone": "",
    "ContactNotes": "",
    "ChattingLanguage": "",
    "ChattingTranslate": false,
    "ContactFax": "",
    "ContactStreet": "",
    "ContactCity": "",
    "ContactPostCode": "",
    "ContactCountry": "",
    "ContactWebAddress": "",
    "ContactOrganization": "",
    "ContactDated": "0001-01-01T00:00:00",
    "CRMId": "",
    "Pages": [
      {
        "Dated": "2019-11-18T07:22:23.133",
        "Name": "index.htm",
        "Status": 200
      },
      {
        "Dated": "2019-11-18T07:22:23.627",
        "Name": "page2.htm",
        "Status": 200
      }
    ],
    "FormFields": [],
    "GeoIP": {
      "IPAddress": "202.42.104.89",
      "IsProxy": false,
      "IsSatellite": false,
      "PostCode": "",
      "Latitude": 35.69,
      "Longitude": 139.69,
      "Radius": 500,
      "ISP": "Telstra Global Internet Services Network Blocks",
      "CountryISO": "JP",
      "CountryName": "Japan",
      "City": "",
      "MetroCode": "",
      "Organization": "",
      "RegionName": "",
      "RegionISO": ""
    }
  }
}

Copy

The VisitDetail event contains the visit detail object which contains information about a specific site visitor. The Pages list contains a list of page views for the visit. The FormFields list contains a list of completed form fields (if form-field tracking is enabled). The GeoIP property contains the GeoIP information for the visitor's IP address.

Server Visitor Event Throttling

The WhosOn Server will enable 'Visitor Throttling' when the currently active visitors for a site reaches 20% of the maximum allowed active tracked visitors setting (which defaults to 1000, so by default throttling will start at 200 active visitors or more). Visitor throttling is designed to improve the performance of operator client applications to prevent them from being overwhelmed by single visitor & visitorremoved events.

When the WhosOn Server enables visitor throttling, single visitor events and visitorremoved events will not be sent. Instead, visitor events will be sent as a batch every 8 seconds. The visitorbatch event will be sent which will contain a list of visitors added or changed since the last batch. The visitorremovedbatch event will contain a list of visitor keys to remove.

VisitorBatch (Event)

{
    "EventName": "visitorbatch",
    "Header": null,
    "Data": {
        "VisitorsBatch": [
            {
                "SiteKey": 1,
                "Key": "1:180.43.107.70:149.10173502",
                "SessionId": "149.10173502",
                "StartTime": "12:08:11",
                "Time": "12:08:11",
                "No": 247,
                "VisitNo": 1,
                "AlertNo": 3,
                "Views": 1,
                "DNS": "180.43.107.70",
                "Page": "index.htm",
                "Flags": "NNNNNNNNNNNNNYN",
                "Browser": "Chrome 24",
                "OS": "Mac OSX",
                "Ref": "https://www.google.com?q=test",
                "Name": "",
                "Email": "",
                "Loc": "Japan - Kanazawa (Ishikawa) - NTT Communications Corporation"
            },
            {
                "SiteKey": 1,
                "Key": "1:180.43.107.70:149.10173502",
                "SessionId": "149.10173502",
                "StartTime": "12:08:11",
                "Time": "12:08:11",
                "No": 247,
                "VisitNo": 1,
                "AlertNo": 3,
                "Views": 2,
                "DNS": "180.43.107.70",
                "Page": "page2.htm",
                "Flags": "NNNNNNNNNNNNNYN",
                "Browser": "Chrome 24",
                "OS": "Mac OSX",
                "Ref": "https://www.google.com?q=test2",
                "Name": "",
                "Email": "",
                "Loc": "Japan - Kanazawa (Ishikawa) - NTT Communications Corporation"
            }
        ]
    }
}

Copy

VistorRemovedBatch (Event)

{
    "EventName": "visitorremovedbatch",
    "Header": null,
    "Data": {
        "VisitorRemovedBatch": [
            "1:186.42.105.50:145.16761196",
            "1:188.12.108.98:549.15374197",
            "1:213.11.85.74:387.33040860",
            "1:209.42.109.60:324.75899400",
            "1:207.23.110.97:141.19141550"
        ]
    }
}

Copy

See the WhosOn 2019 Server release notes for more information about visitor throttling.

The WhosOn Server will disable Visitor Throttling when the currently active visitors for the site drops to below 75% of the throttle level. Regular visitor and visitorremoved events will then resume.

Sending Chat Invite Requests

The WhosOn Server will automatically send chat invites based on Invite & Prospect Detection rules. In addition, client users can manually send invites to any active visitor. If your connected user has 'Can Send Chat Invites' user right, you can send a chat invite request to any active visitor. The invite will appear on the visitor's web page according to the design specifications of the invite type being sent. Send the Invite command:

Invite (Command)

{
    "Command": "Invite",
    "Parameters": [
        "182.34.23.23",
        "123-83738838569",
        "www.whoson.com",
        "2"
    ]
}

Copy

Parameters: IP Address, Visitor Session ID, Domain Name, Invite Number.

Note: The site domain name is passed here, not the sitekey.

The WhosOn Server will respond with an accepted event:

Accepted (Event)

{
    "EventName": "accepted",
    "Header": null,
    "Data": null
}

Copy

Live Visitor View Design Notes

If you want to offer a live visitor view in your client, you should first send the GetVisitors command after login. Followed by the StartVisitorEvents command. Then maintain a list of active visitors for each site by handling the visitor,visitorremoved, visitorbatch & visitorremovedbatch events to update & delete from the list.

For very busy sites with many active visitors (>500) performance becomes a consideration. You can examine the current property in ds event to see the total current visitors for a site. The Visitor events can be disabled if the current visitors count gets too high.

Visitor events should not be enabled if the client user does not need to view active visitors and instead wants to focus on chatting visitors only.

Visit Lists

Visit lists for the current day or any previous day can be requested using the GetVisitList command:

GetVisitList (Command)

{
    "Command": "GetVisitList",
    "Parameters": [
        "1",
        "2019-09-19",
        "0"
    ]
}

Copy

Parameters: SiteKey, Date, From ID

The WhosOn Server will respond with a visitlist event:

VisitList (Event)

{
    "EventName": "visitlist",
    "Header": "1:2019-09-19:0",
    "Data": [
        {
            "VisitID": 8335,
            "SiteKey": 1,
            "IP": "220.22.84.63",
            "SessionId": "418.8001638",
            "Loc": "Japan - Softbank BB",
            "DNS": "softbank220022084063.bbtec.net",
            "Name": "",
            "Company": "",
            "Email": "",
            "VisitNo": 1,
            "VisitDate": "2019-09-19T11:28:29.883",
            "Visits": 1,
            "Views": 2,
            "Duration": 61,
            "Cost": 0,
            "Revenue": 0,
            "Page": "index.htm",
            "FirstDate": "2019-09-19T11:28:29.883",
            "LastDate": "2019-09-19T11:28:29.883",
            "Os": "iPad",
            "Browser": "Safari 6",
            "SearchEngine": "Google",
            "Referrer": "https://www.google.com",
            "Query": "?q=we",
            "Flags": "YYNNNN"
        },
        {
            "VisitID": 8336,
            "SiteKey": 1,
            "IP": "195.21.106.69",
            "SessionId": "161.98375597",
            "Loc": "United Kingdom - Interoute Communications Limited",
            "DNS": "",
            "Name": "",
            "Company": "",
            "Email": "",
            "VisitNo": 1,
            "VisitDate": "2019-09-19T11:28:30.88",
            "Visits": 1,
            "Views": 1,
            "Duration": 64,
            "Cost": 0,
            "Revenue": 0,
            "Page": "index.htm",
            "FirstDate": "2019-09-19T11:28:30.88",
            "LastDate": "2019-09-19T11:28:30.88",
            "Os": "Windows 7",
            "Browser": "IE 9",
            "SearchEngine": "",
            "Referrer": "",
            "Query": "",
            "Flags": "YYNNNN"
        }
    ]
}

Copy

The list will contain every visit for the requested Site & Date.

The FromID parameter of the GetVisitList command is used when requesting the visit list for the current day. If requesting visit lists for previous days send "0".

The FromID parameter allows you to request only new visits since the last request. The VisitID property on each Visit contains the ID. Store the highest ID from the last request and then send that on subsequent requests to receive new visits.

For each visit record:

• Visits contains the total number of visits by that visitor.
• VisitDate contains the date of this visit.
• Duration contains the number of seconds the visitor was on the site for this visit.
• FirstDate contains the date of the first visit by that visitor.
• LastDate contains the date of the last visit by that visitor.
• Name, Company,Email contain the visitor contact information.
• OS, Browser contain the operating system & browser that the visitor used for this visit.

The remaining fields are related to that visit.

The Flags property is a string containing Y and N characters which indicate (Y or N by position):

1. Matched to Site Entry Alert
2. Invited
3. Chatted
4. Prospect
5. Customer
6. Spider

You can use the GetVisit command to request visit detail for any visit.

Visit Lists Design Notes

You should cache visit lists for previous days rather than re-requesting the list from the WhosOn Server.

When viewing for the current day use the 'FromID' parameter to only request new visits since the last request.

Other Commands

These commands are stand alone and can be sent at any time (once logged in).

Sentiment Analysis

The WhosOn Server automatically scores chats for sentiment and automatically trains the Sentiment database based on the Rating field of completed chat Post-Chat Surveys. However, you can use these commands to score & train the Sentiment Analysis database independently. You must be logged in with a user with Admin user rights to use these commands.

SentimentScore (Command)

{
    "Command": "SentimentScore",
    "Parameters": [
        "1",
        "This is good!"
    ]
}

Copy

This command can be used to score any text for sentiment.

Parameters: SiteKey, Text to be scored.

The WhosOn Server maintains separate sentiment training data for each site. You must pass the SiteKey to use for the scoring. The logged in user must have access to the site.

The server will respond with a sentimentscore event:

SentimentScore (Event)

{
    "EventName": "sentimentscore",
    "Header": null,
    "Data": 99
}

Copy

Data will contain the score. 100 being maximum positive, 1 being maximum negative. 50 is neutral. Zero indicates the text could not be scored.

SentimentTrainPos (Command)

{
    "Command": "SentimentTrainPos",
    "Parameters": [
        "1",
        This is good"
    ]
}

Copy

This command is used to add POSITIVE training data to the sentiment database.

Parameters: SiteKey, Text to be trained.

The WhosOn Server maintains separate sentiment training data for each site. You must pass the SiteKey for the site you wish to train.

The server will respond with a sentimenttrained event:

SentimentTrained (Event)

{
    "EventName": "sentimenttrained",
    "Header": null,
    "Data": 99
}

Copy

Data will contain the updated score for the trained text. The training will affect any new sentiment scoring for chats against the site specified.

SentimentTrainNeg (Command)

{
    "Command": "SentimentTrainNeg",
    "Parameters": [
        "1",
        "This is bad"
    ]
}

Copy

This command is used to add NEGATIVE training data to the sentiment database.

As with the SentimentTrainPos command, however the text will be trained as negative sentiment.

The SentimentTrainPos & SentimentTrainNeg commands can be used to train the Sentiment Analysis for any given site. This will improve accuracy of chat scoring.

SummarizeText (Command)

{
    "Command": "SummarizeText",
    "Parameters": [
        "Check this out. It's the Milky Way galaxy as you've probably never seen it before. Astronomers in the western Australian outback have captured this image of the centre of the galaxy in which we live. The picture from the Murchison Widefield Array telescope shows what our galaxy would look like if human eyes could see radio waves. Awesome right?! Experts say that studying our galaxy can be a bit like trying to take in the view of an entire forest while standing in the middle of it. But instead of trees obscuring the view, it's dust and gas"
    ]
}

Copy

This command can be used to summarize any given text. The WhosOn Server automatically adds summary text to each chat, however you can use this command to summarize any text independently.

A summarizedtext event will be sent.

Parameter: The text to be summarized.

SummarizedText (Event)

{
    "EventName": "summarizedtext",
    "Header": null,
    "Data": "The picture from the Murchison Widefield Array telescope shows what our galaxy would look like if human eyes could see radio waves."
}

Copy

Data will contain a summary of the text sent with the last SummarizeText command. The Summarizer algorithm attempts to extract the most important part of the text. If the text cannot be summarized, then a blank string will be returned.

GeoIP

The GetGeoIP command can be used to retrieve Geo-IP data for any IP address. The WhosOn Server automatically assigns Geo-IP data to all visitors and chat sessions, however you can use this command to lookup Geo-IP for any given IP address.

GetGeoIP (Command)

{
    "Command": "GetGeoIP",
    "Parameters": [
        "195.62.193.194"
    ]
}

Copy

Parameters: IP address

A geoip event will be sent:

GeoIP (Event)

{
    "EventName": "geoip",
    "Header": "195.62.193.194",
    "Data": {
        "IPAddress": "195.62.193.194",
        "IsProxy": false,
        "IsSatellite": false,
        "PostCode": "ST1",
        "Latitude": 53.0278,
        "Longitude": -2.1658,
        "Radius": 20,
        "ISP": "Internet Central Limited",
        "CountryISO": "GB",
        "CountryName": "United Kingdom",
        "City": "Stoke-on-Trent",
        "MetroCode": "",
        "Organization": "Parker Software",
        "RegionName": "",
        "RegionISO": ""
    }
}

Copy

Note: The GeoIP data provided by WhosOn should only be used to provide location data for WhosOn users. It is beyond the WhosOn license scope to use the geo-ip data to pass on to 3rd parties or use in applications outside the scope of WhosOn.

---