Skip to content

WhosOn Version 10 Chat API

Introduction

The Chat API is designed to create custom desktop, product embedded or browser-based visitor facing WhosOn Chat applications. Using Chat API, it is possible to completely replace the standard WhosOn Chat Window with your own, using any developer platform that supports WebSockets.

Use Cases

  • Create your own custom chat window using familiar web design tools and existing company styles.
  • Embed chat into existing applications.
  • Easily create custom mobile applications to provide to your customers for chat.

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

Connecting

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

Important: WebSocket connections must be secure (wss://). If you are connecting via a proxy then the web server will need a SSL Certificate. By default the WhosOn Server uses a self-signed certificate. You can assign a trusted certificate using the WhosOn Server settings.

Port

The WhosOn Server listens for chat websocket connections on port 8009 by default. The port can be changed using the WhosOn Service Manager.

Client IP Pass Through

Normally chats would connect using IIS (or another web/proxy server) on port 443 as a proxy (rather than a direct connection to the WhosOn Server itself - although it is ok to do this). The 'X-Forward-For' header value will override the WebSocket chat IP if it exists.

Keeping The Connection Open

Once a WebSocket connection is established it you can keep it open, however that chat will still function if the connection is closed and re-opened. The ChatUID given on the connected event must be maintained and used when the websocket is re-opened.

Sending Commands

JSON text is used for all messages.

All commands sent to the server have the following format:

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

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

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

Example:

{
  "Command": "Connect",
  "Parameters": [
      "myauthstring",
      "www.mycompany.com",
      "en",
      "195.62.193.194",
      "287-3882882",
      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.140 Safari/537.36 Edge/17.17134",
      "https://www.google.com"
  ]
}

Receiving Data

The WhosOn Server will send data to the chat as events occur. This will not only be in response to commands sent, but also when events happen (Eg: An operator sending a message). Your chat application should monitor for events received and process each one accordingly.

All messages received are in the following format:

{
  "EventName": "eventname",
  "ChatUid": "chatuid",
  "Data": "data"
}

Where EventName is the name of the WhosOn Server Event. The ChatUid property will contain the current server assigned ChatUID after a chat session has been established.

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

Example:

{
  "EventName": "newline",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
    "Classname": "pagingmessage",
    "Content": "Please wait. An operator will be with you shortly."
  }
}

All data sent by the WhosOn Server to your chat connection will only contain data relevant to the current chat session. It is not possible to request or receive data outside of the chat session scope.

Establishing A New Chat Session

To establish a new chat session, send the Connect command. Only send this once at the start of a specific chat. If you close and re-open the websocket, do not send the Connect command again if still in the same chat session.

Connect (Command)

{
  "Command": "Connect",
  "Parameters": [
      "myauthstring",
      "www.mycompany.com",
      "en",
      "195.62.193.194",
      "287-3882882",
      "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/64.0.3282.140 Safari/537.36 Edge/17.17134",
      "https://www.google.com",
      "12345678"
  ]
}

Parameters:

  1. Server Authentication String. This must match the Authentication String defined in the WhosOn Server settings.
  2. Domain Name. This must match one of the site domain names that have been setup in WhosOn.
  3. Language code. This is the UI language code. The Strings property of the Connected event will contain a list of UI string labels that you can use with the chat user interface. If blank, the default strings for the site will be returned.
  4. Visitor IP Address. If blank the WebSocket connection IP (or X-Forwarded-For) will be used.
  5. Visitor Tracking ID
  6. Visitor UserAgent string
  7. Visitor Referrer. Optional referrer URL.
  8. HandshakeId. Optional. A string id. This value will be passed back with the Connected event.

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

The Visitor IP and Tracking ID are used to match the chatting visitor to a visitor already being tracked in WhosOn. If a tracked visitor for the IP+Tracking ID is not found, then the WhosOn Server will create a new tracked visitor. If a new tracked visitor is created then the Visitor UserAgent and Visitor Referrer fields are used.

The Visitor UserAgent should be set to the user-agent field of the visitor's browser prior to starting a chat session (this will update the Browser and Operating System fields assigned to the visitor). If this field is blank, then the user-agent header header on the WebSocket connection itself will be used.

Note: Connecting IP addresses will be blacklisted if multiple Connect attempts are made with an invalid Authentication String or Domain name.

Error (Event)

{
  "EventName": "error",
  "ChatUid": null,
  "Data": "The specified site (www.test.co.uk) is not being monitored by WhosOn. A chat session cannot be started."
}

Data will contain a description of the error.

You will receive an error event with Data 'Access Denied' if the Authentication string passed does not match the server Authentication String or the Domain string does not match a site setup in WhosOn.

If an error event is returned from a Connect command the server will disconnect the WebSocket. Multiple invalid connection attempts will result in the WebSocket client IP (or X-Forwarded-For) being blacklisted.

ServerClosed (Event)

{
  "EventName": "serverclosed",
  "ChatUid": null,
  "Data": ""
}

