WhosOn Version 10 Client API

Introduction

The WhosOn Client API enables you 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 custom WhosOn Live Chat Operator Client applications using any developer platform that supports WebSockets.

The maximum number of concurrent client API connections to the WhosOn Server depends on the licensed user count you have purchased. A single WhosOn server is capable of up to 500 concurrent client connections.

Use Cases

Create WhosOn Live Chat Operator Client applications with a much or as little functionality as you need, on any platform using any development tool.
Embed WhosOn Live Chat 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 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.

Terminology

Throughout this document we use the following terms:

Term	Meaning
Client	Your client application. A 'client' also means a single connected user session against the WhosOn Server.
User	The user details for your client connection. When your client logs in to WhosOn you must supply a username/password. These are checked against the user list. Only authenticated users will be allowed to login. A user is an 'operator' within your organization that will respond to chat requests from visitors.
Visitor	A 'visitor' is a user of your website. WhosOn tracks real time visitor information. A visitor may start a chat session by clicking the 'Click To Chat' button. If you are not using visitor tracking or if a chat is started via another source, then a 'visitor' will be created when a chat session is created.
Chats/Chat	A 'chat' is an active chat session. Visitors can start a chat session from your website, or from other sources.
Chatting Visitors	A list of currently active chat sessions.
Site	A monitored site within WhosOn. WhosOn allows you to create multiple 'sites'. Each site can be associated with a different website, or you can use multiple WhosOn 'sites' within different parts of the same website. Visitors and chat sessions are associated with a single site. Each site has a unique 'SiteKey'. You can create various properties for each site, such as departments, skills, chat routing, queuing and text rules. Each user can be assigned to one or more sites.

Sending Commands

JSON text is used for all messages.

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

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

The command 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 "Params": null

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

Example:

{
    "Command": "Login",
    "Params": [
        "thomas@mysite.com",
        "abcd1234"
        "MYSERVERAUTH",
        "Thomas Parker",
        "Support",
        "0",
        "en",
        "WhosOn Client",
        "24.1.1"
    ]
}

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 server events occur (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 as JSON text in the following format:

{
    "EventName": "eventname",
    "Params": [
        "param1",
        "param2"
     ],
    "Data": "data"
}

Where EventName property is the name of the WhosOn Server Event. The event name will always be lower-case. The Params property may contain an array of parameters associated with the event, or it will be null.

The Data property will either be a single string, null or a JSON object (or array).

Example:

{
    "EventName": "connected",
    "Params": [
        "65be1c5cc937df0b17ae1728"
    ],
    "Data": {
        "ApplicationName": "WhosOn",
        "Version": "10.1.1.1",
        "ServerUid": "65d5c4bac937df0f60c916aa",
        "ServerGeoIPDate": "Jan 2024",
        "RegisteredUser": "My Company",
        "MaxUsers": 999,
        "EvaluationVersion": false,
        "GatewayUrl": "https://gateway.mysite.com/",
        "GatewayAddress": "gateway.mysite.com",
        "GatewayPort": 80,
        "GatewayPortSSL": 443,
        "GatewayPassthroughUrl": "https://gateway.mysite.com/p/xxxxx/",
        "ChatUrl": "https://chat.mysite.com/chat/",
        "AuthToken": ""
    }
}

All event data sent by the WhosOn Server to your client connection will only contain data relevant to your logged in 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.

Making The Connection

Connect a secure WebSocket on URL wss://{server}:{port}. Replace {server} with the IP address or DNS name of the WhosOn Server or the Web Server if connecting via a proxy. The WhosOn Server uses a self-signed certificate for the secure connection. You can assign your own full trust certificate in the server settings.

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.

After a successful connection your client will receive a Hello event response:

{
    "EventName": "hello",
    "Params": null,
    "Data": {
        "Application": "WhosOn",
        "Version": "10.1.1.1",
        "ConnectionId": "65c205c8c937df08d2d09fd5"
    }
}

After receiving the Hello response, you can then send the Login command to login. Do not send any commands until you have received the hello response.

Port

The WhosOn Server listens for client websocket connections on port 8013 by default. The port can be changed in the WhosOn Server Settings.

Client IP Pass Through

Clients can connect using IIS (or another web/proxy server) on port 443 as a proxy (rather than a direct connection to the WhosOn Server itself). 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 Client. The WhosOn Client can also be used to clear the temporary blacklist.

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

Logging In

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

{
    "Command": "Login",
    "Params": [
        "thomas@mysite.com",
        "password1234",
        "MYSERVERAUTHSTRING",
        "Thomas Parker",
        "Support",
        "0",
        "en",
        "Windows",
        "1.0.0.1"
    ]
}

Parameters:

Username
Password
Authentication String - this is the WhosOn Server authentication string. It must match the server authentication string setting.
Full name - the user's full name. This is optional. If blank or the 'Can Change Own Name On Login' user right is false then the user's full name from their user record will override this value. This also applies to department.
Department
Status - is the initial status the client user should be set to (0=Online, 1=Busy, 2=BRB, 3=Away).
Language - is the user's two letter language code - if blank the language assigned to the user record is used.
Client Platform - can be a name indicator for your client application.
Client Version - can be a version indicator of your client app.

If the login in accepted, you will receive a number of post-login events. See Events Received After Login.

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

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

Data will contain the reason for the login failure.

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

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

nameduser - user properties for your connected user.
clientsettings - the user specific and server-wide custom user settings (only sent if exists).
sites - an array of sites that the connected user has access to.
clients - an array of currently of connected users.
chatting - an array of current active chat sessions.
missedchats - an array of pending missed chats (only if the user can respond to missed chats).
connected - the connected header.

NamedUser (Event)

{
    "EventName": "nameduser",
    "Params": [
        "65be1adac937df0f6f2582ff"
    ],
    "Data": {
        "Username": "thomas@mysite.com",
        "Name": "Thomas",
        "Dept": "",
        "Email": "thomas@mysite.com",
        "Phone": "",
        "Title": "",
        "UTCBias": -5,
        "MaxChats": 0,
        "AutoAccept": false,
        "SiteKeys": "1,2",
        "Skills": "1,2,3",
        "Rights": "YYYYYYYYYNYYY1NN",
        "IsAdmin": false,
        "IsSupervisor": false,
        "IsTeamLeader": false,
        "IsBot": false,
        "KeepLog": true,
        "WorkPeriodId": "65c0b2d6c937df0524b56709",
        "GroupId": "65c0b508c937df087364f71e",
        "GroupName": "Support",
        "HasPhoto": true,
        "PhotoFileName": "thomas.png",
        "GreetingMessage": "Good %TimeOfDay% %Name%. My name is %MyName% how can I help you?",
        "ClientOptions": "Theme=Dark;AutoLogout=True;",
        "RequirePasswordReset": false,
        "SetPasswordTo": "",
        "BotSettings": null
    }
}

Parameters will contain your connection id.

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 GreetingMessage property contains a custom greeting message that can override the default GreetingMessage property sent with the Site. The greeting message can be used to set the default chat line text when the user starts a new chat. If blank, use the GreetingMessage value received with the Site.

The ClientOptions property contains any client options/settings.

User Rights

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

Can Edit Properties (allowed to login to Settings Portal)
Can View Reports
Can View Daily Summary (Site visitor totals)
Can Edit Local Settings
Can Take Chats
Can Respond To Missed Chats
Can Chat To Other Users (User-To-User Chat)
Can Monitor Other Users Chats
Can Change Own Name On Login
Can Delete Chats
Can See Users Outside Of Own Department
Can Transfer Chats To Users Outside Of Own Department
User-To-User Chats Are Stored In Database
Can Send Single Use Files To Visitors (0=Ask,1=Always,2=Never)
Can Use Co-Browse
Can Ask For Payment
Can Edit Articles
Can Edit Auto Responses
Can Add/Delete Documents
Can Use AI Assist
Can View Active Visitors

If the Rights property ends with a 'S' character, then the user is the System Administrator. Only 1 user can be the system administrator. You will only receive user information for the system administrator if you have logged in using the system administrator credentials.

If the Rights property ends with 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",
    "Params": null,
    "Data": 
        [
            {
                "SiteKey": 1,
                "Name": "My Company",
                "Domain": "www.mysite.com",
                "Paused": false,
                "HasTrackingCode": false,
                "UTCBias": 3600,
                "WorkPeriodId": "65c0b2d6c937df0524b56709",
                "GreetingMessage": "Good %TimeOfDay% %Name%. My name is %MyName% how can I help you?",
                "SLAWarningSeconds": 20,
                "SLAReachedSeconds": 40,
                "AllowEmoji": true,
                "AllowFileUpload": 2,
                "DisableFileSend": false,
                "TranslationEnabled": false,
                "PreventBlock": false,
                "OnDemandFields": [
                    {
                        "FieldName": "Email",
                        "FieldType": "email",
                        "Prompt": "What is your email address?"
                    },
                    {
                        "FieldName": "Reference",
                        "FieldType": "text",
                        "Prompt": "What is your reference"
                    }
                ],
                "WrapUp": {
                    "Message": "Please select one of the options",
                    "Type": "Menu",
                    "Options": [
                        {
                            "Value": "sales",
                            "DisplayValue": "Sales Enquiry",
                            "SubOptions": [
                                {
                                    "Value": "quote",
                                    "DisplayValue": "Wants Quotation",
                                    "SubOptions": null
                                },
                                {
                                    "Value": "call",
                                    "DisplayValue": "Wants Callback",
                                    "SubOptions": null
                                }
                            ]
                        },
                        {
                            "Value": "support",
                            "DisplayValue": "Support Enquiry",
                            "SubOptions": null
                        }
                    ],
                    "Required": true,
                    "Show": "SessionEnd",
                    "Enabled": true
                },
                "CustomForm": {
                    "Enabled": false,
                    "Title": "",
                    "URL": ""
                },
                "CRM": {
                    "Enabled": true,
                    "AutoPosting": true,
                    "ShowClientButton": false
                },
                "Tags": [
                    "Sales",
                    "Order Placed",
                    "Complaint"
                ],
                "TransferQueues": [
                    {
                        "Number": 1,
                        "Name" : "Default Queue",
                        "Count": 0,
                        "CurrentWait": 0,
                        "MaxSessions" : 100
                    }
                ],
                "SiteINI": ""
            }
        ]
}

The Sites array 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 an administrator changes any site properties (for sites that your user has access to).

Site Properties

The following site properties are sent for each site in the sites event. Many more properties can be configured for sites. 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.
SLAWarningSeconds	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. This setting can be used in your client to show waiting chats with a different color if they have been waiting longer than this value.
SLAReachedSeconds	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. This setting can be used in your client to show waiting chats with a different color if they have been waiting longer than this value.
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.
OnDemandFields	A list of On Demand Survey fields defined against the site. On demand fields can be requested during chat sessions. See: FieldRequest.
WrapUp	See Chat Wrap-Up below.
CustomForm	Option to show a custom tab on chat forms. Show a tab with specified title and url.
CRM	The CRM Integration settings defined for the site.
Tags	Any chat tags defined for the site. See: ChatAddTags.
SiteINI	Any custom settings defined for the site.

Chat Wrap-Up

The WrapUp property contains the wrap-up settings defined for the site. This is to allow the user to select a value to assign to a chat. If Enabled is true then you should offer the user the option of selecting a wrap-up value. If Required is true then the user must complete the wrap-up. The wrap-up value is stored with the chat. The Show property will be one of:

SessionStart - show the wrap up selector at the start of the chat.
SessionEnd - show the wrap up at the end of the chat.
OperatorClose - show when the operator closes their chat view.

The Options property is an array of Value/DisplayValue value items. Options can contain sub-options for nested menu style selection. The display value is the text to display in your UI. The value is the value to assign to the wrap-up value if that option is selected.

The Type property will be one of:

Buttons - show a list of buttons
List - show a combo-box style list selector
Menu - show a menu.
Link - show as clickable URL links

In your client you need to construct the UI to allow the user to select one of the Options. The selected value is sent with the ChatWrapUpComplete command.

Clients (Event)

{
    "EventName": "clients",
    "Params": null,
    "Data": 
         [
            {
                "ConnectionId": "65be1adac937df0f6f2582ff",
                "UserName": "thomas@mysite.com",
                "Name": "Thomas",
                "Dept": "",
                "Email": "thomas@mysite.com",
                "Status": 0,
                "StatusMessage": "",
                "Lang": "en",
                "Chats": 0,
                "MaxChats": 0,
                "MaxAsyncChats": 0,
                "Skills": "Sales,Support",
                "Rights": "NYYYYYYYNNNYYNYYN0",
                "Supervisor": false,
                "TeamLeader": false,
                "Admin": false,
                "Platform": "Win",
                "Version": "24.1.1",
                "IP": "192.168.10.43",
                "GroupId": "65c0b508c937df087364f71e",
                "GroupName": "Support",
                "HasPhoto": false,
                "IsBot": false
            },
            {
                "ConnectionId": "65be1afac937df06bb1c86d5",
                "UserName": "martin@mysite.com",
                "Name": "Martin",
                "Dept": "",
                "Email": "martin@mysite.com",
                "Status": 0,
                "StatusMessage": "",
                "Lang": "en",
                "Chats": 1,
                "MaxChats": 0,
                "MaxAsyncChats": 0,
                "Skills": "Support",
                "Rights": "YYYYYYYYYYNYYNYYY0",
                "Supervisor": false,
                "TeamLeader": false,
                "Admin": true,
                "Platform": ".NET Client",
                "Version": "18.0.0.492",
                "IP": "192.168.10.21",
                "GroupId": "",
                "GroupName": "",
                "HasPhoto": true,
                "IsBot": false,
            }
        ]

Data contains an array of currently connected users (clients). The list has an item for each user currently connected to the WhosOn Server that your user has access to (including your own client). The ConnectionId property is the unique 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 status, and ClientRemove events as users disconnect.

Chatting (Event)

{
    "EventName": "chatting",
    "Params": null,
    "Data": [
        {
            "ChatUID": "65b3b5f6c937df03142c7e51",
            "SiteKey": 1,
            "IP": "195.62.193.194",
            "TrackingId": "",
            "Name": "Melina",
            "Dept": "Sales",
            "SkillIds": "65b3b5f6c937df03142c7e83",
            "SkillNames": "Sales",
            "WaitedSeconds": 13,
            "QueuePos": 0,
            "TalkingToClientId": "65be1afac937df06bb1c86d5",
            "Lang": "en",
            "Translation": false,
            "MonitoredBy": null,
            "Location": "United Kingdom - Stoke on Trent",
            "Channel": ""
        }
    ]
}

Data contains an array of currently active chat sessions.

Your client will normally only receive the Chatting event 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 your user has access to) in the Chatting, ChatChanged & ChatClosed events. The TalkingToClientId property contains the Connection ID of the client user that has picked up the chat. If this is blank, then the chat is available to pick up.

MissedChats (Event)

{
    "EventName": "missedchats",
    "Header": null,
    "Data": 
        [
            {
                "ChatUID": "65b3b5f6c937df03142c7e51",
                "SiteKey": 1,       
                "IP": "195.62.193.194",
                "TrackingId": "",
                "VisitNo": 11,
                "DNS": "1234567890.test.com",
                "Location": "United Kingdom - Stoke on Trent",
                "Dept": "",
                "SkillIds": "65b3b5f6c937df03142c7e83",
                "SkillNames": "Sales",
                "Lang": "en",
                "Translation": false,               
                "Started": "2019-09-15T11:25:04.543",
                "WaitedSeconds": 67,
                "Name": "Howard Williams",
                "Email": "howard@test.com",
                "Phone": "01782822577",
                "Message": "I need some support.. Could someone contact me.",
                "ResponseStarted": false,
                "ResponseStartedBy": "",
                "WantsCallback": true,
                "WantsCallbackOn": "2019-09-15T11:26:33.877"
            }
        ]
    }
}

Data contains an array of pending Missed Chats (Missed chats that have not yet been responded to 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 when the missed chat has expired).

You can request the detail of any missed chat by sending the GetChatDetail 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 and also where the visitor leaves a message or callback request because no users were available.

Connected (Event)

{
    "EventName": "connected",
    "Params": [
        "65be1c5cc937df0b17ae1728"
    ],
    "Data": {
        "ApplicationName": "WhosOn",
        "Version": "10.1.1.1",
        "ClientVersion": "10.1.230.1",
        "ServerUid": "65d5c4bac937df0f60c916aa",
        "ServerGeoIPDate": "Jan 2024",
        "RegisteredUser": "My Company",
        "MaxUsers": 999,
        "MinimumPasswordLength": 8,
        "EvaluationVersion": false,
        "GatewayUrl": "https://gateway.mysite.com/",
        "GatewayAddress": "gateway.mysite.com",
        "GatewayPassthroughUrl": "https://gateway.mysite.com/p/xxxx",
        "ChatUrl": "https://chat.mysite.com/chat/",
        "AuthToken": ""
    }
}

This is the last automatic post-login event your client will receive, therefore you can use this event to indicate a successfully completed login. Parameters will contain your client Connection ID. The Connection Id is unique for your client's current connection. Data contains information about the WhosOn Server.

After receiving the connected event - you can populate any current chat/site/user views, since you will have already received the sites, clients and chatting events.

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",
    "Params": [
        "username",
        "oldpassword",
        "newpassword"
    ]
}

Parameters:

Username - must match the username you have logged in with.
Old Password
New Password

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

Note: User passwords are saved by WhosOn as secure on-way hashes, therefore it is not possible to retrieve a plaintext password if a user forgets it. The Administrator must assign a new password in these instances. 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.

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

PasswordChanged (Event)

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

Client Options

The NamedUser and 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;

You can save/update the options string when saving a user using the SaveUser command.

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",
    "Params": null,
    "Data": "Visitor Melina has already started chatting to Daniel"
}

Error (Event)

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

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

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.

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

GetSkills - gets a list of skills.
GetDocuments - gets a list of available uploaded documents.
GetAutoResponses - gets a list of auto-responses (previously called 'Canned Responses').
GetArticleList - gets a list of knowledge store articles.
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.
GetDaySummary - gets site traffic summary data for the current day.
GetUserPhotos - gets avatars for users.
GetVisitors - gets a list of currently active website visitors.

