@humany/widget-chat

Chat Platform for Humany Widgets

The Chat Platform exposes an easy-to-use API for third-party chat services to be fully integrated within Humany widgets.

Limitations

The Chat Platform is currently only available for Bot widgets on implementations running Webprovisions. Contact Humany Support for more information on how to enable the Webprovisions runtime.

About Webprovisions

Webprovisions is a web distribution platform provided by Humany. The client framework orchestrates widgets and plugins and provides an easy-to-use API for controlling and extending their behaviour.

See the Skeleton Plugin repository for an example on how to author a Webprovisions plugin.

Accessing the API

Pass in the container for the current widget to the constructor together with a chatPlatformSettings object. Subscribe to the widget:connect event using this.widget.events.subscribe(eventName, handler). Inside this function we initialize() our platform.

import { Plugin } from '@webprovisions/platform';
import { ChatPlatform } from '@humany/widget-chat';

export class MyChatPlugin extends Plugin {
  constructor(container, settings) {
    const chatPlatformSettings = { adapterClientName: 'myCustomChat' };
    this.chatPlatform = new ChatPlatform(container, chatPlatformSettings);

    this.handleChatConnect = this.handleChatConnect.bind(this);
    this.widget.events.subscribe('widget:connect', this.handleWidgetConnect);
  }

  handleWidgetConnect() {
    this.chatPlatform.initialize();
    console.log('platform is now initialized and ready', this.chatPlatform);
  }
}

Using the API

The API is an abstraction on top of a message stream. Changes will be stored locally when working with the API. Push pending changes onto the message stream by calling commit() on the Platform object. To listen to events on the platform, use this.chatPlatform.events.subscribe(eventName, handler).

The API consists of a chat object for manipulating the chat, and user and agent objects to manipulate the chat agent and user respectively.

Important: Please note that the chat, user and agent objects are available only when the platform is initialized and connected and will cause a null reference exception otherwise.

Chat

Use the chat property to modify the appearance of the chat.

Changing the state

chatPlatform.chat.set({ state: 'ready' });
chatPlatform.commit();

Possible values for the chat´s state is 'queuing' (default), 'ready' and 'closed'.

Create info message

Use the createInfoMessage() on the chat to display a generic information message. This can be used to inform the user of chat related events such as when the chat is initializing, waiting for an available agent and similar.

chatPlatform.chat.createInfoMessage({ text: 'Looking for available agents...' });
chatPlatform.commit();

createInfoMessage() returns a ChatMessage. See below under "Messages" for additional functions.

Chat Agent

Use the agent property to modify the appearance of the chat agent.

Name and avatar

chatPlatform.agent.set({name: 'Mrs Agent', avatar: 'https://[url]');
chatPlatform.commit();

Changing the state

chatPlatform.agent.set({ state: 'typing' });
chatPlatform.commit();

Possible values for the agent´s state is 'idling' (default) and 'typing'.

Messages

Creating messages is made through the agent and user objects.

Plain text message

chatPlatform.agent.createMessage({ text: 'Hi - how can I help?' });
chatPlatform.commit();

HTML message

chatPlatform.agent.createMessage({ html: '<p>Hi - how can I help?</p>' });
chatPlatform.commit();

Changing the state

const userMessage = chatPlatform.user.createMessage({ text: 'I need to know something...', state: 'pending' });
chatPlatform.commit();

// awaiting delivery...

userMessage.set({ state: 'sent' });
chatPlatform.commit();

Possible values for a message's state is 'sent' (default) and 'pending'.

chatPlatformSettings

An object containing settings for the platform.

adapterClientName (required)

The client name of the adapter the platform should attach to. This is a string which you configure on the contact method that will serve as a handler for this specific plugin.

disableAutoMessage (optional)

Whether the platform should automatically create the chat user's message. default: false

enableFiles (optional)

Whether the platform should accept files to be submitted. default: false

Starting and ending a chat session

Connect

The Chat Platform will be attached to adapters with the client name specified in adapterClientName on the chatPlatformSettings object. When an adapter is executed the platform will trigger the chat:connect event. The data object contains the adapter settings and, if available, form data.

chatPlatform.events.subscribe('chat:connect', (event, data) => {
  console.log('platform requesting the chat to connect', data.settings);
});

Receiving message

When the chat is connected the Platform will override the default behaviour for when the user submits a message in the widget. When the user submits a message the platform will trigger the chat:user-submit event, containing the raw text input including the ChatMessage that is automatically created (unless disableAutoMessage is set). Listen to this event to pass on messages to the underlying chat service.

chatPlatform.events.subscribe('chat:user-submit', (event, data) => {
  console.log('user submitted a message:', data.text);
});

Properties of 'data' object

message

A ChatMessage containing the input (unless disableAutoMessage is set to 'true')

text

The input text, if available.

files

The input FileList, if available.

Disconnect

Call the disconnect() method on the Platform to end the current chat session. This will restore the default behaviour of the widget. If a chat session is ended by the user the platform will trigger the chat:disconnect event.

chatPlatform.events.subscribe('chat:disconnect', (event, data) => {
  console.log('the chat session has disconnected');
});

On user input change

When the user starts typing you can use the chat:user-typing event to send information even before the user has actively submitted a message. This event can only be triggered once every 400ms.

chatPlatform.events.subscribe('chat:user-typing', (event, data) => {
  console.log('this is the current value of the user input', data.text)
});