Web Messenger

The Smooch Web Messenger is a highly customizable messaging widget that can be added to any web page. Web Messenger is unique in that it allows the user seamlessly move the conversation beyond the browser to a persistent channel like SMS, Facebook Messenger, or any other OTT channels.

Current version: v

Capabilities

The Web Messenger supports a wide variety of capabilities as seen in the channel capabilities grid. Below is a detailed view of each capabilities.

Content Types

  • Text

    Full SupportAPI
  • Image

    Full SupportAPI
  • File

    Full SupportAPI
  • Emoji

    Full SupportAPI
  • GIF

    Partial SupportAPI
  • Location

    Partial SupportAPI

Action Types

  • Link

    Full SupportAPI
  • Extensions

    Full SupportAPI
  • Buy

    Full SupportAPI
  • Postback

    Full SupportAPI
  • Replies

    Full SupportAPI
  • Location Request

    Full SupportAPI

Structured Messages

  • Compound Messages

    Full SupportAPI
  • Carousel

    Full SupportAPI

Indicators

  • Typing

    Full SupportAPI
  • Read

    Full SupportAPI
  • Conversation Start

    Full SupportAPI

Delivery Events

Delivery events allow you to track deliveries of Smooch messages to the Web Messenger by subscribing to the message:delivery:channel webhook.

Carousels are rendered natively with full functionality in the Web Messenger. See our API documentation for instructions on how to send one.

Carousel web

Carousels support up to a maximum of 10 message items. Each message item must include a title and at least one supported action. Optionally, an image and description can be included as well. Images can be displayed in two different aspect ratios, “square” and “horizontal”. For more information, see our API documentation.

Carousel items with “horizontal” images (default):

Carousel Web horizontal

Carousel items with “square” images:

Carousel Web square

Supported actions

The Web Messenger supports the following action types in a carousel message item:

  • Link
  • Postback
  • Buy
  • Webview

List message fallback

If the Web Messenger receives a list type message, it will display a carousel instead.

Moving to other channels

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

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.

Browser support

Web Messenger supports all popular browsers.

Desktop

  • 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

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

Installation

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.

Region configuration

Web messenger is supported in the following regions:

RegionRegion identifier
United StatesLeave unspecified
European Unioneu-1

To target the EU region for example the region identifier is passed to Smooch.init():

<script>
    Smooch.init({ 
      appId: '<app-id>', 
      region: 'eu-1'
    })
        .then(
            function() {
                // Your code after init is complete
            },
            function(err) {
                // Something went wrong during initialization
            }
        );
</script>

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
            },
            function(err) {
                // Something went wrong during initialization
            }
        );
</script>

NPM method

npm install smooch

In your code:

var Smooch = require('smooch');

