HumaneChat Web Messenger

The HumaneChat Web Messenger will add live web messaging to your website or web app.

Usage

Script Tag

Add the following code towards the end of the head section on your page and replace <app-id> with your app id at the end of the script.

<script>
    !function(e,n,t,r){function s(){try{var e;if((e="string"==typeof this.response?JSON.parse(this.response):this.response).url){var t=n.getElementsByTagName("script")[0],r=n.createElement("script");r.async=!0,r.src=e.url,t.parentNode.insertBefore(r,t)}}catch(e){}}var o,a,p,c=[],i=[];e[t]={init:function(){o=arguments;var e={then:function(n){return i.push({type:"t",next:n}),e},catch:function(n){return i.push({type:"c",next:n}),e}};return e},on:function(){c.push(arguments)},render:function(){a=arguments},destroy:function(){p=arguments}},e.__onWebMessengerHostReady__=function(n){if(delete e.__onWebMessengerHostReady__,e[t]=n,o)for(var r=n.init.apply(n,o),s=0;s<i.length;s++){var u=i[s];r="t"===u.type?r.then(u.next):r.catch(u.next)}a&&n.render.apply(n,a),p&&n.destroy.apply(n,p);for(s=0;s<c.length;s++)n.on.apply(n,c[s])};var u=new XMLHttpRequest;u.addEventListener("load",s),u.open("GET","https://cdn.humane.chat/loader.json",!0),u.responseType="json",u.send()}(window,document,"HumaneChat");
</script>

then initialize the Web Messenger by placing this snippet towards the end of the body section of your page.

<script>
    HumaneChat.init({appId: '<app-id>'}).then(function() {
        // Your code after init is complete
    });
</script>

Browser support

Web Messenger supports all popular browsers.

Desktop versions

• Chrome: Latest and one major version behind
• Edge: Latest and one major version behind
• Firefox: Latest and one major version behind
• Internet Explorer: 11+
• Safari: Latest and one major version behind

Mobile versions

• Stock browser on Android 4.1+
• Safari on iOS 8+

Other browsers

Web Messenger is likely compatible with other and older browsers but we only test against the versions above.

API

Individual functions

init(options)

Initializes the HumaneChat widget in the web page using the specified options. It returns a promise that will resolve when the Web Messenger is ready. Note that excepton and off, all methods needs to be called after a successful init.

Options

region

HumaneChat is available in the following regions:

customColors

customText

The list of localizable strings. These strings can be modified. If an option is not given a custom string, the default value will be used.

See below for an example.

menuItems

See below for an example.

prechatCapture

See below for an example.

prechatCapture uses the following customText options:

Example

