NAV

Core

Introduction

Welcome to the Smooch API. The API allows you to craft entirely unique messaging experiences for your app and website as well as talk to any backend or external service.

Basics

The Smooch API is designed according to REST principles.

The API accepts JSON in request bodies and requires that the content-type: application/json header be specified for all such requests. The API will always respond with a JSON object. Depending on context, resources may be returned as single objects or as arrays of objects, nested within the response object.

The API also facilitates cross-origin resource sharing so that it can be called from a web application.

Errors

401 Unauthorized
{
  "error": {
    "code": "unauthorized",
    "description": "Authorization is required"
  }
}

Smooch uses standard HTTP status codes to communicate errors

200 OK - Everything went as planned.
400 Bad Request - Something in your header or request body was malformed.
401 Unauthorized - Necessary credentials were either missing or invalid.
403 Forbidden - Your credentials are valid but you don’t have access to the requested resource.
404 Not Found - The object you’re requesting doesn’t exist.
409 Conflict - You might be trying to update the same resource concurrently.
429 Too Many Requests - You are calling our APIs more frequently than we allow.
500, 502, 503, 504 Server Errors - Something went wrong on our end.

In addition to the status code, the HTTP body of the response will also contain a JSON representation of the error.

Rate Limits

Smooch APIs are subject to rate limiting. If you exceed the limits, Smooch will start returning a 429 Too Many Requests HTTP status code. We apply rate limits to prevent abuse, spam, denial-of-service attacks, and similar issues. Our goal is to keep the limits high enough so that any application using Smooch as intended will never hit them. However, applications that consistently exceed limits run the risk of being permanently disabled.

Deprecations

The “devices” array returned in the AppUser payload has been changed to “clients”. In order to maintain compatibility, we will keep returning the “devices” array in v1, but in the next version it will be removed.

Authorization

This is an overview of how authorization works with the Smooch API.

Smooch offers two methods for authentication JSON Web Token (JWT) and app token. See below for more details. There are three different scopes of authorization available. These are appUser, app, and appMaker.

Scope Methods Authorized APIs
appUser JWT, appToken Init, App User, Conversations
app JWT Init, App User, Conversations Webhooks, Persistent Menus

The appToken authentication method only allows you to call the API on behalf of users who have not yet been secured by an app user scoped JWT.

JWTs issued with appUser scope grant the caller permission to access that specific user’s data only. Once an app user JWT is used for the first time, the user and their conversation history will transition into secure mode, and from that point onward a JWT will be required for any subsequent API calls pertaining to that user. An appToken will no longer be accepted to access that specific user’s data.

JWTs issued with app scope can be used to access any of the Smooch Core APIs on behalf of the app, or any app user.

Authentication

Smooch APIs offer two methods of authentication:

  1. Using an App Token
  2. Using a JSON Web Token (JWT)

Some APIs accept either of the two authentication methods while others require a jwt credential.

API Valid authentication methods
/v1/appusers jwt, appToken
/v1/init jwt, appToken
/v1/webhooks jwt

App Token

# Calling GET /v1/appusers using an app token
curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'app-token: cr2g6jgxrahuh68n1o3e2fcnt'
// Initializing Smooch Core with an app token
var smooch = new SmoochCore({
    appToken: 'cr2g6jgxrahuh68n1o3e2fcnt'
});

When calling Smooch APIs such as /v1/appusers on behalf of app users, an appToken may be used for basic authentication.

Every Smooch app has an appToken provisioned to it which can be found in the app settings tab. The appToken is sent via the the app-token HTTP header. This will link the caller to a specific Smooch app.

Specifying an appToken alone is sufficient to call any of the app user facing API.

JWT

# Calling GET /v1/appusers using a jwt
curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'authorization: Bearer your-jwt'
// Initializing Smooch Core with a jwt in the browser
var smooch = new SmoochCore({
    jwt: 'your-jwt'
});
// Initializing Smooch Core with a jwt in Node.js
var smooch = new SmoochCore({
    keyId: 'your-key-id',
    secret: 'your-secret',
    scope: 'appUser', // app or appUser
    userId: 'some-id' // not necessary if scope === 'app'
});

JSON Web Tokens (JWTs) are an industry standard authentication mechanism. The full specification is described here, and a set of supported JWT libraries for a variety of languages and platforms can be found at http://jwt.io. To summarize, a JWT is composed of a header, a payload, and a signature. The payload contains information called claims which describe the subject to whom the token was issued.

For added security when making calls on behalf of an app user, a jwt credential can optionally be specified instead of an appToken.

The jwt itself is transmitted via the HTTP authorization header. The token should be prefixed with “Bearer” followed by a space. For example: Bearer your-jwt.

To sign JWTs, you will need to create a secret key in the Smooch dashboard, by going into the Settings tab. Clicking on “Create New Secret Key” will generate a new key id and a secret key pair which you can use to sign JWTs.

JWT header:

{
    "alg": "HS256",
    "typ": "JWT",
    "kid": "b567635f883c819871ace8003c0db14b"
}

The JWT header must contain the key id (kid) of the secret key that is used to sign it. The algorithm (alg) used to sign the JWT can be anything supported by the jsonwebtoken npm module v5.0.4. Unsigned JWTs are not accepted.

JWT payload with appUser scope claim:

{
    "scope": "appUser",
    "userId": "bob@example.com"
}

JWT payload with app scope:

{
    "scope": "app"
}

Scope

The jwt payload must include a scope claim which specifies the caller’s scope of access. There are two levels of scope:

  1. The appUser scope grants access to an individual app user’s data and conversation history, but nothing else. It is used when issuing tokens to individual users. A jwt with appUser scope must also specify a userId which uniquely identifies the appUser being accessed. Node.js code sample

  2. The app scope grants access to all users and conversations within a given Smooch app. The app scope is reserved for server-to-server scenarios, the creation of webhooks for example. Node.js code sample

API Accepted jwt Scopes
/v1/appusers app, appUser
/v1/webhooks app

Webhooks

Webhooks are a fantastic way to extend the Smooch platform beyond the built-in feature set. You can use webhooks to build your own Smooch chat clients, to integrate more deeply with your favorite CRM, or to build a bot.

These webhook APIs require a jwt credential with app level scope. Furthermore, a webhook can only operate within the scope of a single Smooch app.

When a webhook trigger is triggered, a JSON payload will be posted to the URL configured in your webhook object. You can see an example of this payload here.

Create webhook

Request:

curl https://api.smooch.io/v1/webhooks \
     -X POST \
     -d '{"target": "http://example.com/callback"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.webhooks.create({
    target: 'http://example.com/callback'
}).then((response) => {
    // async code
});

Response:

201 CREATED
{
  "webhook": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "triggers": [
      "message"
    ],
    "secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
    "target": "http://example.com/callback"
  }
}

POST /v1/webhooks

Create a webhook for the specified app. The response body will include a secret which will be transmitted with each webhook invocation and can be used to verify the authenticity of the caller.

Alternatively, you can use the Webhooks integration in the Smooch dashboard to easily create a webhook.

Arguments
target
required
URL to be called when the webhook is triggered.
triggers
optional
An array of triggers you wish to have the webhook listen to. If unspecified the default trigger is message. This property is case sensitive. More details.

List webhooks

Request:

  curl https://api.smooch.io/v1/webhooks \
       -H 'authorization: Bearer your-jwt'
smooch.webhooks.list().then((response) => {
    // async code
});

Response:

200 OK
{
  "webhooks": [
    {
      "_id": "55c8d9758590aa1900b9b9f6",
      "triggers": [
        "message"
      ],
      "secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
      "target": "http://example.com/callback"
    }
  ]
}

GET /v1/webhooks

List all webhooks configured for a given app.

Get webhook

Request:

curl https://api.smooch.io/v1/webhooks/55c8d9758590aa1900b9b9f6 \
     -H 'authorization: Bearer your-jwt'
smooch.webhooks.get('55c8d9758590aa1900b9b9f6').then((response) => {
    // async code
});

Response:

200 OK
{
  "webhook": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "triggers": [
      "message"
    ],
    "secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
    "target": "http://example.com/callback"
  }
}

GET /v1/webhooks/{webhookId}

Individual webhooks can be fetched using this API.

Update webhook

Request:

curl https://api.smooch.io/v1/webhooks/55c8d9758590aa1900b9b9f6 \
     -X PUT \
     -d '{"target": "http://example.com/callback"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.webhooks.update('55c8d9758590aa1900b9b9f6', {
    target: 'http://example.com/callback'
}).then((response) => {
    // async code
});

Response:

200 OK
{
  "webhook": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "triggers": [
      "message"
    ],
    "secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
    "target": "http://example.com/callback"
  }
}

PUT /v1/webhooks/{webhookId}

Use this API to update your existing webhooks.

Arguments
target
optional
URL to be called when the webhook is triggered.
triggers
optional
The triggers you wish to have the webhook listen to. The default trigger is message. This property is case sensitive. More details.

Delete webhook

Request:

curl https://api.smooch.io/v1/webhooks/55c8d9758590aa1900b9b9f6 \
     -X DELETE \
     -H 'authorization: Bearer your-jwt'