Smooch.init({ appId: '<app-id>' })
    .then(
        function() {
            // Your code after init is complete
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

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.

Files

The Web Messenger has full native support for sending and receiving files. See our API documentation for instructions on how to send one.

Customization

The Web Messenger includes a set of built-in customization options which you can leverage in 3 ways:

  • Via the Update Integration API.
  • Using the Smooch dashboard to manually set styling options in the Web messenger settings page.
  • Passing in styling settings in the call to the Smooch.init method.

Embedded mode

Supported by the Smooch.init method.

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
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

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

Strings customization

Supported by the Smooch.init method.

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
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Date localization

Supported by the Smooch.init method.

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
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Display Style

Supported by the Smooch.init method, the Web Messenger settings page in the dashboard, and the Update Integration API.

The Web Messenger can be displayed as a button or as a tab. The default style is the button mode.

When the display style is a button, 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.

Smooch.init

Specify the displayStyle and buttonIconUrl in the call to Smooch.init.

Smooch.init({
    appId: '<app-id>',
    // ...
    displayStyle: "button",
    buttonIconUrl: "https://myimage.png"
    // ...
})
    .then(
        function() {
            // Your code after init is complete
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Button Size

Supported by the Smooch.init method, and the Update Integration API.

You can customize the size of the button by setting a buttonWidth and buttonHeight. When not provided, the button will have a default size of 58 x 58 pixels.

Smooch.init

Specify the buttonWidth and buttonHeight in the call to Smooch.init.

Smooch.init({
    appId: '<app-id>',
    // ...
    buttonWidth: '90',
    buttonHeight: '90'
    // ...
})
    .then(
        function() {
            // Your code after init is complete
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Fixed Intro

Supported by the Smooch.init method, and the Update Integration API.

You can set the introduction pane to fixed mode by setting fixedIntroPane to true. When set, the pane will be pinned at the top of the conversation instead of scrolling with it. The default value is false.

Default
Fixed

Smooch.init

Smooch.init({
    appId: '<app-id>',
    // ...
    fixedIntroPane: true
    // ...
})
    .then(
        function() {
            // Your code after init is complete
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Colors

Supported by the Smooch.init method, the Web Messenger settings page in the dashboard, and the Update Integration API.

The supported color customizations are:

  • 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

Smooch.init

Smooch.init({
    appId: '<app-id>',
    // ...
    customColors: {
        brandColor: "7af442",
        conversationColor: "b7b7b5"
        actionColor: "191919"
    }
    // ...
})
    .then(
        function() {
            // Your code after init is complete
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Business profile

Supported by the Smooch.init method, and the Update Integration API.

You can customize your business branding with the businessName and businessIconUrl settings. For the businessIconUrl setting, the image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format.

Web Messenger Business Branding

Smooch.init

Smooch.init({
    appId: '<app-id>',
    // ...
    businessName: "Acme Corporation",
    businessIconUrl: "https://is2-ssl.mzstatic.com/image/thumb/Purple127/v4/67/a4/5b/67a45b68-c821-842f-22f5-9fa83b605ce3/mzl.evidoiah.jpg/1200x630bb.jpg"
    // ...
})
    .then(
        function() {
            // Your code after init is complete
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Background Image

Supported by the Smooch.init method, and the Update Integration API.

You can customize the background image in your SDK with the backgroundImageUrl setting. The image will be displayed at its full size, and tiled if it is not large enough to fill the conversation.

For reference, the following CSS will be used to display the background:

{
    background-image: url("https://a-nice-texture.png")
}

Web Messenger Business Branding

Smooch.init

Smooch.init({
    appId: '<app-id>',
    // ...
    backgroundImageUrl: "https://a-nice-texture.png"
    // ...
})
    .then(
        function() {
            // Your code after init is complete
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Sound notification

Supported by the Smooch.init method.

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
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Supported by the Smooch.init method.

The Web Messenger features a menu that allows the user to send various message types. The types displayed in this menu can be customized, or the menu can be hidden altogether.

If you want to control this menu, add the menuItems option to the Smooch.init call:

Smooch.init({
    appId: <app-id>,
    menuItems: {
      imageUpload: true,
      fileUpload: true,
      shareLocation: true
    },
    // ...
})
    .then(
        function() {
            // Your code after init is complete
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Menu Options

To hide the menu completely, override the menuItems option as follows:

Smooch.init({
    appId: <app-id>,
    menuItems: {},
    // ...
})
    .then(
        function() {
            // Your code after init is complete
        },
        function(err) {
            // Something went wrong during initialization
        }
    );

Menu Options

Filtering and transforming messages

The Web Messenger allows you to filter and transform messages by using the beforeDisplay delegate. To set a delegate, use the setDelegate method.

This may be useful if you want to conditionally filter specific messages or transform their structure. See the Message Schema section to learn more on the message properties that you can access and modify. You may also want to set your own properties using the beforeSend delegate.

Filtering messages

The following example sets a beforeDisplay delegate method to check if a message has been marked as archived in the metadata (this can be done using the beforeSend delegate method for example). If the field isArchived is true, we instruct the SDK to hide the message by returning null. If not, we simply return the original message unmodified.

Smooch.setDelegate({
    beforeDisplay(message) {
        if (message.metadata && message.metadata.isArchived) {
            return null;
        }

        return message;
    }
});

Transforming business messages

The following example sets a default author name on messages that lacks one if they are originating from the business. We first check if the message is sent by the appMaker and if a name has been specified. If not, we set it and return the modified message.

Smooch.setDelegate({
    beforeDisplay(message) {
        if (message.role === 'appMaker' && !message.name) {
            message.name = 'Acme Bank';
        }

        return message;
    }
});

Transforming user messages

The following example adds the URL of the page the user is visiting while messaging a business. This can be useful when users navigate within a site while messaging. We first check if the message role is appUser and then add a currentUrl attribute in the metadata property.

Smooch.setDelegate({
    beforeSend(message) {
        if (message.role === 'appUser') {
            message.metadata = {
                ...message.metadata,
                currentUrl: window.location.href
            };
        }

        return message;
    }
});

Whitelisting Domains

By default, the Web Messenger can be initialized from any domain with the use of the appId. To limit domains where Web messenger can be used, you can use the originWhitelist setting in the Update Integration API.

When the originWhitelist is set, Smooch restricts the access to only the origins listed in the array by implementing Cross Origin Resource Sharing (CORS). More specifically, it will look at the Origin header for every HTTP request and block it if the Origin is not part of the originWhitelist array.

Notes:

  • localhost is supported as a valid hostname in the origin, so you can test when doing local development.
  • Wildcard subdomains are not currently supported, so you need to list all of your supported domains individually.

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://*.smooch.io
        https://*.smooch.io;
    font-src
        https://*.smooch.io;
    script-src
        https://*.smooch.io;
    style-src
        https://*.smooch.io;
    img-src
        blob:
        https://*.smooch.io;">

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

This is used to allow buy actions from the Web Messenger:

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.

Implementing your own User Interface

If you need more customization options than those supported natively by Smooch, you can implement a complete custom UI by leveraging events and APIs exposed by the SDK, which will continue to facilitate the connection with the Smooch platform.

Our sample custom UI project covers the first steps you need to follow to get started.