This event will be sent if the WhosOn Server is shutdown. Your chat client will need to disable any current chat and show an 'inactive' message.

Security

The WhosOn Server checks the WebSocket host IP address and any 'X-Forwarded-For' address against the global blacklist and blocks blacklisted hosts. It will also temporarily blacklist hosts that send invalid data or invalid commands. The WhosOn Server will block multiple requests from the same IP (as defined in the Server Settings - Maximum Concurrent Chats From The Same IP setting).

When using IIS ARR Proxy to forward WebSocket connections from IIS to the WhosOn Server the 'X-Forwarded-For' header will be used for the IP.

Connected (Event)

The connected event provides information about the WhosOn Site specified in the Connect command Domain Name parameter.

{
  "EventName": "connected",
  "ChatUid": null,
  "Data": {
    "ChatUID": "65f001c3c937df0ff7a3e579",
    "HandshakeId": "12345678",
    "Domain": "www.parkersoft.co.uk",
    "SiteName": "Parker Software",
    "UTCBias": 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.",
    "ClosingMessage": "Thank you for chatting to us today.",
    "OfflineMessage": "No operators are available. Please leave a message.",
    "ForwardingURL": "",
    "Layout": "Standard",
    "Color": "Office",
    "Lang": "",
    "Height": 550,
    "Width": 470,
    "OperatorPreview": false,
    "FileUploadAllowed": false,
    "FileUploadAllowedTypes": null,
    "CallbackEnabled": false,
    "LeaveMessageEnabled": true,
    "ServerBuild": "10.1.71.1",
    "PassThroughURL": "http://localhost:8080/p/609EAD1749470415A81EFB97B28ADAC15A8B0699/",
    "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.0,
            "ValidateHigh": 0.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.0,
            "ValidateHigh": 0.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.0,
            "ValidateHigh": 5.0,
            "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.0,
            "ValidateHigh": 0.0,
            "CustomProperties": null,
            "HTML5Type": "email"
          }
        ]
      },
      "Translation": {
        "Enabled": false,
        "DefaultLanguage": "en",
        "Languages": [
        ],
        "ShowLanguageSelector": false,
        "ShowAsOverlay": false,
        "ForceTranslation": false
      },
      "Strings": {
        "Name": "English",
        "Lang": "en",
        "UIStrings": [
          {
            "Id": "OpeningMessage",
            "Name": "Opening Message",
            "Section": "Surveys",
            "Value": "<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.",
            "CanUseHTML": true
          },
          {
            "Id": "SelectDepartment",
            "Name": "Department Selector Text",
            "Section": "Surveys",
            "Value": "Select a Department",
            "CanUseHTML": false
          },
          {
            "Id": "TranslationAvailable",
            "Name": "Translation Available Text",
            "Section": "Surveys",
            "Value": "Real time translation is available. Do you want your chat translated?",
            "CanUseHTML": false
          },
          {
            "Id": "Close",
            "Name": "Close Chat Button Text",
            "Section": "Chat",
            "Value": "End Chat",
            "CanUseHTML": false
          }
        ],
        "SurveyStrings": null
      },
      "GeoIP": {
        "IP": "195.62.193.194",
        "CountryName": "United Kingdom",
        "CountryISO": "GB",
        "City": "Stoke-on-Trent",
        "PostCode": "ST8 7PL",
        "MetroCode": "",
        "Latitude": 53.0958748,
        "Longitude": -2.182005,
        "Radius": 0,
        "ISP": "Internet Central",
        "Organization": "Parker Software",
        "RegionName": "England",
        "RegionISO": "ENG"
      },
      "PreviousChats": [
        {
          "ChatUID": "66262979c937df04210f5759",
          "Name": "Thomas",
          "StartDate": "2024-04-22T10:10:21.926574",
          "TakenByUsers": "Howard Williams",
          "TakenByDept": "Support",
          "Duration": 280
        },
        {
          "ChatUID": "6626282ac937df1024cb1562",
          "Name": "Thomas",
          "StartDate": "2024-04-22T10:05:27.288029",
          "TakenByUsers": "Howard Williams",
          "TakenByDept": "Support",
          "Duration": 452
        }
      ]
    }
}

The ChatUID property is a unique server created chat session ID that can be used for the chat session. A new ChatUID is created each time a valid Connect command is sent. Most commands following a Connect command require a ChatUID to uniquely identify the current chat session.

The HandshakeId property is the value passed with the optional HandshakeId parameter on the Connect event.

The OpeningMessage property contains the site-defined opening message text. You should display this text in your chat window.

The PreChatSurvey list contains a list of fields that the visitor should complete before starting the chat. The PostChatSurvey list contains a list of fields that the visitor should complete after the chat session has ended.

The Strings property contains an array of UI text strings defined in your site properties for the language specified on the Connect command. The UIStrings array contains an item for each UI element (not all are shown in the above example).

The PreviousChats property contains an array of the 10 most recent previous chat sessions for the Visitor's IP address and Tracking Id. This will be null if the AllowShowPrevious property for the site is false. You can include a previous Chat Uid with the Hello command - Previous Chat Uid parameter.