smooch.webhooks.delete('55c8d9758590aa1900b9b9f6').then(() => {
    // async code
});

Response:

200 OK

DELETE /v1/webhooks/{webhookId}

Deletes the specified webhook.

Webhook triggers

Request:

curl https://api.smooch.io/v1/webhooks
     -X POST \
     -d '{"target": "http://example.com/callback", "triggers": ["message:appUser"]}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.webhooks.create({
    target: 'http://example.com/callback',
    triggers: [
        'message:appUser'
    ]
}).then((response) => {
    // async code
});

A webhook will make a request to the target each time a trigger associated with the webhook occurs. Triggers are specified in an optional triggers array in the request body. If triggers is not specified the webhook will be configured with the message trigger by default.

A webhook with a postback trigger will be fired every time a user clicks on an action button with type postback.

trigger
message
default
all messages
message:appUser only messages with role appUser
message:appMaker only messages with role appMaker or whisper
conversation:read when a user reads a conversation
postback when a user clicks on a postback action
merge:appUser when two or more users are merged into one
delivery:success when a message is successfully delivered to a customer channel
delivery:failure when a message fails to be delivered to a customer channel
* when any of the above triggers occurs

Webhooks payload

Webhook example payload for message, message:appMaker and message:appUser triggers:

{
    "trigger": "message:appUser",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "messages":[{
        "_id": "55c8c1498590aa1900b9b9b1",
        "text": "Hi! Do you have time to chat?",
        "role": "appUser",
        "authorId": "c7f6e6d6c3a637261bd9656f",
        "name": "Steve",
        "received": 1444348338.704,
        "metadata": {},
        "actions": [],
        "source": {
            "type": "messenger"
        }
    }],
    "appUser": {
        "_id": "c7f6e6d6c3a637261bd9656f",
        "userId": "bob@example.com",
        "properties": {},
        "signedUpAt": "2015-10-06T03:38:02.346Z",
        "clients": [
          {
            "active": true,
            "appVersion": "1.0",
            "id": "5A7F8343-DF41-46A8-96EC-8583FCB422FB",
            "lastSeen": "2016-03-09T19:09:01.431Z",
            "platform": "ios",
            "pushNotificationToken": "<...>",
            "info": {
              "appName": "ShellApp",
              "devicePlatform": "x86_64",
              "os": "iPhone OS",
              "osVersion": "9.2"
            }
          }
        ]
    }
}

Webhook example payload for the postback trigger:

{
    "trigger": "postback",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "postbacks":[{
        "message": {
            "_id": "55c8c1498590aa1900b9b9b1",
            "text": "Do you want to see more options?",
            "role": "appMaker",
            "authorId": "c7f6e6d6c3a637261bd9656f",
            "name": "LunchBot",
            "received": 1444348338.704,
            "metadata": {},
            "source": {
                "type": "slack"
            },
            "actions": [{
                "_id": "571530ee4fae94c32b78b170",
                "type": "postback",
                "text": "Yes",
                "payload": "YES"
            }, {
                "_id": "571530ee4fae94c32b78b171",
                "type": "postback",
                "text": "No",
                "payload": "NO"
            }]
        },
        "action": {
            "_id": "571530ee4fae94c32b78b170",
            "type": "postback",
            "text": "Read more",
            "payload": "YES"
        }
    }],
    "appUser": {
        "_id": "c7f6e6d6c3a637261bd9656f",
        "userId": "bob@example.com",
        "properties": {},
        "signedUpAt": "2015-10-06T03:38:02.346Z",
        "clients": [
          {
            "active": true,
            "id": "5A7F8343-DF41-46A8-96EC-8583FCB422FB",
            "lastSeen": "2016-03-09T19:09:01.431Z",
            "platform": "telegram"
          }
        ]
    }
}

Webhook example payload for the postback trigger originating from a menu:

{
    "trigger": "postback",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "postbacks":[{
        "action": {
            "_id": "571530ee4fae94c32b78b170",
            "type": "postback",
            "text": "Read more",
            "payload": "YES"
        }
    }],
    "appUser": {
        "_id": "c7f6e6d6c3a637261bd9656f",
        "userId": "bob@example.com",
        "properties": {},
        "signedUpAt": "2015-10-06T03:38:02.346Z",
        "clients": [
          {
            "active": true,
            "id": "5A7F8343-DF41-46A8-96EC-8583FCB422FB",
            "lastSeen": "2016-03-09T19:09:01.431Z",
            "platform": "telegram"
          }
        ]
    }
}

Webhook example payload for the conversation:read trigger:

{
    "trigger": "conversation:read",
    "app": {
        "_id": "57ec2881c47d2d24b0c16427"
    },
    "source": {
        "type": "messenger"
    },
    "appUser": {
        "_id": "7685787bf0e9e8cf56182288"
    },
    "timestamp": 1480349392.103
}

Webhook example payload for the merge:appUser trigger:

{
    "trigger": "merge:appUser",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "surviving": {
        "_id": "a79a0ecfba3260bf145be257",
        "userId": "123",
        "conversationStarted": true
    },
    "discarded": [{
        "_id": "1ac30dad829178f6378f61f4",
        "conversationStarted": false
    }]
}

Webhook example payload for the delivery:success trigger:

{
    "trigger": "delivery:success",
    "app": {
        "_id": "575040549a38df8fb4eb1e51"
    },
    "appUser": {
        "_id": "de13bee15b51033b34162411",
        "userId": "123"
    },
    "destination": {
        "type": "line"
    },
    "messages": [
        {
            "text": "Hi! Do you have time to chat?",
            "received": 1480001439.637,
            "name": "Danny",
            "role": "appMaker",
            "authorId": "5X8AJwvpy0taCkPDniC5la",
            "avatarUrl": "https://www.gravatar.com/image.jpg",
            "_id": "5837079fd84370ef2c0dcabb",
            "source": {
                "type": "slack"
            },
            "items": [],
            "actions": []
        }
    ],
    "timestamp": 1480001440.731
}

Webhook example payload for the delivery:failure trigger:

{
    "trigger": "delivery:failure",
    "app": {
        "_id": "575040549a38df8fb4eb1e51"
    },
    "appUser": {
        "_id": "de13bee15b51033b34162411",
        "userId": "123"
    },
    "destination": {
        "type": "line"
    },
    "error": {
        "code": "unauthorized",
        "underlyingError": {
            "message": "Authentication failed due to the following reason: invalid token. Confirm that the access token in the authorization header is valid."
        }
    },
    "messages": [
        {
            "text": "Hi! Do you have time to chat?",
            "received": 1480001711.288,
            "name": "Danny",
            "role": "appMaker",
            "authorId": "5X8AJwvpy0taCkPDniC5la",
            "avatarUrl": "https://www.gravatar.com/image.jpg",
            "_id": "583708af8d449209ba217871",
            "source": {
                "type": "slack"
            },
            "items": [],
            "actions": []
        }
    ],
    "timestamp": 1480001711.941
}

When a webhook trigger is triggered, a POST request will be made to the URL configured in your webhook object along with a JSON payload.

The structure of the JSON payload differs based on the trigger of the webhook. On the right, you can see examples of the JSON payload for the different triggers. Postbacks originating from a persistent menu do not have messages associated with them, and so omit the message property.

Securing a webhook

When a webhook is created, a shared secret will be generated for it. The secret can be used to determine the veracity of a request to your webhook route. It is included as an X-API-Key header with each webhook request sent to the target URL.

That secret is available in the response to the POST request used to generate the webhook, or through a GET request to the webhook route.

Retry Policy

If a webhook target responds with anything other than a 2xx status code, or if no response is received within 5 seconds, the call will be reattempted up to 5 times at an exponentially increasing interval.

Init

Request:

curl https://api.smooch.io/v1/init \
     -X POST \
     -d '{"device": {"id": "03f70682b7f5b21536a3674f38b3e220", "platform": "ios", "appVersion": "1.0"}, "userId": "bob@example.com"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.appUsers.init({
    device: {
        id: '03f70682b7f5b21536a3674f38b3e220',
        platform: 'ios',
        appVersion: '1.0'
    },
    userId: 'bob@example.com'
}).then((response) => {
    // async code
});

Response:

200 OK
{
    "app": {
        "hasIcon": true,
        "apnEnabled": true,
        "gcmProject": "731399543244"
    },
    "appUser": {
        "_id": "c7f6e6d6c3a637261bd9656f",
        "userId": "bob@example.com",
        "properties": {},
        "signedUpAt": "2015-10-06T03:38:02.346Z",
        "clients": [
          {
            "active": true,
            "appVersion": "1.0",
            "id": "5A7F8343-DF41-46A8-96EC-8583FCB422FB",
            "lastSeen": "2016-03-09T19:09:01.431Z",
            "platform": "ios",
            "pushNotificationToken": "<...>",
            "info": {
              "appName": "ShellApp",
              "devicePlatform": "x86_64",
              "os": "iPhone OS",
              "osVersion": "9.2"
            }
          }
        ]
    }
}

POST /v1/init

This API is called by a mobile device or browser when the app is first loaded. It serves a number of purposes:

  1. Initializes a new appUser and device if they don’t yet exist
  2. Updates an existing app user’s profile and device information
  3. Authenticates the appUser if jwt credentials are provided