All of these are optional, however you should send the GetSkills, GetDocuments & GetAutoResponses 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",
    "Params": null
}

Skills (Event)

{
    "EventName": "skills",
    "Params": null,
    "Data": [
        {
            "Id": "65c0ffd5c937df0b5f889938",
            "ParentId": "",
            "Name": "Sales",
            "CreatedByUser": "thomas@mysite.com",
            "SiteKeys": "1,2,3"
        },
        {
            "Id": "65c10033c937df02e0dd66ec",
            "ParentId": "",
            "Name": "Support",
            "CreatedByUser": "thomas@mysite.com",
            "SiteKeys": "1,2,4"
        }
    }
}

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

You will need to request skills if you want to perform manual skills-based transfers within your client application.

GetDocuments (Command)

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

{
    "Command": "GetDocuments",
    "Params": null
}

Documents (Event)

{
    "EventName": "documents",
    "Params": null,
    "Data": [
        {
            "Id": "65b3b9cfc937df1341329981",
            "FileName": "quote.pdf",
            "Folder": "quotes/recent/",
            "MimeType": "application/pdf",
            "Dated": "2024-01-26T13:56:37.094+00:00",
            "LastAccessed": "2024-01-26T13:56:37.094+00:00",
            "Size": 2839455,
            "CreatedByUser": "thomas@mysite.com",
            "VisitorName": "",
            "VisitorUploaded": false,
            "SiteKey": 23,
            "Pinned": false,
            "SingleUse": false,
            "AccessCount": 23,
            "Base64": null,
        },
        {
            "Id": "65b3b9cfc937df13413340043",
            "FileName": "quote2.pdf",
            "Folder": "quotes/recent/",
            "MimeType": "application/pdf",
            "Dated": "2024-01-26T13:56:37.094+00:00",
            "LastAccessed": "2024-01-26T13:56:37.094+00:00",
            "Size": 2839455,
            "CreatedByUser": "thomas@mysite.com",
            "VisitorName": "",
            "VisitorUploaded": false,
            "SiteKey": 23,
            "Pinned": false,
            "SingleUse": false,
            "AccessCount": 23,
            "Base64": null,
          }
    ]

Data contains a list of uploaded documents that are available to your user.

The Id property is unique to each document (even if multiple files have the same FileName).

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.

GetAutoResponses (Command)

The GetAutoResponses command can be used to get a list of all pre-defined auto-responses (previously called 'Called Responses') available to your user. The WhosOn Server will send the AutoResponses event.

{
    "Command": "GetAutoResponses",
    "Params": null
}

AutoResponses (Event)

{
    "EventName": "autoresponses",
    "Params": null,
    "Data": 
        [
          {
            "Id": "65b3b9cfc937df1341329981",
            "ParentId": "",
            "SortId": "",
            "Dated": "2024-01-26T13:56:37.094+00:00",
            "Subject": "What are your opening hours",
            "Content": "We are open from 9am to 5pm, Monday to Friday.",
            "DocumentId": "",
            "Tag": "",
            "KeywordsFixed": "",           
            "SiteKeys": "1,2",
            "SkillIds": ""
          },
          {...}
          {...}
        ]
}

Data contains a list of auto responses setup on the WhosOn Server that are available to the user. The SiteKeys is a comma separated list of SiteKeys that the auto-response can be used on. If SiteKeys is blank then the auto-response is available to the current user only and not shared with other users. The SkillIds is a comma separated list of Skill Id's that the auto-response is available for (or blank if the article is available for all skills).

Each auto response has an Id and ParentId allowing auto responses to be displayed in a tree structure.

GetArticleList (Command)

The GetArticleList command can be used to get a list of all pre-defined knowledge store articles available to your user. The WhosOn Server will send the ArticleList event.

You should only get all articles when you need to display an 'Knowledge Store Editor' view in your client. The client does not need to load articles for any sort of processing, since the WhosOn Server handles the search and matching of articles for chat line suggestions & bot responses.

{
    "Command": "GetArticleList",
    "Params": null
}

ArticlesList (Event)

{
    "EventName": "articlelist",
    "Params": null,
    "Data": 
        [
          {
            "Id": "65b3b9cfc937df1341329981",
            "ParentId": "",  
            "SortId": "",
            "Subject": "Product Information",       
            "SiteKeys": "1,2",
            "SkillIds": ""
          },
          {...}
          {...}
        ]
}

Data contains a summary list of articles setup on the WhosOn Server that are available to the user. The SiteKeys is a comma separated list of SiteKeys that the article can be used on. The SkillIds is a comma separated list of Skill Id's that the article is available for (or blank if the article is available for all skills).

Each article has an Id and ParentId allowing articles to be displayed in a tree structure.

You would use the GetArticleDetail command to get individual article content.

GetUsers (Command)

The GetUsers command can be used to get a list of all users (available to your user), regardless of logged in status. The WhosOn Server will send the Users event.

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

Users (Event)

{
    "EventName": "users",
    "Params": null,
    "Data":  [
        {
            "UserName": "thomas@mysite.com",
            "Name": "Thomas",
            "Dept": "Support",
            "Email": "thomas@mysite.com",
            "Phone": "",
            "Title": "",
            "Lang": "en",
            "UTCBias": -5,
            "MaxChats": 0,
            "AutoAccept": false,
            "SiteKeys": "1,2",
            "SkillIds": "65c10033c937df02e0dd66ec,65c0ffd5c937df0b5f889938",
            "Rights": "NYYYYYYYNNNYYNYYN0",
            "IsAdmin": false,
            "IsSupervisor": false,
            "IsTeamLeader": false,
            "IsBot": false,
            "KeepLog": true,
            "SuggestResponses": true,
            "WorkPeriodId": "65c34f70c937df08d5e27426",
            "GroupId": "65b3b5f6c937df03142b2a23",
            "GroupName": "Support",
            "HasPhoto": true,
            "PhotoFileName": "thomas.png",
            "GreetingMessage": "Good %TimeOfDay% %Name%. My name is %MyName% how can I help you?",
            "ClientOptions": "Theme=Dark;AutoLogout=True;",
            "RequirePasswordReset": true,
            "SetPasswordTo": "",
            "BotSettings": null
        },
        {
            "UserName": "Kryten",
            "Name": "Kryten",
            "Dept": "",
            "Email": "",
            "Phone": "",
            "Title": "",
            "Lang": "en",
            "UTCBias": 0,
            "MaxChats": 99,
            "AutoAccept": false,
            "SiteKeys": "1010",
            "SkillIds": "",
            "Rights": "NNYYYNYYYYYYY0TrueNN",
            "IsAdmin": false,
            "IsSupervisor": false,
            "IsTeamLeader": false,
            "IsBot": true,
            "KeepLog": true,
            "SuggestResponses": false,
            "WorkPeriodId": "",
            "GroupId": "",
            "GroupName": "",
            "HasPhoto": false,
            "PhotoFileName": "",
            "GreetingMessage": "Good %TimeOfDay% %Name%. My name is %MyName% how can I help you?",
            "ClientOptions": "",
            "RequirePasswordReset": false,
            "SetPasswordTo": "",
            "BotSettings": {
                "Enabled": true,
                "UseLLM": true,
                "BotType": "LLM",
                "PickupSecsOpsOffline": 5,
                "PickupSecsOpsOnline": 30,
                "PickupOnlyWhenOpsOffline": false,
                "CloseIdleAfterSecs": 300,
                "FailAttempts": 3,
                "FailTransfer": true,
                "INI": ""
            }
    ]

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",
    "Params": null
}

UserGroups (Event)

{
  "EventName": "usergroups",
  "Params": null,
  "Data": [
      {
        "Id": "65b3b5f6c937df03142b2a23",
        "Name": "Support",
        "Dept": "",
        "MaxChats": 0,
        "AutoAccept": false,
        "SiteKeys": "1",
        "SkillIds": "",
        "Rights": "NNYNYYYYNNNYYNNYN0",
        "IsAdmin": false,
        "IsSupervisor": false,
        "SuggestResponses": true,
        "WorkPeriodId": "",
        "ModeratorList": "",
        "Lang": "Lang"
      }
    ]
  }
}

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 your user). The WhosOn Server will send the WorkPeriods event. You do not need to specifically request work periods, unless you want to display or edit. The WhosOn Server automatically handles work period status changes.

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

WorkPeriods (Event)

{
  "EventName": "workperiods",
  "Header": null,
  "Data":  [
      {
        "Id": "65b3b5f6c937df03126a9c92",
        "Description": "Default Working Day",
        "CreatedByUser": "admin@mysite.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": ",,,"
      }
    ]

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",
    "Params": [
        "65be1afac937df06bb1c86d5",
        "Hello"
    ]
}

Parameters:

Connection ID - of the other client you want to send a message to.
Message Text - max 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",
    "Params": [
        "65be1afac937df06bb1c86d5"
    ]
}

Parameters:

Your Connection ID

The other user will receive the C1 event.

To disable the typing indicator, send the C0 command:

C0 (Command)

{
    "Command": "C0",
    "Params": [
        "65be1afac937df06bb1c86d5"
    ]
}

Parameters:

Your Connection ID

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",
    "Params": [
        "65be1afac937df06bb1c86d5"
    ],
    "Data": "hello back"
}

Parameters contains the Connection ID of the sending client. 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",
    "Params": [
        "65be1afac937df06bb1c86d5"
    ],
    "Data": ""
}

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

When the other user stops typing you will receive:

{
    "EventName": "c0",
    "Params": [
        "65be1afac937df06bb1c86d5"
    ],
    "Data": ""
}

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": [
        "thomas@mysite.com",
        "",
        ""
    ]
}

Parameters:

Username of the other user
Start At 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 Start At ID parameter is blank, 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 last ID received from the previous ClientChat event.

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",
    "Params": [
        "thomas@mysite.com"
    ],
    "Data": [
        {
            "Id": "65be1c5cc937df0b17ae1728",
            "Dated": "2019-10-05T22:59:07.553",
            "MyLine": true,
            "Text": "hello"
        },
        {
            "Id": "65be1c6ac937df0817058d4f",
            "Dated": "2019-10-05T19:05:49.707",
            "MyLine": true,
            "Text": "Hi.. this is a test"
        }
    ]
}

Parameters 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",
    "Params": [
        "Please logout, we are updating the server."
    ]
}

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",
    "Params": [
        "2",
        "Just grabbing a coffee"
    ]
}

Parameters:

Status Number
Status Message (optional)

The first parameter is the status number:

0 = Online
1 = Busy
2 = Be right back
3 = Away

The second parameter is optional and can be set to a 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 event.

ClientEvent (Event)

{
    "EventName": "clientevent",
    "Params": null,
    "Data": {
        "ConnectionId": "65be1ca7c937df08c475b522",
        "UserName": "thomas@mysite.com",
        "Name": "Thomas",
        "Dept": "",
        "Email": "thomas@mysite.com",
        "Status": 1,
        "StatusMessage": "some message",
        "Lang": "en",
        "Chats": 0,
        "MaxChats": 0,
        "MaxAyncChats": 0,
        "Skills": "",
        "Rights": "NYYYYYYYNNNYYNYYN0",
        "Supervisor": false,
        "TeamLeader": false,
        "Admin": false,
        "Platform": "Web",
        "Version": "19.1.1",
        "IP": "192.168.10.123",
        "GroupId": "",
        "GroupName": "",
        "HasPhoto": false,
        "IsBot": false
    }
}

The ClientEvent will also be received when another user changes their status, or 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, maximum current chats reached etc), or by another user, your client will receive a Status event.

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

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 '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": [
        "65be1ca7c937df08c475b522",
        "2"
    ]
}

Parameters:

Connection ID - of the user you want to change
Status number

Status number should be one of:

Online
Busy
Be Right Back
Away

The other user will receive a Status event.

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

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",
    "Params": null,
    "Data": "65be1ca7c937df08c475b522"
}

Data contains the Connection ID of the user logging out.

You would use the Clients, ClientEvent & ClientRemove events to maintain a list of other connected users that you can display in your client for transfers and user-to-user chat.

Logging Out

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

Close (Command)

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

You should then disconnect the WebSocket connection.

You can just disconnect the WebSocket connection without sending the Close command 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
}

Chatting Visitors

After you have logged in your client will receive the Chatting event containing a list of all current chatting visitor sessions. 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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": {
        "ChatUID": "65b3b5f6c937df03142c7e51",
        "SiteKey": 1,
        "IP": "195.62.193.194",
        "TrackingId": "",
        "Name": "Howard Williams",
        "Dept": "",
        "SkillNames": "Sales",
        "WaitedSeconds": 0,
        "QueuePos": 0,
        "TalkingToClientId": "",        
        "Lang": "en",
        "Translation": false,
        "MonitoredBy": null,
        "Location": "United Kingdom - Stoke on Trent",
        "Channel": ""
    }
}

The ChatChanged event will be sent for any new chat and when an existing chat changes (eg: It is picked up by a user, or a user leaves a chat without closing it). Parameters will contain the ChatUID.

The SkillNames of the Chatting and ChatChanged events contains a comma-separated skills assigned to the chat. The WhosOn Server assigns skills to each chat based on the chat routing rules defined for the site. If the SkillNames 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 TalkingToClientId property will contain the Connection ID of the user that has taken the chat:

{
    "EventName": "chatchanged",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": {
        "ChatUID": "65b3b5f6c937df03142c7e51",
        "SiteKey": 1,   
        "IP": "195.62.193.194",
        "TrackingId": "",
        "Name": "Howard Williams",
        "Dept": "",
        "SkillNames": "Sales",
        "WaitedSecs": 5,
        "QueuePos": 0,
        "TalkingToClientId": "65be1ca7c937df08c475b522",
        "Lang": "en",
        "Translation": false,
        "MonitoredBy": "Thomas",
        "Location": "United Kingdom - Stoke on Trent",
        "Channel": ""
    }
}

The MonitoredBy property will contain the user's name if it is being monitored.

In your client application, you should display a list of current chat sessions.

ChatClosed (Event)

{
    "EventName": "chatclosed",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": ""
}

When a chatting visitor is removed the ChatClosed event will be sent. Parameters contains the ChatUID.

You should 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 a blank TalkingToClientId 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, work period etc. Therefore, if your client user receives a Chat event you 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",
    "Params": [ 
        "65b3b5f6c937df03142c7e51",
        "2",
        "Howard Williams",
        "Support",
        "Technical"
    ],
    "Data": ""
}

This event will be received when a new chat request has been received, that your connected user is able to take.

Parameters array contains:

ChatUID
SiteKey
Visitor name
Requested Department
Skill Names (comma separated list of skill names assigned to that chat).

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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ]   
}

Parameters:

ChatUID

If the WhosOn Server accepts the chat take request it will send a ChatAccepted event. A Msg event will be sent if chat take request was not accepted.

ChatAccepted (Event)

{
    "EventName": "chataccepted",
    "Params": [ 
        "65b3b5f6c937df03142c7e51",
        "Technical"
    ],
    "Data": ""
}

The parameters array will contain:

ChatUID

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

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

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

Auto Accept Chats

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

AcceptChat (Event)

{
    "EventName": "acceptchat",
    "Params": [ 
        "65b3b5f6c937df03142c7e51",
        "2",
        "Test Visitor",
        "Support",
        ""
    ],
    "Data": ""
}

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 choice of whether to take it or not.

PreChatSurvey (Event)

After the ChatAccepted event has been sent the WhosOn Server will send the PreChatSurvey event.

{
    "EventName": "prechatsurvey",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": [
        {
            "Name": "VisitorName",
            "Value": "Howard Williams",
            "BuiltInField": "visitor name"
        },
        {
            "Name": "Company",
            "Value": "Microsoft",
            "BuiltInField": "company name"
        }
    ]
}

The parameter array will contain the following fields:

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. In this case the PreChatSurvey event wont be sent since it is part of the current chat data.

The parameters array will contain the following fields:

ChatUID

{
    "EventName": "currentchat",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": {
        "ChatHeader": {
            "ChatUID": "65b3b5f6c937df03142c7e51",
            "SiteKey": 1,
            "IP": "195.62.193.194",
            "TrackingId": "",
            "DNS": "1234567890.test.com",
            "Location": "United Kingdom - Stoke on Trent",
            "VisitNo": 44,
            "TakenByUsers": "Thomas",
            "TakenByDept": "",
            "TakenByBot": false,
            "Started": "2019-09-24T07:39:18.923",
            "Finished": "2019-09-24T07:40:10.333",
            "WaitedSeconds": 6,
            "DurationSeconds": 51,
            "Lang": "en",
            "Translation": false,
            "Rating": 5,
            "Name": "Howard Williams",
            "Email": "howard@test.com",
            "Phone": "",
            "Missed": false,
            "MissedMessage": "",
            "MissedSeen": false,
            "MissedSeenByUserName": "",
            "MissedSeenOn": "0001-01-01T00:00:00",
            "MissedCallback": false,
            "MissedCallbackOn": "0001-01-01T00:00:00",
            "RequestedDept": "Sales",
            "SentimentScore": 100,
            "WrapUpValue": "Option 1",
            "Tags": ["Sales","Quoted"],
            "Summary": "I need some prices.",
            "Channel": "",
            "State": 0,
            "SkillNames": "",
            "TranscriptURL": ""
        },
        "PreChatSurvey": [
            {
                "Name": "Company",
                "Value": "Microsoft"
            }
        ],
        "PostChatSurvey": [
            {
                "Name": "Rating",
                "Value": "5"
            },
            {
                "Name": "transEmail",
                "Value": ""
            }
        ],
        "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"
            }
        ],
        "VisitDetail": {
            "SiteKey": 1,
            "SiteName": "My Company",
            "IP": "195.62.193.194",
            "TrackingId": "1234.4567890",
            "DNS": "1234567890.test.com",
            "VisitNo": 44,
            "TotalVisits": 44,
            "Browser": "Chrome 76",
            "OS": "Windows 10",
            "Referrer": "https://chat.mysite.com/newchat/chat.aspx",
            "SessionStarted": "2019-09-24T07:39:13.287",
            "Chatting": true,
            "ChattingLanguage": "",
            "ChattingTranslate": false,
            "PageViews": 3,
            "FirstPage": "index.htm",
            "FirstVisit": "2019-09-10T14:44:47.263",
            "ContactName": "Howard Williams",
            "ContactEmail": "howard@test.com",
            "ContactCompany": "Microsoft",
            "ContactTelephone": "01782822577",
            "ContactNotes": "",
            "ContactStreet": "",
            "ContactCity": "",
            "ContactPostCode": "",
            "ContactCountry": "",
            "ContactWebAddress": "",
            "ContactOrganization": "",
            "CRMId": "",
            "Pages": [
                {
                    "Dated": "2019-09-24T07:39:00.117",
                    "Name": "index.aspx"
                },
                {
                    "Dated": "2019-09-24T07:39:13.287",
                    "Name": "chat.aspx"
                }
            ],
            "GeoIP": {
                "IP": "195.62.193.194",
                "CountryName": "United Kingdom",
                "CountryISO": "GB",
                "City": "Stoke-on-Trent",
                "PostCode": "ST1",
                "MetroCode": "",
                "Latitude": 53.0278,
                "Longitude": -2.1658,
                "Radius": 20,
                "ISP": "Internet Central Limited",
                "Organization": "Parker Software"
            }
        }
    }
}

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,Martin' and the OperatorIndex for a line = 2 then the line was sent by 'Martin'.

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",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "65be1ca7c937df08c475b522",
        "Please pick up the chat session for visitor Test Visitor."
    ],
    "Data": ""
}

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