var initPromise = HumaneChat.init({
    appId: '<app-id>',

    // Leave unspecified for US region (default)
    region: 'eu-1',

    // For authenticated mode
    jwt: 'your_jwt',
    userId: 'user_id',
    locale: 'en-US',

    customColors: {
        brandColor: '65758e',
        conversationColor: '65758e',
        actionColor: '65758e',
    },

    menuItems: {
        imageUpload: true,
        fileUpload: true,
        shareLocation: true
    },

    fixedIntroPane: false,

    prechatCapture: {
        enabled: true,
        enableEmailLinking: true,
        fields: [
            {
                type: 'email',
                name: 'email',
                label: 'Email',
                placeholder: 'your@email.com'
            },
            {
                type: 'text',
                name: 'company-website',
                label: 'Company website',
                placeholder: 'mycompany.com'
            },
            {
                type: 'select',
                name: 'company-size',
                label: 'Company size',
                placeholder: 'Choose a number...',
                options: [
                    {
                        name: '1-10',
                        label: '1-10 employees'
                    },
                    {
                        name: '11-50',
                        label: '11-50 employees'
                    },
                    {
                        name: '51+',
                        label: '51+ employees'
                    }
                ]
            }
        ]
    },

    customText: {
        actionPaymentCompleted: 'Payment Completed',
        actionPaymentError: 'An error occurred while processing the card. <br> Please try again or use a different card.',
        actionPostbackError: 'An error occurred while processing your action. Please try again.',
        clickToRetry: 'Message not delivered. Click to retry.',
        clickToRetryForm: 'Form not submitted. Click anywhere on the form to retry.',
        connectNotificationText: 'Give us a way to reach out:',
        connectNotificationSingleText: 'Be notified when you get a reply.',
        connectNotificationSingleButtonText: 'Turn on <name> notifications',
        connectNotificationOthersText: 'others',
        conversationTimestampHeaderFormat: 'MMMM D YYYY, h:mm A',
        couldNotConnect: 'Couldn\'t connect. You can {retry}. '
        couldNotConnectInner: 'retry connecting now'
        couldNotConnectWithRetry: 'Couldn\'t connect. We\'ll keep retrying, or you can {retry}.',
        couldNotConnectWithRetryInner: 'try now',
        emailChangeAddress: 'Change my email',
        emailDescription: 'To be notified by email when you get a reply, enter your email address.',
        emailFieldLabel: 'Your email',
        emailFieldPlaceholder: 'Your email address',
        emailFormButton: 'Continue',
        fetchHistory: 'Load more',
        fetchingHistory: 'Retrieving history...',
        fileTooLargeError: 'Max file size limit exceeded ({size})',
        fileTypeError: 'Unsupported file type.',
        formErrorInvalidEmail: 'Email is invalid',
        formErrorNoLongerThan: 'Must contain no more than ({characters}) characters',
        formErrorNoShorterThan: 'Must contain at least ({characters}) characters',
        formErrorUnknown: 'This doesn\'t look quite right',
        formFieldSelectPlaceholderFallback: 'Choose one...',
        frontendEmailChannelDescription: 'To talk to us using email just send a message to our email address and we\'ll reply shortly:',
        headerText: 'How can we help?',
        imageClickToReload: 'Click to reload image.',
        imageClickToView: 'Click to view {size} image.',
        imagePreviewNotAvailable: 'Preview not available.',
        inputPlaceholder: 'Type a message...',
        inputPlaceholderBlocked: 'Complete the form above...',
        introAppText: 'Message us below or from your favorite app.',
        introductionText: 'We\'re here to talk, so ask us anything!',
        invalidFileError: 'Only images are supported. Choose a file with a supported extension (jpg, jpeg, png, gif, or bmp).',
        lineChannelDescription: 'To talk to us using LINE, scan this QR code using the LINE app and send us a message.',
        linkError: 'An error occurred when attempting to generate a link for this channel. Please try again.',
        locationNotSupported: 'Your browser does not support location services or it’s been disabled. Please type your location instead.',
        locationSecurityRestriction: 'This website cannot access your location. Please type your location instead.',
        locationSendingFailed: 'Could not send location',
        locationServicesDenied: 'This website cannot access your location. Allow access in your settings or type your location instead.',
        messageError: 'An error occured while sending your message. Please try again.',
        messageIndicatorTitlePlural: '({count}) New messages',
        messageIndicatorTitleSingular: '({count}) New message',
        messageRelativeTimeDay: '{value}d ago',
        messageRelativeTimeHour: '{value}h ago',
        messageRelativeTimeJustNow: 'Just now',
        messageRelativeTimeMinute: '{value}m ago',
        messageTimestampFormat: 'h:mm A',
        messageSending: 'Sending...',
        messageDelivered: 'Delivered',
        messengerChannelDescription: 'Connect your Facebook Messenger account to be notified when you get a reply and continue the conversation on Facebook Messenger.',
        notificationSettingsChannelsDescription: 'You can also talk to us from your favorite app or service.',
        notificationSettingsChannelsTitle: 'Other Channels',
        notificationSettingsConnected: 'Connected',
        notificationSettingsConnectedAs: 'Connected as {username}',
        prechatCaptureGreetingText: 'Hi there 👋\nTo start off, we\'d like to know a little bit more about you:',
        prechatCaptureNameLabel: 'Your name',
        prechatCaptureNamePlaceholder: 'Type your name...',
        prechatCaptureEmailLabel: 'Email',
        prechatCaptureEmailPlaceholder: 'name@company.com',
        prechatCaptureConfirmationText: 'Thanks for that! What can we help you with?',
        prechatCaptureMailgunLinkingConfirmation: 'You\'ll be notified here and by email at {email} once we reply.',
        sendButtonText: 'Send',
        settingsHeaderText: 'Settings',
        shareLocation: 'Share location',
        smsBadRequestError: 'We were unable to communicate with this number. Try again or use a different one.',
        smsCancel: 'Cancel',
        smsChangeNumber: 'Change my number',
        smsChannelDescription: 'Connect your SMS number to be notified when you get a reply and continue the conversation over SMS.',
        smsChannelPendingDescription: 'Check your messages at {number} to confirm your phone number.',
        smsContinue: 'Continue',
        smsInvalidNumberError: 'Your phone number isn\'t valid. Please try again.',
        smsLinkCancelled: 'Link to {appUserNumber} was cancelled.',
        smsLinkPending: 'Pending',
        smsPingChannelError: 'There was an error sending a message to your number.',
        smsSendText: 'Send me a text',
        smsStartTexting: 'Start Texting',
        smsTooManyRequestsError: 'A connection for that number was requested recently. Please try again in {minutes} minutes.',
        smsTooManyRequestsOneMinuteError: 'A connection for that number was requested recently. Please try again in 1 minute.',
        smsUnhandledError: 'Something went wrong. Please try again.',
        tapToRetry: 'Message not delivered. Tap to retry.',
        tapToRetryForm: 'Form not submitted. Tap anywhere on the form to retry.',
        telegramChannelDescription: 'Connect your Telegram account to be notified when you get a reply and continue the conversation on Telegram',
        uploadDocument: 'Upload document',
        uploadInvalidError: 'Invalid file',
        uploadPhoto: 'Upload photo',
        uploadVirusError: 'A virus was detected in your file and it has been rejected',
        unsupportedMessageType: 'Unsupported message type.',
        unsupportedActionType: 'Unsupported action type.',
        viberChannelDescription: 'Connect your Viber account to be notified when you get a reply and continue the conversation on Viber. To get started, scan the QR code using the Viber app.',
        viberChannelDescriptionMobile: 'Connect your Viber account to be notified when you get a reply and continue the conversation on Viber. To get started, install the Viber app and tap Connect.',
        viberQRCodeError: 'An error occurred while fetching your Viber QR code. Please try again.',
        wechatChannelDescription: 'Connect your WeChat account to be notified when you get a reply and continue the conversation on WeChat. To get started, scan this QR code using the WeChat app.',
        wechatChannelDescriptionMobile: 'Connect your WeChat account to be notified when you get a reply and continue the conversation on WeChat. To get started, save this QR code image and upload it in the <a href=\'weixin://dl/scan\'>QR code scanner</a>.',
        wechatQRCodeError: 'An error occurred while fetching your WeChat QR code. Please try again.',
        whatsappChannelDescriptionDesktop: 'Sync your account to WhatsApp by scanning the QR code or clicking the link below.\nThen, send the pre-populated message to validate the sync request. (Your code: {{code}}).',
        whatsappChannelDescriptionMobile: 'Sync your account to WhatsApp by clicking the link below.\nThen, send the pre-populated message to validate the sync request. (Your code: {{code}}).',
        whatsappLinkingError: 'An error occurred while fetching your WhatsApp linking information. Please try again.'
    }
}).then(function() {
    // Your code after init is complete
});