The API requires that a device be specified at the very minimum. A userId may also be specified to link app user accounts across devices.

The API responds with an appUser object. The appUser includes an _id that can be used to make further API calls on behalf of that user. If the userId and/or device.id are seen for the first time a new appUser will be created. If not, the existing appUser be returned.

An app object is also returned which includes metadata about the app, such as information about push notification channels.

Arguments
device
required
A descriptor of the user’s device. See below.
userId
optional
A unique identifier for the app user. Unlike the smoochId which is generated by Smooch, the userId is chosen by the API consumer. The userId can be used to link a user to the same conversation across multiple devices.

Device

If a userId is used when calling /v1/init, then devices and app users may have a many-to-many relationship. A single userId may use Smooch from multiple devices and multiple different userIds may log in to the same device.

device arguments
id
required
An identifier for the device. Must be globally unique.
platform
required
ios, android, web, or other
pushNotificationToken
optional
The GCM or APN token to be used for sending push notifications to the device.
appVersion
optional
A reserved string field for reporting the app version running on the device. For example: 8.0
info
optional
A flat JSON structure detailing device properties. See below.

Device Info

The device object may also accept a flat info JSON object. Device information reported here will be rendered alongside app user information inside any app maker channels configured with Smooch. The platform and appVersion fields are special in that they can be used as audience targeting criteria for whispers.

Field Example Relevant Platforms
appName foo ios, android
deviceModel iPhone 5s ios, android
os iPhone OS ios, android
osVersion 8.1.2 ios, android
radioAccessTechnology HSDPA ios, android
carrier Acme ios, android
devicePlatform iPhone6,1 ios, android
wifi YES ios, android
currentUrl http://mywebsite.com web
userAgent Mozilla/5.0... web
referrer http://google.com web
browserLanguage en-US web
currentTittle Welcome web

The API will respond with the _id of the app user in question, which can then be used to make API calls to the conversation API. The response will also include any profile information that was previously set for the app user, including custom properties.

App User

The app user object represents an end user using your app. The app user document contains basic profile information such as givenName, surname, and email, as well as any custom user properties you choose to configure.

The /v1/appusers path gives you APIs that can be used to update the user’s properties, retrieve conversation history, post a message, and track app user events.

userId

App users may be created with an optional userId parameter. This is a unique identifier that is chosen by the API consumer and it can be used to synchronize a single conversation across multiple devices. To understand how this works, see the section covering users on multiple devices.

Get App User

Request by smoochId:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'app-token: cr2g6jgxrahuh68n1o3e2fcnt'
smooch.appUsers.get('c7f6e6d6c3a637261bd9656f').then((response) => {
    // async code
});

Request by userId:

curl https://api.smooch.io/v1/appusers/steveb@channel5.com \
     -H 'app-token: cr2g6jgxrahuh68n1o3e2fcnt'
smooch.appUsers.get('steveb@channel5.com').then((response) => {
    // async code
});

Response:

200 OK
{
    "appUser": {
        "_id": "deb920657bbc3adc3fec7963",
        "userId": "steveb@channel5.com",
        "givenName": "Steve",
        "surname": "Brule",
        "email": "steveb@channel5.com",
        "signedUpAt": "2015-10-08T23:52:11.677Z",
        "properties": {},
        "conversationStarted": true,
        "clients": [
          {
            "active": true,
            "appVersion": "1.0",
            "id": "5A7F8343-DF41-46A8-96EC-8583FCB422FB",
            "lastSeen": "2016-03-09T19:09:01.431Z",
            "platform": "ios",
            "pushNotificationToken": "<...>",
            "info": {
              "appName": "ShellApp",
              "devicePlatform": "x86_64",
              "os": "iPhone OS",
              "osVersion": "9.2"
            }
          }
        ]
    }
}

GET /v1/appusers/{smoochId|userId}

Retrieve a specific app user. Like all other /v1/appusers/ paths, an app user can be identified using either the smoochId or the userId.

Update

Request:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f \
     -X PUT \
     -d '{"givenName": "Steve"}' \
     -H 'content-type: application/json' \
     -H 'app-token: cr2g6jgxrahuh68n1o3e2fcnt'
smooch.appUsers.update('c7f6e6d6c3a637261bd9656f', {
    givenName: 'Steve'
}).then((response) => {
    // async code
});

Response:

200 OK
{
  "appUser": {
    "_id": "deb920657bbc3adc3fec7963",
    "userId": "steveb@channel5.com",
    "givenName": "Steve",
    "surname": "Brule",
    "email": "steveb@channel5.com",
    "signedUpAt": "2015-10-08T23:52:11.677Z",
    "properties": {},
    "conversationStarted": true,
    "clients": [
      {
        "active": true,
        "appVersion": "1.0",
        "id": "5A7F8343-DF41-46A8-96EC-8583FCB422FB",
        "lastSeen": "2016-03-09T19:09:01.431Z",
        "platform": "ios",
        "pushNotificationToken": "<...>",
        "info": {
          "appName": "ShellApp",
          "devicePlatform": "x86_64",
          "os": "iPhone OS",
          "osVersion": "9.2"
        }
      }
    ]
  }
}

PUT /v1/appusers/{smoochId|userId}

Update an app user’s basic profile information and specify custom profile data via properties. This API is additive; only the specific fields specified in the request body, and only the specific JSON sub-fields included in the properties field will be updated. In other words, omitting a field will not delete that field.

Arguments
givenName
optional
The user’s given name (first name).
surname
optional
The user’s surname (last name).
email
optional
The user’s email address.
signedUpAt
optional
The date at which the user signed up. Must be ISO 8601 time format (YYYY-MM-DDThh:mm:ss.sssZ)
properties
optional
A flat JSON object containing custom defined user properties.

Update Device

Request:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/devices/5A7F8343-DF41-46A8-96EC-8583FCB422FB \
     -X PUT \
     -d '{"appVersion": "8.0"}' \
     -H 'content-type: application/json' \
     -H 'app-token: cr2g6jgxrahuh68n1o3e2fcnt'
smooch.appUsers.updateDevice('c7f6e6d6c3a637261bd9656f', '5A7F8343-DF41-46A8-96EC-8583FCB422FB', {
    appVersion: '8.0'
}).then((response) => {
    // async code
});

Response:

200 OK
{
  "device": {
    "active": true,
    "appVersion": "8.0",
    "id": "5A7F8343-DF41-46A8-96EC-8583FCB422FB",
    "lastSeen": "2016-03-09T19:09:01.431Z",
    "platform": "ios",
    "pushNotificationToken": "<...>",
    "info": {
      "appName": "ShellApp",
      "devicePlatform": "x86_64",
      "os": "iPhone OS",
      "osVersion": "9.2"
    }
  }
}

PUT /v1/appusers/{smoochId|userId}/devices/{deviceId}

Update the properties of a device. This API is additive; only the specific fields specified in the request body, and only the specific JSON sub-fields included in the info field will be updated. In other words, omitting a field will not delete that field.

Arguments
pushNotificationToken
optional
The GCM or APN token to be used for sending push notifications to the device.
appVersion
optional
A reserved string field for reporting the app version running on the device. For example: 8.0
info
optional
A flat JSON structure detailing device properties. See Device Info.

Track Event

Request:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/events \
     -X POST \
     -d '{"name":"completed_sale"}' \
     -H 'content-type: application/json' \
     -H 'app-token: cr2g6jgxrahuh68n1o3e2fcnt'
smooch.appUsers.trackEvent('c7f6e6d6c3a637261bd9656f', 'completed_sale').then((response) => {
    // async code
});

Response:

201 CREATED
{
    "conversationUpdated": true
}

POST /v1/appusers/{smoochId|userId}/events

Trigger an event for a given app user. Some Smooch whispers are triggered on discrete events. This API is used to trigger such events. For example, if an app has a whisper configured to be sent whenever a user has triggered the completed_sale event, calling this API is the way to trigger such a whisper.

Arguments
name
required
The name of the triggered event.

Pre-Create App User

Request:

curl https://api.smooch.io/v1/appusers \
     -X POST \
     -d '{"userId": "steveb@channel5.com", "givenName": "Steve", "properties": {"favoriteFood": "prizza"}}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.appUsers.create('steveb@channel5.com', {
    givenName: 'Steve',
    properties: {
        favoriteFood: 'prizza'
    }
}).then((response) => {
    // async code
});

Response:

201 CREATED
{
    "appUser": {
        "_id": "deb920657bbc3adc3fec7963",
        "userId": "steveb@channel5.com",
        "givenName": "Steve",
        "signedUpAt": "2015-10-08T23:52:11.677Z",
        "properties": {
          "favoriteFood": "prizza"
        },
        "conversationStarted": false,
        "credentialRequired": false
    }
}

POST /v1/appusers

Arguments
userId
required
A unique identifier for the app user. The userId can be used to link a user to the same conversation across multiple devices.
credentialRequired
optional
Default is false. Set to true to ensure that the created app user requires a jwt credential. See authenticating your users for more information.
givenName
optional
The user’s given name (first name).
surname
optional
The user’s surname (last name).
email
optional
The user’s email address.
signedUpAt
optional
The date at which the user signed up. Must be ISO 8601 time format (YYYY-MM-DDThh:mm:ss.sssZ)
properties
optional
A flat JSON object containing custom defined user properties.

