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

API Libraries

Smooch provides official API libraries for Javascript, Ruby, Python and Java. Those helpful libraries wraps calls to this API.

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.
402	Payment Required - The action is not available on your payment plan, or you have exceeded usage limits for your current plan.
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.
413	Request entity too large - The request body exceeds the maximum allowed size for the current endpoint.
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 uses JSON Web Token (JWT) for authentication. See below for more details. There are three different scopes of authorization available. These are appUser, app, and account.

Scope	Authorized Methods
appUser	Init, App User, and Conversations methods
app	All Core methods
account	All Core and Managed Accounts methods

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. Once secured users will also have to be logged in in order to chat on web and mobile clients. See the authentication guide for more information.

JWTs issued with app scope can be used to access any of the Smooch Core APIs on behalf of a single app, and any app user related to that app.

JWTs issued with account scope can be used to access any of the Smooch Core and Managed Accounts APIs on behalf of any app belonging to the account, and any app user related to those apps.

Authentication

# 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', // account, app, or appUser
    userId: 'some-id' // only necessary if scope === 'appUser'
});

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.

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.

After using a JWT with appUser scope to authenticate an app user for the /appuser or /init routes, it becomes no longer possible to authenticate that app user on a client SDK with an appToken alone.

JWT header:

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

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 account scope:

{
    "scope": "account"
}

JWT payload with appUser scope claim:

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

Scope

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

JWT with account scope example

const jwt = require('jsonwebtoken');

const KEY_ID = 'act_5963ceb97cde542d000dbdb1';
const SECRET = 'W7JPAd-EaAVuQkWXBwDCkGv4';

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

The account scope grants access to all apps, users, and conversations associated with a given Smooch account. The account scope is reserved for server-to-server scenarios. The account scope JWT is signed with an account secret key.

JWT with appUser scope example

const jwt = require('jsonwebtoken');

const KEY_ID = 'app_596dead8c82a8c2b00cf0db4';
const SECRET = 'RiYfZscraDLq1zrXgBdBxU_Z';
const USER_ID = '08399dbd910734ec28eea677';

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

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. The appUser scope JWT is signed with an app secret key.

JWT with app scope example

const jwt = require('jsonwebtoken');

const KEY_ID = 'app_596dead8c82a8c2b00cf0db4';
const SECRET = 'RiYfZscraDLq1zrXgBdBxU_Z';

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

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 app scope JWT is signed with an app secret key.

Resource Paths

Resource path with account scope token example

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'authorization: your-account-jwt'

smooch.appUsers.get('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f').then((response) => {
    // async code
});

Resource path with appUser scope token example

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'authorization: your-appUser-jwt'

smooch.appUsers.get('c7f6e6d6c3a637261bd9656f').then((response) => {
    // async code
});

Resource path with app scope token example

curl https://api.smooch.io/v1/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'authorization: your-app-jwt'

smooch.appUsers.get('c7f6e6d6c3a637261bd9656f').then((response) => {
    // async code
});

The app resource is implicitly defined in JWTs signed with app secret keys. This includes app and appUser scoped JWTs. However, most Smooch REST API users will use a single account scoped token to authenticate their calls to the API, and will thus provide the full resource path in the URL. Accordingly, the API call examples in these docs will reflect the full resource path.

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.

Webhook triggers

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 specific for the event type.

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.

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
conversation:referral	when a user scans a Messenger code, clicks an ad on Facebook or scans a WeChat QR code
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
payment:success	when a payment is successfully received from a channel
link:success	when a new channel is successfully linked to a user
link:failure	when a user link fails
link:match	when a user is successfully matched to an external system
*	when any of the above triggers occurs

Manage Webhooks

Smooch exposes REST API methods to:

Create webhook
List webhooks
Get webhook
Update webhook
Delete webhook

Create webhook

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/webhooks \
     -X POST \
     -d '{"target": "http://example.com/callback"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.webhooks.create('5963c0d619a30a2e00de36b8', {
    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/apps/5963c0d619a30a2e00de36b8/webhooks \
       -H 'authorization: Bearer your-account-jwt'

smooch.webhooks.list('5963c0d619a30a2e00de36b8').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/apps/5963c0d619a30a2e00de36b8/webhooks/55c8d9758590aa1900b9b9f6 \
     -H 'authorization: Bearer your-account-jwt'

smooch.webhooks.get('5963c0d619a30a2e00de36b8', '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/apps/5963c0d619a30a2e00de36b8/webhooks/55c8d9758590aa1900b9b9f6 \
     -X PUT \
     -d '{"target": "http://example.com/callback"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.webhooks.update('5963c0d619a30a2e00de36b8', '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/apps/5963c0d619a30a2e00de36b8/webhooks/55c8d9758590aa1900b9b9f6 \
     -X DELETE \
     -H 'authorization: Bearer your-account-jwt'

smooch.webhooks.delete('5963c0d619a30a2e00de36b8', '55c8d9758590aa1900b9b9f6').then(() => {
    // async code
});

Response:

200 OK

DELETE /v1/webhooks/{webhookId}

Deletes the specified webhook.

Message Events

Trigger - `message:appUser` (text)

Payload:

{
    "trigger": "message:appUser",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "messages":[{
        "_id": "55c8c1498590aa1900b9b9b1",
        "type": "text",
        "text": "Hi! Do you have time to chat?",
        "role": "appUser",
        "authorId": "c7f6e6d6c3a637261bd9656f",
        "name": "Steve",
        "received": 1444348338.704,
        "source": {
            "type": "messenger"
        }
    }],
    "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": "messenger"
          }
        ]
    }
}

The payload for a text message.

Message event payload schema

Field	Description
trigger	`"message:appUser"`, or `"message:appMaker"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
messages	An array of objects representing the messages associated with the event. See the message schema below for details.
appUser	A nested object representing the appUser associated with the event. See the appUser schema below for details.

Trigger - `message:appUser` (image)

Payload:

{
    "trigger": "message:appUser",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "messages":[{
        "_id": "55c8c1498590aa1900b9b9b1",
        "type": "image",
        "mediaUrl": "http://www.tacobueno.com/media/1338/partytacolarge.png?quality=65",
        "role": "appUser",
        "authorId": "c7f6e6d6c3a637261bd9656f",
        "name": "Steve",
        "received": 1444348338.704,
        "source": {
            "type": "messenger"
        }
    }],
    "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": "messenger"
          }
        ]
    }
}

The payload for an image message.

Trigger - `message:appMaker` (carousel)

Payload:

{
    "trigger": "message:appMaker",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "messages":[{
        "items": [
            {
                "title": "Tacos",
                "description": "Beef and cheese... Mhm...",
                "size": "large",
                "mediaUrl": "http://www.tacobueno.com/media/1338/partytacolarge.png?quality=65",
                "mediaType": "image/png",
                "_id": "5887c9117e4de029005f1fc7",
                "actions": [
                    {
                      "text": "Oh yeah!",
                      "payload": "TACOS",
                      "_id": "5887c9117e4de029005f1fc8",
                      "type": "postback"
                    }
                ]
            }
        ],
        "type": "carousel",
        "role": "appMaker",
        "received": 1485293841.303,
        "authorId": "2cKU9zRO2DpBWgk764Tfro",
        "avatarUrl": "https://www.gravatar.com/avatar/5e543256c480ac577d30f76f9120eb74.png?s=200&d=mm",
        "_id": "5887c9117e4de029005f1fc6",
        "source": {
          "type": "api"
        }
  }],
  "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": "messenger"
        }
      ]
  }
}

The payload for a carousel message.

Trigger - `message:appMaker` (list)

Payload:

{
    "trigger": "message:appMaker",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "messages":[{
        "items": [
            {
                "title": "Tacos",
                "description": "Beef and cheese... Mhm...",
                "size": "large",
                "mediaUrl": "http://www.tacobueno.com/media/1338/partytacolarge.png?quality=65",
                "mediaType": "image/png",
                "_id": "5887c9117e4de029005f1fc7",
                "actions": [
                    {
                      "text": "Oh yeah!",
                      "payload": "TACOS",
                      "_id": "5887c9117e4de029005f1fc8",
                      "type": "postback"
                    }
                ]
            }
        ],
        "actions": [
            {
              "text": "More Choices!",
              "payload": "MORE",
              "_id": "5887c9a37e4de029005f1fce",
              "type": "postback"
            }
        ],
        "type": "list",
        "role": "appMaker",
        "received": 1485293841.303,
        "authorId": "2cKU9zRO2DpBWgk764Tfro",
        "avatarUrl": "https://www.gravatar.com/avatar/5e543256c480ac577d30f76f9120eb74.png?s=200&d=mm",
        "_id": "5887c9117e4de029005f1fc6",
        "source": {
          "type": "api"
        }
  }],
  "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": "messenger"
        }
      ]
  }
}

The payload for a list message.

Trigger - `message:appUser` (location)

Payload:

{
    "trigger": "message:appUser",
    "app": {
        "_id": "55fafea8bf8fd41a00357805"
    },
    "messages": [
        {
            "text": "Location shared:\nhttps://maps.google.com/maps?q=45.5261583,-73.595346",
            "authorId": "76293a38b24c5cca43e79415",
            "received": 1485292067.601,
            "type": "location",
            "coordinates": {
                "lat": 45.5261583,
                "long": -73.595346
            },
            "role": "appUser",
            "_id": "5887c22356c66904009ad602",
            "source": {
                "type": "messenger"
            }
        }
    ],
    "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": "messenger"
          }
        ]
    }
}

The payload for a location message.

Postback Events

Trigger - `postback`

Payload:

{
    "trigger": "postback",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "postbacks":[{
        "message": {
            "_id": "55c8c1498590aa1900b9b9b1",
            "text": "Do you want to see more options?",
            "type": "text",
            "role": "appMaker",
            "authorId": "c7f6e6d6c3a637261bd9656f",
            "name": "LunchBot",
            "received": 1444348338.704,
            "source": {
                "type": "slack"
            },
            "actions": [{
                "_id": "571530ee4fae94c32b78b170",
                "type": "postback",
                "text": "Yes",
                "payload": "YES"
            }]
        },
        "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": "messenger"
          }
        ]
    }
}

The payload for when a user taps a postback button.
Postbacks originating from a persistent menu do not have messages associated with them, and so omit the message property.

Postback event payload schema

Field	Description
trigger	`"postback"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
postbacks	An array of objects representing the postbacks associated with the event. See the postback schema below for details.
appUser	A nested object representing the appUser associated with the event. See the appUser schema below for details.

