WhosOn Channel API

Introduction

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.

Use Cases

  • Create your own channel from any messaging platform.
  • Integrate the chat directly into another chat system or platform.
  • Create a complex mobile application integration.

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.

Difference between the Chat API and the Channels API

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.

Asynchronous Channels

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.

API Key

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.

Connecting

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

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

Sending Commands

JSON text is used for all messages.

All commands sent to the server have the following format:

{
    "Command": "commandname",
  "APIKey": "aaaasdsasasdddcsadad",
  "AuthString": "myauthstring", 
  "Domain": "www.mycompany.com",
  "Channel": "channelnameasync",
  "CustomerID": "12341234",
  "MessageID": "79b768b1-16b9-4e73-a881-66bb8c1346dd"
  /** ... additional fields here **/
}

The commandname is the name of the command to send to the WhosOn Server. Command names are not case sensitive.

  • APIKey is the API Key provided to you by WhosOn for your integration.
  • AuthString is the authentication string of the particular server you are connecting to. This varies from server to server, so is normally a configuration parameter.
  • Domain is the domain of the site that the chat session will belong to. This controls the settings that are applied to the chat startup.
  • Channel is the name of the channel you are integrating between.
  • CustomerID is a unique identifier for this customer. It can be any string up to 50 characters in length. The server will group any sessions from the same Customer ID together.
  • MessageID is a unique identifier for the message. Used for logging and troubleshooting.

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 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:

{
  "EventName": "newline",
  "ChatUid": "gq0i7smlen",
  "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 Channel command.

Channel (Command)

{
  "Command": "Channel",
  "APIKey": "aaaasdsasasdddcsadad",
  "AuthString": "myauthstring", 
  "Domain": "www.mycompany.com",
  "Channel": "channelnameasync",
  "CustomerID": "12341234",
  "MessageID": "79b768b1-16b9-4e73-a881-66bb8c1346dd"
}

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.

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.

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.

State (Event)

The state event provides information about the current status of the active channel session.

{
  "EventName": "state",
  "ChatUID": "aa123412",
  "CustomerId": "12312322",
  "State": "Prechat"
}
  • The ChatUID property gives the current Chat UID that the server has assigned to this session.
  • The State property is a string which descibes the current chat state:
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

Survey Fields

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:

{
  "EventName": "prechat_survey",
  "ChatUid": "gy54x4cvw0",
  "Data": {
    "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,
    "SelectType": "",
    "ValidateLow": 0.0,
    "ValidateHigh": 0.0,
    "CustomProperties": "",
    "RequiredField": true,
    "SelectOptions": [],
    "HTML5Type": "text"
  }
}

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

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

SurveyField (Command)

{
  "Name": "VisitorName",
  "Value": "Daniel T",
  "Command": "SurveyField",
  "APIKey": "aaaasdsasasdddcsadad",
  "AuthString": "myauthstring", 
  "Domain": "www.mycompany.com",
  "Channel": "channelnameasync",
  "CustomerID": "12341234",
  "MessageID": "6ec2a248-26b3-4782-a511-7b373707940d"
}

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

SurveyList (Command)

{
  "Command": "SurveyList",
  "APIKey": "aaaasdsasasdddcsadad",
  "AuthString": "myauthstring", 
  "Domain": "www.mycompany.com",
  "Channel": "channelnameasync",
  "CustomerID": "12341234",
  "MessageID": "6ec2a248-26b3-4782-a511-7b373707940d",
  "Items": {
    "Name": "Daniel T",
    "Option": "ABC"
  }
}

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.

Chat Sessions

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.

Events

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": "gq0i7smlen",
  "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": "gq0i7smlen",
  "Data": {
    "Classname": "lineo linewaiting1",
    "Content": "One moment please..."
  }
}
{
  "EventName": "newline",
  "ChatUid": "gq0i7smlen",
  "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": "gq0i7smlen",
  "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": "gq0i7smlen",
  "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": "gq0i7smlen",
  "Data": "2"
}

Data field will contain the current queue position.

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": "gq0i7smlen",
  "Data": {
     "Name": "Howard Williams",
     "Email": "howard@mycompany.com",
     "Phone": "+441782822577",
     "Dept": "",
     "Skills": [
       "Sales",
       "Marketing"
     ],
     "IsBot": "False",
     "Status": "Online",
     "Lang": "en"
   },
}

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:

NewLine (Event)

{
  "EventName": "newline",
  "ChatUid": "gq0i7smlen",
  "Data": {
    "Classname": "linesays",
    "Content": "Howard Williams says:"
  }
}
{
  "EventName": "newline",
  "ChatUid": "gq0i7smlen",
  "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": "gq0i7smlen",
  "Data": ""
}

TypingStop (Event)

{
  "EventName": "typingstop",
  "ChatUid": "gq0i7smlen",
  "Data": ""
}

Commands

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",
  "APIKey": "aaaasdsasasdddcsadad",
  "AuthString": "myauthstring", 
  "Domain": "www.mycompany.com",
  "Channel": "channelnameasync",
  "CustomerID": "12341234",
  "MessageID": "6ec2a248-26b3-4782-a511-7b373707940d"
}

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.

RequestFile (Event)

{
  "EventName": "requestfile",
  "ChatUid": "gq0i7smlen",
  "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": "gq0i7smlen",
  "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.

You should send the survey field data back with the same survey message as for PreChat Survey.

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": [
    "d6e76b3c-b1fc-4e13-9ee6-f4a788a5269a",
    "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 A Message

To send a chat message send the Text command:

Text (Command)

{
  "Text": "Here is some text going to this chat session.",
  "Command": "Text",
  "APIKey": "aaaasdsasasdddcsadad",
  "AuthString": "myauthstring", 
  "Domain": "www.mycompany.com",
  "Channel": "channelnameasync",
  "CustomerID": "12341234",
  "MessageID": "6ec2a248-26b3-4782-a511-7b373707940d"
}

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": "gq0i7smlen",
  "Data": {
    "Classname": "linesays",
    "Content": "Thomas says:"
  }
}
{
  "EventName": "newline",
  "ChatUid": "gq0i7smlen",
  "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.

Sending Files

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.

File (Command)

{
  "Filename": "mydocument.pdf",
  "URL": "http://chat.mycompany.com/whosoncharts/document.aspx?f=dfc3ffd72bb9416194aaea7c6f14b449f4629aafd2830e0b4716.pdf",
  "Command": "File",
  "APIKey": "aaaasdsasasdddcsadad",
  "AuthString": "myauthstring", 
  "Domain": "www.mycompany.com",
  "Channel": "channelnameasync",
  "CustomerID": "12341234",
  "MessageID": "6ec2a248-26b3-4782-a511-7b373707940d"
}

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",
  "APIKey": "aaaasdsasasdddcsadad",
  "AuthString": "myauthstring", 
  "Domain": "www.mycompany.com",
  "Channel": "channelnameasync",
  "CustomerID": "12341234",
  "MessageID": "6ec2a248-26b3-4782-a511-7b373707940d"
}

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

StopTyping (Command)

{
  "Command": "StopTyping",
  "APIKey": "aaaasdsasasdddcsadad",
  "AuthString": "myauthstring", 
  "Domain": "www.mycompany.com",
  "Channel": "channelnameasync",
  "CustomerID": "12341234",
  "MessageID": "6ec2a248-26b3-4782-a511-7b373707940d"
}

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.

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",
  "APIKey": "aaaasdsasasdddcsadad",
  "AuthString": "myauthstring", 
  "Domain": "www.mycompany.com",
  "Channel": "channelnameasync",
  "CustomerID": "12341234",
  "MessageID": "6ec2a248-26b3-4782-a511-7b373707940d"
}

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

Other Commands

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": [
    "d6e76b3c-b1fc-4e13-9ee6-f4a788a5269a",
    "www.mycompany.com"
  ]
}

Parameters: Unique Session ID, 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"
    },
    {
      "Name": "Daniel Tallentire",
      "Email": "daniel@mycompany.com",
      "Phone": "+441782822577",
      "Dept": "",
      "Skills": [
        "Technical Support",
        "Training"
      ],
      "IsBot": "False",
      "Status": "Busy",
      "Lang": "en"
    }
  ]
}

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

{
  "Command": "GetImage",
  "Parameters": [
    "d6e76b3c-b1fc-4e13-9ee6-f4a788a5269a",
    "www.mycompany.com",
    "1"
  ]
}

Parameters:

  • Unique Session ID
  • Domain name
  • ImageType

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:

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 2020 https://www.whoson.com