In the vast majority of cases app users will be created from the device or browser using the init API. In some cases however it might be necessary to pre-create an app user object before that user runs your app for the first time. This API facilitates this scenario. A userId must be specified so that a future init call made from a device can use the same userId to link the device to the pre-created app user.

Suppose for example you begin a conversation with an end user bob@example.com over email and you wish to transfer this conversation history over into Smooch once that user logs in to your app. To facilitate this, you can call POST /v1/appusers to pre-create a Smooch identity with userId bob@example.com, to which you can import that existing conversation history. After Bob signs in to your app and your app calls init with the same userId, they will see their conversation history.

Get App User Channel Entities

Request:

curl https https://api.smooch.io/v1/appusers/deb920657bbc3adc3fec7963/channels \
    -H 'authorization: Bearer your-jwt'
// This endpoint is not currently wrapped in a JavaScript lib

Response:

200 OK
{
    "channels": [
        {
            "type": "twilio",
            "phoneNumber": "+15145555555"
        },
        {
            "type": "messenger",
            "userId": "198273192387"
        }
    ]
}

GET /v1/appusers/{smoochId|userId}/channels

Retrieves all of the app user’s channel entity IDs.

Request:

curl https://api.smooch.io/v1/appusers/deb920657bbc3adc3fec7963/channels \
     -X POST \
     -d '{"type": "twilio", "phoneNumber": "+15145555555"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.appUsers.linkChannel('steveb@channel5.com', {
    type: 'twilio',
    phoneNumber: '+15145555555'
}).then((response) => {
    // async code
});

Response:

200 OK
{
    "appUser": {
        "_id": "deb920657bbc3adc3fec7963",
        "userId": "steveb@channel5.com",
        "givenName": "Steve",
        "signedUpAt": "2015-10-08T23:52:11.677Z",
        "properties": {
          "favoriteFood": "pizza"
        },
        "conversationStarted": false,
        "credentialRequired": false,
        "clients": [],
        "pendingClients": [
            {
                "id": "d383f9f4-c8d2-42dd-9f7c-f525fad6849d",
                "platform": "twilio",
                "displayName": "+15145555555"
            }
        ]
    }
}

POST /v1/appusers/{smoochId|userId}/channels

Arguments
type
required
The channel to link.
{entity}
required
The required entity for linking. This is different for each channel.
skipConfirmation
optional
Flag to specify whether or not the confirmation message is sent. Requires app scope JWT.

Linking allows users to continue conversations on their preferred channels. An appUser’s linked channels will be found in the clients field.

When a link request is first made, the channel will be added to the pendingClients field. The appUser is then prompted to accept the linking request. If they do so, the corresponding channel is then moved from the pendingClients field to clients field. If they reject the linking request then the channel is removed from pendingClients.

It is possible to skip the confirmation step with the skipConfirmation flag. App scope JWT is required to specify the confirmation option.

Linkable channels and entities

Given that there is no way for you to provide Smooch with the necessary ID to connect Messenger, LINE, WeChat or Telegram, we have limited the API to only accept ‘Twilio’ for now. Support for Frontend Email is coming soon.

Channel type Required entity
twilio phoneNumber
A String of the appUser’s phone number. It must contain the + prefix and the country code.
Examples of valid phone numbers: +1 212-555-2368, +12125552368, +1 212 555 2368.
Examples of invalid phone numbers: 212 555 2368, 1 212 555 2368.

Request:

curl https://api.smooch.io/v1/appusers/deb920657bbc3adc3fec7963/channels/twilio \
     -X DELETE \
     -d '{"type": "twilio"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.appUsers.unlinkChannel('steveb@channel5.com', 'twilio')
.then(() => {
    // async code
});

Response:

200 OK

DELETE /v1/appusers/{smoochId|userId}/channels/{channel}

Removes the specified channel from the appUser’s clients.

Conversations

When the first message is sent to an app user or received from an app user, a conversation is automatically created for them. The conversation and messages for a given app user can be retrieved and created by way of the /v1/appusers/ API.

Get Messages

Request:

curl https://api.smooch.io/v1/appUsers/c7f6e6d6c3a637261bd9656f/messages?before=1471995721 \
     -H 'app-token: cr2g6jgxrahuh68n1o3e2fcnt'
smooch.appUsers.getMessages('c7f6e6d6c3a637261bd9656f', {before: '1471995721'}).then((response) => {
    // async code
});

Response

200 OK
{
  "conversation": {
    "_id": "df0ebe56cbeab98589b8bfa7",
    "unreadCount": 0
  },
  "messages": [{
    "_id": "55c8c1498590aa1900b9b9b1",
    "authorId": "c7f6e6d6c3a637261bd9656f",
    "role": "appUser",
    "name": "Steve",
    "text": "Just put some vinegar on it",
    "avatarUrl": "https://www.gravatar.com/image.jpg",
    "received": 1439220041.586
  }],
  "next": "https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages?after=1471995721"
}

GET /v1/appusers/{smoochId|userId}/messages

Get the specified app user’s conversation history with a limit of 100 messages, if it exists. If a conversation has not yet been created for the specified app user, 404 will be returned.

Pagination

The API endpoint for retrieving messages of a conversation has a limit of a 100 messages. The before and after parameters will have to be specified to indicate which range of messages to return. These parameters are mutually exclusive. If neither is specified, then the most recent 100 messages will be returned.

Parameter Description
before Timestamp of message. The API will return 100 messages before the specified timestamp (excluding any messages with the provided timestamp).
after Timestamp of message. The API will return 100 messages after the specified timestamp (excluding any messages with the provided timestamp).

Reset Unread Count

Request:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/conversation/read \
     -X POST \
     -H 'app-token: cr2g6jgxrahuh68n1o3e2fcnt'
smooch.conversations.resetUnreadCount('c7f6e6d6c3a637261bd9656f').then(() => {
    // async code
});

Response:

200 OK

POST /v1/appusers/{appUserId|userId}/conversation/read

Reset the unread count of the conversation to 0. If the conversation has not yet been created for the specified app user 404 will be returned.

Typing Activity

Request:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/conversation/activity \
     -X POST \
     -d '{"role":"appMaker", "type": "typing:start"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
// This endpoint is not currently wrapped in a JavaScript lib

Response:

200 OK
{
  "conversation": {
    "_id": "df0ebe56cbeab98589b8bfa7",
    "unreadCount": 0
  }
}

POST /v1/appusers/{appUserId|userId}/conversation/activity

Notify Smooch when an app maker starts or stops typing a response.

Arguments
role
required
The role of the actor. Must be appMaker.
type
required
The type of activity to trigger. Must be either typing:start or typing:stop
name
optional
The name of the app maker that starts or stops typing a response
avatarUrl
optional
The avatar URL of the app maker that starts typing a response

Post Message

Request (App User):

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -d '{"text":"Just put some vinegar on it", "role": "appUser", "type": "text"}' \
     -H 'content-type: application/json' \
     -H 'app-token: cr2g6jgxrahuh68n1o3e2fcnt'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
    text: 'Just put some vinegar on it',
    role: 'appUser',
    type: 'text'
}).then(() => {
    // async code
});

Request (App Maker):

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -d '{"text":"Just put some vinegar on it", "role": "appMaker", "type": "text"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
    type: 'text',
    text: 'Just put some vinegar on it',
    role: 'appMaker'
}).then(() => {
    // async code
});

Response:

201 CREATED
{
  "message": {
    "_id": "55c8c1498590aa1900b9b9b1",
    "authorId": "c7f6e6d6c3a637261bd9656f",
    "role": "appMaker",
    "name": "Steve",
    "text": "Just put some vinegar on it",
    "avatarUrl": "https://www.gravatar.com/image.jpg",
    "received": 1439220041.586
  },
  "conversation": {
    "_id": "df0ebe56cbeab98589b8bfa7",
    "unreadCount": 0
  }
}

POST /v1/appusers/{smoochId|userId}/messages

Post a message to or from the app user. If the app user does not yet have a conversation, one will be created automatically. Messages must have a role of either appUser or appMaker.

A message must also have a type specifying the type of message you’re trying to send. Depending on the type, the message object will have additional Required and Optional arguments. See text, image, carousel, list.

Images can be posted by URL using this API via the image type. Alternatively, you may also upload images to the conversation directly using the /images endpoint.

Arguments
role
required
The role of the individual posting the message. Can be either appUser or appMaker.
type
required
The type of the message being posted. Can be text, image, carousel or list.
name
optional
The display name of the message author. Messages with role appUser will default to a friendly name based on the user’s givenName and surname. Messages with role appMaker have no default name.
email
optional
The email address of the message author. This field is typically used to identify an app maker in order to render the avatar in the app user client. If the email of the Smooch account is used, the configured profile avatar will be used. Otherwise, any gravatar matching the specified email will be used as the message avatar.
avatarUrl
optional
The URL of the desired message avatar image. This field will override any avatar chosen via the email parameter.
metadata
optional
Flat JSON object containing any custom properties associated with the message. If you are developing your own messaging client you can use this field to render custom message types.
payload
optional
The payload of a reply action, if applicable