Postback schema

Field	Description
message optional	A nested object representing the message associated with the postback action. See the message schema below for details (Not present in postback payloads triggered by persistent menu items).
action	A nested object representing the postback action. See the action schema below for details.

Conversation Events

Trigger - `conversation:read`

Payload:

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

The payload for when a user reads a conversation.

Conversation event payload schema

Field	Description
trigger	`"conversation:read"`, or `"conversation:start"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
source	A nested object representing the source of the event. See the source schema below for details.
appUser	A nested object representing the appUser (for “conversation:read” events, a truncated appUser is provided).
timestamp	A unix timestamp given in seconds, describing when Smooch received the event.
referral	Referral information. Only present for WeChat and Messenger. See referral schema for details.

Trigger - `conversation:start`

Payload:

{
    "trigger": "conversation:start",
    "app": {
        "_id": "57ec2881c47d2d24b0c16427"
    },
    "source": {
        "type": "messenger"
    },
    "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": "messenger"
          }
        ]
    },
    "timestamp": 1480349392.103
}

The payload for when a user opts in to start receiving messages. conversation:start is only available on a sub set of channels. Channel capabilities lists which channel currently supports it. Also, note that conversation:start won’t be triggered when a user is linking a second channel via the Web Messenger.

The conversation:start event can contain a referral property in the following circumstances:

When a referral parameter is included with a link to Facebook Messenger.
When a WeChat subscribe event is triggered by a new follower and the QR code contains an embedded referral property.

Trigger - `conversation:referral`

Payload:

{
    "trigger": "conversation:referral",
    "app": {
        "_id": "589b7811d626a6d76d6b8555"
    },
    "source": {
        "type": "messenger"
    },
    "appUser": {
        "_id": "4a5f73a36a7b818c2643296f"
    },
    "referral": {
        "code": "my-ref-code",
        "details": {
            "source": "MESSENGER_CODE",
            "type": "OPEN_THREAD"
        }
    },
    "timestamp": 1495650348.685
}

Conversation referral payload schema

Field	Description
trigger	`"conversation:referral"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
source	A nested object representing the source of the event. See the source schema below for details.
appUser	A truncated appUser schema object
referral	Referral information. See referral schema for details.

The payload for when a user is referred to a conversation. This payload will be sent when a user performs the following actions:

Scanning a Messenger code
Clicking a conversion ad on Facebook
Scanning a WeChat QR code (when the user is already a follower).

Merge Events

Trigger - `merge:appUser`

Payload:

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

The payload for when two users are merged into one.

Merge events payload

Field	Description
trigger	`"merge:appUser"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
surviving	A nested object with the truncated appUser that now represents the merged appUser objects. See the truncated appUser schema below for details.
discarded	An array of objects with the truncated appUsers that were unified into `surviving` appUser object. See the truncated appUser schema below for details.

Delivery Events

Trigger - `delivery:success`

Payload:

{
    "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",
            "type": "text",
            "authorId": "5X8AJwvpy0taCkPDniC5la",
            "avatarUrl": "https://www.gravatar.com/image.jpg",
            "_id": "5837079fd84370ef2c0dcabb",
            "source": {
                "type": "slack"
            }
        }
    ],
    "timestamp": 1480001440.731
}

The payload for when the delivery of a message was successful.

Delivery event payload schema

Field	Description
trigger	`"delivery:success"` or `"delivery:failure"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
messages	An array of objects representing the messages associated with the event. See the message schema below for details.
appUser	A nested object representing the truncated appUser associated with the event. See the appUser schema below for details.
destination	A nested object representing the destination of the message. See the destination schema below for details.
timestamp	A unix timestamp given in seconds, describing when the delivery event occurred.
error optional	A nested object (present in `"delivery:failure"` event) representing the error associated with the delivery failure. See the error schema below for details.

Trigger - `delivery:failure`

Payload:

{
    "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",
            "type": "text",
            "authorId": "5X8AJwvpy0taCkPDniC5la",
            "avatarUrl": "https://www.gravatar.com/image.jpg",
            "_id": "583708af8d449209ba217871",
            "source": {
                "type": "slack"
            }
        }
    ],
    "timestamp": 1480001711.941
}

The payload for when the delivery of a message fails.

Error schema

Field	Description
code	The error code associated with the error.
underlyingError optional	A object with the error data returned by the channel a message was meant to be delivered too.
message optional	The description associated with the error.

Payment Events

Trigger - `payment:success`

Payload:

{
    "trigger": "payment:success",
    "app": {
        "_id": "571e3496cb98b3962ce740d7"
    },
    "appUser": {
        "_id": "2b15a54fde9dc2f33f88bc25"
    },
    "payments": [
        {
            "source": {
                "type": "messenger"
            },
            "message": {
                "text": "Just put some vinegar on it",
                "actions": [
                    {
                        "text": "Buy vinegar",
                        "amount": 1000,
                        "currency": "usd",
                        "state": "paid",
                        "_id": "5877fd5624fe8fd934d7c2f3",
                        "uri": "https://app.smooch.io/checkout/5877fd5624fe8fd934d7c2f3",
                        "type": "buy"
                    }
                ],
                "type": "text",
                "role": "appMaker",
                "received": 1484258646.823,
                "authorId": "5X8AJwvpy0taCkPDniC5la",
                "avatarUrl": "https://www.gravatar.com/image.jpg",
                "_id": "5877fd5624fe8fd934d7c2f2",
                "source": {
                    "type": "api"
                }
            },
            "action": {
                "text": "Buy vinegar",
                "amount": 1000,
                "currency": "usd",
                "state": "paid",
                "_id": "5877fd5624fe8fd934d7c2f3",
                "uri": "https://app.smooch.io/checkout/5877fd5624fe8fd934d7c2f3",
                "type": "buy"
            },
            "charge": {
                "id": "ch_19dPrCHQ7f2U7NYSZ45OspXT"
            }
        }
    ],
    "timestamp": 1484258666.455
}

The payload for when a payment is received.

Payment event payload schema