The GeoIP object contains the Visitor Geo-IP location information obtained from the Visitor IP address parameter passed with the Connect command.

The FileUploadAllowedTypes property contains a comma separated list of file extensions that visitors can upload during chat sessions. If this field is blank or the FileUploadAllowed property for the site is false, then no file uploading is allowed.

The Translation object contains chat translation options defined for the WhosOn Site. If Translation is enabled then the WhosOn Server will automatically translate chat messages if the visitor's language is not the same as the operator.

The PassThroughURL property contains the URL that can be used to request site images.

Site images can be requested using passthroughurl/siteimage?domain={domain}&lang={lang}&imagetype={imagetype}. You can also use the GetImage command to request site images.

Survey Fields

The connected event contains a list of pre and post chat survey fields. For example:

{
    "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.0,
    "ValidateHigh": 0.0,
    "CustomProperties": null,
    "HTML5Type": "email"
 }

Any number of fields can be created for the pre and post chat survey.

Your chat application should ask the visitor to input data for each field before the chat starts (Pre-Chat) and after the chat has finished (Post-Chat).

Field Properties

Property Name Details
FieldName A unique name for the field.
FieldType The type of field being one of (text, numeric, date, time, boolean, select, rating, company, email)
Enabled 'true' if the field is currently enabled.
Prompt The prompt text to display.
Length The maximum number of characters allowed (or zero for no limit).
MultiLine 'true' if the input can be over multiple lines (a textarea).
Lines The maximum number of lines for a MultiLine input.
Password 'true' if the field is a password (password masking should be used).
ChangeCase A numeric value (0=No Change, 1=Upper Case, 2=Word Capitalize, 3=Lower Case).
Mask A regular expression mask has been defined for the field.
DefaultValue The default value for the field if any.
DefaultDateToday If FieldType is 'date' then the input should default to today's date.
DefaultTimeToday If FieldType is 'time' then the input should default to the current time.
SelectType If FieldType is 'select' then this will be either 'select' where the options should be displayed as a Select Box or 'radio' where the options should be displayed as Radio buttons.
ValidateLow If FieldType is 'numeric' this is the lowest value that should be accepted (or -1 for no lower limit).
ValidateHigh If FieldType is 'numeric' this is the highest value that should be accepted (or -1 for no upper limit).
RequiredField 'true' if the field is required.
SelectOptions If FieldType is 'select' then this will contain a list of allowed values.
CustomProperties A string containing any custom properties defined for the field.
HTML5Type This field indicates the HTML5 input type that can be used for the field. You do not need to use this and can use whatever input methods you choose.

The fields passed with the connected event are based on the Survey Fields setup in the WhosOn Settings against the selected site. It is up to you how you collect the information for the fields from the visitor.

Survey Field data is passed back to the WhosOn Server using an XML block:

<Fields><Field><Name>fieldname</Name><Value>fieldvalue</Value</Field>…. </Fields>

You can also include additional fields here – they do not need to be setup in WhosOn. The WhosOn Server will record all fields passed in the XML block against the chat – regardless of if they are setup in the Site Properties. This enables you to pass additional data to a chat session without defining Survey Fields in advance.

Chat Sessions

Once you have sent the Connect command and received the connected event you should store the ChatUID & Domain Name to use on subsequent commands.

You should then construct the Pre-Chat Survey form and offer this to the visitor to complete. Display the OpeningMessage at the start of the pre-chat survey.

Chat sessions will time-out after 60 minutes from the connected event to receiving the Hello command. If the visitor has not completed the pre-chat survey before 60 minutes, you will need to send a new Connect command to establish a new session.

To start a chat, send the Hello command:

Hello (Command)

{
  "Command": "Hello",
  "Parameters": [
    "65b3b5f6c937df03142c7e51"
    "Thomas",
    "www.mycompany.com",
    "Support",
    "",
    "195.62.193.194",
    "287-3883882",
    "en",
    "false",
    "[{\"name\": \"VisitorName\",\"value\": \"Thomas\"},{\"name\": \"Company\",\"value\": \"Test Company\"}]",
    ""  
  ]
}

Parameters:

  1. ChatUID (as received via the connected event)
  2. Visitor Name
  3. Domain Name (this must match the domain name received with the connected event).
  4. Department (an optional department name).
  5. Operator Name (an optional operator name if you want the chat to be passed to a specific operator only).
  6. Visitor IP Address. If blank the WebSocket connection IP (or X-Forwarded-For) will be used.
  7. Visitor Tracking ID.
  8. Language Code (optional two-letter language code if translation is to be used).
  9. Translation required (true/false).
  10. Pre-Chat Survey Results (Json or XML).
  11. Previous ChatUID (optional - if requesting detail for a previous chat from the same visitor - see Previous Chat Lines).

The ChatUID must be the ChatUID value from the connected event (even when rejoining a previous chat).

