Web Messenger

The Web Messenger is a highly customizable messaging widget that can be added to any Web page. Smooch offers a hosted version of the widget. It’s also possible to self-host the widget and fork it to change the appearance, branding, and/or functionality of the widget to suit your needs.

The Smooch Web Messenger is unique in that it allows you to seamlessly move the conversation beyond the browser session to a persistent channel like SMS, Facebook Messenger, or any of our other OTT channels.

Reference

Adding Smooch to your site

Web Messenger's UI

There are a few ways you can include the Smooch Web Messenger on your web page.

The easiest way to get started is using the Script Tag method, but you can also include it using npm.

Script Tag Method

Step 1: Include the Smooch Web Messenger on your web page

Add the following code towards the end of the head section on your page and replace <app-id> with your app ID found in your app settings page.

<script>
    !function(e,n,t,r){
        function o(){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 s,p,a,i=[],c=[];e[t]={init:function(){s=arguments;var e={then:function(n){return c.push({type:"t",next:n}),e},catch:function(n){return c.push({type:"c",next:n}),e}};return e},on:function(){i.push(arguments)},render:function(){p=arguments},destroy:function(){a=arguments}},e.__onWebMessengerHostReady__=function(n){if(delete e.__onWebMessengerHostReady__,e[t]=n,s)for(var r=n.init.apply(n,s),o=0;o<c.length;o++){var u=c[o];r="t"===u.type?r.then(u.next):r.catch(u.next)}p&&n.render.apply(n,p),a&&n.destroy.apply(n,a);for(o=0;o<i.length;o++)n.on.apply(n,i[o])};var u=new XMLHttpRequest;u.addEventListener("load",o),u.open("GET","https://"+r+".webloader.smooch.io/",!0),u.responseType="json",u.send()
    }(window,document,"Smooch","<app-id>");
</script>

Step 2: Initialize Smooch with your new app ID

Once Smooch has been included on your web page, you’re almost done. Simply initialize the Web Messenger using this code snippet

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

npm and browserify/webpack

npm install smooch

In your code:

var Smooch = require('smooch');

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

Login with userId and JWT

After Smooch has initialized your user can start sending messages right away. These messages will show up on the business side under a new Smooch appUser. However, these appUsers will not yet be associated to any user record you might have in an existing user directory.

If your application has a login flow, or if a user needs to access the same conversation from multiple devices, this is where the login method comes into play. You can associate Smooch users with your own user directory by assigning them a userId. You will then issue each user a jwt credential during the login flow. You can read more about this in the Authenticating users section.

Continuing the conversation

Web Messenger allows users to continue a conversation on the messaging app of their choosing. After sending their first message, they will be prompted to be notified inside other apps when they get a reply. This takes pressure off of the business to reply instantly and allows the user to close their browser session without having to worry about missing a response.

Be Notified Inside Other Apps

For example, if a user visits your site and would like to close the tab, they can choose to ‘Connect’ to Messenger. This will connect their conversation to Facebook Messenger and enable notifications there.

Send to Messenger

When you reply to your user, Smooch will intelligently detect which messaging channel they most recently used and make sure they don’t get spammed with push notifications if they elect to be notified on multiple apps.

The current supported list of notifiable channels is as follows:

  • Facebook Messenger
  • Twilio
  • MessageBird
  • Mailgun
  • WeChat
  • Telegram
  • Viber

In order to offer these channels, simply integrate any you want and they will be added to the list by default. You may also edit that list through the Update Integration endpoint.

Getting notified by email

Be Notified By Email

In order to maintain the privacy and security of your user’s conversations, when an app user chooses to be notified over email Smooch will create a separate, isolated client for that email thread. Only future replies to that email thread will be added to that conversation. This mitigates the danger of a malicious user attempting to claim ownership of someone else’s address.

The email to conversation mapping follows this logic:

If a user emails your business:

  • Future emails from that address (regardless of thread) will be routed to the same conversation

If you link a given app user to an address via the linking API:

  • Future emails from that address (regardless of thread) will be routed to the same conversation

If a user opts in to continue their conversation over email:

  • Future emails sent from the notification email thread will be routed to the same conversation
  • Future emails sent from that address in a new thread will be routed to a new conversation

Customization

Embedded mode

To embed the widget in your existing markup, you need to pass embedded: true when calling Smooch.init. By doing so, you are disabling the auto-rendering mechanism and you will need to call Smooch.render manually. This method accepts a DOM element which will be used as the container where the widget will be rendered.

Smooch.init({
    appId: '<app-id>',
    embedded: true
}).then(function() {
    // Your code after init is complete
});


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

Strings customization

Smooch lets you customize any strings it displays by overwriting its keys. Simply add the customText key in your Smooch.init() call and specify new values for the keys used in Smooch. You can find all available keys here. If some text is between {}, or if there is an html tag such as <a>, it needs to stay in your customized text.

For example:

Smooch.init({
    appId: '<app-id>',
    customText: {
        headerText: 'How can we help?',
        inputPlaceholder: 'Type a message...',
        sendButtonText: 'Send'
    }
}).then(function() {
    // Your code after init is complete
});

Date localization

When using strings customization to translate the interface, you will also want to have Web Messenger show the date and time in the right language. To do this, simply pass locale at initialization time. You might also want to override the timestamp format to match your language. You can learn more about formats here.

Smooch.init({
    appId: '<app-id>',
    locale: 'fr-CA'
    customText: {
        // ...
        conversationTimestampHeaderFormat: 'Do MMMM YYYY, hh:mm',
        // ...
    }
}).then(function() {
    // Your code after init is complete
});

Styling the Conversation Interface

The Web Messenger settings page allows for customization of various fields. You may also style your Conversation Interface through the Update Integration endpoint.

Web Messenger Settings

Display Style

The Web Messenger can be displayed as a button or as a tab. You can select the style in the web settings of the Smooch dashboard. The default style is the button mode.

With the button style Web Messenger, you have the option of selecting your own button icon. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format.

Color Customization

For customization of colors, you can set the Brand Color, Conversation Color and Action Color in the web settings of the Smooch dashboard.

  • The Brand Color customizes the color of the messenger header. It is also used for the color of the button or tab in idle state, as well as the color of the default app icon. If no color is specified, the brand color will default to #65758e.
  • The Conversation Color customizes the color of customer messages and actions in the footer. If no color is specified, the conversation color will default to #0099ff.
  • The Action Color changes the appearance of links and buttons in your messages. It is also used for the ‘Send’ button when it is in active state. If no color is specified, the action color will default to #0099ff.
Color Customization

Sound notification

By default, a sound notification will be played when a new message comes in and the window is not in focus.

To disable this feature, you need add the soundNotificationEnabled option to the Smooch.init call, like this:

Smooch.init({
    appId: '<app-id>',
    soundNotificationEnabled: false // Add this line to your 'Smooch.init' call
}).then(function() {
    // Your code after init is complete
});