Field	Description
trigger	`"payment:success"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
appUser	A nested object representing the appUser associated with the event. See the truncated appUser schema below for details.
payments	An array of objects representing the payments associated with the event. See the payment schema below for details.
timestamp	A unix timestamp given in seconds, describing when Smooch received confirmation of the payment.

Payment schema

Field	Description
source	A nested object describing the source of the event. See the source schema for details.
message	A nested object representing the appMaker message associated with the postback action. See the message schema below for details (Not present in postback payloads triggered by persistent menu items).
action	A nested of object representing the buy action associated with the event. See the action schema below for details.
charge	A nested of object representing the Stripe charge associated with the event. See the charge schema below for details.

Charge schema

Field	Description
id	The stripe ID of the charge event. See the Stripe docs for more information

Link Events

Trigger - `link:success`

Payload:

{
    "trigger": "link:success",
    "app": {
        "_id": "58b487c74ebf3ce5d4b38e5f"
    },
    "appUser": {
        "_id": "8215a086b271592e01b74e28"
    },
    "channel": "messenger",
    "criteria": {
        "phoneNumber": "+15141234567",
        "givenName": "bleep",
        "surname": "bloop"
    }
}

The payload for a link app user success.

Link success event payload schema

Field	Description
trigger	`"link:success"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
appUser	A nested object representing the appUser associated with the event. See the truncated appUser schema below for details.
channel	The channel for which the link succeeded.
criteria	The criteria specified to establish the link.

Trigger - `link:match`

Payload:

{
    "trigger": "link:match",
    "app": {
        "_id": "58b487c74ebf3ce5d4b38e5f"
    },
    "appUser": {
        "_id": "8215a086b271592e01b74e28"
    },
    "channel": "messenger",
    "criteria": {
        "phoneNumber": "+15141234567",
        "givenName": "bleep",
        "surname": "bloop"
    }
}

The payload for a link app user match.

Link match event payload schema

Field	Description
trigger	`"link:match"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
appUser	A nested object representing the appUser associated with the event. See the truncated appUser schema below for details.
channel	The channel for which the link matched.
criteria	The criteria specified to establish the link.

Trigger - `link:failure`

Payload:

{
    "trigger": "link:failure",
    "app": {
        "_id": "58b487c74ebf3ce5d4b38e5f"
    },
    "appUser": {
        "_id": "8215a086b271592e01b74e28"
    },
    "error": {
        "code": "bad_request",
        "message": "(#100) No matching user found"
    },
    "channel": "messenger",
    "criteria": {
        "phoneNumber": "+15141234567",
        "givenName": "bleep",
        "surname": "bloop"
    }
}

The payload for a link app user failure.

Link failure event payload schema

Field	Description
trigger	`"link:failure"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
appUser	A nested object representing the appUser associated with the event. See the truncated appUser schema below for details.
channel	The channel for which the link failed.
criteria	The criteria specified to establish the link.
error	A nested object representing the error associated with the link failure. See the error schema below for details.

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

A webhook call will be reattempted up to 5 times at an exponentially increasing interval if the target responds with anything but a success (2XX) or a non-recoverable error. If no response is received within 20 seconds, the call will be considered a failure and will also be reattempted.

Non-recoverable Errors

The following status codes are deemed to be non-recoverable and Smooch will not reattempt a call when receiving a response with them:

400: The target exists, but can’t process the payload
401: The target is behind authentication or doesn’t recognize the webhook secret
403: Smooch should not be calling the target
404: The target doesn’t exist
406: The target exists, and rejected webhook intentionally

Init

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/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-account-jwt'