The parameters array will contain the following fields:

ChatUID
Client Connection ID - of the client user sending the transfer.
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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": ""
}

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. Parameters 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",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "Hello. How can I help?"
    ]
}

Parameters:

ChatUID
Message Text

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

LinkTo (Command)

You can send a URL to a chat either as part of the chat message, or you can send a specific link using the LinkTo command. The visitor will receive the chat line with the URL as normal, but also if they are still active on the website, the current page will be redirected to the URL.

{
    "Command": "LinkTo",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "http://www.mysite.com/pricing/"
    ]
}

Parameters:

ChatUID
URL

Message Filtering

If Chat Text Rules are defined against the Site then the server may filter the message before forwarding the message to the visitor's chat session. Chat Text Rules define text masking rules and profanity, finance and other text filtering.

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

SendToFiltered (Event)

{
    "EventName": "SendToFiltered",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "The word ********* should be filtered.<original>The word testfilter should be filtered.</original>"
}

Parameters will contain the ChatUID. The <Original> tag will contain the originally sent text.

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

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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "Hello. How can I help?<translated>Salut. Comment puis-je aider?</Translated>"
}

Parameters:

ChatUID

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.

Translation (Command)

You can manually enable/disable translation for a specific chat.

{
    "Command": "Translation",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "true"
    ]
}

Parameters:

ChatUID
Enabled ('true' or 'false')

If translation is not enabled on the site, then this command will be ignored.

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": [
        "65b3b5f6c937df03142c7e51",
        "# 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"
    ]
}

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

Sending Documents

To send an existing document file, send the SendDocumentTo command:

SendDocumentTo (Command)

{
    "Command": "SendDocumentTo",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "65b3b9cfc937df1341329981"
    ]
}

Parameters:

ChatUID
Document Id

The Document Id should be the Id to one of the files in the document files list sent with the Documents event.

The chat session will receive a message containing a URL that the visitor can click to download the document.

To upload and send a new document file, send the SendNewDocumentTo command:

SendNewDocumentTo (Command)

{
    "Command": "SendNewDocumentTo",
    "Params": [
        "65b3b5f6c937df03142c7e51"
        "quote2.pdf",
        "/quotes/",
        "false",
        "1",
        "base64encodedcontent"
    ]
}

Parameters (all required):

ChatUID
File Name
Folder (an optional folder name (eg \quotes\recent) can be used to organize documents in your client interface). Set to blank for no folder.
Single Use (true or false). If true the document will be removed once it has been accessed by the visitor in the chat session.
SiteKey. If blank or zero the document will be available on all sites you have access to.
Base64 - base64 encoded file contents.

After the document has been saved to the file store the Document event will be sent to all connected users who have access to the document, if the Single Use property was false.

The chat session will receive a message containing a URL that the visitor can click to download the document.

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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

ChatUID

To disable the typing indicator, send the StopTyping command:

StopTyping (Command)

{
    "Command": "StopTyping",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

ChatUID

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 Document

To request a document file from the visitor, send the DocumentRequest command:

DocumentRequest (Command)

{
    "Command": "DocumentRequest",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

ChatUID

The visitor will then be asked to upload a document in their chat session.

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",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "Reference",
        "Please enter your reference code"
    ]
}

Parameters:

ChatUID
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",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "message"
    ]
}

Parameters:

ChatUID
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",
    "Params": [
        "123.456.789.101"
    ]
}

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",
    "Params": [
        "1",
        "65b3b5f6c937df03142c7e51",
        ""
    ]
}

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",
    "Params": [
        "1",
        "65b3b5f6c937df03142c7e51",
        "from@myserver.com",
        "tovisitor@test.com",
        "subject",
        "false",
        "message",
        "true",
        ""
    ]
}

Parameters:

Sitekey
ChatUID
From email address
To email address
Subject
SMS (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.
Message text - this text is shown in the message body of the email before the transcript.
PDF (true/false) - if 'true' the chat will be converted to a PDF and added as an attachment.
Optional document id - the document file will then be added as an attachment.

Note: Visitors can also request a transcript from their chat session.

Transfers

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

To transfer a chat to another user, send either the Transfer, TransferDept, TransferSkills or TransferQueue command.

Transfer (Command)

{
    "Command": "Transfer",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "65be1c6ac937df0817058d4f,65be1ca7c937df08c475b522",
        "message"
    ]
}

Parameters:

ChatUID
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",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "department",
        "message"
    ]
}

Parameters:

ChatUID
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",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "65c10033c937df02e0dd66ec",
        "Please pickup..."
    ]
}

Parameters:

ChatUID
Comma Separated list of Skill Id's (use the GetSkills command after login to receive a 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.

TransferQueue (Command)

To transfer a chat back onto a queue use the TransferQueue command:

{
    "Command": "TransferQueue",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "1"
    ]
}

Parameters:

ChatUID
Queue Number

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.

Transfer (Event)

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

{
    "EventName": "transfer",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "65be1e38c937df06329af6f6",
        "Please pickup transfer request."
    ],
    "Data": ""
}

Parameters:

ChatUID
Client Connection ID of the client user making the transfer request.
Message

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

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

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",
    "Params": [
        "1",
        "195.62.193.194",
        "123-4567890123",
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

Sitekey
Visitor IP Address
Visitor Tracking Id
ChatUID

The WhosOn Server will respond with a visitdetailchat event.

Data will contain the visit detail.

VisitDetailChat (Event)

{
    "EventName": "visitdetailchat",
    "Params": [
        "1",
        "195.62.193.194",
        "123-4567890123",
        "65b3b5f6c937df03142c7e51"
    ],  
    "Data": {
        "SiteKey": 1,
        "SiteName": "My Company",
        "IP": "195.62.193.194",
        "TrackingId": "123-4567890123",
        "DNS": "1234567890.test.com",
        "VisitNo": 1,
        "TotalVisits": 15,
        "Browser": "Chrome 76",
        "OS": "Windows 10",
        "Referrer": "https://chat.mysite.com/newchat/chat.aspx",
        "SessionStarted": "2019-09-10T14:44:47.263",
        "Chatted": true,
        "Chatted": "",
        "ChattedTranslate": false,
        "PageViews": 1,
        "FirstPage": "index.aspx",
        "FirstVisit": "2019-09-10T14:44:47.263",
        "ContactName": "Howard Williams",
        "ContactEmail": "howard@test.com",
        "ContactCompany": "Microsoft",
        "ContactTelephone": "01782822577",
        "ContactNotes": "",
        "ContactStreet": "",
        "ContactCity": "",
        "ContactPostCode": "",
        "ContactCountry": "",
        "ContactWebAddress": "",
        "ContactOrganization": "",
        "ContactDated": "2019-09-10T14:45:00",
        "CRMId": "",
        "Pages": [
            {
                "Dated": "2019-09-10T14:44:01.321",
                "Name": "index.aspx"
            },
            {
                "Dated": "2019-09-10T14:44:47.263",
                "Name": "chat.aspx"
            }
        ],
        "GeoIP": {
            "IP": "195.62.193.194",
            "CountryName": "United Kingdom",
            "CountryISO": "GB",
            "City": "Stoke-on-Trent",
            "PostCode": "ST1",
            "MetroCode": "",
            "Latitude": 53.0278,
            "Longitude": -2.1658,
            "Radius": 20,
            "ISP": "Internet Central Limited",
            "Organization": "Parker Software"
        }
    }
}

Receiving Messages

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

Message (Event)

{
    "EventName": "message",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "Do you offer an on-premises version?"
}

Parameters:

ChatUID

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 TalkingToConnectionId property is blank, 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 <translated> text </translated> will be appended to the message text. You should extract the translated text from the message and display this in the client chat session view (along with the untranslated text).

Server Response Suggestion

If the user property UserSuggestResponses is true, the WhosOn Server will attempt to match the visitor message to up to 3 auto-responses or articles. If no auto-responses or articles are found then the best matching recent previously sent user message. If one or more matches are found, then a <Suggestions> tag will be appended to the message text. Eg:

{
    "EventName": "message",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "Do you offer an on-premises version?<Suggestions><Suggest><Content>Yes, we offer an on-premises version.</Content></Suggest><Suggestions>"
}

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 a document id, then the <Suggest> tag will include it:

<Suggestions>
    <Suggest>
        <Content>Yes, we offer an on-premises version, please see this document for details</Content>
        <DocumentId>65c10033c937df02e0dd66ec</DocumentId>
    </Suggest> 
</Suggestions>

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

The WhosOn Server searches auto-responses and articles first. If no matching auto-response or article is found it searches previous chats for responses to similar visitor messages (for recent user chats with matching skills).

You can manually search for suggestions using the GetSuggestion command.

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

{
    "EventName": "messageserver",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "You havent said anything for 1 minute. Are you still there?"
}

Parameters:

ChatUID

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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": ""
}

0 (Event)

{
    "EventName": "0",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": ""
}

Parameters will contain the ChatUID. 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 0 (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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "Do you offer a on-pr"
}

Parameters:

ChatUID

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

Document Uploads

When a visitor uploads a file during a chat session, the WhosOn Server will send the Document event to all clients that have access to the document. The Base64 property will be blank.

Your client will also receive a Message event:

{
    "EventName": "message",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "<link><url>{url}</url><name>{filename}</name></link>"
}

The data property will contain a <link> tag. The <url> tag will contain the unique URL for the document and the <name> tag will contain the filename.

You can display the filename/url in your client chat session.

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",
    "Params": [
        "1",
        "65b3b5f6c937df03142c7e51",
        "howard@test.com",
        "123456",
        "Please enter the code below into your chat session to verify:"
    ]
}

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. Once a chat is closed it cannot be re-opened. If you want to leave a chat and allow it to be picked up by another user, send the Leave command instead.

CloseChat (Command)

{
    "Command": "CloseChat",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

ChatUID

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 other user closed chats.

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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

ChatUID

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",
    "Params": [
        "1",
        "65b3b5f6c937df03142c7e51",
        "wrap up value"
    ]
}

Parameters:

Sitekey
ChatUID
Value

The ChatWrapUpComplete command 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",
    "Params": [
        "1",
        "65b3b5f6c937df03142c7e51",
        "Sales,Demo"
    ]
}

Parameters:

Sitekey
ChatUID
Tags (single string of tags separated by commas).

The ChatAddTags command 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 and searched by tag value.

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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": [
        {
            "Name": "Rating",
            "Value": "5",
            "BuiltInField": "chat rating"
        },
        {
            "Name": "FoundBy",
            "Value": "Google",
            "BuiltInField": ""
        }
    ]
}

Parameters will contain:

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.

ChatScored (Event)

If Sentiment Analysis is enabled for the site then closed chats will be analyzed for a sentiment score. The score will be between 1 and 100 where 100 is the most positive. Sentiment analysis is performed by the configured LLM service. The WhosOn Server queues closed chats for scoring, so it may be a several seconds after a chat is closed before you receive the ChatScored event. All users who have access to the chat will receive ChatScored events.

{
    "EventName": "chatscored",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "85"
}

Parameters will contain:

ChatUID

Data will contain the Sentiment Score (1-100).

You can use this event to update a dashboard style view. The sentiment score is also saved with the chat in the WhosOn database.

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",
    "Params": [
        "1",
        "195.34.21.32",
        "123-78729473872",
        "{name}",
        "{email}",
        "{company}",
        "{phone}",
        "{notes}",
        "{street}",
        "{city}",
        "{postcode}",
        "{country}",
        "{webaddress}",
        "{organization}",
        "{crmid}"
    ]
}

Parameters:

Sitekey
IP Address
Visitor Tracking 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",
        "",
        "",
        "",
        "",
        "",
        "",
        "",
        "",
        ""
    ]
}

Once contact information is assigned to a visitor it will show in the Visit Detail for against subsequent visits for the same SiteKey, IP Address, Visitor Tracking 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",
    "Params": null,
    "Data": null
}

The accepted event will also be sent in response to 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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

ChatUID

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

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

Monitoring (Event)

{
    "EventName": "monitoring",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "65be1e8ec937df0cf801e209"
    ],
    "Data": ""
}

Parameters will contain the ChatUID and the Client Connection ID. 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, this contains the full current detail of the monitored chat. The WhosOn Server will also start sending MonitorC and MonitorV Cevents as the monitored chat progresses.

MonitoredChat (Event)

{
    "EventName": "monitoredchat",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": {
        "ChatHeader": {
            "ChatUID": "65b3b5f6c937df03142c7e51",
            "SiteKey": 1,
            "IP": "195.62.193.194",
            "TrackingId": "",
            "DNS": "1234567890.test.com",
            "Location": "United Kingdom - Stoke on Trent",
            "VisitNo": 44,
            "TakenByUsers": "Thomas",
            "TakenByDept": "",
            "TakenByBot": false,
            "Started": "2019-09-24T07:39:18.923",
            "Finished": "2019-09-24T07:40:10.333",
            "WaitedSeconds": 6,
            "DurationSeconds": 51,
            "Lang": "en",
            "Translation": false,
            "Rating": 5,
            "Name": "Howard Williams",
            "Email": "howard@test.com",
            "Phone": "",
            "Missed": false,
            "MissedMessage": "",
            "MissedSeen": false,
            "MissedSeenByUserName": "",
            "MissedSeenOn": "0001-01-01T00:00:00",
            "MissedCallback": false,
            "MissedCallbackOn": "0001-01-01T00:00:00",
            "RequestedDept": "Sales",
            "SentimentScore": 100,
            "WrapUpValue": "Option 1",
            "Tags": ["Sales","Quoted"],
            "Summary": "I need some prices.",
            "Channel": "",
            "State": 0,
            "SkillNames": "",
            "TranscriptURL": ""
        },
        "PreChatSurvey": [
            {
                "Name": "Company",
                "Value": "Microsoft"
            }
        ],
        "PostChatSurvey": [
            {
                "Name": "Rating",
                "Value": "5"
            },
            {
                "Name": "transEmail",
                "Value": ""
            }
        ],
        "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"
            }
        ],
        "VisitDetail": {
            "SiteKey": 1,
            "SiteName": "My Company",
            "IP": "195.62.193.194",
            "TrackingId": "1234.4567890",
            "DNS": "1234567890.test.com",
            "VisitNo": 44,
            "TotalVisits": 44,
            "Browser": "Chrome 76",
            "OS": "Windows 10",
            "Referrer": "https://chat.mysite.com/newchat/chat.aspx",
            "SessionStarted": "2019-09-24T07:39:13.287",
            "Chatting": true,
            "ChattingLanguage": "",
            "ChattingTranslate": false,
            "PageViews": 3,
            "FirstPage": "index.htm",
            "FirstVisit": "2019-09-10T14:44:47.263",
            "ContactName": "Howard Williams",
            "ContactEmail": "howard@test.com",
            "ContactCompany": "Microsoft",
            "ContactTelephone": "01782822577",
            "ContactNotes": "",
            "ContactStreet": "",
            "ContactCity": "",
            "ContactPostCode": "",
            "ContactCountry": "",
            "ContactWebAddress": "",
            "ContactOrganization": "",
            "CRMId": "",
            "Pages": [
                {
                    "Dated": "2019-09-24T07:39:00.117",
                    "Name": "index.aspx"
                },
                {
                    "Dated": "2019-09-24T07:39:13.287",
                    "Name": "chat.aspx"
                }
            ],
            "GeoIP": {
                "IP": "195.62.193.194",
                "CountryName": "United Kingdom",
                "CountryISO": "GB",
                "City": "Stoke-on-Trent",
                "PostCode": "ST1",
                "MetroCode": "",
                "Latitude": 53.0278,
                "Longitude": -2.1658,
                "Radius": 20,
                "ISP": "Internet Central Limited",
                "Organization": "Parker Software"
            }
        }
    }
}

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",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "Daniel"
    ],
    "Data": "message"
}

Parameters:

ChatUID
Other client name

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",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "Daniel"
    ],
    "Data": "message"
}

Parameters

ChatUID
Other client name

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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "Thomas"
}

Parameters:

ChatUID

Data will contain operator name.

Operator Stopped Typing

{
    "EventName": "mc0",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "Thomas"
}

Parameters:

ChatUID

Data will contain the operator name.

Visitor Started Typing

{
    "EventName": "m1",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": ""
}

Parameters:

ChatUID

Visitor Stopped Typing

{
    "EventName": "m0",
    "Header": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": ""
}

Parameters:

ChatUID

Whilst Monitoring

Whilst monitoring another chat your client user can send private messages that only show to the other user (not the visitor) using the Whisper command.

You can also optionally send typing status (when your client is typing a whisper message). Send the MCW1 command when typing starts and MCW0 when typing ends.

MCW1/MCW0 (Command)

