The Channel API is designed to create custom input channels for chat to come into the WhosOn Server. Using the
Channel API, it is possible to create your own input channel with any integration, using any developer platform that
supports WebSockets.
It allows the creation of custom asynchronous chat channels.
The WebSocket channel interface shares port 8009 with the WhosOn Chat API 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 Channel API, the standard WhosOn Chat channels can still be used. You can use the WhosOn Chat Window and Channels in combination with any custom chat applications you create or use your own exclusively.
When connecting to the channel API, each websocket connection should only be used for a single chat session.
Although both APIs use the same websocket port and protocol to interact with the WhosOn Server, the way that they work is quite different. The Channels API is stateless - the WhosOn Server manages the state, whereas the Chat API requires that you maintain and preserve the chat state in the client application. The Channels API also supports asynchronous chats. This means you have to do more work to handle more message states and options.
If you are creating an unregistered custom channel, then the name you choose for your channel is important. If you want to have an asynchronous channel that supports soft close and resume, you should end your channel name with Async e.g. "mychannelasync". The client software removes the word "async" from the end of the channel name when displaying it.
An API key must be supplied with every command. Please contact Parker Software to obtain your API key before you start development against the Channels 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.
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 Channel command.
Parameters: No added parameters
The WhosOn Server will respond with either an error event or a state event, followed by any of the appropriate messages given the current chat state.
The domain, channel name and customer id are used to match the customer against an existing session inside
WhosOn.
If using an asynchronous channel, the server will check if there are any soft closed or currently open channels and
reply with the correct current status.
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 state event provides information about the current status of the active channel session.
| State | Meaning |
|---|---|
| NotStarted | The chat session does not exist |
| Created | The chat session exists in the server but has not been checked against any opening rules |
| PreChat | The chat session is being asked for required pre-chat survey fields |
| Accepted | Survey has been gathered and the chat session has been assigned a routing rule |
| Chatting | Chat has been allocated to an operator or is in process of being allocated |
| SoftClose | Operator has marked the chat as completed but left open the possibility of rejoining |
| HardClose | Operator has ended the chat and marked that it has completed finished |
| PostChat | Post chat survey fields are being gathered |
| Completed | Post chat survey has been completed |
Once a chat has been connected, the server will ask for any pre-chat survey fields that it requires. The prechat_survey event triggers this:
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 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 customer.
Survey Field data is passed back to the WhosOn Server using the survey field message:
After you have sent a field, WhosOn will send you the next survey field that needs to be collected.
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 through the field message.
You can also elect not to wait for the events, and send the SurveyList command
The SurveyList command is used to send all required fields to the server in advance without waiting for each survey
event.
If you miss one that is set up inside WhosOn, then the server will send you a survey event.
Once you have sent all the required survey fields, the chat will then be processed by WhosOn's routing rules to check if an operator is available and what the state of the chat is.
Now, the server will send you state events at any time. The state will move to Accepted whilst the chat is waiting to be assigned to an operator. After this has happened, the state will move to Chatting, and all chat commands can then be used.
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.
When a chat is not accepted your chat session will receive the notaccepted event. The data part will contain the message to be displayed to the customer.
This event can be shown when the chat is started and rejected due to rules not matching, or when a queue is closed whilst the chat is in that queue, or when a chat is expired (meets maximum wait time) whilst in a queue.
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.
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:
Sending the Quit command stops the chat from showing as waiting for operators, and triggers the post chat survey procedure if the chat has been in the chatting state.
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.
You should send the survey field data back with the same survey message as for PreChat Survey.
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.
To send a chat message send the Text command:
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.
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.
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.
This command informs the WhosOn Server that the visitor has started typing.
This command informs the WhosOn Server that the visitor has stopped typing. You do not need to send this command before sending a Text 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:
If the operator ends the chat the WhosOn Server will send the quit event.
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: Unique 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.