Install libraries we'll use in this tutorial

This walkthrough makes use of a few common libraries in order to teach you the ropes.

npm install smooch-core express body-parser

This will lay the foundation for what we're building today.

To make sure you've got everything you need, open up your terminal and navigate to the directory you'll be working from.

Once there, copy/paste:

Access the Smooch API

Open a separate tab in your browser and go to your Smooch account settings page, then click on Generate API Key.


Let's get started.

Access the Smooch API

Enter your Account Secret Key:

Key ID



Access the Smooch API

Next, launch node in a terminal window and copy/paste this line:

const Smooch = require("smooch-core");

This brings the NodeJS library for the Smooch API into your environment

Then copy/paste this:

const smooch = new Smooch({
    				    keyId: "",
    				    secret: "",
    				    scope: “account”

Here we instantiate the Smooch NodeJS library with the credentials we copied from the UI. Behind the scenes, this method generates a JWT  that Smooch will validate.


Create an App

An app contains a set of messaging channel integrations as well as any associated end-user profile and conversation data.


if you are working with a free Smooch Account, and already have an app created, you may need to delete the already created app through the settings page to be able to create a new app in this tutorial as each account has a limit of only one app. Alternatively, you can create a new account .


You’ll need to create an "App" in Smooch for each separate business using your software.

Create an App

Create your first Smooch App by copying and pasting this into your node environment:

  name: 'Smooch Demo'
}).then((response) => {
  console.log('App ID: ' +;

The response to the create app request will contain your app's id, which will be used in subsequent API calls. Paste it here:

App ID


Integrate a channel

Smooch allows your software to connect to a variety of messaging channels.

Let’s connect to Web Messenger, for simplicity’s sake. This will add a web chat widget directly to this tutorial.


Integrate a channel

You'll need to call the Integrations API to connect your app to a messaging channel, in this case, Web Messenger.

    smooch.integrations.create('', {
            type: 'web',
            businessName: 'Smooch Interactive Walkthrough',
            brandColor: '00ff00'
        }).then((response) => {
            console.log("integration ID: " + response.integration._id)

Paste in your integration ID:


Copy/Paste this into your node environment to configure the messaging channel and return an integration ID.:

Prepare to receive a message

So far, we’ve configured Smooch to connect to a messaging channel but we're not ready to start receiving messages just yet. Let's write some code to process new messages as they are received.

const express = require('express');
const bodyParser = require('body-parser');
const Smooch = require('smooch-core');
const smooch = new Smooch({
  keyId: '',
  secret: '',
  scope: 'account'

const app = express();
app.use(bodyParser.json());'/webhook', function(req, res) {
console.log('Webhook PAYLOAD:\n', JSON.stringify(req.body, null, 3));

const appUserId = req.body.appUser._id;
console.log('AppUser ID: ' + appUserId);

app.listen(3000, () => {
console.log(`App listening on port 3000`);

Fire up a text editor and create a new Javascript file. Paste the code on left inside.


This code listens on port 3000 for new messages from Smooch. When it receives a message, it will print the webhook payload and the AppUser ID to the console.

Once you've pasted the code into your new file, save it , open a new terminal window and run the script with node leaving the service running an listening on port 3000.


 Receiving Webhook Events

In order to receive notifications about new messages and other events from the Smooch platform, we need to make sure that our dev machine can be accessed from the Internet.

Most of the time, this means using a tool like ngrok to create a tunnel between a port on your machine and the Internet. To set this up, simply run the following command in a new terminal window and keep the terminal window open, we’ll be needing it!

ngrok http 3000

Once you've run the command, paste the URL it generated here:

Create a webhook

A webhook can subscribe to multiple trigger events , including read receipts, typing indicators and message delivery success or failure.


In order to receive notifications about new messages and other events from the Smooch platform, we need to make sure that our dev machine can be accessed from the Internet.


Webhooks are essential for receiving messages in Smooch.


Create a webhook

Let's create a webhook to allow your software to receive messages from an "AppUser", or the end-users communicating with a business.

    target: “”,
    triggers: [ “message:appUser” ]

The response will include a secret, which can be used to verify the authenticity of the caller.

Copy/Paste the webhook ID here:



Receive a message

Once you've configured an integration via the API, messages will be able to flow over the channel to your Smooch App.

Since we've just integrated the embeddable Smooch Web Messenger, let's add it to this page.

Once you've completed this, click the 👉 icon to move to the next step.


Receive a message

Now that your app is running, use the Web Messenger on this page👇 to send a message and see the data that your application receives.

In the terminal window running your js code, you'll see that a message was received from an "AppUser" (in this case, you) via Web Messenger, along with a bunch of useful metadata.

Notice that Smooch has generated a unique user ID so we can recognize you across different channels and devices.

Paste the AppUser ID you received here and validate it in order to continue:

Send a reply

Reply to your message using the API by pasting this into your node terminal window:

smooch.appUsers.sendMessage(, , {
    text: “Hello from the other side",
    role: “appMaker",
    type: “text”

Notice how simple the code above is. We’re sending a message without specifying the channel it’s to be delivered on, only the message content! As you dive deeper with Smooch and add support for more channels and features, you’ll be able to do so without changing any of the code that sends/receives messages.


Don't leave yourself hanging.

Congrats! You've mastered the basics of Smooch.

You're ready to go further down the rabbit hole.

Take a look at some of these videos to get inspired by what's possible with Smooch


Or get started digging deeper with our guides  and API reference