initPromise.then(function() {
    // do something
});

// pass it around...

initPromise.then(function() {
    //do something else
});

open()

Opens the conversation widget (noop when embedded)

HumaneChat.open();

close()

Closes the conversation widget (noop when embedded)

HumaneChat.close();

isOpened()

Tells if the widget is currently opened or closed.

HumaneChat.isOpened();

login(userId , jwt)

Logs a user in the Web Messenger, retrieving the conversation the user already had on other browsers and/or devices. Note that you don't need to call this after init if you passed the user id and jwt already, it's done internally. This returns a promise that resolves when the Web Messenger is ready again.

HumaneChat.login('some-id', 'some-jwt');

logout()

Logs out the current user and reinitialize the widget with an anonymous user. This returns a promise that resolves when the Web Messenger is ready again.

HumaneChat.logout();

destroy()

Destroys the Web Messenger and makes it disappear. The Web Messenger has to be reinitialized with init to be working again because it also clears up the app id from the Web Messenger. It will also unbind all listeners you might have with HumaneChat.on.

HumaneChat.destroy();

sendMessage(message)

Sends a message on the user's behalf

HumaneChat.sendMessage({
    type: 'text',
    text: 'hello'
});

// OR

HumaneChat.sendMessage('hello');

startTyping()

Sends an event indicating the appUser has started typing. When called, a stopTyping timer will be created and will call stopTyping() after 10s, unless stopTyping() has been called manually. Everytime startTyping() is called the timer is reset. If startTyping() is called repeatedly, an event will only be sent if the time since the last sent event is greater then 10s.

HumaneChat.startTyping();

stopTyping()

Sends an event indicating the appUser has stoped typing.

HumaneChat.stopTyping();

triggerPostback(actionId)

Trigger a postback action on the user's behalf.
The actionId is the _id property of the targeted action.

If you have the _id of the targetted postback action, you can pass it directly to triggerPostback.

const actionId = '5a747faa065bbe4e7804f2a4';
HumaneChat.triggerPostback(actionId);

Otherwise, you can get the _id of an action by using HumaneChat.getConversation(), e.g.

const conversation = HumaneChat.getConversation();