smooch.appUsers.init('5963c0d619a30a2e00de36b8', {
    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/apps/{appId}/init

This API is called by an iOS, Android, or browser client when the app is first loaded. It serves a number of purposes:

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

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

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

Caution: If you’re specifying a userId then in order to keep conversations private we strongly suggest authenticating your users. If a userId is used without a JWT credential, then anyone who can discover a user’s userId could potentially eavesdrop on the conversation.

Devices are a type of client

Smooch uses the term client to refer generally to means by which a user can send and receive messages. This includes 3rd party accounts such as a connected Facebook Messenger account, however the init API specifically deals with registration and identification of iOS, Android and Web devices, which become persisted as one or many clients connected to a single user.

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

Note: Only one userId can be active on a given client at a time. On a push notification capable client that’s shared between multiple userIds, only the most recent userId to have called /v1/init will receive push notifications from the integrated application on that client.

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

In some scenarios, the appUser._id returned in an app boot call may change. This is possible for example when the userId is being used to log a user in on multiple clients, which may cause two distinct app users to merge together. The caller should always check if the returned appUser._id has changed, and re-fetch conversation history whenever appropriate.

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/apps/{appId}/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 clients. To understand how this works, see the section covering users on multiple clients.

If a userId has been specified for a given app user, it can be used in place of the appUser._id in any /v1/apps/{appId}/appusers/ API path.

Get App User

Request by smoochId:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'authorization: your-account-jwt'

smooch.appUsers.get('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f').then((response) => {
    // async code
});

Request by userId:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/steveb@channel5.com \
     -H 'authorization: your-account-jwt'

smooch.appUsers.get('5963c0d619a30a2e00de36b8', '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/apps/{appId}/appusers/{smoochId|userId}

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

Update App User

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
     -X PUT \
     -d '{"givenName": "Steve"}' \
     -H 'content-type: application/json' \
     -H 'authorization: your-account-jwt'

smooch.appUsers.update('5963c0d619a30a2e00de36b8', '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/apps/{appId}/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 object containing custom defined user properties.

Delete User Profile

Request by smoochId:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/profile \
     -X DELETE \
     -H 'authorization: Bearer your-account-jwt'

smooch.appUsers.deleteProfile('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f').then((response) => {
    // async code
});

Request by userId:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/steveb@channel5.com/profile \
     -X DELETE \
     -H 'authorization: Bearer your-account-jwt'

smooch.appUsers.deleteProfile('5963c0d619a30a2e00de36b8', 'steveb@channel5.com').then((response) => {
    // async code
});

Response:

200 OK

{
    "appUser": {
        "_id": "deb920657bbc3adc3fec7963",
        "userId": "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": "<...>"
          }
        ]
    }
}

DELETE /v1/apps/{appId}/appusers/{smoochId|userId}/profile

Delete a user’s profile. Calling this API will clear givenName, surname, email and every custom property for the specified user.

For every client owned by the user, it will also clear displayName, avatarUrl and any channel specific information stored in the info field.

This endpoint requires a jwt credential with app, integration or account level scope.

Update Device

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/devices/5A7F8343-DF41-46A8-96EC-8583FCB422FB \
     -X PUT \
     -d '{"appVersion": "8.0"}' \
     -H 'content-type: application/json' \
     -H 'authorization: your-account-jwt'

smooch.appUsers.updateDevice('5963c0d619a30a2e00de36b8', '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/apps/{appId}/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/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/events \
     -X POST \
     -d '{"name":"completed_sale"}' \
     -H 'content-type: application/json' \
     -H 'authorization: your-account-jwt'

smooch.appUsers.trackEvent('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', 'completed_sale').then((response) => {
    // async code
});

Response:

201 CREATED

{
    "conversationUpdated": true
}

POST /v1/apps/{appId}/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/apps/5963c0d619a30a2e00de36b8/appusers \
     -X POST \
     -d '{"userId": "steveb@channel5.com", "givenName": "Steve", "properties": {"favoriteFood": "prizza"}}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.appUsers.create('5963c0d619a30a2e00de36b8', '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/apps/{appId}/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 clients.
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 object containing custom defined user properties.

In the vast majority of cases app users will be created from the device or browser registered 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/apps/{appId}/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.

Unlike the other App User APIs in this section, this endpoint is not intended to be called from an end user’s device or from a browser. It requires a jwt credential with app level scope.

Get App User Channel Entities

Request:

curl https https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/channels \
    -H 'authorization: Bearer your-account-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/apps/{appId}/appusers/{smoochId|userId}/channels

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

Link App User To Channel

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/channels \
     -X POST \
     -d '{"type": "twilio", "confirmation": {"type": "prompt"}, "phoneNumber": "+15145555555"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.appUsers.linkChannel('5963c0d619a30a2e00de36b8', 'steveb@channel5.com', {
    type: 'twilio',
    phoneNumber: '+15145555555',
    confirmation: {
      type: 'prompt'
    }
}).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/apps/{appId}/appusers/{smoochId|userId}/channels

Arguments
type required	The channel to link. Can be `twilio`, `messenger` or `mailgun`
{entity} required	The required entity for linking. This is different for each channel.
confirmation required	The confirmation option for linking.
primary optional	Default is `true`. Flag indicating whether the client will become the primary once linking is complete.

Some extra arguments are supported depending on the selected type.

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. At this point, the API call will be considered a success and a response will be returned. Future updates on the status of the link request can be tracked by listening to the link:match, link:success and link:failure webhooks.

The skipConfirmation flag is still supported to preserve backwards compatibility, but will only be accepted for twilio linking.

Linking confirmation

The confirmation option allows you to specify the strategy used to initiate a link with the target user.

Arguments
type required	The type of confirmation. Types include immediate, userActivity or prompt
message	The message used to reach out to the user. Must be a valid message object as per the post message API

Messages sent via the Linking API can only be of type text and image at the moment. If actions are included they can only be of type link. The confirmation message will not be added to the appUser’s conversation.

Immediate

Available on: Twilio, Messenger, Mailgun

If you specify an immediate confirmation, Smooch will not wait for the user to confirm the link before converting the pending client to a full client. On a successful link, the link:success webhook will be triggered.

If the message property is provided, Smooch will attempt to deliver it to the channel prior to completing the link. Successfully sending this message will trigger a link:match webhook. Failure to deliver this message will result in a link:failure webhook, and the pending client will be removed from the user.

User activity

Available on: Twilio, Messenger

If you specify a userActivity confirmation, Smooch will wait for the user to confirm the link before converting the pending client to a full client. If the user performs an activity acknowledging the message was received (for example accepting the message request on Facebook Messenger), the link:success webhook will be triggered.

The message property is mandatory for this confirmation type. Smooch will attempt to deliver it to the channel prior to listening for the user’s activity. This is a good opportunity to welcome the user to the new channel and invite them to begin messaging you there. Successfully sending this message will trigger a link:match webhook. Failure to deliver this message will result in a link:failure webhook, and the pending client will be removed from the user.

Prompt

Available on: Twilio

If you specify a prompt confirmation, the user will be prompted to either accept or deny your link request. The message sent to prompt the user can’t be customized.

Successfully sending the prompt will trigger a link:match webhook. Failure to deliver this message or a denial of the prompt will result in a link:failure webhook, and the pending client will be removed from the user.

Linkable channels and entities

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

Channel type	Required entity	Extra properties
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`.
messenger	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`.	`givenName` and `surname` may be specified as additional criteria to increase the likelihood of a match.
mailgun	address A String of the appUser’s email address	`subject` may be specified to set the subject for the outgoing email. Default `subject`: “New message from {appName}”

Messenger linking requires a special permission on your Facebook page and is subject to a $99 USD one-time fee. Given this permission requirement, Messenger linking is only possible when targeting an app integrated via our Integration API. A confirmation message is also required to initiate a link for the Messenger channel.

Unlink App User From Channel

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/channels/twilio \
     -X DELETE \
     -d '{"type": "twilio"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.appUsers.unlinkChannel('5963c0d619a30a2e00de36b8', 'steveb@channel5.com', 'twilio')
.then(() => {
    // async code
});

Response:

200 OK

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

Removes the specified channel from the appUser’s clients.

Schema

App user schema

The appUser schema describes the appUser data sent in webhook payloads, and in GET appUser responses.

Field	Description
_id	A canonical ID that can be used to retrieve the appUser.
userId optional	An optional ID that if specified can also be used to retreive the appUser.
properties	A flat object of optional properties set by the app maker.
signedUpAt	A datetime string with the format yyyy-mm-ddThh:mm:ssZ representing the moment an appUser was created.
clients	An array of objects representing the clients associated with the appUser. See the client schema below for details.
pendingClients	As clients, but containing linked clients which have not been confirmed yet (i.e. Twilio SMS)
devices	Identical to the clients array, but deprecated.
conversationStarted	A boolean representing of whether a message has been sent or not.
credentialRequired	A boolean representing whether the appUser is secured by a JSON Web Token or not.
email optional	An optional email address.
givenName optional	An optional given name.
surname optional	An optional surname.

Truncated app user schema

The truncated appUser is a partial selection of properties from the appUser model. The truncated appUser is provided in the payloads of certain webhooks.

Field	Description
_id	A canonical ID that can be used to retrieve the appUser.
userId optional	An optional ID that if specified can also be used to retrieve the appUser.
conversationStarted optional	A boolean representing of whether a message has been sent or not.

Client schema

Client specific info

Field	Description
active	If active is `false` then the appUser is not logged in to the client and signifies that the appUser will not receive APN or FCM notifications. This pertains to the SDKs.
platform	Includes one of `"web"`, `"ios"`, `"android"`, `"messenger"`, `"viber"`, `"telegram"`, `"wechat"`, `"line"`, `"twilio"`, and `"frontendEmail"`, `"other"`, or any number of other platforms.
primary	Boolean indicating if the platform is the appUser’s primary channel. The primary channel is the user’s most active channel and the preferred delivery channel for the appMaker’s messages.
id	A unique identifier for a device if on Web, iOS, or Android, or a client on other channels.
displayName optional	The appUser’s display name as provided by the client.
avatarUrl optional	The URI for an appUser’s avatar, as provided by the client.
info optional	A flat Object with raw properties that vary for each client platform. All keys are optionals and not guaranteed to be available.
appVersion optional	For the SDK in a native app, signifies the version of the app.
lastSeen	A datetime string with the format yyyy-mm-ddThh:mm:ssZ representing the last time the appUser sent a message, or launched a client like Web, Android, or iOS.
linkedAt optional

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/apps/{appId}/appusers/ API.

Post Message

Request (App User):

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -d '{"text":"Just put some vinegar on it", "role": "appUser", "type": "text"}' \
     -H 'content-type: application/json' \
     -H 'authorization: your-account-jwt'

smooch.appUsers.sendMessage('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', {
    text: 'Just put some vinegar on it',
    role: 'appUser',
    type: 'text'
}).then(() => {
    // async code
});

Request (App Maker):

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/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-account-jwt'

smooch.appUsers.sendMessage('5963c0d619a30a2e00de36b8', '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",
    "type": "text",
    "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/apps/{appId}/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.

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.

For messages originating from an app maker, a jwt credential with app level scope must be used.

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`, `file`, `carousel`, `list`, or `location`.
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.
destination optional	The channel where you want your message delivered to. This only works for messages with role `appMaker`. See Channel Targeting for more information.
metadata optional	Flat 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. See the metadata schema for more information.
payload optional	The payload of a `reply` action, if applicable

Text Message

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt' \
     -d '
{
    "role": "appMaker",
    "type": "text",
    "text": "Hello!",
    "metadata": {
        "lang": "en-ca",
        "items": 3
    }
    "actions": [{
        "text": "More info",
        "type": "link",
        "uri": "http://example.org",
        "metadata": {
            "buttonIntent": "more"
        }
    }]
}'

smooch.appUsers.sendMessage('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', {
    role: 'appMaker',
    type: 'text',
    text: 'Hello!',
    metadata: {
        lang: 'en-ca',
        items: 3
    },
    actions: [{
        text: 'More info',
        type: 'link',
        uri: 'http://example.org',
        metadata: {
            buttonIntent: 'moreInfo'
        }
    }]
}).then(() => {
    // async code
});

Response:

201 CREATED

{
  "message": {
    "_id": "57966d21c19c9da00839a5e9",
    "role": "appMaker",
    "type": "text",
    "metadata": {
        "items": 3,
        "lang": "en-ca"
    },
    "actions": [{
        "_id": "57966d22c19c9da00839a5ec",
        "text": "More info",
        "type": "link",
        "uri": "http://example.org",
        "metadata": {
            "buttonIntent": "moreInfo"
        }
    }]
  }
}

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/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-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('5963c0d619a30a2e00de36b8', '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`.

File Message

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt' \
     -d '
{
    "role": "appMaker",
    "type": "file",
    "mediaUrl": "http://example.org/document.pdf",
    "mediaType": "application/pdf"
}'

smooch.appUsers.sendMessage('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', {
    role: 'appMaker',
    type: 'file',
    mediaUrl: 'http://example.org/document.pdf',
    mediaType: 'application/pdf'
}).then(() => {
    // async code
});

Response:

201 CREATED

{
  "message": {
    "_id": "57966d21c19c9da00839a5e9",
    "role": "appMaker",
    "type": "file",
    "mediaUrl": "http://example.org/document.pdf",
    "mediaType": "application/pdf"
  }
}

201 CREATED

A file type message is a message that is sent with a file attachment. If you have a raw unhosted file you want to send, you can use the attachments upload API to upload the file to Smooch before sending the message.

Arguments
text optional	Accompanying text or a description of the file.
mediaUrl required	The URL of the file attachment.
mediaType optional	The media type is defined here, for example `application/pdf`. If `mediaType` is not specified, the media type will be resolved with the `mediaUrl`.

Channel Support

File messages are fully supported on Facebook Messenger and will render as such:

messenger file upload

On all other channels, they are rendered as a link.

Location Message

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt' \
     -d '
{
    "role": "appUser",
    "type": "location",
    "coordinates": {
        "lat": 45.5261583,
        "long": -73.595346
    }
}'

smooch.appUsers.sendMessage('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', {
    role: 'appUser',
    type: 'location',
    coordinates: {
        lat: 45.5261583,
        long: -73.595346
    }
}).then(() => {
    // async code
});

Response:

201 CREATED

{
  "message": {
      "text": "Location shared:\nhttps://maps.google.com/maps?q=45.5261583,-73.595346",
      "authorId": "76293a38b24c5cca43e79415",
      "received": 1485292067.601,
      "type": "location",
      "coordinates": {
          "lat": 45.5261583,
          "long": -73.595346
      },
      "role": "appUser",
      "_id": "5887c22356c66904009ad602",
      "source": {
          "type": "messenger"
      }
  }
}

201 CREATED

A location type message includes the coordinates (latitude and longitude) of a location. Typically sent in response to a Location Request.

Arguments
coordinates required	The coordinates of the location. See Coordinates.

Coordinates

Arguments
lat required	A floating point value representing the latitude of the location
long required	A floating point value representing the longitude of the location

Carousel Message

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-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('5963c0d619a30a2e00de36b8', '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.
displaySettings optional	Settings to adjust the carousel layout. See Display Settings.

Display Settings

A business can modify a carousel message layout by including an optional displaySettings object. Supported settings are:

Arguments
imageAspectRatio optional	Specifies how to display all carousel images. Valid values are `horizontal` (default) and `square`.

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

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.

List Message

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-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('5963c0d619a30a2e00de36b8', '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.

In Messenger, list messages sent with multiple actions either in a message item or the message itself will be truncated, as only 1 action is supported.

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 supported). 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.

Action buttons can only be sent with an appMaker role.

Link

A link action will open the provided URI when tapped.

Send link action:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/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-account-jwt'

smooch.appUsers.sendMessage('5963c0d619a30a2e00de36b8', '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
});

Arguments
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 object containing any custom properties associated with the action. See the metadata schema for more information.
extraChannelOptions optional	Extra options to pass directly to the channel API. See Extra Channel Options

Action buttons sent to LINE must have http or https protocol or the message will not be delivered.

Extra Channel Options Schema

For features that are not yet supported natively by the Smooch platform, or are specific to a certain channel implementation, the Extra Channel Options Schema allows the caller to specify certain parameters that will be passed directly to the channel API.

Extra channel options exist for the following channels:

Arguments
messenger optional	An object conforming to the Messenger Extra Channel Options Schema

Messenger Extra Channel Options Schema

Arguments
webview_height_ratio optional	Controls the webview height in a `link` type action. Possible values are `compact`, `tall`, and `full`. More Info
messenger_extensions optional	For `link` type actions, a boolean value indicating whether the URL should be loaded with Messenger Extensions enabled. Default value is `false`. More Info
fallback_url optional	If `messenger_extensions` is `true`, the URL to use on clients that don’t support Messenger Extensions. More Info

Buy

A buy action will prompt the user to purchase an item.

Send buy action:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/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-account-jwt'

smooch.appUsers.sendMessage('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', {
    text: 'Just put some vinegar on it',
    role: 'appMaker',
    type: 'text',
    actions: [
      {
        type: 'buy',
        text: 'Buy vinegar',
        amount: 8000
      }
    ]
}).then(() => {
    // async code
});

Arguments
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 object containing any custom properties associated with the action. See the metadata schema for more information.

Postback

A postback action will post the action payload to the server.

Send postback action:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/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-account-jwt'

smooch.appUsers.sendMessage('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', {
    text: 'Just put some vinegar on it',
    role: 'appMaker',
    type: 'text',
    actions: [
      {
        type: 'postback',
        text: 'Buy vinegar',
        payload: 'buy_vinegar'
      }
    ]
}).then(() => {
    // async code
});

Arguments
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 object containing any custom properties associated with the action. See the metadata schema for more information.

Reply

A reply action will echo the user’s choice as a message.
You may optionally specify an iconUrl which will render as an icon for each option.

Send reply action:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'
     -d '
{
    "text":"Which do you prefer?",
    "role": "appMaker",
    "type": "text",
    "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('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', {
    text: 'Which do you prefer?',
    type: 'text',
    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
});

Arguments
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 object containing any custom properties associated with the action. See the metadata schema for more information.

reply type actions can be sent either alone or with location request actions. If an action of a different type is included in the message, it will be rejected.

Facebook Messenger Facebook Messenger reply icons

Web Messenger Web Messenger reply icons

Location Request

A location request action will prompt the user to share their location. See Channel capabilities for the list of supported channels. Unsupported clients will receive text fallback: “YourApp has requested a location”.

Send locationRequest action:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -d '{"text":"Where are you?", "role": "appMaker", "type": "text", "actions": [{"type": "locationRequest", "text": "Send Location"}]}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.appUsers.sendMessage('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', {
    text: 'Where are you?',
    role: 'appMaker',
    type: 'text',
    actions: [
      {
        type: 'locationRequest',
        text: 'Send Location'
      }
    ]
}).then(() => {
    // async code
});