{
    "Command": "mcw1",
    "Params": [
        "65be1e8ec937df0cf801e209",
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

Client Connection ID (of other user)
ChatUID

The other user will receive the MCW1 or MCW0 event:

MCW1/MCW0 (Event)

{
    "EventName": "mcw1",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "Stephen"
    ],
    "Data": ""
}

Parameters:

ChatUID
Monitoring User's Name

Whisper (Command)

You can send a whisper message to a monitored chat by sending the Whisper command:

{
    "Command": "Whisper",
    "Params": [
        "65be1e8ec937df0cf801e209",
        "65b3b5f6c937df03142c7e51",
        "I think that product is discontinued. Check first before you answer."
    ]
}

Parameters:

Client Connection ID (of other user)
ChatUID
Message Text

The other client will receive a Whisper event:

Whisper (Event)

{
    "EventName": "whisper",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "Stephen"
    ],
    "Data": "I think that product is discontinued. Check first before you answer."
}

Parameters:

ChatUID
Monitoring User's Name

Data will contain the message text.

RequestMonitor (Command)

Your client can request that another user or bot monitors a current chat. The current user must already have taken that chat.

{
    "Command": "RequestMonitor",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "Could you monitor this chat."
    ]
}

Parameters:

ChatUID
Message

The message is an optional message to send to other users. Other users (who have access to the chat and have monitoring rights) will receive the RequestMonitor event.

RequestMonitor (Event)

If another user that is chatting to a visitor has requested someone to monitor their 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",
    "Params": [
        "2",
        "65b3b5f6c937df03142c7e51",
        "Howard Williams",
        "Thomas",
        "65be1e8ec937df0cf801e209"
    ],
    "Data": "message"
}

Parameters will contain the following fields:

SiteKey
ChatUID
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. If the user chooses to monitor, send the Monitor command to start monitoring.

StopMonitor (Command)

To stop monitoring a chat send the StopMonitor command.

{
    "Command": "StopMonitor",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

ChatUID

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",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "Thomas"
    ],
    "Data": ""
}

Parameters will contain the ChatUID and the chatting users name.

The MonitorStop event will also be sent if the chat is closed by the other user/visitor, or is transferred to another user.

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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

ChatUID

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

ChatAquired (Event)

{
    "EventName": "chataquired",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "Thomas"
    ],
    "Data": ""
}

Parameters will contain the ChatUID and the user's name that is acquiring the chat. The client receiving this event should display a message saying the 'Chat has been acquired by {name}' and exit the chat (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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": ""
}

Parameters will contain the ChatUID. You should then send a Chat command to open the chat session.

Previous Chats

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",
    "Params": [
        "1",
        "2019-09-24"
    ]
}

Parameters:

Sitekey
Date

The WhosOn Server will respond with a Chats event.

Chats (Event)

{
    "EventName": "chats",
    "Params": [
        "1",
        "2019-09-24"
    ],
    "Data": [
        {
            "ChatUID": "65b3b5f6c937df03142c7e51",
            "SiteKey": 1,
            "IP": "195.62.193.194",
            "TrackingId": "",
            "DNS": "1234567890.test.com",
            "Location": "United Kingdom - Stoke on Trent",
            "VisitNo": 44,
            "TakenByUsers": "Thomas",
            "TakenByDept": "",
            "TakenByBot": false,
            "Started": "2019-09-24T07:39:18.923",
            "Finished": "2019-09-24T07:40:10.333",
            "WaitedSeconds": 0,
            "DurationSeconds": 51,
            "Lang": "en",
            "Translation": false,
            "Rating": 5,
            "Name": "Howard Williams",
            "Email": "howard@test.com",
            "Phone": "",
            "Missed": false,
            "MissedMessage": "",
            "MissedSeen": false,
            "MissedSeenByUserName": "",
            "MissedSeenOn": "0001-01-01T00:00:00",
            "MissedCallback": false,
            "MissedCallbackOn": "0001-01-01T00:00:00",
            "RequestedDept": "",
            "SentimentScore": 100,
            "WrapUpValue": "Option 1",
            "Tags": ["Sales","Quoted"],
            "Summary": "I need some prices.",
            "Channel": "",
            "State": 0,
            "SkillNames": "",
            "TranscriptURL": ""
        }
    ]
}

Parameters will contain the SiteKey and date.

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

You can then request the detail for any chat by sending the GetChatDetail command:

GetChatDetail (Command)

{
    "Command": "GetChatDetail",
    "Params": [
        "1",
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

Sitekey
ChatUID

The WhosOn Server will respond with a ChatDetail event:

ChatDetail (Event)

{
    "EventName": "chatdetail",
    "Params": [
        "1",
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": {
        "ChatHeader": {
            "ChatUID": "65b3b5f6c937df03142c7e51",
            "SiteKey": 1,
            "IP": "195.62.193.194",
            "TrackingId": "",
            "DNS": "1234567890.test.com",
            "Location": "United Kingdom - Stoke on Trent",
            "VisitNo": 44,
            "TakenByUsers": "Thomas",
            "TakenByDept": "",
            "TakenByBot": false,
            "Started": "2019-09-24T07:39:18.923",
            "Finished": "2019-09-24T07:40:10.333",
            "WaitedSeconds": 6,
            "DurationSeconds": 51,
            "Lang": "en",
            "Translation": false,
            "Rating": 5,
            "Name": "Howard Williams",
            "Email": "howard@test.com",
            "Phone": "",
            "Missed": false,
            "MissedMessage": "",
            "MissedSeen": false,
            "MissedSeenByUserName": "",
            "MissedSeenOn": "0001-01-01T00:00:00",
            "MissedCallback": false,
            "MissedCallbackOn": "0001-01-01T00:00:00",
            "RequestedDept": "Sales",
            "SentimentScore": 100,
            "WrapUpValue": "Option 1",
            "Tags": ["Sales","Quoted"],
            "Summary": "I need some prices.",
            "Channel": "",
            "State": 0,
            "SkillNames": "",
            "TranscriptURL": ""
        },
        "PreChatSurvey": [
            {
                "Name": "Company",
                "Value": "Microsoft"
            }
        ],
        "PostChatSurvey": [
            {
                "Name": "Rating",
                "Value": "5"
            },
            {
                "Name": "transEmail",
                "Value": ""
            }
        ],
        "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"
            }
        ],
        "VisitDetail": {
            "SiteKey": 1,
            "SiteName": "My Company",
            "IP": "195.62.193.194",
            "TrackingId": "1234.4567890",
            "DNS": "1234567890.test.com",
            "VisitNo": 44,
            "TotalVisits": 44,
            "Browser": "Chrome 76",
            "OS": "Windows 10",
            "Referrer": "https://chat.mysite.com/newchat/chat.aspx",
            "SessionStarted": "2019-09-24T07:39:13.287",
            "Chatting": true,
            "ChattingLanguage": "",
            "ChattingTranslate": false,
            "PageViews": 3,
            "FirstPage": "index.htm",
            "FirstVisit": "2019-09-10T14:44:47.263",
            "ContactName": "Howard Williams",
            "ContactEmail": "howard@test.com",
            "ContactCompany": "Microsoft",
            "ContactTelephone": "01782822577",
            "ContactNotes": "",
            "ContactStreet": "",
            "ContactCity": "",
            "ContactPostCode": "",
            "ContactCountry": "",
            "ContactWebAddress": "",
            "ContactOrganization": "",
            "CRMId": "",
            "Pages": [
                {
                    "Dated": "2019-09-24T07:39:00.117",
                    "Name": "index.aspx"
                },
                {
                    "Dated": "2019-09-24T07:39:13.287",
                    "Name": "chat.aspx"
                }
            ],
            "GeoIP": {
                "IP": "195.62.193.194",
                "CountryName": "United Kingdom",
                "CountryISO": "GB",
                "City": "Stoke-on-Trent",
                "PostCode": "ST1",
                "MetroCode": "",
                "Latitude": 53.0278,
                "Longitude": -2.1658,
                "Radius": 20,
                "ISP": "Internet Central Limited",
                "Organization": "Parker Software"
            }
        }
    }
}

GetChatDetailHTML

GetChatDetailText

GetChatDetailPDF

GetPrevChatsForIP (Command)

{
    "Command": "GetPrevChatsForIP",
    "Params": [
        "1",
        "196.32.13.56"
    ]
}

This command returns all previous chats for a specific IP address.

Parameters:

Sitekey
IP Address

The WhosOn Server will respond with the PrevChatsForIP event.

PrevChatsForIP (Event)

{
    "EventName": "prevchatsforip",
    "Params": [
        "1",
        "196.32.13.56",
    ],
    "Data": [
        {
            "ChatUID": "65b3b5f6c937df03142c7e51",
            "Name": "Howard Williams",
            "StartDate": "2024-01-01 09:01:01",
            "TakenByUsers": "thomas@mysite.com",
            "TakenByDept": "support",
            "Duration": 500
        }
    ]
}

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",
    "Params": [
        "1",
        "65b3b5f6c937df03142c7e51,65b3b5f6c937df03142c7e52"
    ]
}

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",
    "Params": [
        "1"
    ],
    "Data": "65b3b5f6c937df03142c7e51,65b3b5f6c937df03142c7e52"
}

Searching Chats

To perform a search, send the command GetChatSearch:

GetChatSearch (Command)

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

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, wrap-up value, tags).

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

ChatSearch (Event)

{
    "EventName": "chatsearch",
    "Params": [
        "1",
        "2019-09-24",
        "2019-09-24"
    ],
    "Data": [
        {
            "ChatUID": "65b3b5f6c937df03142c7e51",
            "SiteKey": 1,
            "IP": "195.62.193.194",
            "TrackingId": "",
            "DNS": "1234567890.test.com",
            "Location": "United Kingdom - Stoke on Trent",
            "VisitNo": 44,
            "TakenByUsers": "Thomas",
            "TakenByDept": "",
            "TakenByBot": false,
            "Started": "2019-09-24T07:39:18.923",
            "Finished": "2019-09-24T07:40:10.333",
            "WaitedSeconds": 8,
            "DurationSeconds": 51,
            "Lang": "en",
            "Translation": false,
            "Rating": 5,
            "Name": "Howard Williams",
            "Email": "howard@test.com",
            "Phone": "",
            "Missed": false,
            "MissedMessage": "",
            "MissedSeen": false,
            "MissedSeenByUserName": "",
            "MissedSeenOn": "0001-01-01T00:00:00",
            "MissedCallback": false,
            "MissedCallbackOn": "0001-01-01T00:00:00",
            "RequestedDept": "",
            "SentimentScore": 100,
            "WrapUpValue": "Option 1",
            "Tags": ["Sales"],
            "Summary": "I need some prices.",
            "Channel": "",
            "State": 0,
            "SkillNames": "",
            "TranscriptURL": ""
        }
    ]
}

Parameters will contain the SiteKey, From Date and To Date.

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",
    "Params": null,
    "Data": {
        "ChatUID": "65b3b5f6c937df03142c7e51",
        "SiteKey": 1,
        "IP": "195.62.193.194",
        "TrackingId": "",
        "VisitNo": 11,
        "DNS": "1234567890.test.com",
        "Location": "United Kingdom - Stoke on Trent",
        "Dept": "",
        "SkillNames": "Sales,Quote",
        "Lang": "en",
        "Translation": false,
        "Started": "2019-09-15T11:25:04.543",
        "WaitedSeconds": 6,
        "Name": "Howard Williams",
        "Email": "howard@test.com",
        "Phone": "01782822577",
        "Message": "I need some support.. Could someone contact me.",
        "ResponseStarted": false,
        "ResponseStartedBy": "",
        "WantsCallback": true,
        "WantsCallbackOn": "2019-09-15T11:26:33.877"
    }
}

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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ]
}

Parameters:

ChatUID

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

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

MissedChatResponded (Command)

{
    "Command": "MissedChatResponded",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "message text"
    ]
}

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, which will be converted to HTML when the email response is sent.

MissedChatClosed (Event)

{
    "EventName": "MissedChatClosed",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": ""
}

Parameters will contain the ChatUID.

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",
    "Params": [
        "1",
        "65b3b5f6c937df03142c7e51",
        "07799123456"
    ]
}

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",
    "Params": null,
    "Data": {
        "ID": 1,
        "SiteKey": 1,
        "ChatUID": "jl8a91yj4c",
        "FromNumber": "01782822577",
        "ToNumber": "07799123456",
        "UserName": "thomas@mysite.com",
        "VisitorName": "Howard",
        "CallStarted": "2019-09-15T14:04:57.193",
        "CallStatus": "in-progress",
        "CallRecordingURL": "",
        "TranscriptLine": "Call connected."
    }
}

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.

Skills

You can create multiple skills. Individual skills can be assigned to specific sites. Each user and user group can be assigned to one or more skills. New chat requests can be queued/routed to available operators based on skills.

Your client does not need to requests skills unless you want to provide manual skills-based transfers within your client, or you want to edit skills.

To read a list of skills use the GetSkills command.

SaveSkill (Command)

To add or update a skill send the SaveSkill command.

{
    "Command": "SaveSkill",
    "Params": [
        "{skilljson}"
    ]
}

Parameters:

Skill Json

The {skilljson} should be a single skill object, eg:

{
    "Id": "65c0ffd5c937df0b5f889938",
    "ParentId": "",
    "Name": "Sales",
    "CreatedByUser": "thomas@mysite.com",
    "SiteKeys": "1,2,3"
}

To create a new skill - set the Id property to a blank string.

The SiteKeys property should be a comma separated list of site keys that the skill is available on. If blank, the site keys available to the connected user will be assumed.

Skills can be multi-level. Set the ParentId property to the Id of an existing skill if the skill is a child of the parent.

The WhosOn Server will send the Skills event after each successful save.

DeleteSkill (Command)

To delete a skill send the DeleteSkill command:

{
    "Command": "DeleteSkill",
    "Params": [
        "65c0ffd5c937df0b5f889938"
    ]
}

Parameters:

Skill Id

Any child skills will also be deleted.

The WhosOn Server will send the Skills event after each successful delete.

Auto Responses

You can build a collection of auto-responses (previously called 'Canned Responses'). Clients can select an auto-response when responding to chat messages. The WhosOn Server will also automatically suggest auto-responses to the client user during chat sessions when a chat message is received.

The GetAutoResponses command can be used to get a list of all pre-defined auto-responses (previously called 'Canned Responses') available to your user. The WhosOn Server will send the AutoResponses event.

GetAutoResponses (Command)

{
    "Command": "GetAutoResponses",
    "Params": null
}

AutoResponses (Event)

{
    "EventName": "autoresponses",
    "Params": null,
    "Data": 
        [
          {
            "Id": "65c49ff2c937df00af7fa0fd",
            "ParentId": "",
            "SortId": "",
            "Dated": "2024-01-26T13:56:37.094+00:00",
            "Subject": "What are your opening hours",
            "Content": "We are open from 9am to 5pm, Monday to Friday.",
            "DocumentId": "",
            "Tag": "",
            "KeywordsFixed": "",
            "SiteKeys": "1,2",
            "SkillIds": ""
          },
          {...}
          {...}
        ]
}

Data contains a list of auto responses setup on the WhosOn Server that are available to the user. The SiteKeys is a comma separated list of SiteKeys that the auto response can be used on. If SiteKeys is blank then the auto-response is available to the current user only and not shared with other users.

Each auto response has an Id and ParentId allowing auto responses to be displayed in a tree structure.

The SortId property can be used to define a sort order when creating a view in your client. It is not used by the server.

AutoResponseUpdate (Command)

To add or change an auto-response, send the AutoResponseUpdate command.

{
    "Command": "AutoResponseUpdate",
    "Parameters": [
        "id",
        "parentid",
        "sortid", 
        "sitekeys",
        "skillids"
        "subject",
        "content",
        "keywordsfixed",
        "documentid",
        "tag"
    ]
}

Parameters:

Id - the auto-response id. Set to blank to add a new auto-response.
ParentId - if the auto-response is a child of another auto-response. Pass a blank value if no parent. If an auto-response does not exist with the Id of the parent id - or the user does not have access to the parent, then the parent id will be ignored.
SortId - an optional sort identifier. This can be used to define a sort order within your client interface. It is not used by the server.
SiteKeys - a comma separated list of site keys that this auto-response is available for. If a blank string is passed then the auto-response is available to the current user only and not shared with other users.
Skill Ids - a comma separated list of skill ids that this auto-response is available for. If a blank string is passed then the auto-response will be available for any skill.
Subject - text of the message that this auto-response is for.
Content - text or markdown only. Should not exceed 2000 characters.
Keywords Fixed - a comma separated list of additional keywords. Keywords will be automatically extracted from the subject and content when the auto-response is saved. These are used when WhosOn suggests responses from incoming chat lines. The KeyWordsFixed parameter can be used to add additional keywords that may not be part of the content.
DocumentId - the Id of a Document uploaded with the SaveDocument command. When WhosOn suggests responses it will include the document URL if a document has been assigned to the auto-response.
Tag - an optional tag value to assign to the auto-response.

All connected users who have access to the article (including your client) will receive the AutoResponse event with details of the new/updated auto-response.

AutoResponse (Event)

You will receive this event whenever an auto-response (that your user has access to) is added or updated.

{
    "EventName": "autoresponse",
    "Params": null,
    "Data": 
        {
          "Id": "65c49ff2c937df00af7fa0fd",
          "ParentId": "",
          "SortId": "",
          "Dated": "2024-01-26T13:56:37.094+00:00",
          "Subject": "What are your opening hours",
          "Content": "We are open from 9am to 5pm, Monday to Friday.",
          "DocumentId": "",
          "Tag": "",
          "KeywordsFixed": "",
          "SiteKeys": "1,2",
          "SkillIds": "65c0ffd5c937df0b5f889938"
        }
}

AutoResponseDelete (Command)

To delete an existing auto-response, send the AutoResponseDelete command:

{
    "Command": "AutoResponseDelete",
    "Params": [
        "65c49ff2c937df00af7fa0fd"
    ]
}

Parameters: The auto-response id to delete. Any child auto-responses will also be deleted.

All connected users who have access to the deleted (including your client) auto-response will receive the AutoResponseDeleted event.

AutoResponseDeleted (Event)

This event is sent to all connected users who have access to the auto-response(s) whenever an auto-response is deleted.

{
    "EventName": "autoresponsedeleted",
    "Params": null,
    "Data": "id1,id2"
}

