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.
The WebSocket chat interface uses port 8009 by default. The port can be changed using the WhosOn Service Manager. The WebSocket chat interface only accepts connections from IP addresses in the WhosOn Server Whitelist, since it is designed to be used via a secure Web Server proxy to the WhosOn Server.
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.
An API key must be supplied with the Connect command. Please contact Parker Software to obtain your API key before you start development against the Chat API.
Connect a WebSocket on URL ws://{server}:{port} (or wss://{server}:{port} for a secure connection). Replace {server} with the IP address of the WhosOn Server or the Web Server if connecting via a proxy.
Important: WebSocket connections should always be secure (wss://). If you are connecting via a proxy then the web server will need a SSL Certificate. The WhosOn Server does not - since traffic between the proxy and WhosOn will be internal. If connecting to WhosOn directly then the WhosOn Server must be assigned a certificate and the 'Secure' setting of the Chat Server WebSocket must be enabled.
Once a WebSocket connection is established it should remain open for the duration of the Chat session.
UTF8 encoding should be used for sending & receiving.
JSON text is used for all messages.
All commands sent to the server have the following format:
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:
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:
Where EventName is the name of the WhosOn Server Event. The ChatUid property will contain the current server assigned Chat UID 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:
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.
To establish a new chat session, send the Connect command.
Parameters:
The WhosOn Server will respond with either an error event or a connected event.
The Visitor IP and Cookie Session ID are used to match the chatting visitor to a visitor already being tracked in WhosOn. If a tracked visitor for the IP+Cookie Session 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.
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.
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.
The connected event provides information about the WhosOn Site specified in the Connect command Domain Name parameter.
The SessionID property is a unique server created Session ID that can be used for the chat session. A new Session ID is created each time a valid Connect command is sent. Most commands following a Connect command require a session ID to uniquely identify the current chat session.
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 GeoIP object contains the Visitor Geo-IP location information obtained from the Visitor IP address parameter passed with the Connect command.
The AllowedFileTypes property contains a comma separated list of file extensions that visitors can upload during chat sessions. If this field is blank, 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 connected event contains a list of pre and post chat survey fields. For example:
Any number of fields can be created for the pre and post chat survey using the WhosOn Settings Portal.
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).
| 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. |
| 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 Portal 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:
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.
Once you have sent the Connect command and received the connected event you should store the Session ID & Domain Name to use on subsequent commands.
You should then construct the Pre-Chat Survey and offer this to the visitor to complete. Display the OpeningMessage at the start of the pre-chat survey.
To start a chat, send the Hello command:
Parameters:
The Chat Session ID should be the SessionID value from the connected event.
The Pre-Chat Survey should be an XML block enclosed in <Fields> tags. Each field should be:
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 XML 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.
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.
The notaccepted event is sent if the server is unable to accept the chat request.
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.
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.
| 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.
Operators can include Markdown text in chat messages. The WhosOn Server will convert Markdown to HTML before sending newline events.
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 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'.
If no operator picks up the chat after a period (defined in the Site Properties) then the final waiting message will be sent:
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.
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.
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:
Data field will contain the current queue position.
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:
Parameters: Chat Session ID, Domain
Sending the Quit command stops the chat from showing as waiting for operators.
When a chat is picked up by an operator your chat session will first receive a operatorjoined event and then start receiving newline events:
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.
From then on you will receive newline events as the operator (or bot) sends messages:
The WhosOn Server will send events when the operator starts and stops typing. Use these events to display an 'operator is typing' indicator.
To send a chat message send the Message command:
Parameters: Chat Session ID, Domain Name, 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:
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.
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:
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.
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:
Parameters: Chat Session ID, Domain, 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.
Visitors can send files during chat sessions, provided visitor file uploading is allowed in the Site Properties.
Before you can send a file through the Chat Session you need to upload the file to the WhosOn Document Store. This is done using the DocumentWriteForSite method on the WhosOn Web Services. The Web Services URL is returned with the connected event. This method will upload a file and return a unique URL which you include with the File command.
Parameters:
The File extension must be one of the allowed file extensions specified in the AllowedFileTypes property of the Site and Visitor file uploading must be enabled, otherwise an error event will be sent:
Operators can request that the visitor uploads a file. Your chat session will receive the requestfile event.
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.
Operators can request that the visitor complete a dynamic survey field during a chat session. You will receive the requestfield event:
You should then construct user input to match the field and validate. Then send the input data with a DynamicField command:
Sends the result of a dynamic field request.
Parameters: Chat Session ID, Domain, Field Name, 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.
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.
Parameters: Chat Session ID
This command informs the WhosOn Server that the visitor has started typing.
Parameters: Chat Session ID
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.
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:
Parameters: Chat Session ID, Domain
If the operator ends the chat the WhosOn Server will send the quit event:
The quit event will be received if the operator or server ends the chat.
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:
Parameters:
The Post-Chat Survey should be an XML block enclosed in <Fields> tags. Each field should be:
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:
You can request that the WhosOn Server sends an email of the chat transcript using the Transcript command.
Parameters: Chat Uid, Chat Session ID, Domain, Visitor IP Address, 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).
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. You can also offer a 'Leave A Message' form at any point – you do not need to attempt to start a chat session first. Left messages will be added as 'missed chats', which operators can respond to later.
To leave a message send the LeaveMessage command:
Parameters:
The Chat Uid/Chat Session ID 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).
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.
Parameters: Chat Session ID, Domain Name
A list of operators for the given domain will be returned in the operators event.
IsBot will be True if the operator is a bot.
Status will be one of: Online,Busy,Be Right Back, Away
This command can be used to request an image assigned to the site. Images are set using the WhosOn Settings Portal - Chat Designer. You can request any of the image types. Images can be requested at any point after establishing a chat session.
Parameters:
Where ImageType is one of:
| ImageType | Description |
|---|---|
| 1 | Chat button 'available' image. |
| 2 | Chat button 'not available' image. |
| 5 | Site logo image. |
| 8 | Site mobile logo image. |
The WhosOn Server will send an image event:
{base64} will contain the Base 64 encoded image string.