console.log(conversation.messages);
// [
//     {
//         "text": "Do you want to continue?",
//         "actions": [
//             {
//                 "payload": "text:continue",
//                 "text": "Continue conversation",
//                 "_id": "5a7c65211aaa9b61f69c95e3",
//                 "type": "postback"
//             }
//         ],
//         "type": "text",
//         "role": "appMaker",
//         "_id": "5a7c65211aaa9b61f69c95e2",
//         // ...
//     }
// ]

// Indicate that the user has clicked on the "Continue conversation" postback action.
HumaneChat.triggerPostback(conversation.messages[0].actions[0]._id);

updateUser(user)

Updates user information

HumaneChat.updateUser({
    givenName: 'Updated',
    surname: 'Name',
    email: 'updated@email.com',
    properties: {
      'justGotUpdated': true
    }
});

getUser()

Returns the current user.

var user = HumaneChat.getUser()

getConversation()

Returns the conversation if it exists

var conversation = HumaneChat.getConversation();

loadConversation(conversationId)

Loads a conversation into the current session

HumaneChat.loadConversation('<conversation-id>');

startConversation()

Creates a user and conversation on the server, allowing the business to reach out proactively to the user via the public API.

It is strongly recommended to only call this method in the case where a message is likely to be sent.

This method is called automatically when starting a conversation via the sendMessage method, or when a user sends a message via the conversation view.

If a conversation already exists for the current user, this call is a no-op.

HumaneChat.startConversation();

markAllAsRead()

Marks all unread messages as read.

HumaneChat.markAllAsRead();

showNotificationChannelPrompt()

Displays a prompt to the user suggesting the linking of the current chat instance with other 3rd-party apps.

HumaneChat.showNotificationChannelPrompt();

setPredefinedMessage(message)

Prefills the user's chat input with a predefined message.

HumaneChat.setPredefinedMessage(message);

setDelegate(delegate)

Sets a delegate on the conversation. HumaneChat must be initialized before calling this method. See the delegate section for more details.

HumaneChat.setDelegate(delegate);

Delegate

HumaneChat allows you to set a delegate to receive callbacks when important changes happen in the conversation.
To set a delegate, pass the delegate parameter in to init options, or use the setDelegate method. The delegate object may optionally contain beforeDisplay, beforeSend, beforePostbackSend and onInvalidAuth delegate functions.

const delegate = {
    beforeDisplay(message) {
        return message;
    },
    beforeSend(message) {
        return message;
    },
    beforePostbackSend(postback) {
        return postback;
    },
    onInvalidAuth() {
        return new Promise((resolve) =>
            resolve('<my-new-auth-token>')
        )
    }
}

// Passing delegate as an init parameter
HumaneChat.init({
    appId: '<app-id>',
    delegate
});

// Using setDelegate
HumaneChat.init({ appId: '<app-id>' }).then(() => {
    HumaneChat.setDelegate(delegate);
});

beforeDisplay

The beforeDisplay delegate allows a message to be hidden or modified before it is displayed in the conversation. This delegate should return a falsy value such as null to hide the message. It can also return a modified message object in order to change what the user will see rendered in their conversation history. Note that this change affects the client side rendering only; the server side copy of this message can not be modified by this delegate.

HumaneChat.init({
    appId: '<app-id>',
    delegate: {
        beforeDisplay(message) {
            if (message.metadata && message.metadata.isHidden) {
                return null;
            }

            return message;
        }
    }
});

beforeSend

The beforeSend delegate method allows you to modify properties of a message before sending it to HumaneChat.
The modified message must be returned for it to take effect.

Note that when a file or an image is uploaded, only the message metadata may be updated. Other message properties such as type or text won't be considered.

HumaneChat.init({
    appId: '<app-id>'
    delegate: {
        beforeSend(message) {
            message.metadata = {
                any: 'info'
            };

            return message;
        }
    }
});

beforePostbackSend

The beforePostbackSend delegate method allows you to modify properties of a postback before sending it to HumaneChat.
The modified postback must be returned for it to take effect.

HumaneChat.init({
   appId: '<app-id>',
   delegate: {
       beforePostbackSend(postback) {
           postback.metadata = {
               any: 'info'
           };

           return postback;
       }
   }
});

onInvalidAuth

The onInvalidAuth delegate notifies the delegate of a failed request due to invalid credentials and allows the implementer to set a new auth token in order to retry the request. The delegate must return a new JWT token as a string or Promise<string> that will resolve into the JWT.

Smooch.init({
    appId: '<app-id>',
    delegate: {
        onInvalidAuth() {
            return '<my-new-auth-token>';
        }
    }
});

Events