Data will contain a comma separated list of auto-response id's deleted. If a single auto-response is deleted then the **AutoResponseDeleted ** event may contain multiple id's if the auto-response was a parent of other auto-responses (since these will have also been deleted).

Knowledge Store Articles

You can build a knowledge store of articles. These are used by WhosOn for chat line suggestions and for building context for bot responses.

A list of articles can be requested by sending the GetArticles command.

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

GetArticleList (Command)

Get a list of all articles available to the user. You should only get all articles when you need to display a 'Knowledge Store Editor' view in your client. The client does not need to load articles for any sort of processing, since the WhosOn Server handles the search and matching of articles for suggested responses and bot context.

{
    "Command": "GetArticleList",
    "Params": null
}

The ArticleList event will contain a summary of all articles available to your user:

ArticleList (Event)

{
    "EventName": "articlelist",
    "Params": null,
    "Data": 
        [
          {
            "Id": "65b3b9cfc937df1341329981",
            "ParentId": "", 
            "SortId": "",
            "Subject": "Product Information",
            "SiteKeys": "1,2",
            "SkillIds": "65c0ffd5c937df0b5f889938"
          },
          {...}
          {...}
        ]
}

GetArticleDetail (Command)

Get the detail for a single article. The server will send the article in the ArticleDetail event.

{
    "Command": "GetArticle",
    "Params": [
        "65b3b9cfc937df1341329981"
    ]
}

ArticleDetail (Event)

The full detail for a single article requested using the GetArticle command.

{
    "EventName": "articledetail",
    "Params": null,
    "Data": 
        {
           "Id": "65b3b9cfc937df1341329981",
           "ParentId": "",
           "SortId": "",
           "Dated": "2024-01-26T13:56:37.094+00:00",
           "Subject": "Product Information",
           "Content": "We offer the following products ....",
           "DocumentId": "",
           "Tag": "",
           "KeywordsFixed": "",
           "SiteKeys": "1,2",
           "SkillIds": "65c0ffd5c937df0b5f889938"
        }
}

ArticleUpdate (Command)

Send the ArticleUpdate command to add or update an article:

{
    "Command": "ArticleUpdate",
    "Parameters": [
        "id",
        "parentid",
        "sortid",
        "sitekeys",
        "skillids",
        "subject",
        "content",
        "keywordsfixed",
        "documentid",
        "tag"
    ]
}

Parameters:

Id - the article id. Set to blank to add a new article.
ParentId - if the article is a child of another article. Pass a blank value if no parent. If an article does not exist with the Id of the parent id - or the user does not have access to the parent, then the parent id will be ignored.
SortId - an optional sort identifier. This can be used to define a sort order within your client interface. It is not used by the server.
SiteKeys - a comma separated list of site keys that this article is available for. If a blank string is passed then the site keys available to the current user are used.
SkillIds - a comma separated list of skill ids that this article is available for. If a blank string is passed then the article will be available for any skill.
Subject
Content - text or markdown only. Should not exceed 10,000 characters.
Keywords Fixed - a comma separated list of additional keywords. Keywords will be automatically extracted from the subject and content when the article is saved. These are used when WhosOn suggests responses from incoming chat lines. The KeyWordsFixed parameter can be used to add additional keywords that may not be part of the content.
DocumentId - the Id of a Document uploaded with the SaveDocument command. When WhosOn suggests responses it will include the document URL if a document has been assigned to the article.
Tag - an optional tag value to assign to the article.

All connected users who have access to the article (including your client) will receive the Article event with details of the new/updated article.

ArticleImport (Command)

The ArticleImport command can be used to import articles from the following document types:

PDF
Word (Docx,Doc)
OpenDocument (ODT)
Richtext (rtf)
Excel (xlsx, xls)
HTML
Text files
Markdown files (md)

The document will be converted to plain text and added as one or more articles. Where the converted plain text is >10k characters, the text will be split into pages of roughly 10k each, and each page added as a separate article. When importing Markdown, the page splitting will use ## header markers to attempt to split into logical pages.

{
    "Command": "ArticleImport",
    "Parameters": [
        "parentid",
        "sortid",
        "sitekeys",      
        "skillids",
        "filename",
        "subject",
        "keywordsfixed",
        "tag",
        "base64content"
    ]
}

Parameters:

ParentId - if the article is a child of another article. Pass a blank value if no parent.
SortId - an optional sort identifier. This can be used to define a sort order within your client interface. It is not used by the server.
SiteKeys - a comma separated list of site keys that this article is available for. If a blank string is passed then the site keys available to the current user are used.
SkillIds - a comma separated list of skill ids that this article is available for. If a blank string is passed then the article will be available for any skill.
File Name - the filename of the imported document.
Subject - the article subject. If a blank subject is passed the filename will be used. When multiple articles are added the text 'page x' will be appended to the article subject.
Keywords Fixed - a comma separated list of additional keywords. Keywords will be automatically extracted from the subject and content when the article is saved. These are used when WhosOn suggests responses from incoming chat lines. The KeyWordsFixed parameter can be used to add additional keywords that may not be part of the content.
Tag - an optional tag value to assign to the article.
Base64 Content - the base 64 encoded content of the document file.

All connected users who have access to the article (including your client) will receive the articles event, which will contain a list of articles imported.

If you import the same File Name again, then any existing articles that were imported from the same file name will be deleted before the import. You should delete these from your local client storage before sending this command.

After the import the ArticlesImported event will be sent. This event will contain an array of articles added (in the same format as the ArticleList event).

ArticleDelete (Command)

To delete an existing response, send the ArticleDelete command:

{
    "Command": "ArticleDelete",
    "Params": [
        "65b3b9cfc937df1341329981"
    ]
}

Parameters: The article id to delete. Any child articles will also be deleted.

All connected users who have access to the deleted (including your client) article will receive the ArticleDeleted event.

Article (Event)

This event is sent to all connected users who have access to the article, whenever an article is added or updated.

{
    "EventName": "article",
    "Params": null,
    "Data": 
          {
            "Id": "65b3b9cfc937df1341329981",
            "ParentId": "",
            "SortId": "",
            "Subject": "Product Information",
            "SiteKeys": "1,2",
            "SkillIds": ""
          }
}

ArticleDeleted (Event)

This event is sent to all connected users who have access to the article(s) whenever an article is deleted.

{
    "EventName": "articledeleted",
    "Params": null,
    "Data": "id1,id2"
}

Data will contain a comma separated list of artlcle id's deleted. If a single article is deleted then the ArticleDeleted event may contain multiple id's if the article was a parent of other articles (since these will have also been deleted).

ArticleSearch (Command)

This command can be used to perform a search of articles and auto-responses for any search term. The top x articles will be returned in the ArticleSearch event (in relevancy order).

{
    "Command": "ArticleSearch",
    "Params": [
        "1010",
        "65c0ffd5c937df0b5f889938",
        "How do I login?",
        "5"
    ]
}

Parameters:

SiteKey - only include articles and auto-responses assigned to the specified site key (required).
SkillIds - a comma-separated list of skill ids. Only include articles and auto-responses that have at least one matching skill (or no skills). If a blank string is passed then skill id's are not checked.
Search Term - the text to search for (required).
TopX - the number of articles to return. If this parameter is zero or blank, then the number of articles specified in the site properties (AddContextReturnTop) is assumed.

The ArticleSearch event will include the results:

ArticleSearch (Event)

{
    "EventName": "articlesearch",
    "Params": null,
    "Data": 
        {
            "SiteKey": 1010,
            "SearchTerm": "How do I login?",
            "Articles": [
                {
                    "Id": "65e418fcc937df016e647852",
                    "Subject": "How do I login?",
                    "Content": "You login using the Login command.\r\n",
                    "DocumentId": "",
                    "Similarity": 1,
                    "Tokens": 0
                },
                {
                    "Id": "65e41911c937df130398c4b2",
                    "Subject": "Login (Command)",
                    "Content": "To login, send your username and password.",
                    "DocumentId": "",
                    "Similarity": 0.117647058823529,
                    "Tokens": 0
                }
            ]
        }
}

The ArticleSearch event contains the top most matching articles from a previous ArticleSearch command. Data will include the Sitekey and SearchTerm properties, containing the sitekey and search term used on the previous search. The Articles array will contain a list of matching articles - in similarity order, with the most similar first (or null if no articles were found).

Both Articles and Auto-Responses are searched.

Semantic Search

If LLM (Large Language Model) settings have been defined for the WhosOn Server or Site, then the search is performed using Embeddings. Embeddings are a list of numbers (a 'vector') that are used to measure the relatedness of text strings. This enables semantic search, which searches based on the meaning rather than keyword matching. This provides a much more accurate list of relevant articles when doing a search. If LLM is enabled, then the search results will include the Tokens count for each article.

If LLM settings have not been defined, then searches are performed using keyword matching.

Bot Context

If you have setup a LLM type bot user, then bots will use the Articles and Auto-Responses to provide 'context'. When a chat message is received, the WhosOn Server will automatically search articles and auto-responses that are most relevant to the chat message. This context and previous conversation text is sent to the LLM service (for example, ChatGPT). The LLM will then be able to answer the chat message based on your own specific knowledge. When articles and auto-responses are searched, only articles assigned to the chat Site and Skills will be used. The search is dynamic, so any articles added or updated will immediately be available for the next chat message. To improve bot responses you simply need to add more articles.

GetSuggestion (Command)

This command can be used to search all auto-responses, articles and recently sent chat lines for the most relevant relating to a search term.

{
    "Command": "GetSuggestion",
    "Params": [
        "2",
        "",
        "What is your telephone number?"
    ]
}

Parameters:

SiteKey - required
SkillIds - a comma-separated list of skill ids. Only include articles and auto-responses that have at least one matching skill (or no skills). If a blank string is passed then skill id's are not checked.
Search Term - the text to search. This could be an incoming chat message.

All auto-responses and articles available to the specified SiteKey & Skills will be searched. The auto-response or article with the best match will be returned in the Suggestion event. If no auto-responses or articles are found, then previously sent chat lines will be searched.

Suggestion (Event)

{
    "EventName": "suggestion",
    "Params": null,
    "Data": 
    {
        "SiteKey": 2,
        "SearchTerm": "What is your telephone number?",
        "Content": "Our telephone number is 800 1234 5678",
        "DocumentId": ""
    }
}

The SearchTerm property will contain the search term used. The Content property will contain the content for the best matching article, or a recently sent chat line. The Content will be blank if no match was found.

The DocumentId property will contain a Document Id if the article has been assigned an attached document.

If the user property UserSuggestResponses is true and the user has taken a chat, then incoming chat lines will automatically be checked for a suggested response and a tag will be appended to incoming chat messages (see: Message event).

Documents

WhosOn can store document files in its File Store. The file store is a secure document database. Once saved, documents can be sent to visitors during chat sessions. You can either pre-upload common documents to a library, which you can then send during chat sessions or upload and send single-use documents as one operation during chat sessions.

A list of documents can be requested by sending the GetDocuments command.

GetDocuments (Command)

{
    "Command": "GetDocuments",
    "Params": null
}

A list of uploaded documents that the currently connected user has access to will be returned in with the Documents event:

Documents (Event)

{
    "EventName": "documents",
    "Params": null,
    "Data": 
        [
          {
            "Id": "65b3b9cfc937df1341329981",
            "FileName": "quote.pdf",
            "Folder": "quotes/recent/",
            "MimeType": "application/pdf",
            "Dated": "2024-01-26T13:56:37.094+00:00",
            "LastAccessed": "2024-01-26T13:56:37.094+00:00",
            "Size": 2839455,
            "CreatedByUser": "thomas@mysite.com",
            "VisitorName": "",
            "VisitorUploaded": false,
            "SiteKey": 23,
            "Pinned": false,
            "SingleUse": false,
            "AccessCount": 23,
            "Url": "https://gateway.mysite.com/p/609EAD1749470415A81EFB97B28ADAC15A8B0699/document?id=65b3b9cfc937df1341329981",
            "Base64": null
          },
          {
            ...  
          }
        ]
}

This event will return a list of documents available to your user. These can be sent during chat sessions. The Base64 property will be null when receiving the file list. The file content can be read using the GetDocument command.

GetDocument (Command)

{
    "Command": "GetDocument",
    "Params": [
        "65b3b9cfc937df1341329981"
    ]
}

The parameter must be set to the document Id. The Document event will contain the document details and the base64 encoded document content.

Document (Event)

Returns a single document, including the base64 encoded content.

{
    "EventName": "document",
    "Params": null,
    "Data": 
          {
            "Id": "65b3b9cfc937df1341329981",
            "FileName": "quote.pdf",
            "Folder": "quotes/recent/",
            "MimeType": "application/pdf",
            "Dated": "2024-01-26T13:56:37.094+00:00",
            "LastAccessed": "2024-01-26T13:56:37.094+00:00",
            "Size": 2839455,
            "CreatedByUser": "thomas@mysite.com",
            "VisitorName": "",
            "VisitorUploaded": false,
            "SiteKey": 23,
            "Pinned": false,
            "SingleUse": false,
            "AccessCount": 23,
            "Url": "https://gateway.mysite.com/p/609EAD1749470415A81EFB97B28ADAC15A8B0699/document?id=65b3b9cfc937df1341329981",
            "Base64": "base64encodedcontent",
          }
}

Adding A New Document

Use the SaveDocument command to save a new document to the document store.

SaveDocument (Command)

{
    "Command": "SaveDocument",
    "Params": [
        "quote2.pdf",
        "quotes/recent/",
        "false",
        "1",
        "base64encodedcontent"
    ]
}

Parameters (all required):

Filename
Folder (an optional folder name (eg /quotes/recent) can be used to organize documents in your client interface). Set to blank for no folder. The Folder property is not used by the WhosOn Server. It is only used as a folder identifier that you can use within your Client interface.
Single Use (true or false). If true the document will be removed once it has been sent to a visitor in a chat.
SiteKey. If blank or zero the document will be available on all sites you have access to.
Base64 - base64 encoded file contents.

After the document has been saved to the file store the Document event will be sent to all connected users who have access to the document (if the Single Use value was false). The Base64 property of the Document event will be blank.

Saved documents are automatically deleted based on the document retention properties set on each site.

Deleting Documents

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

DeleteDocument (Command)

{
    "Command": "DeleteDocuments",
    "Params": [
        "id1,id2"
    ]
}

Parameters should contain a comma separated list of document Id to delete (not file names). If no id's are specified then all documents for your user will be deleted.

A DeletedDocuments 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.

DeletedDocuments (Event)

{
    "EventName": "deleteddocuments",
    "Params": null,
    "Data": "id1,id2"
}

Data will contain a list of deleted id's separated by a comma.

Pinning Documents

Existing documents can be marked as 'Pinned' by sending the PinDocuments command:

PinDocuments (Command)

{
    "Command": "PinDocuments",
    "Params": [
        "id1,id2"
    ]
}

Parameters should contain a comma separated list of id's 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.

These events do not include user photos but do include a HasPhoto property. This will be true if the user has a photo assigned.

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

GetUserPhotos (Command)

{
    "Command": "GetUserPhotos",
    "Params": [
        "thomas@mysite.com,martin@mysite.com"
    ]
}

Parameters:

Comma separated list of usernames to request photos for.

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

UserPhoto (Event)

{
    "EventName": "userphoto",
    "Params": [
        "thomsas@mysite.com"
    ],
    "Data": 
        {
            "UserName": "thomas@mysite.com",
            "FileName": "image.png",
            "Base64": "{base64data}"
        }
}

Parameters will contain the username.

Data will contain the filename and a base64 encoded string of the user photo image (or blank if no image). The filename extension can be used to handle decoding/display depending on the image type.

Note: To improve performance, user images should be cached locally in some way by your client rather than requesting after each login.

UserPhoto (Command)

To add or update a photo for a user, send the UserPhoto command:

{
    "Command": "UserPhoto",
    "Params": [
        "thomas@mysite.com",
        "image.png",
        "{base64}"
    ]
}

Parameters:

Username
Filename
Base64 encoded photo

You must be logged in with a user with Administrator rights if you want to update a user other than your own. The FileName property must include the extension of the image type (eg: filename.png).

The UserPhoto event will be sent to all users who have access to the user being updated.

Pass a blank filename / base64 values to clear a user photo.

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

Parameters:

SiteKey

The WhosOn Server will send a MonthlySummary event containing:

MonthySummary (Event)

{
    "EventName": "monthsummary",
    "Params": [
        "1"
    ],
    "Data": [
        {
            "SiteKey": 1,
            "Dated": "2024-01-01",
            "PeakTime": "13:30:30",
            "Total": 100,
            "New": 75,
            "Views": 300,
            "Peak": 200,
            "Chats": 23,
            "ChatsMissed": 2,
            "ChatsLines": 300,
            "ChatsOnTime": 20,
            "AvgRating": 8,
            "AvgSentiment": 89,
            "WaitSecs": 100,
            "ChatSecs": 1883
        }
        ...
        ...

    ]
}

Each Day in the Days array contains the json summary for that day.

The monthly summary will not include the current day. For the current day use the GetDaySummary 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.

GetDaySummary (Command)

The GetDaySummary command is used to get the current visitor & chat totals summary for all sites (that the logged in user has access to).

{
    "Command": "GetDaySummary",
    "Params": null
}

You can request a specific date by passing a date in the parameters. If no date is specified then the current live totals are returned.

The WhosOn Server will send the DaySummary event:

DaySummary (Event)

{
    "EventName": "daysummary",
    "Params": null,
    "Data": [
        {
            "SiteKey": 1,
            "Dated": "2024-01-01",
            "PeakTime": "13:30:30",
            "Current": 6,
            "Total": 100,
            "New": 75,
            "Views": 300,
            "Peak": 200,
            "Chats": 23,
            "ChatsMissed": 2,
            "ChatsLines": 300,
            "ChatsOnTime": 20,
            "AvgRating": 8,
            "AvgSentiment": 89,
            "WaitSecs": 100,
            "ChatSecs": 1883
        }
    ]

Data will contain an array of current totals for each site.

Your client can request an update of the current 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).

The AvgSentiment property will contain the average sentiment score for all chats on date specified. See: ChatScored.

The AvgRating property will be the average rating for all chats on the date specified. Visitors can add a rating using a Post-Chat Survey field.

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",
    "Params": null
}

The WhosOn Server will respond with the Ct event:

Ct (Event)

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

}

Data will contain an array, with an item 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 WhosOn Server sends the Ct event automatically whenever the visitor current totals change.

Send the StartCurrentVisitorTotalsEvents command:

StartCurrentVisitorTotalsEvents (Command)

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

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
}

Listen Mode

Listen mode can be enabled by users with Admin or Supervisor 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).

To enable Listen Mode, send the StartListening command:

StartListening (Command)

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

To disable Listen Mode, send the StopListening command:

StopListing (Command)

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

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

Listen Events

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

ListenC (Event)

When another 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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "message from operator"
}

Parameters:

ChatUID

Data will contain the message text.

ListenV (Event)

When a 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",
    "Params": [
        "65b3b5f6c937df03142c7e51"
    ],
    "Data": "message from visitor"
}

Parameters:

ChatUID

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",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "TransferTarget"
    ],
    "Data": "message"
}

Parameters:

ChatUID
Transfer Target - Name, Department or Skill

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 GetChatDetail command to read the chat detail for all currently active chats.
When a listenv or listenc event is received use the GetChatDetail 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.

Visitor Monitoring

The WhosOn Server tracks all website visitor activity for each monitored site, even for visitors who are not chatting. By default, the client interface does not send individual visitor events unless visitor events are enabled.

Do not enable visitor events if you are running WhosOn on a busy site and your operators do not need to view live visitor information, this will improve the performance of your client application.

StartVisitorEvents (Command)

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

Enables visitor events. The WhosOn Server will send the Visitor event whenever a site visitor is added or changed and VisitorRemoved event whenever a site visitor is removed.

StopVisitorEvents (Command)

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

GetVisitors (Command)

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

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

Get a list of all currently active website visitors (whether chatting or not). The WhosOn Server will respond with the Visitors event:

Visitors (Event)

{
    "EventName": "visitors",
    "Header": null,
    "Data": 
        [
            {
                "Id": "1:212.45.112.80:301.6863295",
                "SiteKey": 1,
                "TrackingId": "301.6863295",
                "StartTime": "10:06:47",
                "Time": "10:06:47",
                "No": 13,
                "VisitNo": 1,
                "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"
            },
            {
                "Id": "1:218.35.86.86:343.13095511",
                "SiteKey": 1,
                "TrackingID": "343.13095511",
                "StartTime": "10:06:46",
                "Time": "10:06:47",
                "No": 12,
                "VisitNo": 1,
                "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"
            }
        ]

}

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. After receiving the Visitors event you should then send the StartVisitorEvents command to enable visitor event mode.

If you do not want to monitor active site visitors in your client then do not send the GetVisitors and StartVisitorEvents commands. This will improve performance of both your client and the WhosOn Server on busy web sites.

Visitor Events

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",
    "Params": [
        "1:196.15.109.60:991.61915693"
    ],
    "Data": {
        "Id": "1:196.15.109.60:991.61915693",
        "SiteKey": 1,
        "TrackingId": "991.61915693",
        "StartTime": "10:16:19",
        "Time": "10:16:19",
        "No": 14,
        "VisitNo": 1,
        "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"
    }
}

The Key property contains a string combining SiteKey : IP Address : Visitor Tracking Id. 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):

Not moving (hasn't change pages for a period of time)
Is currently chatting
Callback Requested
Polling - the WhosOn Tracking code for the site has updated the visitor
Geo-IP organization is not an ISP
Requesting pages via SSL

VisitorRemove (Event)

{
    "EventName": "visitorremove",
    "Params": [ 
        "1:196.15.109.60:991.61915693"
    ],
    "Data": ""
}

The WhosOn Server will send this event when a visitor leaves the site. Parameter contains the visitor id (SiteKey: IP Address: Visitor Tracking ID) (the Id property of the Visitor event).

VisitorBatch (Event)

During times of high visitor load the WhosOn Server will enter 'throttle' mode. In this mode individual Visitor and VisitorRemove events are not sent. Instead a VisitorBatch event is sent every 8 seconds. This will contain all visitors added/updated and removed since the event was last sent. This is to improve performance of both the server and client applications. The WhosOn Server will disable throttle mode when visitor load is reduced. By default throttle mode will be enabled when the current active visitors for a site reaches 200.

Throttle mode is enabled on a site-by-site basis.

Your client needs to listen for both Visitor, VisitorRemove and VisitorBatch events.

{
    "EventName": "visitorbatch",
    "Params": [],
    "Data": {
        { 
            "updates": [
                {
                    "Id": "1:196.15.109.60:991.61915693",
                    "SiteKey": 1,
                    "TrackingId": "991.61915693",
                    "StartTime": "10:16:19",
                    "Time": "10:16:19",
                    "No": 14,
                    "VisitNo": 1,
                    "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"
                },
                {...},
                {...},
            ],
            "removes": ["1:196.15.109.60:991.61915693","...","..."]
        }

    }
}

The updates array will contain a visitors updated (in the same format as the Visitor event). The removes array contains a list of visitor id's removed.

Requesting Visit Detail

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

GetVisit (Command)

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

Parameters:

Sitekey
IP Address
Tracking ID
Visit Number

The WhosOn Server will send a VisitDetail event:

VisitDetail (Event)

{
  "EventName": "visitdetail",
  "Params": [
      "1010",
      "202.42.104.89",
      "589.14498921",
      "1"
  ],
  "Data": {
    "SiteKey": 1010,
    "SiteName": "My Company",
    "IP": "202.42.104.89",
    "TrackingId": "589.14498921",
    "DNS": "",   
    "VisitNo": 1,
    "TotalVisits": 1,
    "Browser": "Edge 13",
    "OS": "Windows 10",
    "Referrer": "https://www.google.com",
    "SessionStarted": "2019-11-18T07:22:23.133",
    "Chatted": false,
    "ChattedLanguage": "",
    "ChattedTranslate": false,
    "PageViews": 3,
    "FirstPage": "index.htm",
    "FirstVisit": "2019-11-18T07:22:23.133",
    "ContactName": "",
    "ContactEmail": "",
    "ContactCompany": "",
    "ContactTelephone": "",
    "ContactNotes": "",
    "ContactStreet": "",
    "ContactCity": "",
    "ContactPostCode": "",
    "ContactCountry": "",
    "ContactWebAddress": "",
    "ContactOrganization": "",
    "CRMId": "",
    "Pages": [
      {
        "Dated": "2019-11-18T07:22:23.133",
        "Name": "index.htm"
      },
      {
        "Dated": "2019-11-18T07:22:23.627",
        "Name": "page2.htm"
      }
    ],
    "GeoIP": {
      "IP": "202.42.104.89",
      "CountryName": "Japan",
      "CountryISO": "JP",
      "City": "",
      "PostCode": "",
      "MetroCode": "",
      "Latitude": 35.69,
      "Longitude": 139.69,
      "Radius": 500,
      "ISP": "Telstra Global Internet Services Network Blocks",
      "Organization": ""
    }
  }
}

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 GeoIP property contains the GeoIP information for the visitor's IP address.

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 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 DaySummary 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",
    "Params": [
        "1",
        "2019-09-19"
    ]
}

Parameters:

Sitekey
Date

The WhosOn Server will respond with a VisitList event:

VisitList (Event)

{
    "EventName": "visitlist",
    "Params": [
        "1",
        "2019-09-19"
    ],
    "Data": [
        {
            "SiteKey": 1,
            "IP": "220.22.84.63",
            "TrackingId": "418.8001638",
            "Loc": "Japan - Softbank BB",
            "DNS": "softbank220022084063.bbtec.net",
            "Name": "",
            "Company": "",
            "Email": "",
            "Chatted": false,
            "VisitNo": 1,
            "VisitDate": "2019-09-19T11:28:29.883",
            "Visits": 1,
            "Views": 2,
            "Duration": 61,
            "Page": "index.htm",
            "FirstDate": "2019-09-19T11:28:29.883",
            "LastDate": "2019-09-19T11:28:29.883",
            "OS": "iPad",
            "Browser": "Safari 6",
            "Referrer": "https://www.google.com"
        },
        {
            "SiteKey": 1,
            "IP": "195.21.106.69",
            "TrackingId": "161.98375597",
            "Loc": "United Kingdom - Interoute Communications Limited",
            "DNS": "",
            "Name": "",
            "Company": "",
            "Email": "",
            "Chatted": true,
            "VisitNo": 1,
            "VisitDate": "2019-09-19T11:28:30.88",
            "Visits": 1,
            "Views": 1,
            "Duration": 64,
            "Page": "index.htm",
            "FirstDate": "2019-09-19T11:28:30.88",
            "LastDate": "2019-09-19T11:28:30.88",
            "OS": "Windows 7",
            "Browser": "IE 9",,
            "Referrer": ""
        }
    ]
}

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

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.

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.

Updating User Properties

If your user has Administrator rights you can create, update & delete: Users, User Groups, Work Periods, & Skills.

You can read lists of Users, User Groups, Work Periods and Skills using the following commands:

GetUsers - get a list of users.
GetUserGroups - get a list of user groups.
GetWorkPeriods - get a list ok work periods.
GetSkills - get a list of skill groups.

You can update users, user groups, work periods and skills using the following commands:

SaveUser - save user properties.
SaveUserGroup - save user group properties. To create a new group, set the Id property to blank.
SaveWorkPeriod - save work period properties. To create a new work period, set the Id property to blank.
SaveSkill - save skill properties. To create a new skill, set the Id property to blank.
DeleteUser - pass the user name to delete as the parameter.
DeleteUserGroup - pass the group Id as the parameter.
DeleteWorkPeriod - pass the work period Id as the parameter.
DeleteSkill - pass the skill Id as the parameter.

When saving you must pass the full Json in the first parameter. The Json must be valid for the item you are saving. When deleting users, any skills, work periods or auto-responses created by that user will also be deleted. The user will be removed from any user groups. Any user groups that have no remaining users will also be deleted.

When deleting user groups, any none-admin users that are members of the group will also be deleted.

SaveUser (Command)

Users are created and updated using the SaveUser command.

{
    "Command": "SaveUser",
    "Params": [
        "{userjson}",
        "true"
    ]
}

Parameters:

User Json - a single user json (in the same format shown in the User event)
Boolean true/false - must be set to true when creating a new user.

If the SiteKeys property is blank, then the user will be assigned to the same SiteKeys list that the connected user has access to.

The Rights property should be formatted correctly - see User Rights.

For new users, the SetPasswordTo property must be set to the user password. For existing users, the SetPasswordTo property can be set to a new password. If the existing user password should not be changed, then set the SetPasswordTo property to a blank string.

The WhosOn Server will save a secure hash of the password in the database. Plain text passwords are not stored, so it is not possible to recover a forgotten password. The user must be edited and a new password applied if a password is forgotten.

If the RequirePasswordReset property is set to True, then the user must change their password on the next login.

If the save is successful then all connected clients that have access to the user (including your connection) will receive a User event with details of the new/updated user. An error even will be sent otherwise.

If an existing user is saved and that user is currently connected, then their connection will be closed if any site key assignments, password or user rights are changed.

User (Event)

{
    "EventName": "user",
    "Params": null,
    "Data": 
        {
            "UserName": "thomas@mysite.com",
            "Name": "Thomas",
            "Dept": "Support",
            "Email": "thomas@mysite.com",
            "Phone": "",
            "Title": "",
            "UTCBias": -5,
            "MaxChats": 0,
            "AutoAccept": false,
            "SiteKeys": "1,2",
            "SkillIds": "65c10033c937df02e0dd66ec,65c0ffd5c937df0b5f889938",
            "Rights": "YYYYYYYYYNYYY1NN",
            "IsAdmin": false,
            "IsSupervisor": false,
            "IsTeamLeader": false,
            "IsBot": false,
            "KeepLog": true,
            "SuggestResponses": false,
            "WorkPeriodId": "65c34f70c937df08d5e27426",
            "GroupId": "65b3b5f6c937df03142b2a23",
            "GroupName": "Support",
            "HasPhoto": true,
            "GreetingMessage": "Good %TimeOfDay% %Name%. My name is %MyName% how can I help you?",
            "ClientOptions": "Theme=Dark;AutoLogout=True;",
            "RequirePasswordReset": false,
            "SetPasswordTo": "",
            "BotSettings": null
        }
}

DeleteUser (Command)

To delete a user send the DeleteUser command:

{
    "Command": "DeleteUser",
    "Params": [
        "thomas@mysite.com"
    ]
}

Parameters:

Username

If the delete is successful the WhosOn Server will send the Users event which will contain all remaining users, or an error event otherwise.

Any skills, articles, work periods or documents created by the user will also be deleted.

SaveUserGroup (Command)

User groups are created and updated using the SaveUserGroup command.

{
    "Command": "SaveUserGroup",
    "Params": [
        "{usergroupjson}"
    ]
}

Parameters:

User Group Json - a single user group json (in the same format shown in the UserGroups event)

If the SiteKeys property is blank, then the user will be assigned to the same SiteKeys list that the connected user has access to.

The Rights property should be formatted correctly - see User Rights.

If the save is successful then your connection will receive a UserGroups event with details of all user groups. An error even will be sent otherwise.

Updating Site Properties

If your user has Administrator rights you can create, update and delete: Site properties, Site Images and Site Strings. This will enable you to create a client that can add/update/delete Site data and related properties. An error event with 'Access Denied' message will be returned when attempting to access site data that your connected user does not have access to.

The Sites will send a list of sites after login. The event data contains only a subset of site properties that are useful for client applications. Full site properties can be read using the GetSiteProperties command.

The following commands are available:

CreateSite - create a new site with default site properties.
GetSiteProperties - get the full site properties for a specific site.
GetSiteImages - get a list of all images for a site (pass the sitekey as the parameter).
GetSiteStrings - get a list of all site strings for a site (pass the sitekey as the parameter).
DeleteSite - delete an existing site.

An error event will be returned if your user does not have access to the requested item(s).

CreateSite (Command)

Use the CreateSite command to create a new site. The site will inherit the default properties, or inherit properties from an existing site. You will receive the Site event containing the new site data (and the new sitekey). You can then use this with the GetSiteProperties command if you want to edit site properties.

{
    "Command": "CreateSite",
    "Params": [
        "www.mynewsite.com",
        "New Site",
        "",
        ""
    ]
}

Parameters:

Domain Name
Site Name
Clone SiteKey - optional another site SiteKey. The new site will inherit all site properties (apart from the domain and name). The user must have access to the cloned site.
User Names - optional. Comma separated list of user names that should be assigned to the new site.

The Domain Name must be unique.

If the User Names parameter is blank then all users and user groups that the connected user has access to will be automatically assigned access to the new site.

If the create is successful then any connected clients that have access to the site (including your connection) will receive a Site event with details of the new site. An error event will be sent otherwise.

Site (Event)

{
    "EventName": "site",
    "Params": null,
    "Data": 
            {
                "SiteKey": 1001,
                "Name": "New Site",
                "Domain": "www.mynewsite.com",
                "Paused": false,
                "HasTrackingCode": false,
                "UTCBias": 3600,
                "WorkPeriodId": "",
                "GreetingMessage": "Good %TimeOfDay% %Name%. My name is %MyName% how can I help you?",
                "SLAWarningSeconds": 20,
                "SLAReachedSeconds": 40,
                "AllowEmoji": true,
                "AllowFileUpload": 2,
                "DisableFileSend": false,
                "TranslationEnabled": false,
                "OnDemandFields": [ ],
                "WrapUp": {},
                "CustomForm": {},
                "CRM": {},
                "Tags": [],
                "TransferQueues": [
                    {
                        "Number": 1,
                        "Name" : "Default Queue",
                        "Count": 0,
                        "CurrentWait": 0,
                        "MaxSessions" : 100
                    }
                ],
                "SiteINI": ""
        }
}

The Site event contains a sub-set of site properties that are useful in your client interface (See: Sites). To obtain the full site properties, use the GetSiteProperties command.

GetSiteProperties (Command)

Returns the full site properties for a single site.

{
    "Command": "GetSiteProperties",
    "Params": [
        "1"
    ]
}

Parameters:

SiteKey

The WhosOn Server will respond with a SiteProperties event:

SiteProperties (Event)

{
    "EventName": "siteproperties",
    "Params": [
        "1"
    ],
    "Data": 
        {
            "Id": "65be1e8ec937df0cf801e209",
            "SiteKey": 1,
            "Name": "Site1",
            "Domain": "mysite.com",
            "HomePage": "index.htm",
            ...
        },
        ...

}

The full site json is not shown in the above sample. See: Site Json for detail.

GetSiteImages (Command)

Returns all site images for a single site.

{
    "Command": "GetSiteImages",
    "Params": [
        "1"
    ]
}

The WhosOn Server will send the SiteImages event:

SiteImages (Event)

{
    "EventName": "siteimages",
    "Params": [
        "1"
    ],
    "Data": 
    [
        {
            "SiteKey": 1,
            "Domain": "www.mysite.com",
            "ImageType": 1,
            "Language": "en",
            "Ext": "gif",
            "Base64": "{base64imagedata}"
        },
        {
            "SiteKey": 1,
            "Domain": "www.mysite.com",
            "ImageType": 2,
            "Language": "en",
            "Ext": "png",
            "Base64": "{base64imagedata}"
        },
        {
            "SiteKey": 1,
            "Domain": "www.mysite.com",
            "ImageType": 3,
            "Language": "en",
            "Ext": "png",
            "Base64": "{base64imagedata}"
        },
        {
            "SiteKey": 1,
            "Domain": "www.mysite.com",
            "ImageType": 4,
            "Language": "en",
            "Ext": "png",
            "Base64": "{base64imagedata}"
        },
        {
            "SiteKey": 1,
            "Domain": "www.mysite.com",
            "ImageType": 5,
            "Language": "en",
            "Ext": "png",
            "Base64": "{base64imagedata}"
        },
        {
            "SiteKey": 1,
            "Domain": "www.mysite.com",
            "ImageType": 6,
            "Language": "en",
            "Ext": "png",
            "Base64": "{base64imagedata}"
        }
    ]
}

By default each site has 6 images for each language (defined by the ImageType property):

