Naughty Pinching Mannequins

    @humany/widget-chat
    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.

    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;
    };

    Keywords

    Install

    npm i @humany/widget-chat

    DownloadsWeekly Downloads

    3

    Version

    1.1.11

    License

    SEE LICENSE IN LICENSE.txt

    Unpacked Size

    214 kB

    Total Files

    117

    Last publish

    Collaborators

    • donami
    • bratn
    • anderslindvall
    • totte