Naughty Pinching Mannequins

    TypeScript icon, indicating that this package has built-in type declarations

    1.1.11 • Public • Published

    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.


    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);
       'chat:connect', (event, data) => {
          // connect to your chat client


    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


      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, 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.


    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{   
      name: 'System', 
      avatar: 'https://[system-avatar].png',
      state: 'ready',


    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

      name: 'Mrs Agent', 
      avatar: 'https://[agent-avatar].png',
      state: 'typing',


    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...' });

    HTML message

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

    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.{ text: 'Looking for available agents...' });

    Updating the state

    const userMessage = chatPlatform.user.createMessage({ text: 'I need to know something...', state: 'pending' });
    // awaiting delivery...
    userMessage.set({ state: 'sent' });

    Resource texts

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

    // Will return the 'userSenderLabel' text passed to the platform or its default value.

    Starting, handling and ending a chat session


    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.'chat:connect', (event, connectionData) => {
      console.log('platform requesting the chat to connect', connectionData);


    An object containing the connection data.

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


    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.'chat:user-submit', (event, submissionData) => {
      console.log('user submitted a message:', submissionData);


    An object containing the submission data.

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


    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.


    This will restore the default behaviour of the widget and trigger the chat:disconnect event.'chat:disconnect', (event) => {
      // disconnect from your chat client
      // if disableAutoDisconnect === true

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


    An object containing the text currently typed by user.

    type TypingData = {
      text: string;



    npm i @humany/widget-chat

    DownloadsWeekly Downloads






    Unpacked Size

    214 kB

    Total Files


    Last publish


    • donami
    • bratn
    • anderslindvall
    • totte