Arguments
text required	The button text.
type required	`locationRequest`
metadata optional	Flat object containing any custom properties associated with the action. See the metadata schema for more information.

locationRequest type actions can be sent either alone or with reply actions. If an action of a different type is included in the message, it will be rejected.

Actions in a message item may also include a share button.

Send share action:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H "authorization: Bearer your-account-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('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', {
    text: 'Title',
    role: 'appMaker',
    type: 'carousel',
    items: [{
      title: 'Title',
      actions: [{
        type: 'share'
      }]
    }]
}).then(() => {
    // async code
});

messenger carousel

Arguments
type required	`share`
metadata optional	Flat object containing any custom properties associated with the action. See the metadata schema for more information.

Channel Targeting

A business can choose which channel to deliver a message to. To do this, include a destination object in the message payload and provide one of the following:

Arguments
integrationId optional	The integration id. See List Integrations
integrationType optional	The integration type. See List Integrations

Note that for this to work, the user needs to have a client linked to the targeted channel.

Get Messages

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appUsers/c7f6e6d6c3a637261bd9656f/messages?before=1471995721 \
     -H 'authorization: your-account-jwt'

smooch.appUsers.getMessages('5963c0d619a30a2e00de36b8', '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/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages?after=1471995721"
}

GET /v1/apps/{appId}/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).

Delete Messages

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X DELETE \
     -H 'authorization: Bearer your-account-jwt'

smooch.appUsers.deleteMessages('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f').then(() => {
    // async code
});

Response:

200 OK

DELETE /v1/apps/{appId}/appusers/{smoochId|userId}/messages

Clears the message history for a user, permanently deleting all messages, but leaving any connections to Messaging Channels and Business Systems intact. These connections allow for the conversation to continue in the future, while still being associated to the same appUser.

Upload Attachment

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/attachments?access=public \
     -X POST \
     -H 'authorization: Bearer your-account-jwt' \
     -H 'content-type: multipart/form-data' \     
     -F 'source=@document.pdf;type=application/pdf'