The Pre-Chat Survey can be an XML block enclosed in <Fields> tags, or as a Json array. For example:

<Fields>
    <Field>
        <Name>Company</Name>
        <Value>ABC Company</Value>
    </Field>
    <Field>
        <Name>Email</Name>
        <Value>visitor@emailaddress.com</Value>
    </Field>
</Fields>

Or you can pass Json text in the following format:

[
    {
        "name": "Company",
        "value": "ABC Company"
    },
    {
        "name": "Email",
        "value": "visitor@emailaddress.com"
    }
]

You do not need to pass the Visitor Name in the Pre-Chat survey – however it can be included (the Visitor Name should still be passed as the first parameter). You can include additional fields in the Pre-Chat Survey that are not part of the server returned pre-chat survey (field names must be unique). Additional fields will still be recorded against the chat.

The Translation Required parameter can be 'true' or 'false'. If True, then Translation will be activated using the Visitor's language specified with the Language Code parameter. Translation will not be performed if the chat is picked up by an operator that has the same language as the visitor.

If a Department is specified, then the chat request will be sent to only those operators with a matching department (or no department). This is optional (pass a blank string for no department).

If an Operator Name is specified, then the chat request will be sent only to the specified operator. This is optional. Pass a blank string to send the chat request to all operators - based on the WhosOn Server routing rules.

The server will respond to the Hello command with either an accepted or notaccepted event.

Previous Chat Lines

Previous chat lines and survey values can be requested if the Previous ChatUID parameter is specified. This must be a valid previous Chat UID for the same Domain, Visitor IP Address and Visitor Tracking ID. A list of the last 10 previous chats available will be returned with the Connected event.

If a valid previous Chat UID is included with the Hello command, then the WhosOn Server will send the PreviousChat event (prior to the Accepted event):

PreviousChat (Event)

{
  "EventName": "previouschat",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
    "ChatHeader": {
        "ChatUID": "66262979c937df04210f5759",
        "IP": "195.62.193.194",
        "TrackingId": "459.79732263",
        "TakenByUsers": "Howard Williams",
        "TakenByDept": "Support",
        "Started": "2024-04-22T10:10:19.926574",
        "Finished": "2024-04-22T10:10:42.466662",
        "WaitedSeconds": 2,
        "DurationSeconds": 23,
        "Lang": "en",
        "Translation": false,
        "Rating": 10,
        "Name": "Thomas",
        "Email": "",
        "Phone": "",
        "Missed": false,
        "MissedMessage": "",
        "MissedSeen": false,
        "MissedSeenByUserName": "",
        "MissedSeenOn": "0001-01-01T00:00:00",
        "MissedCallback": false,
        "MissedCallbackOn": "0001-01-01T00:00:00",
        "RequestedDept": "Support",
        "TranscriptURL": "http://localhost:8080/p/609EAD1749470415A81EFB97B28ADAC15A8B0699/chatview?id=743DF24959BC5C8D9F33A4F8C9EB39DB1BC2CF6605DF0540AF52B63E0BCF36B4"
      },
      "PreChatSurvey": [
        {
          "Name": "VisitorName",
          "Value": "Thomas"
        },
        {
          "Name": "Company",
          "Value": "Parker Software"
        }
      ],
      "PostChatSurvey": null,
      "Lines": [
        {
          "Dated": "2024-04-22T10:10:24.67516",
          "OperatorIndex": 1,
          "Message": "Good Morning Thomas. My name is Howard Williams how can I help you?"
        },
        {
          "Dated": "2024-04-22T10:10:36.471159",
          "OperatorIndex": 0,
          "Message": "do you have a support email address?"
        },
        {
          "Dated": "2024-04-22T10:10:39.977122",
          "OperatorIndex": 1,
          "Message": "Our email address for support is support@parkersoftware.com"
        },
        {
          "Dated": "2024-04-22T10:10:42.466662",
          "OperatorIndex": 0,
          "Message": "thanks"
        }
      ]
    }
}

You can use this event to display the previous chat session lines.

If the Visitor Name, Department or Pre-Chat Survey XML parameters of the Hello command are blank, then they will inherit the existing chat values.

Note: This event will only be sent if the AllowShowPrevious property is enabled for the WhosOn site.

Accepted (Event)

{
  "EventName": "accepted",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": "Please wait. An operator will be with you shortly."
}

If the chat is accepted the server will send the accepted event.

ChatUid will contain the server generated unique ID for the current chat session.

Data contains the default Paging Message. The paging message will also be sent as the first newline event.

After this event is received you should display the OnlineMessage as specified in the connected event.

The WhosOn Server will then send the chat request to operators (based on status & routing rules). Whilst waiting for an operator to pick up the chat the server will send waiting & queueing messages to the chat session as newline events.

NotAccepted (Event)

{
  "EventName": "notaccepted",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": "No operators are available at this time. Operators may only be available during office hours. The time is currently 12:26."
}

The notaccepted event is sent if the server is unable to accept the chat request.

