Creating and Managing Apps

Smooch apps act as interfaces for individual business to communicate over messaging channels like Facebook Messenger, SMS and the Smooch Web Messenger. A single Smooch app aggregates communication with appUsers over any number of channels and delivers messages to and from those users via the REST API and webhooks.

You don’t have to manage your Smooch apps through the dashboard UI. Smooch offers a series of account provisioning APIs that can be used to create and manage apps programmatically.

Creating an App

Creating an app requires an account scoped JWT - this can either be signed with a user account key, or a service account key. To create an app, use the create app endpoint, supplying your JWT in the Authentication header, and a name for your app in the request body.

curl https://api.smooch.io/v1.1/apps \
  -X POST \
  -d '{"name": "My App"}' \
  -H 'authorization: Bearer your-service-account-jwt'

The response to the create app request will contain the app’s _id, which can be used to initialize the Web and Mobile SDKs, and is also used to reference the app in other API paths.

Configuring Webhooks

To create a webhook for a given app, call the create webhook endpoint, specifying the target URL of your server, and optionally a list of triggers to subscribe to.

curl https://api.smooch.io/v1.1/apps/55c8d9758590aa1900b9b9f6/webhooks \
  -X POST \
  -d '{"target": "https://my-server.some-domain.com/path/to/my/handler"}' \
  -H 'authorization: Bearer your-service-account-jwt'

When specifying a target URL, Smooch will make a HTTP HEAD request to the provided domain in order to verify that the domain exists and that there is a service running.

For example, if you specify a target URL of https://my-server.some-domain.com/path/to/my/handler, Smooch will issue the following request and parse the response:

curl -I https://my-server.some-domain.com

Generating an App Scoped JSON Web Token (JWT)

If your software needs to distribute credentials that give access to an app, you can use the app keys APIs to manage the list of secret keys for an app. Similar to creating an app, an account scoped JWT is required to manage an app’s secret keys. To create an app key, simply call the create key API and specify a name for the key:

curl https://api.smooch.io/v1.1/apps/55c8d9758590aa1900b9b9f6/keys \
  -X POST \
  -d '{"name": "My Key"}' \
  -H 'authorization: Bearer your-account-jwt'

Once an app has a secret key pair, you can use the returned key _id and secret to sign a JWT and distribute it to any user or service that requires access to your app’s data. Here is an example of how to create a JWT in Node.js:

const jwt = require('jsonwebtoken');

const KEY_ID = 'app_5735dcf248011972d621dc01';
const SECRET = 'Y4SINFtAUzEjayxgUjJZoTjG';

const signJwt = function() {
    return jwt.sign({
        scope: 'app'
    },
    SECRET,
    {
        header: {
            kid: KEY_ID,
            typ: 'JWT',
            alg: 'HS256'
        }
    });
}

Alternatively, you can use the get app JWT API to generate an app JWT for a given secret key pair.

Integrating Messaging Channels

Now that you have prepared your app, the next step is to add messaging channels. See the Configuring Messaging Channels guide.