Online - the click to chat image displayed when operators are available.
Offline - the click to chat image displayed when operators are not available.
Chat Logo - the logo image for the site.
Mobile logo - the logo image for the site for mobile devices.
Mobile online - the online image for mobile devices.
Mobile offline - the offline image for mobile devices.

The Language property should be the two letter language code. The default language is assumed if an image does not exist for a language.

Images can be saved using the SaveSiteImage command:

SaveSiteImage (Command)

{
    "Command": "SaveSiteImage",
    "Params": [
        "{singlesiteimagejson}"
    ]
}

GetSiteStrings (Command)

Returns all chat window strings for all sites that your logged in user has access to.

{
    "Command": "GetSiteStrings",
    "Params": null
}

The WhosOn Server will send the SiteStrings event:

SiteStrings (Event)

{
    "EventName": "sitestrings",
    "Params": [
        "1"
    ],
    "Data": 
        [
            {
                "Id": "65dc4e37c937df00e0bef7ce",
                "SiteKey": 0,
                "LanguageName": "English",
                "LanguageCode": "en",
                "BaseLanguage": "en",
                "IsDefault": true,
                "IncludeSurveys": false,
                "UIStrings": [
                    {
                        "OriginalValue": "<h3>Welcome</h3>Please enter your name and click the <strong>Start Chat</strong> button to begin<br /><br />If we are available we will respond, if not please leave us a message.",
                        "CustomValue": "<h3>Welcome</h3>Please enter your name and click the <strong>Start Chat</strong> button to begin<br /><br />If we are available we will respond, if not please leave us a message.",
                        "Section": "Surveys",
                        "CanUseHTML": true,
                        "StringID": "OpeningMessage",
                        "StringName": "Opening Message"
                    },
                    {
                        "OriginalValue": "Select a Department",
                        "CustomValue": "Select a Department",
                        "Section": "Surveys",
                        "CanUseHTML": false,
                        "StringID": "SelectDepartment",
                        "StringName": "Department Selector Text"
                    },
                   {...}
               }
        ]
    }

Each site strings object has a unique Id property. The SiteKey property will be zero for the default site strings. Each site can have its own site strings object for each LanguageCode. If no specific language is created then the 'en' is assumed.

Each site strings object has a UIStrings array. This array contains individual strings for each UI element. The UI element is specified with the StringId property. The StringName property contains a description of the UI element. The CustomValue can be changed.

Not all UIStrings are shown in the above sample json - as there are many.

You can add/update site strings using the SaveSiteStrings command. Pass a single site strings object - with all UI strings. Specify a specific sitekey/language if you need site/language specific strings. For new site strings the Id property should be blank.

SaveSite (Command)

To save full site properties, use the SaveSite command:

{
    "Command": "SaveSite",
    "Params": [
        "{sitejson}"
    ]
}

Parameters:

Json Site Properties

The json must be the full site properties.

When saving existing sites, the Domain property cannot be changed.

All connected users that have access to the site (including your connection) will receive the Site event with details of the new/updated site.

Some site properties (Evaluation, Chat.MaxOperators, Chat.MaxBots, MaxVisitorsDay etc) can only be changed by the system administrator user. Changes to these properties made by none-system administrator users will be ignored.

The WhosOn Server will send an accepted event if the save was successful, or an error event otherwise.

DeleteSite (Command)

{
    "Command": "DeleteSite",
    "Params": [
        "1"
    ]
}

Parameters:

SiteKey

The site assignment will be removed from any user/group/auto-response that had access to it. Any users/groups/auto-response that do not have access to any other sites will also be deleted.

Any connected users who had access to the site will be disconnected and must re-login.

The server will send a SiteDeleted event to your connected user if the delete was successful, or an error event otherwise.

{
    "Command": "SiteDeleted",
    "Params": [
        "1"
    ]
}

Reporting

The WhosOn Server includes a selection of data report definitions. Your client can request a list of available reports and then request data for a specific report.

GetReports (Command)

Use this command to request a list of available report definitions.

{
    "Command": "GetReports",
    "Params": null
}

The server will respond with the Reports event:

Reports (Event)

[
  {
    "_id": "667ae552c937df077d177850",
    "GroupName": "General",
    "Name": "New Visits",
    "Type": 2,
    "ChartField": "New Visits",
    "ChartLabel": "Dated",
    "ChartLabelIsDate": true,
    "DateSelectorType": 8,
    "FormatString": "",
    "FormatColor": "",
    "SQL": "SELECT NewVisitors AS \"New Visits\",Dated \r\nFROM DaySummary\r\nWHERE SiteKey = @SiteKey AND Dated Between @FromDate AND @ToDate \r\nORDER BY Dated",
    "UseArchive": false,
    "MaxRows": 1000,
    "SiteKeys": ""
  },
  {
    "_id": "667bbe0ac937df117c9962b9",
    "GroupName": "General",
    "Name": "Total Visits",
    "Type": 2,
    "ChartField": "Visits",
    "ChartLabel": "Dated",
    "ChartLabelIsDate": true,
    "DateSelectorType": 8,
    "FormatString": "",
    "FormatColor": "",
    "SQL": "SELECT Visits,Dated \r\nFROM DaySummary\r\nWHERE SiteKey = @SiteKey AND Dated Between @FromDate AND @ToDate \r\nORDER BY Dated",
    "UseArchive": false,
    "MaxRows": 1000,
    "SiteKeys": ""
  },
  ...
]

Each report definition has an _id property. This will be used when requesting report data.

The GroupName property can be used to group reports in your client view. In your Client you can show a tree view (grouped by GroupName) of available reports that the user can select from.

The Type property will be:

0 - Tabular report (display the results in a grid)
1 - Single value
2 - Bar Chart
3 - Pie Chart
4 - Line Chart
5 - Point Chart
6 - Area Chart

For chart type reports the ChartField property will contain the data column name for the data values. The ChartLabel property contains the data column name for the data labels. The ChartLabelIsDate property will be true if the ChartLabel is a data (to allow you to format the chart series accordingly).

The DateSelectorType property will be:

0 - No dates
1 - Today
2 - Yesterday
3 - This Week
4 - Previous Week
5 - This Month
6 - Last Month
7 - Single Date (provide a date input)
8 - Date Range (provide a from and to date range input)

The SQL property shows the SQL query that will be used. This cannot be changed.

To request data for a specific report send the ExecuteReport command:

ExecuteReport (Command)

{
    "Command": "ExecuteReport",
    "Params": [
        "667ae552c937df077d177850",
        "1014",
        "2024-08-01",
        "2024-08-19"
    ]
}

Parameters:

Report Id - the _id of the report to execute.
SiteKey (required)
From Date (in yyyy-mm-dd format)
To Date (in yyyy-mm-dd) format)

The WhosOn Server will execute the report to obtain the data. The WhosOn server will send the ReportData event containing the results:

ReportData (Event)

{
  "ReportId": "667ae552c937df077d177850",
  "SiteKey": 1014,
  "FromDate": "2024-08-01T00:00:00",
  "ToDate": "2024-08-19T00:00:00",
  "ColumnNames": [
    "New Visits",
    "Dated"
  ],
  "ColumnTypes": [
    "Int64",
    "DateTime"
  ],
  "ExecuteMs": 1,
  "DataCSV": "New Visits,Dated\r\n246,2024-08-01 00:00:00\r\n202,2024-08-02 00:00:00\r\n125,2024-08-03 00:00:00\r\n112,2024-08-04 00:00:00\r\n260,2024-08-05 00:00:00\r\n251,2024-08-06 00:00:00\r\n234,2024-08-07 00:00:00\r\n858,2024-08-08 00:00:00\r\n246,2024-08-09 00:00:00\r\n148,2024-08-10 00:00:00\r\n493,2024-08-11 00:00:00\r\n254,2024-08-12 00:00:00\r\n295,2024-08-13 00:00:00\r\n291,2024-08-14 00:00:00\r\n261,2024-08-15 00:00:00\r\n234,2024-08-16 00:00:00\r\n161,2024-08-17 00:00:00\r\n159,2024-08-18 00:00:00\r\n886,2024-08-19 00:00:00\r\n"
}

The ColumnNames and ColumnTypes arrays will contain a list of column names and data types.

The DataCSV property will contain the actual data in CSV format.

Other Commands

Translate (Command)

Translates text from one language to another, using the LLM settings configured for the WhosOn Server/Site. Chat messages are translated automatically by the WhosOn Server if translation is enabled (and the visitor/operator languages are different).

This command can be used to perform generic translations for any other purposes.

{
    "Command": "Translate",
    "Params": [
        "1001",
        "Hello!",
        "fr",
        "en"
    ]
}

Parameters:

SiteKey
Text To Translate
To Language
From Language

If the From Language is not specified, then the default language assigned to the site will be assumed.

The WhosOn Server will respond with a Translation event:

Translation (Event)

{
    "EventName": "translation",
    "Params": null,
    "Data": {
        "SiteKey": 1001,
        "FromLang": "en",
        "ToLang": "fr",
        "Text": "Hello!",
        "Translation": "Bonjour!"
    }
}

Noop (Command)

{
    "Command": "Noop",
    "Params": null
}

This command does nothing, other than ensuring long running inactive client sessions are not terminated due to inactivity.

Client connections that do not send or receive any data within 60 minutes will be disconnected. You should send this command every 30 minutes if you want to maintain inactive sessions.

A noop event will be sent back in response.

MetaData Json

Site Json

{
    "Id": "65d87207c937df0e2094dbfc",
    "SiteKey": 1009,
    "Name": "My Site",
    "Domain": "www.mysite.com",
    "HomePage": "index.htm",
    "EndPage": "",
    "WorkPeriodId": "",
    "HasTrackingCode": false,
    "Paused": false,
    "GatewayExitPoll": true,
    "UTCBiasUseDefault": true,
    "UTCBias": 0,
    "TimeZone": "GMT Standard Time",
    "IncludeQuery": true,
    "HideIPFromClient": false,
    "EmailAddress": "thomas@mysite.com",
    "EmailAdminAlso": false,
    "DeleteOldVisits": true,
    "DeleteOldChats": true,
    "DeleteOldVisitsAfterDays": 90,
    "DeleteOldChatsAfterDays": 90,
    "DeleteOldChatsPolicy": "Delete",
    "DontSaveTrafficHistory": false,
    "PreventBlockChatVisitor": false,
    "MaxVisitorsConcurrent": 1000,
    "MaxVisitorsDay": 0,
    "MaxPageViewsDay": 0,
    "Chat": {
        "FolderRoot": "C:\\Program Files\\WhosOn10\\Chat\\",
        "Enabled": true,
        "MaxOperators": 0,
        "MaxBots": 0,
        "OpeningMessage": "<h3>Welcome</h3>Please enter your name and click the <b>Start Chat</b> button to begin<br><br>If we are available we will respond, if not please leave us a message.",
        "GreetingMessage": "Good %TimeOfDay% %Name%. My name is %MyName% how can I help you?",
        "OnLineMessage": "Please wait. An operator will be with you shortly.",
        "OffLineMessage": "No operators are available at this time. Operators may only be available during office hours. The time is currently %TIME%.",
        "LeaveAMessageEnabled": true,
        "LeaveMessageSMS": false,
        "ClosingMessage": "Thank you for chatting to us today.",
        "OnLineGraphicPath": "onlinelink.gif",
        "OffLineGraphicPath": "offlinelink.gif",
        "OnLineInlineGraphicPath": "desktop-inline-online.png",
        "OffLineInLineGraphicPath": "desktop-inline-offline.png",
        "ForwardURL": "",
        "NotAnsweredAfter": 90,
        "EmailAutoSendTranscript": false,
        "EmailAutoSendTranscriptToSiteAdmin": false,
        "NewChatRequestSMS": false,
        "Rotate": false,
        "InactiveOptions": {
            "Enabled": false,
            "InactiveSeconds": 30,
            "InactiveMessage": "",
            "CloseEnabled": false,
            "CloseSeconds": 90,
            "CloseMessage": ""
        },
        "WaitingMessages": [
            {
                "Seconds": 10,
                "Message": "One moment please...",
                "Enabled": true
            },
            {
                "Seconds": 30,
                "Message": "We apologize for the delay. An operator will be with you shortly.",
                "Enabled": true
            }
        ],
        "PreChatSurvey": {
            "Enabled": true,
            "Fields": [
                {
                    "FieldName": "VisitorName",
                    "FieldType": "text",
                    "Enabled": true,
                    "Prompt": "Please enter your name:",
                    "BuiltIn": true,
                    "BuiltInField": "Visitor Name",
                    "Length": 100,
                    "MultiLine": false,
                    "Lines": 0,
                    "Password": false,
                    "ChangeCase": 0,
                    "Mask": "",
                    "DefaultValue": "",
                    "DefaultDateToday": false,
                    "DefaultTimeToday": false,
                    "SelectIndex": 0,
                    "SelectType": "",
                    "SelectOptions": [],
                    "Validate": true,
                    "ValidateType": 0,
                    "ValidateLow": 0,
                    "ValidateHigh": 0,
                    "CustomProperties": null,
                    "HTML5Type": "text"
                },
                {
                    "FieldName": "Company",
                    "FieldType": "text",
                    "Enabled": true,
                    "Prompt": "Please enter your company name:",
                    "BuiltIn": true,
                    "BuiltInField": "Company Name",
                    "Length": 200,
                    "MultiLine": false,
                    "Lines": 0,
                    "Password": false,
                    "ChangeCase": 0,
                    "Mask": "",
                    "DefaultValue": "",
                    "DefaultDateToday": false,
                    "DefaultTimeToday": false,
                    "SelectIndex": 0,
                    "SelectType": "",
                    "SelectOptions": [],
                    "Validate": false,
                    "ValidateType": 0,
                    "ValidateLow": 0,
                    "ValidateHigh": 0,
                    "CustomProperties": null,
                    "HTML5Type": "text"
                }
            ]
        },
        "PostChatSurvey": {
            "Enabled": true,
            "Fields": [
                {
                    "FieldName": "Rating",
                    "FieldType": "rating",
                    "Enabled": true,
                    "Prompt": "Please rate your chat experience:",
                    "BuiltIn": true,
                    "BuiltInField": "Chat Rating",
                    "Length": 0,
                    "MultiLine": false,
                    "Lines": 0,
                    "Password": false,
                    "ChangeCase": 0,
                    "Mask": "",
                    "DefaultValue": "",
                    "DefaultDateToday": false,
                    "DefaultTimeToday": false,
                    "SelectIndex": 0,
                    "SelectType": "",
                    "SelectOptions": [],
                    "Validate": false,
                    "ValidateType": 10,
                    "ValidateLow": 1,
                    "ValidateHigh": 5,
                    "CustomProperties": null,
                    "HTML5Type": ""
                },
                {
                    "FieldName": "transEmail",
                    "FieldType": "text",
                    "Enabled": true,
                    "Prompt": "Enter your email address to receive a transcript of this chat",
                    "BuiltIn": true,
                    "BuiltInField": "Chat Transcript",
                    "Length": 250,
                    "MultiLine": false,
                    "Lines": 0,
                    "Password": false,
                    "ChangeCase": 0,
                    "Mask": "",
                    "DefaultValue": "",
                    "DefaultDateToday": false,
                    "DefaultTimeToday": false,
                    "SelectIndex": 0,
                    "SelectType": "",
                    "SelectOptions": [],
                    "Validate": false,
                    "ValidateType": 0,
                    "ValidateLow": 0,
                    "ValidateHigh": 0,
                    "CustomProperties": null,
                    "HTML5Type": "email"
                }
            ]
        },
        "PostChatSurveyURL": "",
        "OnDemandFields": {
            "Enabled": true,
            "Fields": []
        },
        "IsCustomTheme": false,
        "IsCustomColor": false,
        "Layout": "Standard",
        "Color": "Office",
        "Lang": "",
        "PreSelect": "",
        "BackgroundURL": "",
        "WindowHeight": 550,
        "WindowWidth": 470,
        "WindowTitle": "WhosOn Live Chat",
        "OfflineChatWindowTitle": "",
        "WindowFormTitle": "WhosOn Live Chat",
        "Tags": [
            "customer",
            "supplier"
        ],
        "SendToStatus": 0,
        "SLAWarningSeconds": 20,
        "SLAReachedSeconds": 40,
        "StorageOption": "",
        "AllowFileUpload": 2,
        "AllowVisitorSingleUse": 0,
        "DisableFileSend": false,
        "RemoveUploadedFile": 30,
        "RemoveSentFile": 7,
        "FileTypesFilter": "pdf, doc, docx, odt, xls, xlsx, csv, pptx, rtf, txt, jpg, jpeg, gif, bmp, png, webp, md, xml",
        "OperatorPreview": false,
        "UseGravatar": false,
        "Style": 1,
        "Position": 0,
        "MissedHandle": true,
        "MissedExpireAfter": 14,
        "AllowEmoji": true,
        "OnlineBehaviour": "text",
        "OfflineBehaviour": "show",
        "InLineStyle": "text",
        "InLineOnlineText": "Click To Chat",
        "InLineOfflineText": "Leave A Message",
        "StackButtonText": "Click To Chat",
        "StackOfflineButtonText": "",
        "StackButtonColor": "Black",
        "TranscriptTemplate": ""
    },
    "ChatSkillRules": {
        "Dict": {
            "1": {
                "Name": "Backup Async Skill Rule",
                "Number": 1,
                "Condition": {
                    "List": []
                },
                "SkillIds": {
                    "CommaSeparated": ""
                },
                "Dept": "",
                "Cancel": false,
                "AlwaysAction": "",
                "AlwaysData": "",
                "OnlineAction": "online",
                "OnlineData": "",
                "BusyAction": "queue",
                "BusyData": "",
                "OfflineAction": "queue",
                "OfflineData": "",
                "OutsideAction": "cancel",
                "OutsideData": "",
                "QueueWaitingMsg": "Thank you for waiting. You are in queue position %position% of %count%. Expected time in the queue is %expected% minutes.",
                "QueueInitialMsg": "You are in queue position %position% of %count%. Expected time in the queue is %expected% minutes.",
                "QueueFullMsg": "Thank you for waiting. Unfortunately the queue is full. Please try again later or leave us a message.",
                "QueueExpiryMsg": "Thank you for waiting. Unfortunately operators are unavailable. Please try again later or leave us a message.",
                "QueueTransferMsg": "You have been transferred to a queue. You are in position %position%.",
                "QueueMaxSessions": 10,
                "QueueMaxExpected": 5,
                "QueueMaxActual": 10,
                "QueueAllowTransfers": false,
                "BotForTriage": "",
                "AsyncBackup": true
            }
        }
    },
    "ChatTextRules": {
        "ProfanityFilter": true,
        "ProfanityFilterClient": false,
        "FinanceFilter": false,
        "FinanceFilterClient": false,
        "List": []
    },
    "ChatChannels": {},
    "ChatWrapUp": {
        "Message": "Please complete the wrapup",
        "Type": "menu",
        "Options": [
            {
                "Value": "pricing",
                "DisplayValue": "Asked About Pricing",
                "SubOptions": null
            },
            {
                "Value": "support",
                "DisplayValue": "Asked About Support",
                "SubOptions": null
            }
        ],
        "Required": false,
        "Show": "SessionEnd",
        "Enabled": false
    },
    "Archive": {
        "EveryMins": 60,
        "Database": false,
        "ConnectionStringEnc": "",
        "DatabaseName": "",
        "DatabaseType": 0,
        "MongoDB": false,
        "MongoDBConnectionStringEnc": "",
        "External": false,
        "ExternalURL": "",
        "ExternalPath": ""
    },
    "LLM": {
        "Enabled": false,
        "LLMType": "openai",
        "APIKeyEnc": "",
        "OrgKey": "",
        "LocalServerAddress": "",
        "Model": "gpt-3.5-turbo-16k",
        "Temperature": 0.5,
        "SystemPrompt": "",
        "BotPrompt": "",
        "TranslationPrompt": "",
        "SummarizeAndSentimentPrompt": "",
        "Moderated": false,
        "AddContextReturnTop": 6,
        "AddContextSearchSimilartyThreshold": 0.75,
        "UseForSuggestions": false,
        "UseForTranslation": false,
        "UseForSummarizeAndSentiment": true
    },
    "Translation": {
        "Enabled": false,
        "DefaultLanguage": "en",
        "Languages": [],
        "ShowLanguageSelector": false,
        "ShowAsOverlay": false,
        "ForceTranslation": false
    },
    "Twilio": {
        "Enabled": false,
        "SID": "",
        "TokenEnc": "",
        "CallbackEnabled": false,
        "CallbackSay": "Please wait while we connect you to %SITENAME%",
        "CallbackSayOperator": "Connecting you to %NAME%",
        "DefaultPhone": "",
        "DefaultRecipients": "",
        "CallbackFemale": true,
        "CallbackRingFor": 30,
        "CallbackRecord": false
    },
    "CRM": {
        "Enabled": false,
        "ChatAutoPosting": false,
        "ChatShowClientForm": false,
        "ChatShowClientButton": false,
        "ChatPostOnFormSubmit": false,
        "ChatIncludeMissedChats": false,
        "CallBackAutoPosting": false,
        "CallBackShowClientForm": false,
        "CallBackShowClientButton": false,
        "CallBackPostOnFormSubmit": false,
        "CallBackIncludeMissedChats": false,
        "Condition": {
            "List": []
        }
    },
    "WebHooks": {
        "Enabled": false,
        "URL": "",
        "EventChatStart": false,
        "EventChatLine": false,
        "EventChatTransfer": false,
        "EventChatEnd": false
    },
    "Braintree": {
        "MerchantId": null,
        "AccountId": null,
        "PublicKey": null,
        "PrivateKeyEnc": null,
        "Currency": "GBP",
        "EnableCustomerTracking": false,
        "CustomEmailMappingField": null,
        "Sandbox": false,
        "Enabled": false
    },
    "Upscope": {
        "PrivateApiKeyEnc": null,
        "PublicApiKey": null,
        "Endpoint": null,
        "UserCapHandling": 0,
        "UserCap": 0,
        "Enabled": false
    },
    "Excludes": {
        "IPAddresses": "",
        "Pages": "",
        "Referrers": "sex;porn;poker;viagra",
        "Countries": ""
    },
    "BotTransferMaintainEqualLevels": false,
    "CreatedByUser": "Admin",
    "CreatedDate": "2024-02-23T10:23:03.639+00:00",
    "LastEditedByUser": "Admin",
    "LastEditedDate": "2024-02-23T10:29:53.4188845Z",
    "LastRevisionId": "",
    "LastEditedRevisionDesc": "",
    "AdminContact": "Stephen Parker",
    "AdminEmail": "stephen@parkersoft.co.uk",
    "AdminNotes": "",
    "Evaluation": false,
    "EvaluationExpires": "2024-03-24T00:00:00+00:00",
    "EvaluationExpiryEmailSent": false,
    "SiteINI": ""
}

