Javascript API

Introduction

When adding site_connect.js to your website you enable a lightweight publish/subscribe transport mechanism. The page contains a extremely lightweight message broker which allows one to route messages from publishers to multiple subscribers.

A Quick Overview

Messages are published to topics. All subscribers to a topic will get the message. A topic is a string, much like a file-path. For example "truck/001/temperature". A subscriber can directly subscribe to a topic, or use wildcards '+' and '#'. '+' matches exactly one word between the slashes, and '#' can be used at the end of a pattern to match all sub-topics.

Examples::

  • truck/0001/temperature - Matches the temperature publications of truck 0001.
  • truck/+/temperature - Matches the temperature publications of all trucks.
  • +/+/temperature - Matches the temperature publications of all vehicles.
  • truck/0001/# - Matches all publishes of truck 0001 on all its sub-topics.

Publish/Subscribe in Channel.me

After loading //channel.me/site_connect.js it is possible to subscribe and publish topics on your local page.

  • site_connect.subscribe(topic, msg_fun, ack_fun) Subscribe to 'topic', when a message arrives which matches topic, the msg_fun callback will be called. The ack_fun callback will be called when the subscription is ready. This is needed because subscribing to topics on the site-connect frame is asynchronous. Returns subscription id.
  • site_connect.unsubscribe(subscription_id) Unsubscribe from the specified subscription id.
  • site_connect.publish(topic, msg) Publish a msg under 'topic'.

Host Page

All topics on the host page begin with the '~/' character. Messages published under this topic are not transferred to the site-connect frame and remain local.

  • ~/site_connect/ready The site-connect frame is ready. Note that the site connect frame can be loaded independently of the host page.

Site-Connect Frame

The site connect scripts loads a separate frame which serves as a connection to the channel.me servers. When a customer agent starts a co-browse or chat session this frame is used to display the interface. Components can be loaded on demand during the lifetime of the host-page. During its lifetime messages can be published. Subscribers can subscribe to these messages by subscribing to the following set of topics.

Site-Connect Topics

  • ~/site_connect/ready The site connect is ready to go and has a customer contact code.
  • ~/site_connect/retry Occasionally, when the channel.me server is too busy the frame is returned without a code. The page is trying to get a new customer contact code.
  • ~/site_connect/error The page gave up trying to get a new customer contact code.
  • ~/site_connect/new_code The site connect frame gets a new customer contact code. This can happen after a co-browse session.

Co-browsing Topics

  • ~pagesession/cobrowsing/start A co-browsing session is started.
  • ~pagesession/cobrowsing/stop A co-browsing session is stopped.

Site-Connect Frame Handling Topics

  • ~pagesession/show_frame Show the site-connect frame. This is done when a chat requested is opened, or another component like the proactive chat request should be made visible.
  • ~pagesession/minimize_frame Minimize the site-connect frame. This is triggered when the user minimises the chat component.
  • ~pagesession/hide_frame Completely hide the site-connect frame. This is done when the chat session is stopped.

Chat Button Topics

  • ~/site_connect/chat_button/:button_id:/enabled The chat button with id :button_id: is enabled. This means there is an agent available to receive an incoming chat message.
  • ~/site_connect/chat_button/:button_id:/disabled The chat button with id :button_id: is disabled. This means there is no agent available to receive an incoming chat message.
  • ~pagesession/chat/trigger The user clicked on a chat button. The message contains the id of the button.
  • ~pagesession/proactive/trigger The proactive chat was triggered.