The Smooch Javascript SDK will add live web messaging to your website or web app.
JavaScript CSS HTML
Failed to load latest commit information.
config/default fix jumpy input - needs refactoring Mar 8, 2016
dev-server Better packaging for npm (#261) May 30, 2016
release_notes Fix image upload (#456) Jan 2, 2017
src Release v3.9.3 [ci skip] Jan 3, 2017
test Fix round corners for single message (#454) Dec 22, 2016
webpack/lib fix all files according to new linting rules Mar 10, 2016
.babelrc added defaultProps to message component Jan 26, 2016
.csscomb.json made notification close hander surface bigger Jul 23, 2015
.esformatter copy over config files Mar 10, 2016
.eslintignore Add flag selector to twilio channel (#315) Aug 12, 2016
.eslintrc Improve test suite (#312) Jul 12, 2016
.gitignore Vendor in blueimp-load-image and add browser directive for Faye (#384) Aug 30, 2016
.npmignore Better packaging for npm (#261) May 30, 2016
.npmrc fix versions and add .npmrc Mar 9, 2016
Gruntfile.js Externalize assets (#9) Jun 14, 2016
LICENSE fix LICENSE in pkg.json, update karma-webpack config, update some dep… Feb 21, 2016 Define standard npm dev scripts (#450) Dec 19, 2016
bower.json Release v3.9.3 [ci skip] Jan 3, 2017
circle.yml Auto deploy integration to staging website (#326) Jul 26, 2016
karma.conf.js fix LICENSE in pkg.json, update karma-webpack config, update some dep… Feb 21, 2016
make-webpack-config.js Fix assets file for npm build (#398) Sep 26, 2016
package.json Release v3.9.3 [ci skip] Jan 3, 2017
smooch-js.sublime-project Add sublime-project file Jan 20, 2016
webpack-assets.config.js Fix npm assets in build process (#287) Jun 22, 2016
webpack-dev-server.config.js added webpack config stuff, started to work on test setup Nov 30, 2015
webpack-hot-dev-server.config.js added webpack config stuff, started to work on test setup Nov 30, 2015
webpack-production.config.js fix merge leftovers Dec 15, 2015
webpack-staging.config.js Auto deploy integration to staging website (#326) Jul 26, 2016
webpack-test.config.js added webpack config stuff, started to work on test setup Nov 30, 2015
webpack.config.js added webpack config stuff, started to work on test setup Nov 30, 2015

Smooch Web Messenger

Circle CI npm version Bower version

Smooch is the best way to have personal, rich conversations with people on your website or customers on any device. Our features, integrations and developer-friendly APIs empower companies to connect with their customers in a whole new way.

The Smooch Web Messenger will add live web messaging to your website or web app. Customers will be able to talk to you from your website, while you manage conversations using your favorite business systems.

  • Let your customers talk to you the way they want by seamlessly moving web chat conversations to any messaging app.
  • Sync conversations across every device and channel your customers use.
  • Build better relationships with messaging that feels and looks tailored to your website.
  • Delight your customers with the most engaging conversational experience using rich messaging.
  • Maximize development productivity with a single codebase across platforms and add more channels anytime.
  • Bring every conversation into your existing business systems. No new tool to learn. See all integrations.


Script Tag

Add the following code towards the end of the body section on your page. Placing it at the end allows the rest of the page to load first.

<script src=""></script>

Initialize the plugin using this code snippet

    Smooch.init({appToken: 'your_app_token'});

Browserify and Webpack

Install from npm

npm install --save smooch

// The library also has peer dependencies. If you don't already have them in your project, go ahead and install them too

npm install --save babel-polyfill@6.9 babel-runtime@6.9 react@15 react-dom@15

Require and init

var Smooch = require('smooch');

Smooch.init({appToken: 'your_app_token'});

Notes about Webpack

If you are building an isomorphic app, make sure you init the widget in client code only. It currently won't work on the server side. You'll also need to add the following to your plugins since iconv-loader doesn't work very well with webpack :

new webpack.NormalModuleReplacementPlugin(/\/iconv-loader$/, 'node-noop')

You will need to install node-noop in your project. See

Notes about Angular 2

Some users reported that including the Smooch Web Messenger script in their Angular 2 app would cause some problems. The workaround for that is to add it after all your scripts.


Install from bower

bower install smooch

Include in JS using preferred method and init

Smooch.init({appToken: 'your_app_token'});


Individual functions


Initializes the Smooch widget in the web page using the specified options. It returns a promise that will resolve when the widget is ready.

Option Optional? Default value Description
appToken No - Your app token
givenName Yes - User's given name
surname Yes - User's surname
email Yes - User's email
jwt Yes - Token to authenticate your communication with the server (see
userId Yes - User's id
properties Yes - An object with all properties you want to set on your user
emailCaptureEnabled Yes false Deprecated won't be supported in 4.x - Enables prompt for email after the first user's message. You can retrieve that email in Slack using /sk !profile. Forced to false if other messaging channels are enabled in your Smooch app
soundNotificationEnabled Yes true Enables the sound notification for new messages
imageUploadEnabled Yes true Enables the image upload feature.
embedded Yes False Tells the widget it will be embedded. (see Embedded section below)
customText Yes See the example below Strings used in the widget UI. You can use these to either customize the text or translate it. If something is between {}, it's a variable and needs to stay in your customized text if you want to use it.
var skPromise = Smooch.init({
    appToken: 'your_app_token',
    givenName: 'Cool',
    surname: 'Person',
    email: '',
    // For secure mode
    jwt: 'your_jwt',
    userId: 'user_id',
    // Additional properties
    properties: {
        'anything': 'whatever_you_want'    
    customText: {
        headerText: 'How can we help?',
        inputPlaceholder: 'Type a message...',
        sendButtonText: 'Send',
        introductionText: 'We\'re here to talk, so ask us anything!',
        introAppText: 'Message us below or from your favorite app.',
        settingsText: 'You can leave us your email so that we can get back to you this way.',
        settingsReadOnlyText: 'We\'ll get back to you at this email address if we missed you.',
        settingsInputPlaceholder: 'Your email address',
        settingsSaveButtonText: 'Save',
        settingsHeaderText: 'Settings',
        settingsNotificationText: 'In case we\'re slow to respond you can <a href data-ui-settings-link>leave us your email</a>.',
        actionPaymentError: 'An error occurred while processing the card. <br> Please try again or use a different card.',
        actionPaymentCompleted: 'Payment Completed',
        actionPostbackError: 'An error occurred while processing your action. Please try again.',
        messageError: 'An error occured while sending your message. Please try again.',
        invalidFileError: 'Only images are supported. Choose a file with a supported extension (jpg, jpeg, png, gif, or bmp).',
        messageIndicatorTitleSingular: '({count}) New message',
        messageIndicatorTitlePlural: '({count}) New messages',
        connectNotificationText: 'Be notified inside your other apps when you get a reply.',
        notificationSettingsChannelsTitle: 'Other Channels',
        notificationSettingsChannelsDescription: 'You can also talk to us from your favorite app or service.',
        notificationSettingsConnectedAs: 'Connected as {username}',
        notificationSettingsConnected: 'Connected',
        wechatQRCodeError: 'An error occurred while fetching your WeChat QR code. Please try again.',
        messengerChannelDescription: 'Connect your Facebook Messenger account to be notified when you get a reply and carry the conversation on Facebook Messenger.',
        frontendEmailChannelDescription: 'To talk to us using email just send a message to our email address and we\'ll reply shortly:',
        smsChannelDescription: 'To talk to us using SMS, just send a text message to this number from your favorite SMS app:',
        smsChannelPendingDescription: 'Check your messages at {number} to confirm your phone number.',
        telegramChannelDescription: 'To talk to us using Telegram, add our bot:',
        wechatChannelDescriptionMobile: 'To send us a message from WeChat, save this QR code image and upload it in the <a href=\'weixin://dl/scan\'>QR code scanner</a>.',
        wechatChannelDescription: 'To send us a message from WeChat, scan this QR code using the WeChat app.',
        lineChannelDescription: 'To talk to us using LINE, scan this QR code using the LINE app and send us a message.',
        smsTooManyRequestsError: 'A connection for that number was requested recently. Please try again in {seconds} seconds.',
        smsBadRequestError: 'We were unable to communicate with this number. Try again or use a different one.',
        smsUnhandledError: 'Something went wrong. Please try again.',
        smsPingChannelError: 'There was an error sending a message to your number.'

skPromise.then(function() {
    // do something

// pass it around...

skPromise.then(function() {
    //do something else


Opens the conversation widget (noop when embedded);


Closes the conversation widget (noop when embedded)



Tells if the widget is currently opened or closed.


login(userId [, jwt] [, attributes])

Logs a user in the widget, retrieving the conversation that user already had on other browsers and/or devices. This will destroy and reinitialize the widget with the user's data. Note that you don't need to call this after init, it's already done internally. This returns a promise that resolves when the widget is ready again.


// in case you are using the jwt authentication
Smooch.login('some-id', 'some-jwt');

// in case you want to update user attributes at the same time
Smooch.login('some-id', { email: ''});

// in case you want to update user attributes at the same time and use jwt
Smooch.login('some-id', 'some-jwt', { email: ''});


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



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



Sends a message on the user's behalf



Updates user information

    givenName: 'Updated',
    surname: 'Name',
    email: '',
    properties: {
      'justGotUpdated': true


Returns the userId of the current user.



Returns promise that resolves to conversation object, or rejects if none exists

Smooch.getConversation().then(conversation => ...);


Tracks an event for the current user.



Returns an instance of smooch-core to allow access to APIs the Web Messenger doesn't expose. For more information on how to use Smooch-Core, please visit the documentation.


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

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


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



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



// This event triggers when the user receives a message
Smooch.on('message:received', function(message) {
    console.log('the user received a message', message);


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


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


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


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

Embedded mode

As describe above, to activate the embedded mode, 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.

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

How to contribute

Clone the git repo

git clone

Install Node.js and run the following

npm install

In one console, run npm run dev to start the web server. In another, run npm run webpack to start the webpack dev server.

Then, go to http://localhost:8282 to test the normal widget or http://localhost:8282/embedded for the embedded one.