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 and Floating widgets on implementations running Webprovisions (version 4 or higher).

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.

import { Plugin } from '@humany/widget-core';
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.chatPlatform.events.subscribe('chat:connect', (event, data) => {
      // connect to your chat client
    });
  }
}

chatPlatformSettings

An object containing settings for the platform.

type ChatPlatformSettings = {
  adapterClientName: string,
  enableFiles?: boolean,
  disableAutoMessage?: boolean,
  disableAutoDisconnect?: boolean,
  texts?: { [key: string]: string },
}

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

disableAutoDisconnect (optional)

Whether the platform should automatically disconnect once the user confirms end chat from the widget.

default: false

enableFiles (optional)

Whether the platform should accept files to be submitted.

default: false

texts (optional)

Object string with key-value-pairs used for keys

default:

{
  connectingToChat: 'Connecting to chat...', 
  // Displayed in widget header when connecting to chat.
  queuingForChat: 'Queuing...', 
  // Displayed in widget header when queuing for chat.
  chatInProgress: 'Chat in progress...', 
  // Displayed in widget header during chat session.
  endChat: 'End chat', 
  // Label on end-chat-button in widget header.
  confirmEndChat: 'Are you sure you want to end the ongoing chat session?', 
  // Message shown in confirmation box when clicking end-chat-button.
  userSenderLabel: 'Me', 
  // Sender label displayed below user messages.
}

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 property. To listen to events on the platform, use this.chatPlatform.events.subscribe(eventName, handler).

The API consists of a chat, user and agent objects to handle 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 state, name or avatar of the chat.

enum CHAT_STATE {
  queuing = 'queuing',
  connecting = 'connecting',
  ready = 'ready',
  closed = 'closed',
}

type Chat = {
  name?: string;
  avatar?: string;
  state?: CHAT_STATE;
};

Updating the name, avatar and/or state

chatPlatform.chat.set({   
  name: 'System', 
  avatar: 'https://[system-avatar].png',
  state: 'ready',
});
chatPlatform.commit();

Agent

Use the agent property to modify the state, name or avatar of the agent.

enum AGENT_STATE {
  idling = 'idling',
  typing = 'typing',
}

type Agent = {
  name?: string;
  avatar?: string;
  state?: AGENT_STATE;
}

Updating the name, avatar and/or state

chatPlatform.agent.set({ 
  name: 'Mrs Agent', 
  avatar: 'https://[agent-avatar].png',
  state: 'typing',
});
chatPlatform.commit();

Messages

Messages are created and handled by the agent, user and chat objects.

enum MESSAGE_STATE {
  pending = 'pending',
  sent = 'sent',
}

type Message = {
  id?: string;
  html?: string;
  text?: string;
  files?: FileList;
  state: MESSAGE_STATE;
}

Plain text message

chatPlatform.agent.createMessage({ text: 'Hi! how can I help?' });
chatPlatform.user.createMessage({ text: 'I need help with...' });
chatPlatform.commit();

HTML message

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

Create info message

Use the createInfoMessage() on the chat to inform the user of chat related events such as when the chat is initializing, waiting for an available agent or similar.

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

Updating 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();

Resource texts

You can access resource texts from texts on the chatPlatformSettings object by calling get() on the platform.texts property:

chatPlatform.texts.get('userSenderLabel');
// Will return the 'userSenderLabel' text passed to the platform or its default value.

Starting, handling and ending a chat session

Connecting

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.

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

connectionData

An object containing the connection data.

type ConnectionData = {
  settings: { [key: string]: string },
  formData?: { [key: string]: any },
};

settings

Contact method settings.

formData (if triggered by form submission)

A key-value-pair object with the form values.

Receiving messages

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.

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

submissionData

An object containing the submission data.

type SubmissionData = {
  html?: string;
  text?: string;
  files?: FileList;
  message?: Message,
};

Disconnecting

Call the disconnect() method on the platform to end the current chat session. If a chat session is ended by the user and the disableAutoDisconnect is false the platform will automatically disconnect otherwise it will just emit the chat:disconnect event.

chatPlatform.disconnect();

This will restore the default behaviour of the widget and trigger the chat:disconnect event.

chatPlatform.events.subscribe('chat:disconnect', (event) => {
  // disconnect from your chat client

  // if disableAutoDisconnect === true
  chatPlatform.disconnect();
});

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, typingData) => {
  console.log('this is the current value of the user input', typingData)
});

typingData

An object containing the text currently typed by user.

type TypingData = {
  text: string;
};