JavaScript SDK
The Channel.me JavaScript Chat SDK is a small JS library which enables interaction between your JavaScript code and the Channel.me chat system, for use when integrating chatbots or websites which require customisation of the chat interface.
API Version: 20191111
Installation
Simply add the following script tag to your HTML pages:
<script src="//channel.me/chatapi.js"></script>Usage Example
Library initialization
let channel = chat_api();Using the chat API
function message_handler(msg) {
switch(msg.event) {
case "chat/initialized":
case "agent/changed":
my_ux.info(`You are now connected with ${msg.agent.name}`);
break;
case "agent/typing/started":
my_ux.show_typing_message();
break;
case "agent/typing/stopped":
my_ux.hide_typing_message();
break;
case "chat/status":
my_ux.set_chat_log(msg.messages.reverse());
break;
default: // `error/*`
my_ux.error("Reconnecting...");
my_app.reconnect();
break;
}
};
channel.init("{MY_API_KEY}", message_handler);API Reference
init(apikey, callback[, options])
Initialize a chat session. If an active session_id is provided in options the client will attempt to reconnect to an existing session.
Parameters
apikey : string
The API key provided by Channel.me
callback : function
The function which will be called with new events. Receives a single object.
options : object
An object containing optional params, which may include:
session_id – an active Session ID, used for reconnections.
group – the Agent Group to which the chat should be directed.
user_info – an object containing details of the Visitor, which will be presented to the Agent in Key: Value format.
page_info – an object containing details of the web page which the Visitor is viewing, which will be presented to the Agent in Key: Value format.
Response
The server will issue one of the following states as an initial response:
chat/initializedwhen initialization has completed and a connection with an Agent has been establishederror/init/unknowngroupwhen thegroupprovided inoptionsis not known to the systemerror/agents/offlinewhen there are no Agents onlineerror/agents/noresponsewhen there are Agents online but the chat has not been accepted within the time limit
state()
Request a new chat/status message from the server.
Response
The server will issue a chat/status message.
is_typing(status)
Inform the Agent when the Visitor is typing.
Parameters
status : boolean
Send true when the Visitor starts typing, and false when they stop. Please debounce calls to this method.
Response
None.
send(message)
Send a message from the Visitor. message should be a UTF8 string. URLs and newlines are formatted correctly. HTML is not allowed and will be escaped.
Parameters
message : string
The message from the Visitor.
Response
The server will issue a chat/status message.
stop()
End the chat session from the Visitor’s side.
Response
The server will issue a chat/ended message.
Response Reference
Responses from the server trigger a call to the registered callback function, which is called with a single object argument. This object will contain an event and a session_id, along with a number of other common parameters. For example:
{
event: "chat/status",
session_id: "A1B2C3D4E5",
timestamp: 1573119404814,
agent: {
name: "Arnold S"
},
messages: [...]
}Common Parameters
All messages provided to your callback will contain one or more of the following common parameters:
event
The type of event.
session_id
The ID of the chat session, used to reestablish the chat should the Visitor’s page refresh.
timestamp
The timestamp the message was issued from the server.
agent
Details of the Agent to which the Visitor is connected. Includes the Agent’s name.
messages
A list of chat messages, ordered newest-first (LIFO), between the Visitor and the Agent. Messages contain the timestamp of the message, the message body, the author (Visitor or Agent), etc.
Event Types
chat/*
chat/initialized
The chat has been successfully initialized.
chat/status
An update message containing the latest state of the chat session.
chat/ended
The chat was ended by the Agent.
agent/*
agent/changed
The Agent has changed, usually due to an internal transfer. The message will contain the new Agent’s details.
agent/typing/started
The Agent is currently typing.
agent/typing/stopped
The Agent has stopped typing.
error/*
In general when errors occur you may need to check the current status with a state() call, inspect the state and reissue the original call, or possibly reinitialise the chat.
Error responses include:
error/init/unknowngroup
The group provided is unknown to the system.
error/agents/offline
No Agents are online currently.
error/agents/noresponse
No Agent was available to answer the chat request. Reinitialize to try again.
error/timeout
Communication with the service has timed-out at some point.
error/unknown
An unknown error has occurred.
Glossary
Visitor
The user of the website who is interacting with the public chat widget.
Agent
The member of the support staff waiting for incoming chats.
Agent Group
Agents are often members of specific groups which assist on specific topics.
Session
The chat interaction between the Visitor and the Agent.
Callback
Your JavaScript function which will be called when new events occur.
FAQs
Why are the message lists ordered newest-first?
The messages are ordered newest-first (Last-in, First-out) to make incremental interfaces more efficient.
For example, if your interface already displays the latest message from the Visitor and 3 new messages from the Agent arrive, the code can iterate forward through the list taking messages until it reaches the last-known message, then stop, reverse this short list, and append to the chat display.
This approach reduces the amount of comparison necessary to find new messages for very long chat sessions.
Support
For any support queries, please contact support@channel.me.