The WhosOn Server will close the WebSocket connection at this point. If you want to use the LeaveMessage command to allow the visitor to leave a message, you should re-open the WebSocket - but do not re-send the Connect command.

ChatUid will contain the server generated unique ID for the current chat session.

Data will contain the message to display or a forwarding URL.

If the LeaveMessageEnabled property of the connected event is True, then you can offer the visitor the option of leaving a message. See: LeaveMessage

If the LeaveMessageEnabled property is False and the ForwardingUrl property of the connected event is not blank, then you can forward the visitor to the URL specified.

NewLine (Event)

All chat lines are sent in newline events. This includes both operator and visitor messages. Data contains Classname and Content properties. Classname is the type of message and you can use this to provide different styling according to the message type.

Class Names

Classname Type
pagingmessage The first line sent after a chat is accepted.
lineo linewaiting1 The first 'waiting' message sent before an operator picks up the chat.
lineo linewaiting2 The second 'waiting' message sent before an operator picks up the chat.
lineo final The final waiting message sent only if an operator has not picked up the chat before the waiting limit has been reached.
queuemessage Messages sent whilst the chat is waiting in a queue.
linesays A line preceding a chat line indicating the operator or visitor has said something.
linev A line from the visitor.
lineo A line from the operator.
linet A line from the operator that is a translation of the previous line (if translation is enabled for that chat session).

Content can contain HTML (for example links), however the WhosOn Server restricts HTML content to only a fixed number of allowed tags.

Markdown

Operators can include Markdown text in chat messages. The WhosOn Server will convert Markdown to HTML before sending newline events.

Paging Message

{
  "EventName": "newline",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
    "Classname": "pagingmessage",
    "Content": "Please wait. An operator will be with you shortly."
  }
}

The Paging Message is sent as a newline event.

The Paging message is the first line that is sent after a chat is accepted. It will have the class name pagingmessage.

Waiting Messages

{
  "EventName": "newline",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
    "Classname": "lineo linewaiting1",
    "Content": "One moment please..."
  }
}

{
  "EventName": "newline",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
    "Classname": "lineo linewaiting2",
    "Content": "We apologize for the delay. An operator will be with you shortly."
  }
}

Waiting messages are sent whilst waiting for an operator to pickup the chat session and the chat is not in a queue. The interval between the 1st and 2nd waiting message is defined in the Site Properties.

The ClassName will be 'lineo linewaiting1' and 'lineo linewaiting2'.

Final Waiting Message

If no operator picks up the chat after a period (defined in the Site Properties) then the final waiting message will be sent:

{
  "EventName": "newline",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
    "Classname": "lineo final",
    "Content": "No operators are available at this time. Operators may only be available during office hours. The time is currently 08:54."
  }
}

This will have the ClassName 'lineo final'

If the LeaveMessageEnabled property of the connected event is True, then you can offer the visitor the option of leaving a message.

If the LeaveMessageEnabled property is False and the ForwardingURL property of the connected event is not blank, then you can forward the visitor to the URL specified.

Queuing

Depending on the Site routing rules – chat requests can be added to a queue if no operators are available to take the chat. In these cases, the server will send newline events once per minute while the chat is in the queue.

{
  "EventName": "newline",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
    "Classname": "queuemessage",
    "Content": "Thank you for waiting. You are in position 3 of 10."
  }
}

Chats remain in a queue until the chat is picked up by an operator or until the queue timeout time is reached (defined by the Rule properties). A notaccepted event will be sent when a chat in a queue reaches the timeout value.

The Server will also send queue events approximately once per second whilst a chat is in a queue:

Queue (Event)

{
  "EventName": "queue",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": "2"
}

Data field will contain the current queue position.

Ending A Chat

If you receive the final waiting message or a notaccepted event if the chat was in a queue – you should end the chat and optionally offer the visitor, the option of leaving a message.

To end the chat, send the Quit command:

Quit (Command)

{
  "Command": "quit",
  "Parameters": [
    "65b3b5f6c937df03142c7e51",
    "www.mycompany.com"    
  ]
}

Parameters:

  1. ChatUID
  2. Domain

Sending the Quit command stops the chat from showing as waiting for operators.

Chat Picked Up By An Operator

When a chat is picked up by an operator your chat session will first receive a operatorjoined event and then start receiving newline events:

OperatorJoined (Event)

{
  "EventName": "operatorjoined",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
     "Name": "Howard Williams",
     "Email": "howard@mycompany.com",
     "Phone": "+441782822577",
     "Dept": "",
     "Skills": [
       "Sales",
       "Marketing"
     ],
     "IsBot": "False",
     "Status": "Online",
     "Lang": "en",
     "ImageUrl": "https://gateway.mysite.com/p/xxxxx/operatorimage?id=xxxxx",
     "Bio": "",
     "ExternalID",""
   }
}

This event provides details of the operator that has picked up the chat. The IsBot property indicates if the operator that has picked up the chat is a bot. If the operator has been assigned an image, the ImageUrl property will contain a url to the operator photo (or blank if no photo has been assigned).