User Json

{
   "UserName": "thomas@mysite.com",
    "Name": "Thomas",
    "Dept": "Support",
    "Email": "thomas@mysite.com",
    "Phone": "",
    "Title": "",
    "UTCBias": -5,
    "MaxChats": 0,
    "MaxAsyncChats": 0,
    "AutoAcceptChats": false,
    "SiteKeys": "1,2",
    "SkillIds": "65c10033c937df02e0dd66ec,65c0ffd5c937df0b5f889938",
    "Rights": "NYYYYYYYNNNYYNYYN0",
    "IsAdmin": false,
    "IsSupervisor": false,
    "IsTeamLeader": false,
    "IsBot": false,
    "KeepLog": true,
    "SuggestResponses": true,
    "WorkPeriodId": "65c34f70c937df08d5e27426",
    "GroupId": "65b3b5f6c937df03142b2a23",
    "GroupName": "Support",
    "HasPhoto": true,
    "RequirePasswordReset": true,
    "MinPasswordLength": 8,
    "GreetingMessage": "",
    "ClientOptions": "Theme=Dark;AutoLogout=True;"
}

System Administrator Commands

The following commands are available if your client has logged in with the System Administrator user only.

GetServerSettings (Command)

Request the global server settings.

{
    "Command": "GetServerSettings",
    "Params": null
}

The WhosOn Server will respond with the ServerSettings event:

{
    "ServerUid": "65d87205c937df0e2094dbfb",
    "AuthenticationString": "VMWIN1832d",
    "SystemAdminUsername": "Admin",
    "SystemAdminSalt": "r2vgOfZjh98eC7jteJ+sjHoe3srpgwjl",
    "SystemAdminPasswordEnc": "ubb8SexOOKqHOWT7+z64GsOqOMNIY4JN03MfUU+a8q1j/mwQZUMvqgDdVmQKKj2X2kNMj86msw092TURN32ggOUTVKUYf/nHDGMakm+vWlA=",
    "InactivityMinutes": 10,
    "WorkPeriodGraceMinutes": 3,
    "ReverseDNS": true,
    "UseIPV6": false,
    "UseTLS13": false,
    "DNSUseExternal": false,
    "DNSServer": "",
    "NoSpiders": true,
    "UTCBias": 0,
    "UTCBiasUseSystem": true,
    "HTTPInterfacePort": 8899,
    "ChatExternalIP": "localhost",
    "ChatServer": true,
    "ChatPortWebSocket": 8009,
    "ChatBindTo": "",
    "ChatClientPortWebSocket": 8013,
    "ChatClientBindTo": "",
    "ChatFirstMessage": "Please wait. An operator will be with you shortly.",
    "ChatBusyMessage": "No operators are available at this time. Operators may only be available during office hours. The time is currently %TIME%.",
    "ChatTimeOutMinutes": 15,
    "ChatBlockForMinutes": 1440,
    "ChatURL": "https://mydomain/chat/",
    "MaxConnectionsFromSingleIP": 50,
    "ChatLog": true,
    "ChatDontQueue": false,
    "ExpiredSubscriptionMessage": "Dear %CONTACT%,\r\n\r\nYour WhosOn subscription for domain %DOMAIN% has expired. If you would like to continue using the service, please visit our web site to order.\r\n",
    "UTDefaultLang": "en",
    "MaxPageViewsSingleVisit": 500,
    "MaxClientVisitors": 1000,
    "NoAutoBlackList": false,
    "BlackListAfter": 10,
    "BlackListRetrySeconds": 20,
    "BlackListClearAfterMinutes": 60,
    "AnonIPAddress": false,
    "AllowChangePassword": true,
    "LDAPEnabled": false,
    "LDAPDomain": "",
    "AlwaysAskForPassword": false,
    "PreventChatTextCopy": false,
    "HideVisitors": false,
    "DisableChatEvents": false,
    "TimeZone": "GMT Standard Time",
    "MinimumPasswordLength": 8,
    "AlwaysStoreOperatorChats": false,
    "DocumentStoreEncryptFiles": true,
    "DocumentStoreEncryptKey": "65d87205c937df0e2094dbfb",
    "SerialNumber": "",
    "RegisteredEmail": "",
    "RegisteredUser": "",
    "Email": {
        "MailServer": "",
        "UserName": "",
        "PasswordEnc": "",
        "SendTo": "stephen@parkersoft.co.uk",
        "From": "stephen@parkersoft.co.uk",
        "Subject": "Message From WhosOn",
        "SSLOption": 0,
        "ServerPort": 25,
        "OverrideFrom": true,
        "AllowUserReplyTo": true,
        "SendGrid": false,
        "SendGridAPIKeyEnc": "",
        "DefaultCSS": "",
        "WebSetupEmail": "WhosOn live chat is now active for the site %DOMAIN%.\r\n\r\nPlease download and install the WhosOn Client from:\r\nhttps://www.whoson.com/download/\r\n\r\nYour Client connection details are:\r\n\r\nWhosOn DNS:            %EXTERNALIP%\r\nAuthentication String: %AUTHENTICATIONSTRING%\r\nUser Name:             %USERNAME%\r\nTemporary Password:    %PASSWORD%\r\n",
        "WebSetupEmailFile": ""
    },
    "Gateway": {
        "BindTo": "",
        "Port": 8080,
        "PortSSL": 8443,
        "External": "localhost",
        "MaxGif": 35000,
        "SSLStore": "",
        "SSLSubject": "",
        "SSLPFXFile": "",
        "SSLStorePWEnc": "",
        "ServerPort": 8012,
        "ServerBind": ""
    },
    "Archive": {
        "EveryMins": 60,
        "Database": true,
        "ConnectionStringEnc": "/IwPD5bt7wwWuPWAP1qy+pjeNUI3pYlRvt8yA6xmofGTK+NBxOq5szXl1rjRFlZn6eltEGFNGFc99Mk79l+IvSgEUWsqKKLLkdqNgdMnoL8ABmTo9W9Zd5DJRSfyOYdDvAiQFOKFU4ew5T7k5OEVRnHfsu/X2GKVJXsbRnSwrOqYXYEnFctKj1QOpXYadNKcsGLOeNSqau7wpPHygpv3Mt+DmEu/H+Ub30wQM5OnVvNf+7Ey7Mio8Jp5IgMASmkG",
        "DatabaseName": "WhosOn10Archive",
        "DatabaseType": 10,
        "MongoDB": false,
        "MongoDBConnectionStringEnc": "",
        "External": false,
        "ExternalURL": "",
        "ExternalPath": ""
    },
    "Twilio": {
        "Enabled": false,
        "SID": "",
        "TokenEnc": "",
        "CallbackEnabled": false,
        "CallbackSay": "Please wait while we connect you to %SITENAME%",
        "CallbackSayOperator": "Connecting you to %NAME%",
        "DefaultPhone": "",
        "DefaultRecipients": "",
        "CallbackFemale": true,
        "CallbackRingFor": 30,
        "CallbackRecord": false
    },
    "WebHooks": {
        "Enabled": false,
        "URL": "",
        "EventChatStart": false,
        "EventChatLine": false,
        "EventChatTransfer": false,
        "EventChatEnd": false
    },
    "LLM": {
        "Enabled": false,
        "LLMType": "openai",
        "APIKeyEnc": "",
        "OrgKey": "",
        "LocalServerAddress": "",
        "Model": "gpt-3.5-turbo-16k",
        "Temperature": 0.5,
        "SystemPrompt": "",
        "BotPrompt": "You are a very enthusiastic representative working at %Company%. Given the provided sections from our documentation, answer the user's question using only that information, outputted in markdown format.\r\n\r\nQuestion: \"\"\"\r\n%ChatMessage%\r\n\"\"\"\r\n\r\nAnswer:\r\n",
        "TranslationPrompt": "Please translate the text below from %FromLanguage% to %ToLanguage%. Return only the translated text.\r\n\r\nText: \"\"\"\r\n%Text%\r\n\"\"\"\r\n\r\nAnswer:\r\n",
        "SummarizeAndSentimentPrompt": "Below is a chat transcript between our representative %OperatorName% and %VisitorName%. Please summarize the chat without losing key information. Also, analyze the chat for sentiment and return a sentiment score between 1 and 100, where 100 is the most positive and 1 is the most negative. \r\nYou should return the summary followed by the sentiment score only. You should return your response in the following format only:\r\nSummary:\r\n'summary'\r\nScore:\r\n'score'\r\n\r\nChat transcript: \"\"\"\r\n%Transcript%\r\n\"\"\"\r\n\r\nAnswer:\r\n",
        "Moderated": false,
        "AddContextReturnTop": 6,
        "AddContextSearchSimilartyThreshold": 0.75,
        "UseForSuggestions": false,
        "UseForTranslation": false,
        "UseForSummarizeAndSentiment": true
    },
    "ThrottleSendEverySeconds": 8,
    "ThrottleAtPercent": 20,
    "TCPBackLog": 128,
    "DailyMaintenanceDisable": false,
    "MetaDataMaxRevisions": 25,
    "SendUsageData": false,
    "DailyMaintenanceTime": "22:00:00,04:00:00",
    "Server": {
        "DataPath": "C:\\ProgramData\\Parker Software\\WhosOnV10\\",
        "RootPath": "D:\\Program Files\\WhosOn10\\",
        "DatabaseType": 999,
        "NetworkInterfaces": [
            "169.254.190.163;Microsoft Wi-Fi Direct Virtual Adapter",
            "169.254.209.249;Microsoft Wi-Fi Direct Virtual Adapter #2"
        ]
    }
}

These settings are normally edited using the WhosOn Service Manager application. If you want to update the server settings via your client, send the SaveServerSettings command:

SaveServerSettings (Command)

{
    "Command": "SaveServerSettings",
    "Params": {
        .. server settings json (as above)
    }
}

GetLog (Command)

This command can be used to read the server log file for the current day:

{
    "Command": "GetLog",
    "Params": null
}

The WhosOn Server will respond with the FirstLog event:

FirstLog (Event)

{
    "EventName": "firstlog",
    "Params": null,
    "Data": 
"2024-02-23:16:36:58 WhosOn 10.1.3.1 Server Started (SPDELLXPS13)
2024-02-23:16:36:58 Server Timezone GMT Standard Time
2024-02-23:16:36:58 Evaluation version expires on 24 March 2024
2024-02-23:16:36:58 Database size 308KB
2024-02-23:16:36:59 Loaded 1 Work Periods
2024-02-23:16:36:59 Loaded 0 Skill Groups
2024-02-23:16:36:59 Loaded 0 User Groups
2024-02-23:16:36:59 Loaded 1 Users
2024-02-23:16:36:59 Loaded 1 Site
2024-02-23:16:36:59 Loaded 1 Site Strings
2024-02-23:16:36:59 Loaded 0 Documents
2024-02-23:16:36:59 Database opened (308KB) (1 connection)
2024-02-23:16:36:59 GeoIP database initialized: (Oct 2019)
2024-02-23:16:36:59 Outbox monitor task started
2024-02-23:16:36:59 Email sending: Not Configured
2024-02-23:16:36:59 External IP/DNS address is NOT set. Chat will only work on the local machine.
2024-02-23:16:36:59 Listening For WebSocket Clients On All Interfaces:8013 (Secure)
2024-02-23:16:36:59 Listening For WebSocket Gateway On All Interfaces:8012
2024-02-23:16:36:59 Chat processor task started
2024-02-23:16:36:59 Listening For WebSocket Chats On All Interfaces:8009 (Secure)
2024-02-23:16:36:59 Tracking processor task started
2024-02-23:16:36:59 Threads available: 1000 (16 cores)"

}

Data will contain a single string, with the server log for the current day. Each log line separated by LF characters (not show in above sample for readability).

When you connect using the System Administrator user, the WhosOn Server will also send single Log events when new log lines are added.

(c) Parker Software 2025 https://www.whoson.com

WhosOn Version 10 Client API

Introduction

Use Cases

Terminology

Sending Commands

Receiving Data

Making The Connection

Port

Client IP Pass Through

Security

Logging In

Login (Command)

Events Received After Login

NamedUser (Event)

User Rights

Sites (Event)

Site Properties

Chat Wrap-Up

Clients (Event)

Chatting (Event)

MissedChats (Event)

Connected (Event)

Change Password

ChangePassword (Command)

PasswordChanged (Event)

Client Options

General Message Events

Msg (Event)

Error (Event)

Requesting Other Data After Login

GetSkills (Command)

Skills (Event)

GetDocuments (Command)

Documents (Event)

GetAutoResponses (Command)

AutoResponses (Event)

GetArticleList (Command)

ArticlesList (Event)

GetUsers (Command)

Users (Event)

GetUserGroups (Command)

UserGroups (Event)

GetWorkPeriods (Command)

WorkPeriods (Event)

User To User Chat

SendToClient (Command)

Showing Typing Status

C1 (Command)

C0 (Command)

FromClient (Event)

User To User Chat Typing Status

C1,C0 (Event)

Loading Previous User To User Chat Lines

GetClientChat (Command)

ClientChat (Event)

Sending A Message To All Connected Users

Broadcast (Command)

Changing Status

Status (Command)

ClientEvent (Event)

Status (Event)

Changing The Status For Another User

SetStatus (Command)

Users Disconnecting

ClientRemove (Event)

Logging Out

Close (Command)

When The WhosOn Server Closes Your Connection

Chatting Visitors

ChatChanged (Event)

ChatClosed (Event)

Chat Requests

Chat (Event)

Chat (Command)

ChatAccepted (Event)

Auto Accept Chats

AcceptChat (Event)

PreChatSurvey (Event)

CurrentChat (Event)

Transfer (Event)