• Hosted in the EU
  • GDPR Compliant

JavaScript SDK

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:

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.