From then on you will receive newline events as the operator (or bot) sends messages:

NewLine (Event)

{
  "EventName": "newline",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
    "Classname": "linesays",
    "Content": "Howard Williams says:"
  }
}
{
  "EventName": "newline",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
    "Classname": "lineo",
    "Content": "Good Morning Thomas. My name is Howard Williams how can I help you?"
  }
}

Operator Typing Status

The WhosOn Server will send events when the operator starts and stops typing. Use these events to display an 'operator is typing' indicator.

Typing (Event)

{
  "EventName": "typing",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": ""
}

TypingStop (Event)

{
  "EventName": "typingstop",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": ""
}

Sending A Message

To send a chat message send the Message command:

Message (Command)

{
  "Command": "Message",
  "Parameters": [
    "65b3b5f6c937df03142c7e51",
    "www.mycompany.com",
    "Could you please help me with product installation"
  ]
}

Parameters:

  1. ChatUID
  2. Domain Name
  3. Line Text (max 4000 characters)

The WhosOn Server will send the message to the operator. The newline event will also be sent back to the chat session:

{
  "EventName": "newline",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
    "Classname": "linesays",
    "Content": "Thomas says:"
  }
}

{
  "EventName": "newline",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
    "Classname": "linev",
    "Content": "Could you please help me with product installation"
  }
}

newline events are sent for both operator and visitor lines. For visitor lines the class will be 'linev'.

Note: Your chat client should update the chat view in response to newline events, rather that directly after any Message commands. This is because the WhosOn Server may change the sent message content due to Translation or Chat Text Rules.

Handling Translation

If Translation is enabled for the chat session, then operator sent chat lines will also include a translated version of the operator's text. This will be sent as an additional newline event with the ClassName of 'linet'.

For visitor sent lines you can either make use of your own translation or allow the WhosOn Server to translate the text if translation is enabled for the Site and the current chat session.

To send a visitor line including your own translation you should append the original (untranslated) visitor text to the message text enclosed in <original></original> tags:

{
  "Command": "Message",
  "Parameters": [
    "65b3b5f6c937df03142c7e51",
    "www.mycompany.com",
    "Hello<original>Bonjour</original>"
  ]
}

If you do not add the <Original> tag and Translation is enabled for the Site then the WhosOn Server will handle the translation before the message is sent to the operator.

Sending Visitor Preview

You can send a preview of visitor typed text – before the visitor sends a message. Previewed text will be sent to the operator, allowing the operator to view what the visitor has typed so far. Chat preview can be disabled in the Site Properties. The OperatorPreview property of in the connected event will be True if preview is allowed.

To send preview text send the Preview command:

Preview (Command)
{
  "Command": "Preview",
  "Parameters": [
    "65b3b5f6c937df03142c7e51",
    "www.mycompany.com",
    "I would li"
  ]
}

Parameters:

  1. ChatUID
  2. Domain
  3. Typed text

You can send the Preview command on every key press or enable a timer and send the current text every few seconds.

Note: Use of the Preview feature is optional. The Preview command will be ignored by the WhosOn Server if OperatorPreview is not enabled for the Site.

Sending Files

Visitors can send files during chat sessions, provided visitor file uploading is allowed in the Site Properties FileUploadAllowed property is true.

Files are uploaded using the FileUpload command:

FileUpload (Command)

{
  "Command": "FileUpload",
  "Parameters": [
    "65b3b5f6c937df03142c7e51",
    "www.mycompany.com",
    "mydocument.pdf",
    "{base64content}"
  ]
}

Parameters:

  1. ChatUID
  2. Domain
  3. File Name
  4. Base64 encoded file contents

This command will be rejected with an error event if visitor file uploads are not enabled for the site, or if the file extension is not allowed.

Once the upload is complete you will receive the NewLine event which will include the unique URL for the file.

Operator Requesting Files

Operators can request that the visitor uploads regardless of the FileUploadAllowed property. Your chat session will receive the requestfile event.

RequestFile (Event)

{
  "EventName": "requestfile",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": "pdf, doc"
}

Data will contain a comma separated list of allow file extensions.

If your chat session receives this event you should offer the visitor the option of uploading a file.

Operator Requested Dynamic Fields

Operators can request that the visitor complete a dynamic survey field during a chat session. You will receive the requestfield event:

RequestField (Event)

{
  "EventName": "requestfield",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": {
      "FieldName": "OrderNumber",
      "FieldType": "text",
      "Enabled": true,
      "Prompt": "Please enter the order number:",
      "Length": 10,
      "MultiLine": false,
      "Lines": 0,
      "Password": false,
      "ChangeCase": 1,
      "Mask": "",
      "DefaultValue": "",
      "DefaultDateToday": false,
      "DefaultTimeToday": false,
      "SelectType": "",
      "ValidateLow": 0,
      "ValidateHigh": 0,
      "RequiredField": false,
      "SelectOptions": [],
      "HTML5Type": "text"
    }
}

You should then construct user input to match the field and validate. Then send the input data with a DynamicField command:

DynamicField (Command)

{
  "Command": "DynamicField",
  "Parameters": [
    "65b3b5f6c937df03142c7e51",
    "www.mycompany.com",
    "OrderNumber",
    "12345"
  ]
}

Sends the result of a dynamic field request.

Parameters:

  1. ChatUID
  2. Domain
  3. Field Name
  4. Field Value

The field will be added to the chat session fields (and show with the Survey Fields for operators). A new chat line will also be added.

Sending Visitor Typing Status

You should send StartTyping and StopTyping commands when the visitor starts and stops typing – the WhosOn Server will then inform the operator that the visitor has started or stopped typing.

StartTyping (Command)

{
  "Command": "StartTyping",
  "Parameters": [
    "65b3b5f6c937df03142c7e51"
  ]
}

Parameters: ChatUID

This command informs the WhosOn Server that the visitor has started typing.

StopTyping (Command)

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

Parameters: ChatUID

This command informs the WhosOn Server that the visitor has stopped typing. You do not need to send this command before sending a Message command. The server assumes when it receives a visitor message that the visitor has stopped typing.

In your chat application you need to enable a timer when the visitor 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.

Ending A Chat

Chat sessions can be ended by the visitor, operator or by the server (based on inactivity timeout). To end a chat from the visitor side, send the Quit command:

Quit (Command)

{
  "Command": "quit",
  "Parameters": [
    "65b3b5f6c937df03142c7e51",
    "www.mycompany.com"    
  ]
}

Parameters:

  1. ChatUID
  2. Domain

If the operator ends the chat the WhosOn Server will send the quit event:

Quit (Event)

The quit event will be received if the operator or server ends the chat.

{
  "EventName": "quit",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": ""
}

Regardless of how the chat ends, if the chat was accepted you should then offer the visitor the option of completing the Post Chat Survey.

The Post Chat Survey fields will have been sent in the connected event.

Once the visitor has completed the Post Chat Survey you should send the PostChatSurvey command:

PostChatSurvey (Command)

{
  "Command": "PostChatSurvey",
  "Parameters": [
    "65b3b5f6c937df03142c7e51",
    "www.mycompany.com",
    "195.62.193.194", 
    "<Fields><Field><Name>Rating</Name><Value>5</Value></Field></Fields>"
  ]
}

Parameters:

  1. ChatUID
  2. Domain Name
  3. Visitor IP Address
  4. Post Chat Survey XML

The Post-Chat Survey should be an XML block enclosed in <Fields> tags. Each field should be:

<Field>
    <Name>fieldname</Name>
    <Value>fieldvalue</Value>
</Field>

You can also include additional field values for data not included in the post-chat survey (provided the 'fieldnames' are unique).

When the Post Chat Survey is accepted by the WhosOn Server, the server will send an acknowledged event:

{
  "EventName": "acknowledged",
  "ChatUid": "65b3b5f6c937df03142c7e51",
  "Data": ""
}

Requesting A Transcript

You can request that the WhosOn Server sends an email of the chat transcript using the Transcript command.

Transcript (Command)

{
  "Command": "Transcript",
  "Parameters": [
    "65b3b5f6c937df03142c7e51",
    "www.mycompany.com",
    "195.62.193.194",
    "thomas@test.com"
  ]
}

Parameters:

  1. ChatUid
  2. Domain
  3. Visitor IP Address
  4. Visitor Email

The Transcript command can be sent at any time after a chat session starts – and after it has completed.

The chat transcript will be sent to the email address provided. The email address will also be added to the visitor record. The WhosOn Server can also be configured to automatically send transcripts to visitors that supply an email address (via the pre/post chat survey or during the chat).

Leaving Messages

If a chat is not accepted (IE: You receive the notaccepted event) and the LeaveMessage property of the connected event is True, then you can offer the visitor the option of leaving a message. Left messages will be added as 'missed chats', which operators can respond to later.

To leave a message send the LeaveMessage command:

LeaveMessage (Command)

{
  "Command": "LeaveMessage",
  "Parameters": [
        "65b3b5f6c937df03142c7e51",
        "www.mycompany.com",
        "195.62.193.194",
        "Thomas",
        "Support",
        "thomas@test.com", 
        "07799123456",
        "Please call back as soon as possible"
    ]
}

Parameters:

  1. ChatUID
  2. Domain name
  3. Visitor IP Address
  4. Visitor Name
  5. Department
  6. Visitor Email Address
  7. Visitor Phone Number
  8. Message Text

The ChatUID can be blank if you have not attempted to start a chat session beforehand.

The Department, Visitor Email Address & Visitor Phone Number are optional. If an Email Address is supplied then operators will be able to respond to the missed chat via email (using the WhosOn Client). If a Phone Number is supplied then operators can respond with a Callback (if phone callbacks are enabled on the WhosOn Server).

If you send more than one LeaveMessage command for the same ChatUID - the subsequent ones will be ignored.

Other Commands

GetPreviousChats (Command)