Text Message

Request:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt' \
     -d '
{
    "role": "appMaker",
    "type": "text",
    "text": "Hello!",
    "actions": [{
        "text": "More info",
        "type": "link",
        "uri": "http://example.org"
    }]
}'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
    role: 'appMaker',
    type: 'text',
    text: 'Hello!',
    actions: [{
        text: 'More info',
        type: 'link',
        uri: 'http://example.org'
    }]
}).then(() => {
    // async code
});

Response:

201 CREATED
{
  "message": {
    "_id": "57966d21c19c9da00839a5e9",
    "role": "appMaker",
    "type": "text",
    "actions": [{
        "_id": "57966d22c19c9da00839a5ec",
        "text": "More info",
        "type": "link",
        "uri": "http://example.org"
    }]
  }
}
201 CREATED

A text type message is a message that is sent with text and/or actions.

Arguments
text
required*
The text content of the message. Optional only if actions are provided.
actions
optional*
Array of action buttons.

Image Message

Request:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt' \
     -d '
{
    "role": "appMaker",
    "type": "image",
    "text": "Hello!",
    "mediaUrl": "http://example.org/image.jpg",
    "actions": [{
        "text": "More info",
        "type": "link",
        "uri": "http://example.org"
    }]
}'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
    role: 'appMaker',
    type: 'image',
    text: 'Hello!',
    mediaUrl: 'http://example.org/image.jpg',
    actions: [{
        text: 'More info',
        type: 'link',
        uri: 'http://example.org'
    }]
}).then(() => {
    // async code
});

Response:

201 CREATED
{
  "message": {
    "_id": "57966d21c19c9da00839a5e9",
    "role": "appMaker",
    "type": "image",
    "mediaUrl": "http://example.org/image.jpg",
    "mediaType": "image/jpeg",
    "actions": [{
        "_id": "57966d22c19c9da00839a5ec",
        "text": "More info",
        "type": "link",
        "uri": "http://example.org"
    }]
  }
}
201 CREATED

An image type message is a message that is sent with an image, and, optionally, text and/or actions.

Arguments
text
optional*
The text content of the message.
actions
optional*
Array of action buttons.
mediaUrl
required*
The image URL used for the image message.
mediaType
optional
The media type is defined here, for example image/jpeg. If mediaType is not specified, the media type will be resolved with the mediaUrl.

Request:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt' \
     -d '
{
    "role": "appMaker",
    "type": "carousel",
    "items": [{
        "title": "Tacos",
        "description": "Description",
        "mediaUrl": "http://example.org/image.jpg",
        "actions": [{
            "text": "Select",
            "type": "postback",
            "payload": "TACOS"
        }, {
            "text": "More info",
            "type": "link",
            "uri": "http://example.org"
        }]
    }, {
        "title": "Ramen",
        "description": "Description",
        "mediaUrl": "http://example.org/image.jpg",
        "actions": [{
            "text": "Select",
            "type": "postback",
            "payload": "RAMEN"
        }, {
            "text": "More info",
            "type": "link",
            "uri": "http://example.org"
        }]
    }]
}'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
    role: 'appMaker',
    type: 'carousel',
    items: [{
        title: 'Tacos',
        description: 'Description',
        mediaUrl: 'http://example.org/image.jpg',
        actions: [{
            text: 'Select',
            type: 'postback',
            payload: 'TACOS'
        }, {
            text: 'More info',
            type: 'link',
            uri: 'http://example.org'
        }]
    }, {
        title: 'Ramen',
        description: 'Description',
        mediaUrl: 'http://example.org/image.jpg',
        actions: [{
            text: 'Select',
            type: 'postback',
            payload: 'RAMEN'
        }, {
            text: 'More info',
            type: 'link',
            uri: 'http://example.org'
        }]
    }]
}).then(() => {
    // async code
});

Response:

201 CREATED
{
  "message": {
    "_id": "57966d21c19c9da00839a5e9",
    "role": "appMaker",
    "type": "carousel",
    "items": [{
        "_id": "57966d21c19c9da00839a5ea",
        "title": "Tacos",
        "description": "Description",
        "mediaUrl": "http://example.org/image.jpg",
        "mediaType": "image/jpeg",
        "actions": [{
            "_id": "57966d22c19c9da00839a5eb",
            "text": "Select",
            "type": "postback",
            "payload": "TACOS"
        }, {
            "_id": "57966d22c19c9da00839a5ec",
            "text": "More info",
            "type": "link",
            "uri": "http://example.org"
        }]
    }, {
        "_id": "57966d22c19c9da00839a5ed",
        "title": "Ramen",
        "description": "Description",
        "mediaUrl": "http://example.org/image.jpg",
        "mediaType": "image/jpeg",
        "actions": [{
            "_id": "57966d31c19c9da00839a5ee",
            "text": "Select",
            "type": "postback",
            "payload": "RAMEN"
        }, {
            "_id": "57966d31c19c9da00839a5ef",
            "text": "More info",
            "type": "link",
            "uri": "http://example.org"
        }]
    }]
  }
}
201 CREATED

Carousel messages are a horizontally scrollable set of items that may each contain text, an image, and action buttons. Not all messaging channels fully support carousel messages; currently only Facebook Messenger, LINE and Telegram cover the full functionality. For all other platforms a carousel message is rendered as raw text. The raw text fallback does not include any images or postback action buttons.

Arguments
items
required*
Array of message items. The array is limited to 10 items.

Channel Support

Smooch will deliver carousel messages to users across all messaging channels regardless of whether or not a given channel can natively render a carousel message UI. For channels that don’t render carousels, a raw text representation is sent. In the future, the Smooch API will expand to support new messaging app carousel experiences as they become available. For current messaging channels, carousel messages will render in the following ways:

Facebook Messenger

Full support. messenger carousel

Telegram

Full support, with cards arranged vertically. telegram carousel

LINE

Full support. line carousel

All Other Channels

Sample Raw Text Format:

1. Tacos
Description
More info http://example.org

2. Ramen
Description
More info http://example.org

Text fallback. text fallback

List Message

Request:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt' \
     -d '
     {
        "role":"appMaker",
        "type":"list",
        "items":[
           {
              "title":"Tacos",
              "description":"Beef and cheese... Mhm...",
              "size": "large",
              "mediaUrl":"https://www.tacojohns.com/globalassets/2016-tacos-menu/taco-bravo---436x420.jpg",
              "actions":[
                 {
                    "text":"Oh yeah!",
                    "type":"postback",
                    "payload":"TACOS"
                 }
              ]
           },
           {
              "title":"Burritos",
              "description":"Beefier and cheesier... Mhm...",
              "mediaUrl":"http://www.tacobueno.com/media/1381/beefbob.png?quality=65",
              "actions":[
                 {
                    "text":"Burritooo!",
                    "type":"postback",
                    "payload":"BURRITOS"
                 },
                 {
                    "text":"Burritooo!",
                    "type":"link",
                    "uri":"http://burritos.com",
                    "default": true
                 }
              ]
           }
        ],
        "actions":[
           {
              "text":"More Choices!",
              "type":"postback",
              "payload":"MORE"
           }
        ]
     }'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
   role:"appMaker",
   type:"list",
   items:[
      {
         title:"Tacos",
         description:"Beef and cheese... Mhm...",
         size: "large",
         mediaUrl:"https://www.tacojohns.com/globalassets/2016-tacos-menu/taco-bravo---436x420.jpg",
         actions:[
            {
               text:"Oh yeah!",
               type:"postback",
               payload:"TACOS"
            }
         ]
      },
      {
         title:"Burritos",
         description:"Beefier and cheesier... Mhm...",
         mediaUrl:"http://www.tacobueno.com/media/1381/beefbob.png?quality=65",
         actions:[
            {
               text:"Burritooo!",
               type:"postback",
               payload:"BURRITOS"
            },
            {
               text:"Burritooo!",
               type:"link",
               uri:"http://burritos.com",
               default: true
            }
         ]
      }
   ],
   actions:[
      {
         text:"More Choices!",
         type:"postback",
         payload:"MORE"
      }
   ]
}).then(() => {
    // async code
});

Response:

201 CREATED
{
  "message": {
    "type": "list",
    "role": "appMaker",
    "received": 1480021430.242,
    "text": "1. Tacos\nBeef and cheese... Mhm...\n\n\n2. Burritos\nBeefier and cheesier... Mhm...\nBurritooo!: http://burritos.com",
    "authorId": "7AJ4zpAVxEwKkjCZD2EYKk",
    "avatarUrl": "https://www.gravatar.com/avatar/5e543256c480ac577d30f76f9120eb74.png?s=200&d=mm",
    "_id": "583755b6be483684d148602b",
    "source": {
      "type": "api"
    },
    "items": [
      {
        "title": "Tacos",
        "description": "Beef and cheese... Mhm...",
        "size": "large",
        "mediaUrl": "https://www.tacojohns.com/globalassets/2016-tacos-menu/taco-bravo---436x420.jpg",
        "mediaType": "image/jpeg",
        "_id": "583755b6be483684d1486033",
        "actions": [
          {
            "text": "Oh yeah!",
            "payload": "TACOS",
            "_id": "583755b6be483684d1486034",
            "uri": "",
            "type": "postback"
          }
        ]
      },
      {
        "title": "Burritos",
        "description": "Beefier and cheesier... Mhm...",
        "mediaUrl": "http://www.tacobueno.com/media/1381/beefbob.png?quality=65",
        "mediaType": "image/png",
        "_id": "583755b6be483684d1486030",
        "actions": [
          {
            "text": "Burritooo!",
            "payload": "BURRITOS",
            "_id": "583755b6be483684d1486032",
            "uri": "",
            "type": "postback"
          },
          {
            "text": "Burritooo!",
            "default": true,
            "_id": "583755b6be483684d1486031",
            "uri": "http://burritos.com",
            "type": "link"
          }
        ]
      }
    ],
    "actions": [
      {
        "text": "More Choices!",
        "payload": "MORE",
        "_id": "583755b6be483684d1486035",
        "uri": "",
        "type": "postback"
      }
    ]
  },
  "conversation": {
    "unreadCount": 1,
    "_id": "94eb1cd68c3e072a5ea0e242"
  }
}
201 CREATED

List messages are a vertically scrollable set of items that may each contain text, an image, and action buttons. Not all messaging channels fully support list messages; currently only Facebook Messenger has support. LINE and Telegram have a carousel fallback, and for all other platforms a list message is rendered as raw text. The raw text fallback does not include any images or postback action buttons.

Arguments
items
required*
Array of message items. The array is limited to 10 items.
actions
optional*
Array of action buttons.

messenger list

Message Items

Message items can be sent through the post message API by including them in the message payload.

Only carousel and list messages currently support message items.

Arguments
title
required
The title of the carousel item.
actions
required
Array of action buttons. At least 1 is required, a maximum of 3 are allowed. link and postback and share actions are supported.
description
optional
The text description, or subtitle.
mediaUrl
optional
The image URL to be shown in the carousel/list item.
size
optional
The size of the image to be shown in the carousel/list item (Only top item of Facebook Messenger carousel supportted). Choose from compact and large
mediaType
optional
If a mediaUrl was specified, the media type is defined here, for example image/jpeg. If mediaType is not specified, the media type will be resolved with the mediaUrl.

Action Buttons

Actions buttons can be sent through the post message API by including them in the message payload.

There are 4 types of supported actions : link, buy, postback, and reply. Type must be specified by providing a type argument in the action object.

Send link action:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -d '{"text":"Just put some vinegar on it", "role": "appMaker", "type": "text", "actions": [{"type": "link", "text": "Put vinegar", "uri": "http://example.com" }]}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
    text: 'Just put some vinegar on it',
    role: 'appMaker',
    type: 'text',
    actions: [
      {
        type: 'link',
        text: 'Put vinegar',
        uri: 'http://example.com'
      }
    ]
}).then(() => {
    // async code
});
Link
text
required
The button text.
type
required
link
uri
required
The action URI. This is the link that will be used in the clients when clicking the button.
default
optional
Flag indicating the message action is the default for a message item in Facebook Messenger.
metadata
optional
Flat JSON object containing any custom properties associated with the action.

Send buy action:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -d '{"text":"Just put some vinegar on it", "role": "appMaker", "type": "text", "actions": [{"type": "buy", "text": "Buy vinegar", "amount": 1000 }]}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
    text: 'Just put some vinegar on it',
    role: 'appMaker',
    type: 'text',
    actions: [
      {
        type: 'buy',
        text: 'Buy vinegar',
        amount: 8000
      }
    ]
}).then(() => {
    // async code
});
Buy
text
required
The button text.
type
required
buy
amount
required
The amount being charged. It needs to be specified in cents and is an integer (9.99$ -> 999).
currency
optional
The currency of the amount being charged (USD, CAD, etc.). If not specified, it would use the default one set in your account. See supported currencies.
metadata
optional
Flat JSON object containing any custom properties associated with the action.

Send postback action:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -d '{"text":"Just put some vinegar on it", "role": "appMaker", "type": "text", "actions": [{"type": "postback", "text": "Send vinegar", "payload": "buy_vinegar" }]}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
    text: 'Just put some vinegar on it',
    role: 'appMaker',
    type: 'text',
    actions: [
      {
        type: 'postback',
        text: 'Buy vinegar',
        payload: 'buy_vinegar'
      }
    ]
}).then(() => {
    // async code
});
Postback
text
required
The button text.
type
required
postback
payload
required
A string payload to help you identify the action context. You can also use metadata for more complex needs.
metadata
optional
Flat JSON object containing any custom properties associated with the action.

Send reply action:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
     -d '
{
    "text":"Which do you prefer?",
    "role": "appMaker",
    "type": "text",
    "actions": [{
        "type": "reply",
        "text": "Tacos",
        "payload": "TACOS"
    }, {
        "type": "reply",
        "text": "Burritos",
        "payload": "BURRITOS"
    }]
}'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
    text: 'Which do you prefer?',
    role: 'appMaker',
    type: 'text',
    actions: [
      {
        type: 'reply',
        text: 'Tacos',
        payload: 'TACOS'
      }, {
        type: 'reply',
        text: 'Burritos',
        payload: 'BURRITOS'
      }
    ]
}).then(() => {
    // async code
});
Reply
text
required
The button text.
type
required
reply
payload
required
A string payload to help you identify the action context. Used when posting the reply. You can also use metadata for more complex needs.
iconUrl
optional
An icon to render next to the reply option (Facebook Messenger and Web Messenger only)
metadata
optional
Flat JSON object containing any custom properties associated with the action.

Reply Actions with icon

Send reply actions with icon URLs:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
     -d '
{
    "text":"Which do you prefer?",
    "role": "appMaker",
    "actions": [{
        "type": "reply",
        "text": "Tacos",
        "iconUrl": "http://example.org/taco.png"
        "payload": "TACOS"
    }, {
        "type": "reply",
        "text": "Burritos",
        "iconUrl": "http://example.org/burrito.png"
        "payload": "BURRITOS"
    }]
}'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
    text: 'Which do you prefer?',
    role: 'appMaker',
    actions: [
      {
        type: 'reply',
        text: 'Tacos',
        iconUrl: 'http://example.org/taco.png',
        payload: 'TACOS'
      }, {
        type: 'reply',
        text: 'Burritos',
        iconUrl: 'http://example.org/burrito.png',
        payload: 'BURRITOS'
      }
    ]
}).then(() => {
    // async code
});

For reply actions you may optionally specify an iconUrl which will render as an icon for each option.

Facebook Messenger Facebook Messenger reply icons

Web Messenger Web Messenger reply icons

Share Actions

Send share action:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H "authorization: Bearer your-jwt" \
     -d '
{
    "role": "appMaker",
    "type": "carousel",
    "items": [{
        "title": "Title",
        "description": "Description",
        "mediaUrl": "http://example.org/image.jpg",
        "mediaType": "image/jpeg",
        "actions": [{
            "type": "share"
        }]
    }]
}'
smooch.appUsers.sendMessage('c7f6e6d6c3a637261bd9656f', {
    text: 'Title',
    role: 'appMaker',
    type: 'carousel',
    items: [{
      title: 'Title',
      actions: [{
        type: 'share'
      }]
    }]
}).then(() => {
    // async code
});

Actions in a message item may also include a share button. Currently, this feature is only supported in Facebook Messenger. For more information, see the Facebook Messenger platform documentation.

messenger carousel

Share
type
required
share
metadata
optional
Flat JSON object containing any custom properties associated with the action.

Upload Image

Request:

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f/images \
     -X POST \
     -H 'app-token: cr2g6jgxrahuh68n1o3e2fcnt' \
     -H 'content-type: multipart/form-data' \
     -F 'source=@screenshot.jpg;type=image/jpeg' \
     -F 'role=appUser' \
     -F 'name=Steve'
// Frontend version
var file = fileInput.files[0];
smooch.appUsers.uploadImage('c7f6e6d6c3a637261bd9656f', file,
{
    text: 'Just put some vinegar on it',
    role: 'appUser'

}).then(() => {
    // async code
});

// Not yet supported on Node.

Response:

201 CREATED
{
  "message": {
    "_id": "55c8c1498590aa1900b9b9b1",
    "authorId": "c7f6e6d6c3a637261bd9656f",
    "role": "appUser",
    "name": "Steve",
    "text": "https://media.smooch.io/image.jpg",
    "mediaUrl": "https://media.smooch.io/image.jpg",
    "mediaType": "image/jpeg",
    "avatarUrl": "https://www.gravatar.com/image.jpg",
    "received": 1446599350.851
  },
  "conversation": {
    "_id": "df0ebe56cbeab98589b8bfa7",
    "unreadCount": 0
  }
}

POST /v1/appusers/{smoochId|userId}/images

Upload an image and post it to the conversation. Images are uploaded using the multipart/form-data content type. Similar to the /messages endpoint, a role parameter must be specified. The /images endpoint accepts the same parameters as /messages but they are sent as form parameters as opposed to being encoded in JSON bodies. The uploaded image will render as part of the message thread in all supported app maker channels (email, Slack, HipChat, Zendesk, Helpscout).