If you want to make sure your events are triggered, try to bind them before calling HumaneChat.init.

To bind an event, use HumaneChat.on(<event name>, <handler>);. To unbind events, you can either call HumaneChat.off(<event name>, handler) to remove one specific handler, call HumaneChat.off(<event name>) to remove all handlers for an event, or call HumaneChat.off() to unbind all handlers.

ready

// This event triggers when init completes successfully... Be sure to bind before calling init!
HumaneChat.on('ready', function(){
    console.log('the init has completed!');
});

HumaneChat.init(...).then(function() {
    // Your code after init is complete
});

destroy

// This event triggers when the widget is destroyed.
HumaneChat.on('destroy', function(){
    console.log('the widget is destroyed!');
});

HumaneChat.destroy();

message:received

// This event triggers when the user receives a message
HumaneChat.on('message:received', function(message, data) {
    console.log(`The user received a message in conversation ${data.conversation._id}: `, message);
});

message:sent

// This event triggers when the user sends a message
HumaneChat.on('message:sent', function(message) {
    console.log('the user sent a message', message);
});

message

// This event triggers when a message was added to the conversation
HumaneChat.on('message', function(message) {
    console.log('a message was added to the conversation', message);
});

unreadCount

// This event triggers when the number of unread messages changes
HumaneChat.on('unreadCount', function(unreadCount) {
    console.log('the number of unread messages was updated', unreadCount);
});

widget:opened

// This event triggers when the widget is opened
HumaneChat.on('widget:opened', function() {
    console.log('Widget is opened!');
});

widget:closed

// This event triggers when the widget is closed
HumaneChat.on('widget:closed', function() {
    console.log('Widget is closed!');
});

connected

// This event triggers when an active connection has been established for the first time,
// or when the connection has been re-established after a `disconnect` event.
HumaneChat.on('connected', function(e) {
    console.log('Connected');
});

disconnected

// This event triggers when an active connection is lost
// While disconnected, the client will not be able to recieve messages
HumaneChat.on('disconnected', function(e) {
    console.log('Disonnected');
});

typing:start

// This event triggers when appMaker starts typing
HumaneChat.on('typing:start', function() {
    console.log('appMaker starts typing!');
});

typing:stop

// This event triggers when appMaker stops typing
HumaneChat.on('typing:stop', function() {
    console.log('appMaker stops typing!');
});

Embedded mode

As describe above, to activate the embedded mode, you need to pass embedded: true when calling HumaneChat.init. By doing so, you are disabling the auto-rendering mechanism and you will need to call HumaneChat.render manually. This method accepts a DOM element which will be used as the container where the widget will be rendered.

HumaneChat.init({
    appId: '<app-id>',
    embedded: true
});

HumaneChat.render(document.getElementById('chat-container'));

The embedded widget will take full width and height of the container. You must give it a height, otherwise, the widget will collapse.

Authenticating the user: init() vs login()

For authenticated user scenarios, a user's credentials can be passed in to either init() or login(). The question remains: when should you use which?

When init() is called without a userId and jwt, the UI will be initialized in an anonymous user context, and the user will be able to send messages as an anonymous user. After init() has completed, login() may be called to authenticate the user and resume any existing conversation. This is useful if you want your users to be able to send messages before they've logged in to your website. Once a user does login and the browser is issued a valid jwt, login() may be called so that the user may continue the conversation in an authenticated session.

If however your use case requires that all users be logged in before they may send messages, then you should consider passing userId and jwt directly to the init() call upfront.

Content Security Policy

If your deployment requires CSP compatibility, add the following meta tag to your configuration.

<meta http-equiv="Content-Security-Policy" content="
    connect-src
        wss://*.{{YOUR_DOMAIN_NAME}}
        https://*.{{YOUR_DOMAIN_NAME}};
    font-src
        https://*.{{YOUR_DOMAIN_NAME}};
    script-src
        https://*.{{YOUR_DOMAIN_NAME}};
    style-src
        https://*.{{YOUR_DOMAIN_NAME}};
    img-src
        blob:
        https://*.{{YOUR_DOMAIN_NAME}};">

Note that an equivalent configuration can be done server side.

According to the channels you use, other domains may need to be added (these are used to display QR codes to link the Web Messenger conversation):

• LINE: https://qr-official.line.me
• WeChat: https://mp.weixin.qq.com
• WhatsApp: https://wa.me

Note that your CSP configuration should also include any domains used to host images or files sent in messages.
If you require blob: to be excluded for img-src, you must disable the image upload feature via the init settings.

Acknowledgements

https://github.com/lipis/flag-icon-css