This command can be used to read a list of previous chats for a specific Domain/Visitor IP Address/Visitor Tracking Id. This can be used to present the visitor with a list of their previous chat sessions. Previous chat detail can be read using the GetPreviousChatDetail command.

{
    "Command": "GetPreviousChats",
    "Params": [
        "www.mycompany.com",
        "195.62.193.194",
        "1234-56890"
    ]
}

Parameters:

  1. Domain - only include articles assigned to the specified site (required).
  2. IP Address - the text to search for (required).
  3. Tracking Id - the visitor tracking id (required).

The PreviousChats event will include the results:

PreviousChats (Event)

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

The PreviousChats event contains the top 20 most recent chat sessions for the Site/IP/TrackingId specified with the GetPreviousChats command.

GetPreviousChatDetail (Command)

This command can be used to read the detail of a previous chat session.

{
    "Command": "GetPreviousChatDetail",
    "Params": [
        "65b3b5f6c937df03142c7e51",
        "www.mycompany.com",
        "195.62.193.194",
        "1234-56890"
    ]
}

Parameters:

  1. ChatUID - required.
  2. Domain - required.
  3. IP Address - required.
  4. Tracking Id - required.

The PreviousChatDetail event will include the results:

PreviousChatDetail (Event)

{
    "EventName": "previouschat",
    "ChatUID": "65b3b5f6c937df03142c7e51",
    "Data": {
        "ChatHeader": {
            "ChatUID": "65b3b5f6c937df03142c7e51",
            "SiteKey": 1,
            "IP": "195.62.193.194",
            "TrackingId": "1234-567890",
            "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"
            }
        }
    }
}

ArticleSearch (Command)

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

{
    "Command": "ArticleSearch",
    "Params": [
        "www.mycompany.com",
        "How do I login?",
        "5"
    ]
}

Parameters:

  1. Domain - only include articles assigned to the specified site (required).
  2. Search Term - the text to search for (required).
  3. 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",
    "ChatUID": "",
    "Data": 
        {
            "Domain": "www.mycompany.com",
            "SearchTerm": "How do I login?",
            "Articles": [
                {
                    "Subject": "How do I login?",
                    "Content": "You login using the Login command.\r\n",
                    "DocumentId": "",
                    "Similarity": 1,
                    "Tokens": 0
                },
                {
                    "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 Domain and SearchTerm properties, containing the domain 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).

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.

GetOperators (Command)

This command can be used to request a list of operators. Normally chat requests are routed to the correct operators based on server rules, so there is no need to know available operators in advance. However you can use this command if you wish to show a list of chat operators to the visitor and allow the visitor to select an operator. The GetOperators command can be sent after establishing a chat session, before sending the Hello command.

{
  "Command": "GetOperators",
  "Parameters": [
    "65b3b5f6c937df03142c7e51",
    "www.mycompany.com"
  ]
}

Parameters:

  1. ChatUID
  2. Domain Name

A list of operators for the given domain will be returned in the operators event.

Operators (Event)

{
  "EventName": "operators",
  "ChatUid": null,
  "Data": [
    {
      "Name": "Howard Williams",
      "Email": "howard@mycompany.com",
      "Phone": "+441782822577",
      "Dept": "",
      "Skills": [
        "Sales",
        "Marketing"
      ],
      "IsBot": "False",
      "Status": "Online",
      "Lang": "en",
      "ImageUrl": "",
      "Bio": "",
      "ExternalID": ""
    },
    {
      "Name": "Martin Butler",
      "Email": "martin@mycompany.com",
      "Phone": "+441782822577",
      "Dept": "",
      "Skills": [
        "Technical Support",
        "Training"
      ],
      "IsBot": "False",
      "Status": "Busy",
      "Lang": "en",
      "ImageUrl": "",
      "Bio": "",
      "ExternalID": ""
    }
  ]
}

IsBot will be True if the operator is a bot.

Status will be one of: Online,Busy,Be Right Back, Away

GetImage (Command)

This command can be used to request an image assigned to the site. You can request any of the image types. Images can be requested at any point after establishing a chat session.

{
  "Command": "GetImage",
  "Parameters": [
    "65b3b5f6c937df03142c7e51",
    "www.mycompany.com",
    "en",
    "1"
  ]
}

Parameters:

  1. ChatUID
  2. Domain name
  3. Language - two letter language code (if blank the default will be used).
  4. ImageType

Where ImageType is one of:

ImageType Description
1 Chat button 'available' image.
2 Chat button 'not available' image.
3 Chat logo
4 Site mobile logo image.
5 Chat button 'available' image for mobile devices.
6 Chat button 'not available' image for mobile devices.

The WhosOn Server will send an image event:

Image (Event)

{
  "EventName": "image",
  "ChatUid": "",
  "Data": {
      "Domain": "www.mycompany.com",
      "ImageType": 1,
      "Language": "en",
      "Ext": "png",
      "Base64": "{base64}"
    }
}

{base64} will contain the Base 64 encoded image string.

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