Form Parameters
source
required
The image data.
role
required
The role of the individual posting the message. Can be either appUser or appMaker.

Persistent Menus

Smooch provides a /v1/menu/ API to set persistent menus on messaging channels that support custom menus in their chat UIs (Facebook Messenger and WeChat). Menus are configured on a per app basis (not per user).

Get Menu

Request:

curl https://api.smooch.io/v1/menu \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.menu.get()
.then(() => {
    // async code
});

Response:

200 OK
{
    "menu": {
        "name": "My Awesome Menu",
        "items": [
            {
                "type": "link",
                "text": "Smooch",
                "uri": "http://smooch.io",
                "_id": "57b331fbf1c6aeba1f940dc7"
            },
            {
                "type": "postback",
                "text": "Hello",
                "payload": "HELLO",
                "_id": "57b331fbf1c6aeba1f940dc6"
            }
        ]
    }
}

GET /v1/menu

Get the specified app’s menu.

Update Menu

Request:

curl https://api.smooch.io/v1/menu \
     -X PUT \
     -d '{"items": [{"type": "link", "text": "Smooch", "uri": "http://smooch.io"}]}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.menu.configure({
    name: 'My Awesome Menu',
    items: [{
        type: 'link',
        text: 'Smooch',
        uri: 'http://smooch.io'
    }]
})
.then(() => {
    // async code
});

Response:

200 OK
{
    "menu": {
        "name": "My Awesome Menu",
        "items": [{
            "type": "link",
            "text": "Smooch",
            "uri": "http://smooch.io",
            "_id": "57b331fbf1c6aeba1f940dc7"
        }]
    }
}

PUT /v1/menu

Configure the specified app’s menu.

Arguments
items
required
A list of menu items. See below.
name
optional
An optional text to use as a menu name. If none is provided defaults to “Menu”. Not all channels support a custom menu name (e.g. Facebook Messenger’s menu name is fixed)

Menus contain 1 to 5 menu items.

Arguments
type
required
Can either be link or postback, which correspond to Smooch’s link and postback actions
text
required
The button text of the menu item.
uri
optional
A valid address, like http://smooch.io. Required for a “link” type item.
postback
optional
A payload for a postback. Required for a “postback” type item.

Delete Menu

Request:

curl https://api.smooch.io/v1/menu \
     -X DELETE \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-jwt'
smooch.menu.remove()
.then(() => {
    // async code
});

Response:

200 OK
{
    "menu": {
        "items": []
    }
}

DELETE /v1/menu

Remove the specified app’s menu.

Managed accounts

Introduction

If you’re looking to enable messaging inside your product for your customers, with as much control over the experience as you’d like, you can create and control Smooch apps programmatically using Managed Accounts.

Authentication

Managed Accounts require a account scoped JWT. To sign those JWTs, you will need to use an Account level secret key. You can create one by going into your account page. For more details about signing JWTs, see this section.

Using the Account Scoped Token

Use the account scoped JWT in the same way that you would use an app or appUser scoped JWT, by passing it as an Authorization header, with the token prefaced by the Bearer keyword. See Authentication for more details.

All of the existing core APIs such as /v1/appusers and /v1/webhooks are accessible using an account JWT, provided the appId is included in the the path (e.g. /v1/appusers becomes /v1/apps/{appId}/appusers)

Apps

Endpoints used for provisioning Smooch apps.

Create App

Request:

curl https://api.smooch.io/v1/apps \
     -X POST \
     -d '{"name": "My App"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

201 CREATED
{
  "app": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
    "name": "My App"
  }
}

POST /v1/apps

Creates a new app. The response body will include the appToken, which can be used to initialize the Web, iOS and Android clients and make calls to the app user facing API.

Arguments
name
required
The User facing name of the app.

List Apps

Request:

  curl https://api.smooch.io/v1/apps \
       -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

200 OK
{
  "apps": [
        {
          "_id": "55c8d9758590aa1900b9b9f6",
          "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
          "name": "My App"
        }
    ],
    "hasMore": false,
    "offset": 0
}

GET /v1/apps

Lists all apps configured. This API is paginated. It returns a max of 25 apps by default, and accepts offset and limit query parameters. The max limit is 100.

Parameter Description
limit Integer, the number of records to return (maximum 100, default 25).
offset Integer, the number of initial records to skip before picking records to return.

Get App

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6 \
     -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

200 OK
{
  "app": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
    "name": "My App"
  }
}

GET /v1/apps/{appId}

Fetches an individual app.

Delete App

Request:

  curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6 \
       -X DELETE \
       -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

200 OK
{}

DELETE /v1/apps/{appId}

Removes the specified app, including all its enabled integrations.

App Keys

This set of endpoints is used to provision and revoke secret keys for a Smooch app. A JWT with scope ‘account’ is required to access the secret keys API.

Create Key

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/keys \
     -X POST \
     -d '{"name": "key1"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

201 CREATED
{
  "key": {
    "secret": "Y4SINFtAUzEjayxgUjJZoTjG",
    "name": "key1",
    "_id": "app_5735dcf248011972d621dc01"
  }
}

POST /v1/apps/{appId}/keys

Creates a secret key for the specified app. The response body will include a secret as well it’s corresponding id, which you can use to generate JSON Web Tokens to securely make API calls on behalf of the app.

Arguments
name
required
A friendly identifier for the secret key.

List keys

Request:

  curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/keys \
       -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

200 OK
{
  "keys": [
    {
      "secret": "5XJ85yjUtRcaQu_pDINblPZb",
      "name": "key1",
      "_id": "app_5723a347f82ba0516cb4ea34"
    },
    {
      "secret": "sTE74doRFsxtiwyT9JGCBQ6H",
      "name": "key2",
      "_id": "app_5723a347f82ba0516cb4ea35"
    }
  ]
}

GET /v1/apps/{appId}/keys

Lists all secret keys for a given app.

Get Key

Request:

  curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34 \
       -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

200 OK
{
  "key": {
    "secret": "5XJ85yjUtRcaQu_pDINblPZb",
    "name": "key1",
    "_id": "app_5723a347f82ba0516cb4ea34"
  }
}

GET /v1/apps/{appId}/keys/{keyId}

Returns a secret key.

Delete Key

Request:

  curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34 \
       -X DELETE \
       -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

200 OK
{}

DELETE /v1/apps/{appId}/keys/{keyId}

Removes a secret key.

Get JWT

Request:

  curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34/jwt \
       -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

200 OK
{
    "jwt": "eyJraWQiOiJhcHBfNTczNDE0NjQwN2E2OWI2MTAwNzQiLCJhbGciOiJIUzI1NiJ9.eyJzY29wZSI6ImFwcCJ9.aDkuZKRXzI3I3XRDtnqbrxIsQQuA7kMrV4r7KcwmeHc"
}

GET /v1/apps/{appId}/keys/{keyId}/jwt

Returns an app-scoped JWT signed using the requested keyId/secret pair.

Integrations

This set of endpoints is used to configure and manage various front-end messaging channels. A JWT is required with account scope. The paths below assume that the call will be made using an ‘account’ scoped JWT.

The currently supported integration types are: Facebook Messenger, LINE, Telegram, Twilio SMS, WeChat, Viber and Email.

Create Integration

POST /v1/apps/{appId}/integrations

The Create Integration endpoint currently allows you to provision apps with front-end messaging channels. See the sections below for channel specific instructions.

Facebook Messenger

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{ "type": "messenger", "pageAccessToken": "your_access_token", "appId": "your_fb_app_id", "appSecret": "your_fb_app_secret"
}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

201 CREATED
{
  "integration": {
    "_id": "582dedf230e788746891281a",
    "type": "messenger",
    "pageId": "841556169307254",
    "appId": "1674554616147204"
  }
}

Facebook Messenger Setup steps:

  1. Take note of your Facebook app ID and secret (apps can be created at developer.facebook.com);
  2. The Facebook app must have been submitted to Facebook for approval with the “manage_pages” and “pages_messaging” permissions.

In order to integrate a Facebook Messenger app you must acquire a Page Access Token from your user. Once you have acquired a page access token from your user, call the Create Integration endpoint with your app secret and ID and the user’s page access token.

Arguments
type
required
The integration type: messenger.
pageAccessToken
required
A Facebook Page Access Token.
appId
required
A Facebook App ID.
appSecret
required
A Facebook App Secret.

Twilio

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "twilio", "accountSid": "ACa1b4c65ee0722712fab89867cb14eac7", "authToken": "160c024303f53049e1e060fd67ca6aefc", "phoneNumberSid": "PN0674df0ecee0c9819bca0ff0bc0a159e"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

201 CREATED
{
    "integration": {
      "_id": "5735ddf948011972d621dc08",
      "type": "twilio",
      "phoneNumberSid": "PN0674df0ecee0c9819bca0ff0bc0a159e",
      "phoneNumber": "+15146125236",
      "name": "Mike's Account",
      "accountSid": "ACa1b4c65ee0722712fab89867cb14eac7"
    }
}

To configure a Twilio integration, acquire the required information from the user and call the Create Integration endpoint.