var file = fileInput.files[0];
smooch.attachments.create('5963c0d619a30a2e00de36b8', 'public', file).then(() => {
    // async code
});

Response:

201 CREATED

{
  "mediaUrl": "https://media.smooch.io/apps/c7f6e6d6c3a637261bd9656f/a77caae4cbbd263a0938eba00016b7c8/document.pdf",
  "mediaType": "application/pdf"
}

POST /v1/apps/{appId}/attachments?access={access}

Upload an attachment to Smooch to use in future messages. Files are uploaded using the multipart/form-data content type. Use the returned mediaUrl and mediaType to send file messages.

Form Parameters
source required	The attachment data, provided as a readable file stream.

Query Parameters
access required	The access level for the attachment. Currently the only available access level is `public`

Upload and Send Image (Deprecated)

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/images \
     -X POST \
     -H 'authorization: your-account-jwt' \
     -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('5963c0d619a30a2e00de36b8', '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
  }
}

This API is deprecated. It is recommended that you use the upload attachment API then attach the resulting mediaUrl and mediaType to an image type message.

POST /v1/apps/{appId}/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`.

Typing Activity

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/conversation/activity \
     -X POST \
     -d '{"role":"appMaker", "type": "typing:start"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.appUsers.typingActivity('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', {
    role: 'appMaker',
    type: 'typing:start'
}).then(() => {
    // async code
});

Response:

200 OK

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

POST /v1/apps/{appId}/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

Reset Unread Count

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/conversation/read \
     -X POST \
     -H 'authorization: your-account-jwt'

smooch.conversations.resetUnreadCount('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f').then(() => {
    // async code
});

Response:

200 OK

POST /v1/apps/{appId}/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.

Schema

Message schema

This table represents the fields you can expect to receive in a webhook payload’s message, or in the response to a GET Messages API call.

Field	Description
_id	The unique ID for the message.
text	The message text.
role	The role of the message sender. `"appUser"`, `"appMaker"`, or `"whisper"`.
authorId	The appUser’s _id if the message `role` is `"appUser"`, otherwise, a hash based on the appMaker’s email address.
name optional	The appUser’s friendly name, or an optionally provided appMaker name.
received	A unix timestamp given in seconds, describing when Smooch received the message.
source	A nested object describing the source of the message. See the source schema below for details.
avatarUrl optional	The URL for an image of the appMaker.
type	`"text"`, `"image"`, `"file"`, `"carousel"`, `"location"`, or `"list"`.
actions optional	An array of objects representing the actions associated with the message. See the action schema below for details.
mediaUrl optional	The URL for media, such as an image, attached to the message.
mediaType optional	The MIME type for any media attached in the mediaUrl.
coordinates optional	A nested object describing the coordinates sent by an appUser. Only present in a `"location"` type message. See the coordinates schema below for details.

Source/Destination schema

Data representing the source or destination of a message, whether an appUser or appMaker message.

Field	Description
type	An identifier for the channel from which a message originated. May include one of `"web"`, `"ios"`, `"android"`, `"messenger"`, `"viber"`, `"telegram"`, `"wechat"`, `"line"`, `"twilio"`, `"frontendEmail"`, `"api"`, or any number of other channels.
id optional	An identifier used by Smooch for internal purposes.

Coordinates schema

Data representing a location sent by the appUser.

Field	Description
_id	The unique ID of the coordinates item.
lat	Global latitude.
long	Global longitude.

Action schema

This table represents the fields you can expect to receive nested inside postback or message data, in a webhook payload, or in the response to a GET Messages API call.

Field	Description
_id	A canonical ID.
type	`"link"`, `"reply"`, `"postback"`, `"share"`, `"location"`, or `"buy"`.
uri optional	The URI for a link type button, a checkout page for buy type buttons. May also be an empty string.
text optional	The button text.
payload optional	The payload of a postback or reply button.
amount optional	An integer representing an amount of money in hundredths of a dollar (or equivalent in other currencies).
currency optional	An ISO 4217 standard currency code in lowercase.
state optional	The value “offered”, or “paid” sent with a buy action type.

Referral schema

Data representing a referral object when a user is referred to a conversation via a Messenger code, clicking a conversion ad on Facebook, or scanning a parametric QR code event on WeChat.

Field	Description
code	The referral’s identifier. Available in referrals from WeChat and Messenger
details optional	Nested object containing additional information. Only available on Messenger. See the referral details schema for more details

Referral details schema

Field	Description
source	The source of the referral. Ex: `MESSENGER_CODE`, `ADS` etc… Only available on Messenger
type	The type of referral, typically `OPEN-THREAD`. Only available on Messenger
adId optional	If the referral came from an ad, this field will be present with the ad’s Id. Only available on Messenger

Metadata schema

Data representing an optional flat object sent as an argument of a POST Message API call containing additional properties associated with the message. Metadata can be attached to the message itself and to optional Action Buttons like links or postbacks. The metadata properties are sent back to the appMaker in the appropriate payload delivered through webhook.

Strings, numbers and booleans are the only supported format that can be passed to metadata.

Persistent Menus

Smooch provides an API to set persistent menus on messaging channels that support custom menus in their chat UIs (Facebook Messenger and WeChat). Menus can be configured on a per-app basis and on a per-integration basis.

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/menu \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.menu.get('5963c0d619a30a2e00de36b8', '5963c0d619a30a2e00de36b8')
.then(() => {
    // async code
});

Response:

200 OK

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

GET /v1/apps/{appId}/menu

Get the specified app’s menu.

Request:

curl https://api.smooch.io/v1/apps/5963c0d619a30a2e00de36b8/menu \
     -X PUT \
     -d '{"items": [{"type": "link", "text": "Smooch", "uri": "http://smooch.io"}]}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.menu.configure('5963c0d619a30a2e00de36b8', {
    items: [{
        type: 'link',
        text: 'Smooch',
        uri: 'http://smooch.io'
    }]
})
.then(() => {
    // async code
});

Response:

200 OK

{
    "menu": {
        "items": [{
            "type": "link",
            "text": "Smooch",
            "uri": "http://smooch.io",
            "_id": "57b331fbf1c6aeba1f940dc7"
        }]
    }
}

PUT /v1/apps/{appId}/menu

Configure the specified app’s menu. See the persistent menu schema for possible options.

Request:

curl https://api.smooch.io/v1/menu \
     -X DELETE \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.menu.remove('5963c0d619a30a2e00de36b8')
.then(() => {
    // async code
});

Response:

200 OK

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

DELETE /v1/apps/{appId}/menu

Remove the specified app’s menu.

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/menu \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.menu.get('55c8d9758590aa1900b9b9f6', '5735dded48011972d621dc02')
.then(() => {
    // async code
});

Response:

200 OK

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

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

Get the specified integration’s menu.

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/menu \
     -X PUT \
     -d '{"items": [{"type": "link", "text": "Smooch", "uri": "http://smooch.io"}]}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.menu.update('55c8d9758590aa1900b9b9f6', '5735dded48011972d621dc02', {
    items: [{
        type: 'link',
        text: 'Smooch',
        uri: 'http://smooch.io'
    }]
}).then(() => {
    // async code
});

Response:

200 OK

{
    "menu": {
        "items": [{
            "type": "link",
            "text": "Smooch",
            "uri": "http://smooch.io",
            "_id": "57b331fbf1c6aeba1f940dc7"
        }]
    }
}

PUT /v1/apps/{appId}/integrations/{integrationId}/menu

Set the specified integration’s menu, overriding the app menu if configured. See the persistent menu schema for possible options.

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/menu \
     -X DELETE \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.menu.delete('55c8d9758590aa1900b9b9f6', '5735dded48011972d621dc02')
.then(() => {
    // async code
});

Response:

200 OK

{}

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

Remove the specified integration’s menu, falling back to the app menu if configured.

Schema

Arguments
items required	A list of menu items. See menu items for more detail.
settings optional	An optional object for menu settings. See menu settings for more detail.

Menus contain 1 to 3 menu items at its first level of hierarchy. Submenus contain 1 to 5 menu items.

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

A business can modify whether to have its chat text input enabled or not by including an optional settings object.

Arguments
inputEnabled required	Specifies whether the text input should be enabled or not. Defaults to `true`. This feature is only supported in Facebook Messenger

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

# Calling GET /v1/appusers using an account scoped jwt
        curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/appusers/c7f6e6d6c3a637261bd9656f \
             -H 'authorization: Bearer your-account-jwt'

// Initializing Smooch Core with an account scoped key
var smooch = new SmoochCore({
    keyId: 'your-account-key-id',
    secret: 'your-account-secret-key',
    scope: 'account'
});

// Retrieving an appUser when authed with account scope
smooch.appUsers.get('55c8d9758590aa1900b9b9f6', 'c7f6e6d6c3a637261bd9656f').then((response) => {
    // async code
});

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

App schema and endpoints used for provisioning Smooch apps.

Create App

Request:

curl https://api.smooch.io/v1/apps \
     -X POST \
     -d '{"name": "My App", "settings": {"maskCreditCardNumbers": false}}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'

smooch.apps.create({
    name: 'My App',
    settings: {
      maskCreditCardNumbers: false
    }    
}).then((response) => {
    // async code
});

Response:

201 CREATED

{
  "app": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
    "name": "My App",
    "settings": {
      "maskCreditCardNumbers": false
    }    
  }
}

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.
settings	Customizable app settings (see app settings).

List Apps

Request:

  curl https://api.smooch.io/v1/apps \
       -H 'authorization: Bearer your-account-token'

smooch.apps.list().then((response) => {
    // async code
});

Response:

200 OK

{
  "apps": [
        {
          "_id": "55c8d9758590aa1900b9b9f6",
          "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
          "name": "My App",
          "settings": {
            "maskCreditCardNumbers": true
          }          
        }
    ],
    "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'

smooch.apps.get('55c8d9758590aa1900b9b9f6').then((response) => {
    // async code
});

Response:

200 OK

{
  "app": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
    "name": "My App",
    "settings": {
      "maskCreditCardNumbers": true
    }
  }
}

GET /v1/apps/{appId}

Fetches an individual app.

Update App

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6 \
     -X PUT \
     -d '{"name": "My New App", "settings": {"maskCreditCardNumbers": false}}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'

smooch.apps.update('55c8d9758590aa1900b9b9f6', {
  name: 'My New App',
  settings: {
    maskCreditCardNumbers: false
  }
}).then((response) => {
    // async code
});

Response:

200 OK

{
  "app": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
    "name": "My New App",
    "settings": {
      "maskCreditCardNumbers": false
    }
  }
}

PUT /v1/apps/{appId}

Updates an app.

Arguments
name required	The User facing name of the app.
settings	Customizable app settings (see app settings).

Delete App

Request:

  curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6 \
       -X DELETE \
       -H 'authorization: Bearer your-account-token'

smooch.apps.delete('55c8d9758590aa1900b9b9f6').then((response) => {
    // async code
});

Response:

200 OK

{}

DELETE /v1/apps/{appId}

Removes the specified app, including all its enabled integrations.

Schema

App schema

The schema describes the fields you can expect to be associated with an app.

Field	Description
_id	A canonical ID that can be used to reference the Smooch app that the event is associated with.
appToken	A public token that can be used to initialize Smooch’s mobile and Web SDKs and authorize API calls on behalf of appUsers who haven’t been secured by JWT.
name	the friendly name of the app.
settings	Customizable app settings (see app settings).

App settings

The customizable settings associated with an app.

Field	Description
maskCreditCardNumbers	A boolean specifying whether credit card numbers should be masked when sent through Smooch.

Truncated app schema

A truncated version of the app sent with webhook payloads.

Field	Description
_id	A canonical ID that can be used to reference the Smooch app that the event is associated with.

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'

smooch.apps.keys.create('55c8d9758590aa1900b9b9f6', 'key1').then((response) => {
    // async code
});

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'

smooch.apps.keys.list('55c8d9758590aa1900b9b9f6').then((response) => {
    // async code
});

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'

smooch.apps.keys.get('55c8d9758590aa1900b9b9f6', 'app_5723a347f82ba0516cb4ea34').then((response) => {
    // async code
});

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'

smooch.apps.keys.delete('55c8d9758590aa1900b9b9f6', 'app_5723a347f82ba0516cb4ea34').then((response) => {
    // async code
});

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'

smooch.apps.keys.getJwt('55c8d9758590aa1900b9b9f6', 'app_5723a347f82ba0516cb4ea34').then((response) => {
    // async code
});

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 or app scope.

The supported integration types are: Facebook Messenger, Twitter DM, LINE, Telegram, Twilio SMS, WeChat, Viber and Mailgun.

Create Integration

POST /v1/apps/{appId}/integrations

The Create Integration endpoint 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-jwt'

smooch.integrations.create('55c8d9758590aa1900b9b9f6', {
    type: 'messenger',
    pageAccessToken: 'your_access_token',
    appId: 'your_fb_app_id',
    appSecret: 'your_fb_app_secret'
}).then((response) => {
    // async code
});

Response:

201 CREATED

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

Facebook Messenger Setup steps:

Take note of your Facebook app ID and secret (apps can be created at developer.facebook.com);
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.

Twitter DM

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{ "type": "twitter", "consumerKey": "your_consumer_key", "consumerSecret": "your_consumer_secret", "accessTokenKey": "your_access_token_key", "accessTokenSecret": "your_access_token_secret" }' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.create('55c8d9758590aa1900b9b9f6', {
    type: 'twitter',
    consumerKey: 'your_consumer_key',
    consumerSecret: 'your_consumer_secret',
    accessTokenKey: 'your_access_token_key',
    accessTokenSecret: 'your_access_token_secret'
}).then((response) => {
    // async code
});

Response:

201 CREATED

{
  "integration": {
    "_id": "58ecfde7e2aa9fda95fa122c",
    "type": "twitter",
    "userId": "0000000000",
    "username": "Mike Mikeson",
    "accessTokenKey": "your_access_token_key",
    "consumerKey": "your_consumer_key"
  }
}

Twitter DM Setup steps:

Take note of your Twitter consumer key and secret (apps can be created at apps.twitter.com).
Your app must have been whitelisted with Twitter for access to the Account Activity API.

In order to create a Twitter DM integration you must acquire an Access Token Key and Secret from your user. These can be obtained via the Twitter OAuth Flow. Once you have acquired an access token pair from your user, call the Create Integration endpoint with your consumer key and secret, and the user’s access token pair.

Arguments
type required	The integration type: twitter.
consumerKey required	The consumer key for your Twitter app
consumerSecret required	The consumer key secret for your Twitter app
accessTokenKey required	The access token key obtained from your user via oauth
accessTokenSecret required	The access token secret obtained from your user via oauth

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-jwt'

smooch.integrations.create('55c8d9758590aa1900b9b9f6', {
    type: 'twilio',
    accountSid: 'ACa1b4c65ee0722712fab89867cb14eac7',
    authToken: '160c024303f53049e1e060fd67ca6aefc',
    phoneNumberSid: 'PN0674df0ecee0c9819bca0ff0bc0a159e'
}).then((response) => {
    // async code
});

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.

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-jwt'

smooch.integrations.create('55c8d9758590aa1900b9b9f6', {
    type: 'telegram',
    token: '192033615:AAEuee2FS2JYKWfDlTulfygjaIGJi4s'
}).then((response) => {
    // async code
});

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-jwt'

smooch.integrations.create('55c8d9758590aa1900b9b9f6', {
    type: 'line',
    channelAccessToken: 'jZak8gGEYxfy1gIxk869os...',
    channelSecret: 'b85cff984b26eac4297917abd365c4d6'
}).then((response) => {
    // async code
});

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-jwt'

smooch.integrations.create('55c8d9758590aa1900b9b9f6', {
    type: 'viber',
    token: 'df5f8c5233399561-926...'
}).then((response) => {
    // async code
});

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-jwt'

smooch.integrations.create('55c8d9758590aa1900b9b9f6', {
    type: 'wechat',
    appId: 'ACa1b4c65ee0722712fab89867cb14eac7',
    appSecret: '160c024303f53049e1e060fd67ca6aefc'
}).then((response) => {
    // async code
});

Response:

201 CREATED

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

To configure a WeChat integration, browse to the Develop section of the WeChat dashboard and add the following IP addresses to the whitelist, separated by new lines. This must be done before calling the Create Integration endpoint.

34.224.190.28

52.6.201.31

52.0.232.16

From the same page, 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.

Mailgun

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "mailgun", "apiKey": "key-f265hj32f0sd897lqd2j5keb96784043", "domain": "sandbox123.mailgun.org",  "incomingAddress": "mytestemail@sandbox123.mailgun.org"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.create('55c8d9758590aa1900b9b9f6', {
    type: 'mailgun',
    apiKey: 'key-f265hj32f0sd897lqd2j5keb96784043',
    domain: 'sandbox123.mailgun.org',
    incomingAddress: 'mytestemail@sandbox123.mailgun.org'
}).then((response) => {
    // async code
});

Response:

201 CREATED

{
    "integration": {
        "type": "mailgun",
        "domain": "sandbox123.mailgun.org",
        "incomingAddress": "mytestemail@sandbox123.mailgun.org",
        "_id": "58adf047b90af0f747cff1d2"
    }
}

To configure a Mailgun integration, visit the API Keys tab in the settings page of the Mailgun dashboard and copy your active API key. Call the Create Integration endpoint with your API Key, a domain you have configured in Mailgun, and the incoming address you would like to use.

Arguments
type required	The integration type: mailgun.
apiKey required	The public API key of your Mailgun account.
domain required	The domain used to relay email. This domain must be configured and verified in your Mailgun account.
incomingAddress required	Smooch will receive all emails sent to this address. It will also be used as the Reply-To address.

Note: The incomingAddress must have the same domain as the one specified in the domain parameter.

MessageBird

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "messagebird", "accessKey": "V0oSoktDijjGiAof265hj32fh", "originator": "12262121021"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.create('55c8d9758590aa1900b9b9f6', {
    type: 'messagebird',
    accessKey: 'V0oSoktDijjGiAof265hj32fh',
    originator: '12262121021'
}).then((response) => {
    // async code
});

Response:

201 CREATED

{
    "integration": {
        "type": "messagebird",
        "webhookSecret": "72ade38394d1da51566cede33bd1e67e",
        "originator": "12262121021",
        "_id": "594850b82e4a8e5e04ef2a11"
    }
}

To configure a MessageBird integration, acquire the accessKey and the MessageBird number you would like to use, then call the Create Integration endpoint.

In the SMS Configurations of the MessageBird number you’ve used to integrate, add a new rule with the following settings:

If [Always], Then Forward to URL and POST. Then, enter the following into the URL field: https://app.smooch.io/api/messagebird/webhooks/:appId/:integrationId/:webhookSecret

Arguments
type required	The integration type: messagebird.
accessKey required	The public API key of your MessageBird account.
originator required	Smooch will receive all messages sent to this phone number.

Apple Push Notification

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "apn", "certificate": "HjkUD4rWvZj7wSDzA8Hu2hd7ICs274Z=="}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.create('55c8d9758590aa1900b9b9f6', {
    type: 'apn',
    certificate: 'HjkUD4rWvZj7wSDzA8Hu2hd7ICs274Z=='
}).then((response) => {
    // async code
});

Response:

201 CREATED

{
  "integration": {
    "type": "apn",
    "_id": "58878a8842fadcdb7b70b74c",
    "production": false,
    "autoUpdateBadge": false
  }
}

To configure an Apple Push Notification integration, call the create integration endpoint with a base64 encoded Apple Push Notification certificate from the Apple Developer Portal.

Arguments
type required	The integration type: apn.
certificate required	The binary of your APN certificate base64 encoded.
password optional	The password for your APN certificate.
autoUpdateBadge optional	Use the unread count of the conversation as the application badge. true/false

To base64 encode your certificate you can use this command in the terminal: openssl base64 -in YOUR_CERTIFICATE.p12 | tr -d '\n'

In Node.js:

fs.readFile('path/to/your/certificate.p12', function(err, data) {
    const base64Cert = data.toString('base64');
})

Firebase Cloud Messaging

Request:

curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "fcm", "serverKey": "AAAA_hSf4g2J2Q3zDh2DbvSh27dhKlm2", "senderId": "1429457686312"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.create('55c8d9758590aa1900b9b9f6', {
    type: 'fcm',
    serverKey: 'AAAA_hSf4g2J2Q3zDh2DbvSh27dhKlm2',
    senderId: '1429457686312'
}).then((response) => {
    // async code
});

Response:

201 CREATED

{
  "integration": {
    "_id": "5876a3d4abf286d0c0af1467",
    "type": "fcm",
    "senderId": "1429457686312"
  }
}

To configure a Firebase Cloud Messaging integration, first visit the Firebase Console. Copy the serverKey and senderId from the Cloud Messaging tab in the settings of your project and call the create integrations endpoint with this data.

If you would like to continue using your legacy GCM serverKey you can also obtain it from the Google Developer Console.

Arguments
type required	The integration type: fcm.
serverKey required	Your server key from the fcm console.
senderId required	Your sender id from the fcm console.

List Integrations

Request:

  curl https://api.smooch.io/v1/apps/55c8d9758590aa1900b9b9f6/integrations \
       -H 'authorization: Bearer your-account-jwt'

smooch.integrations.list('55c8d9758590aa1900b9b9f6').then((response) => {
    // async code
});

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, twitter, line, telegram, twilio, mailgun, wechat, and viber. 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-jwt'

smooch.integrations.get('55c8d9758590aa1900b9b9f6', '5735dded48011972d621dc02').then((response) => {
    // async code
});

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-jwt'

smooch.integrations.delete('55c8d9758590aa1900b9b9f6', '5735dded48011972d621dc02').then((response) => {
    // async code
});

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.

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

Get 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 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/apps/*	No
/v1/integrations/*	No
/v1/menu/*	No

Revoke Access

Request:

curl -X DELETE https://api.smooch.io/oauth/authorization \
     -H 'authorization: Bearer your-token'

// This endpoint is not currently wrapped in a JavaScript lib

Response:

200 OK

DELETE https://app.smooch.io/oauth/authorization

This endpoint is used to revoke your integration’s access to the user’s Smooch app. Revoking access means your integration will no longer be able to interact with the app, and any webhooks the integration had previously configured will be removed.

Calling this endpoint is equivalent to the user removing your integration manually in the Smooch web app. Your integration’s removeUrl (if configured) will also be called when an integration is removed in this way.

Core

Introduction

Basics

API Libraries

Errors

Rate Limits

Deprecations

Authorization

Authentication

Header

Scope

Resource Paths

Webhooks

Webhook triggers

Manage Webhooks

Create webhook

List webhooks

Get webhook

Update webhook

Delete webhook

Message Events

Trigger - message:appUser (text)

Message event payload schema

Trigger - message:appUser (image)

Trigger - message:appMaker (carousel)

Trigger - message:appMaker (list)

Trigger - message:appUser (location)

Postback Events

Trigger - postback

Postback event payload schema

Postback schema

Conversation Events

Trigger - conversation:read

Conversation event payload schema

Trigger - conversation:start

Trigger - conversation:referral

Conversation referral payload schema

Merge Events

Trigger - merge:appUser

Merge events payload

Delivery Events

Trigger - delivery:success

Delivery event payload schema

Trigger - delivery:failure

Error schema

Payment Events

Trigger - payment:success

Payment event payload schema

Payment schema

Charge schema

Link Events

Trigger - link:success

Link success event payload schema

Trigger - link:match

Link match event payload schema

Trigger - link:failure

Link failure event payload schema

Securing a webhook

Retry Policy

Non-recoverable Errors

Init

Devices are a type of client

Device Info

App User

userId

Get App User

Update App User

Delete User Profile

Update Device

Track Event

Pre-Create App User

Get App User Channel Entities

Link App User To Channel

Linking confirmation

Immediate

User activity

Prompt

Linkable channels and entities

Unlink App User From Channel

Schema

Trigger - `message:appUser` (text)

Trigger - `message:appUser` (image)

Trigger - `message:appMaker` (carousel)

Trigger - `message:appMaker` (list)

Trigger - `message:appUser` (location)

Trigger - `postback`

Trigger - `conversation:read`

Trigger - `conversation:start`

Trigger - `conversation:referral`

Trigger - `merge:appUser`

Trigger - `delivery:success`

Trigger - `delivery:failure`

Trigger - `payment:success`

Trigger - `link:success`

Trigger - `link:match`

Trigger - `link:failure`