Arguments
type
required
The integration type: twilio.
accountSid
required
Twilio Account SID.
authToken
required
Twilio Auth Token.
phoneNumberSid
required
SID for specific phone number.

Telegram

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "telegram", "token": "192033615:AAEuee2FS2JYKWfDlTulfygjaIGJi4s"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

201 CREATED
{
    "integration": {
      "_id": "5735ddfb48011972d621dc09",
      "type": "telegram",
      "username": "mikes_smooch_bot"
    }
}

To configure a Telegram integration, acquire the required information from the user and call the Create Integration endpoint.

Arguments
type
required
The integration type: telegram.
token
required
Telegram Bot Token.

LINE

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "line", "channelAccessToken": "jZak8gGEYxfy1gIxk869osf2SuT6o11rtLqZQnAx9TiKE7eFXwgnnL58dtwOd1ON9e11GPTDfq+b4hson3dvvYAnAaAnbXYjj1rCUIzgxAa4xVZwGqyS+2rzpswZnGhAuMBWQxCMsF9dwztolUr01wdB04t89/1O/w1cDnyilFU=", "channelSecret": "b85cff984b26eac4297917abd365c4d6"' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

201 CREATED
{
    "integration": {
      "_id": "5735ddfd48011972d621dc0a",
      "type": "line",
      "botName": "Mike Bot"
    }
}

For LINE, each of your customers will need to manually configure a webhook in their LINE configuration page that will point to Smooch servers. You must instruct your customers how to configure this manually on their LINE bot page.

Your customers must set the Callback URL field in their LINE Business Center page.

The URL should look like the following: https://app.smooch.io:443/api/line/webhooks/{appId}.

Once you’ve acquired all the required information and the callback url has been configured, call the Create Integration endpoint.

Arguments
type
required
The integration type: line.
channelAccessToken
required
LINE Channel Access Token.
channelSecret
required
LINE Channel Secret.

Viber

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "viber", "token": "df5f8c5233399561-92636b0c5ba30da9-16d4928fc004a72d"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

201 CREATED
{
    "integration": {
        "_id": "5818fa177682fcb51368635d",
        "type": "viber",
        "uri": "MikesBusiness"
    }
}

To configure a Viber integration, acquire the Viber Public Account token from the user and call the Create Integration endpoint.

Arguments
type
required
The integration type: viber.
token
required
Viber Public Account token.

WeChat

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "wechat", "appId": "ACa1b4c65ee0722712fab89867cb14eac7", "appSecret": "160c024303f53049e1e060fd67ca6aefc"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

201 CREATED
{
    "integration": {
        "_id": "5735ddfd48011972d621dc0a",
        "type": "wechat",
        "appId": "c69175d6d125b772b",
        "webhookSecret": "3889794ab2fd4a70940a97c4b4a6372e"
    }
}

To configure a WeChat integration, acquire the WeChat app ID and app secret from the customer and call the Create Integration endpoint.

In their WeChat dashboard, the customer must set the “URL” field to https://app.smooch.io/api/wechat/webhooks/{smoochAppId}, and set the “Token” field to the value of the webhookSecret found in the response to the call to the Create Integration endpoint.

Arguments
type
required
The integration type: wechat.
appId
required
WeChat App ID.
appSecret
required
WeChat App Secret.
encodingAesKey
optional
AES Encoding Key.

Email

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "frontendEmail"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

201 CREATED
{
    "integration": {
        "_id": "5735ddfd48011972d621dc0a",
        "type": "frontendEmail",
        "shortId": "tki1106",
        "smoochAddress": "app.tki1106@mail.smooch.io"
    }
}

To configure an Email integration, simply call the Create Integration endpoint with the type argument frontendEmail.

Arguments
type
required
The integration type: frontendEmail.
fromAddress
optional
Email will display as coming from this address.

List Integrations

Request:

  curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
       -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

200 OK
{
  "integrations": [
    {
      "_id": "582dedf230e788746891281a",
      "type": "messenger",
      "pageId": "841556169307254",
      "appId": "1674554616147204"
    },
    {
      "_id": "5735ddf948011972d621dc08",
      "type": "twilio",
      "phoneNumberSid": "PN0674df0ecee0c9819bca0ff0bc0a159e",
      "phoneNumber": "+15146125236",
      "name": "Mike's Account",
      "accountSid": "ACa1b4c65ee0722712fab89867cb14eac7"
    },
    {
      "_id": "5735ddfb48011972d621dc09",
      "type": "telegram",
      "username": "mikes_smooch_bot"
    },
    {
      "_id": "5735ddfd48011972d621dc0a",
      "type": "line",
      "mid": "uf0c0bc1813d372ac5af4c5b5faee9923",
      "channelId": "1462776483",
      "botName": "Mike Bot"
    }
  ]
}

GET /v1/apps/{appId}/integrations

Lists all integrations for a given app.

Parameter Description
types String, the list can be filtered to return only integrations of a specific type. Possible values are messenger, line, telegram, and twilio. More than one value can be specified through comma separation e.g. ?types=twilio,line

Get Integration

Request:

  curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02 \
       -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

200 OK
{
  "integration": {
    "_id": "582dedf230e788746891281a",
    "type": "messenger",
    "pageId": "841556169307254",
    "appId": "1674554616147204"
  }
}

GET /v1/apps/{appId}/integrations/{integrationId}

Return the specified integration.

Delete Integration

Request:

  curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02 \
       -X DELETE \
       -H 'authorization: Bearer your-account-token'
// These endpoints are not currently wrapped in a JavaScript lib

Response:

200 OK
{}

DELETE /v1/apps/{appId}/integrations/{integrationId}

Removes the specified integration.

Smooch Connect

Introduction

Smooch has a rapidly growing partner ecosystem which helps you unlock messaging in your product or service and lets customers find you alongside complementary partners. If you’re interested in becoming a partner, tell us what you’re building with Smooch using our partner application and we’ll provision you with everything you’ll need to build your end of the OAuth flow using Smooch Connect. In the meantime the OAuth endpoints detailed below can be tested by impersonating Shoplifter, a partnership we built for testing purposes.

Add to Smooch Button

<a href="https://app.smooch.io/oauth/authorize?client_id=shoplifter&response_type=code"><img alt="Add to Smooch" height="40" width="165" src="https://cdn.smooch.io/images/add_to_smooch.png" srcset="https://cdn.smooch.io/images/add_to_smooch.png 1x, https://cdn.smooch.io/images/add_to_smooch@2x.png 2x"/></a>

This HTML template can be used to place an “Add to Smooch” button on your website.

Add to Smooch

Sample Application

An open source sample application implementing Smooch Connect has been created to help demonstrate how to get it working. Give Shoplifter a try.

The source code is available here.

OAuth Endpoints

Authorize

Request:

curl https://app.smooch.io/oauth/authorize?client_id=shoplifter&response_type=code
// This endpoint is not currently wrapped in a JavaScript lib

GET https://app.smooch.io/oauth/authorize

This endpoint begins the OAuth flow. It relies on a browser session for authentication. If the user is not logged in to Smooch they will be redirected to the login page. If the user has many apps, they will first be prompted to select the one they wish to integrate with. They will then be presented with an Allow/Deny dialog, describing details of the access your integration is requesting.

Parameter Description
client_id
required
Your integration’s unique identifier
response_type
required
For now the only acceptable value is code
state
optional
You may pass in any arbitrary string value here which will be returned to you along with the code via browser redirect
redirect_uri
optional
You may pass in a redirect_uri to determine which URI the response is redirected to. This URI must be contained in the list configured by your integration. If this option is not passed, the first URI present in the list will be used

Success Response

A successful response is delivered via a 302 redirect to the redirect URI configured by your integration.

Parameter Description
code An authorization code which can be exchanged for an access token
state Your state parameter (if one was provided)

Error Response

Parameter Description
error For example: access_denied
state Your state parameter (if one was provided)

Error Codes

Error Code Delivery Method Description
access_denied 302 The user denied access

Token

Request:

curl -X POST https://api.smooch.io/oauth/token \
     -d code=your_code \
     -d grant_type=authorization_code \
     -d client_id=shoplifter \
     -d client_secret=secret
// This endpoint is not currently wrapped in a JavaScript lib

POST https://app.smooch.io/oauth/token

This endpoint is used to exchange an authorization code for an access token. It should only be used in server-to-server calls.

Parameter Description
code
required
The authorization code received via /oauth/authorize
grant_type
required
Must be set to authorization_code
client_id
required
Your integration’s unique identifier
client_secret
required
Your integration’s secret

Success Response:

Parameter Description
access_token An access token that can now be used to call Smooch APIs
token_type Bearer. All issued tokens are of this type

Scope

The default scope of an issued access token is integration scope. This allows API calls to be made to a specific Smooch app on behalf of an integration, identified by the integration’s clientId. The access token grants permission to get and create app users and conversations associated with the app. The token also grants permission to create webhooks, however only webhooks created for the integration will be visible. An access token with integration scope cannot see or modify webhooks that were created by other integrations for example.

API Root Access
/v1/appusers/* Yes
/v1/webhooks/* Yes
/v1/menu/* No