NAV Navbar

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.

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 an object. Depending on context, resources may be returned as single objects or as arrays of objects, nested within the response object.

In some cases, the API will also facilitate cross-origin resource sharing so that it can be called from a web application.

Regions

# Use US region (default)
export SMOOCH_ROOT=https://api.smooch.io

# Use EU region
export SMOOCH_ROOT=https://api.eu-1.smooch.io
// Use US region (default)
const smooch = new SmoochCore({
    keyId: 'your-key-id',
    secret: 'your-secret',
    scope: 'app' // account or app
});

// Use EU region
const smooch = new SmoochCore({
    keyId: 'your-key-id',
    secret: 'your-secret',
    scope: 'app', // account or app
    serviceUrl: 'https://api.eu-1.smooch.io'
});

Smooch is available in the following regions. Each Smooch region has its own API host.

Region Host
United States https://api.smooch.io
European Union https://api.eu-1.smooch.io

For more information on regions, visit the guide.

API Version

The latest version of the API is v1.1. Version v1 is still supported and you can continue using it but we encourage you to upgrade to the latest version. To learn more about API versioning at Smooch, including instructions on how to upgrade to the latest version, visit our docs.

API Libraries

Smooch provides official API libraries for JavaScript, Ruby, Python and Java. These helpful libraries wrap calls to the API and can make interfacing with Smooch easier.

Postman Collection

In addition to api libraries, Smooch also has a Postman collection that can be used for development or testing purposes. See the guide for information on how to install and use the collection in your Postman client.

Errors

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

Smooch uses standard HTTP status codes to communicate errors. In general, a 2xx status code indicates success while 4xx indicates an error, in which case, the response body includes a JSON error object, with a text code and description containing more details. A 5xx status code indicates that something went wrong on our end.

Code Status Description
bad_request 400 Something in your header or request body was malformed.
not_an_image 400 Smooch was expecting an URL to an image, but got something else.
payments_not_configured 400 A buy action was attempted but target channels do not support payments.
invalid_syntax 400 The provided shorthand syntax contains an error.
invalid_auth 401 Submitted credentials are either missing or malformed.
unauthorized 401 Insufficient credentials for access to the requested resource.
payment_required 402 The action is not available on your payment plan, or you have exceeded usage limits for your current plan.
trial_expired 402 Your API trial has expired.
forbidden 403 Your credentials are valid but you don’t have access to the requested resource.
not_found
user_not_found
app_not_found
app_maker_not_found
integration_not_found
client_not_found
menu_not_found
conversation_not_found
webhook_not_found
processor_not_found
message_not_found
route_not_found
404 The object you’re requesting doesn’t exist.
request_entity_too_large 413 The request body exceeds the maximum allowed size.
conflict 409 You might be trying to update the same resource concurrently.
locked 423 The requested resource is temporarily unavailable.
too_many_requests 429 You are calling our APIs more frequently than we allow.
5xx Something went wrong on our end.

Rate Limits

Smooch APIs are subject to rate limiting. If the rate limit is exceeded Smooch may return 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 not encounter them, however usage spikes do occur and encountering a rate limit may be unavoidable. In order to avoid production outages, when calling the Smooch API you should implement 429 retry logic using exponential backoff and jitter.

If your use case involves making API calls in bulk, please contact us.

Request Size Limits

The Smooch API imposes the following size limits on HTTP requests:

Request Type Limit
JSON 100kb
File upload 25mb

Authorization

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

Smooch allows basic authentication or JSON Web Tokens (JWTs) as authentication methods for server-to-server calls. See below for more details.

There are two different authorization scopes available - app and account.

Scope Authorized Methods
app All Core methods
account All Core and Account Provisioning methods

The app scope can be used to access any of the Smooch Core APIs on behalf of a single app, or any app user related to that app.

The account scope can be used to access any of the Smooch Core and Account Provisioning APIs on behalf of the account owner, any app belonging to the account, or any app user related to those apps.

Authentication

To authenticate requests to the API, you will need an API key, composed of a key id and a secret.

For an overview of how authentication works in Smooch and instructions on how to generate an API key, see the guide.

API requests can be authenticated in two ways:

Before using an API key in produciton, make sure to familiarize yourself with best practices on how to securely handle credentials.

Basic Authentication

# Calling GET /v1/appusers using basic authentication
curl $SMOOCH_ROOT/v1/appusers/c7f6e6d6c3a637261bd9656f \
     --user keyId:secret

API requests can be authenticated with basic authentication using an API key. The key id is used as the username and the secret as the password.

The scope of access is determined by the owner of the API key. See the guide for more details.

JWTs

# Calling GET /v1.1/appusers using a JWT
curl $SMOOCH_ROOT/v1.1/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'authorization: Bearer your-jwt'
// Initializing Smooch Core in Node.js
var smooch = new SmoochCore({
    keyId: 'your-key-id',
    secret: 'your-secret',
    scope: 'app' // account or app
});

JSON Web Tokens (JWTs) are an industry standard authentication method. 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 generate a JWT, you need an API key, which is composed of a key ID and a secret. The key ID is included in a JWT’s header, as the kid property, while the secret is used to sign the JWT.

For more in-depth coverage, see the guide.

JWT header:

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

The JWT header must contain the key id (kid) of the API key that is used to sign it. The algorithm (alg) used should be HS256. Unsigned JWTs are not accepted.

Payload

JWT payload with account scope:

{
    "scope": "account"
}

JWT payload with app scope claim:

{
    "scope": "app"
}

The JWT payload must include a scope claim which specifies the caller’s scope of access.

Resource Paths

Resource path with account scope API key example

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
     --user 'keyId:keySecret'
smooch.appUsers
    .get({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f'
    })
    .then((response) => {
        // async code
    });

Resource path with app scope API key example

curl $SMOOCH_ROOT/v1.1/appusers/c7f6e6d6c3a637261bd9656f \
     --user 'keyId:keySecret'
smooch.appUsers
    .get({
        userId: 'c7f6e6d6c3a637261bd9656f'
    })
    .then((response) => {
        // async code
    });

The app resource is implicitly defined when using basic authentication or JWTs with app API keys. However, most Smooch REST API users will use an account scoped API key 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.

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.

Basic Triggers

trigger
message:appUser only messages with role appUser
message:appMaker only messages with role appMaker
message:delivery:channel when a message is successfully delivered to a customer channel
message:delivery:user when a message is successfully delivered to the user’s device
message:delivery:failure when a message fails to be delivered to a customer channel or the user’s device
appUser:delete when an app user is deleted through the Delete App User endpoint
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
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
client:add when a new client has been added to an existing user
client:remove when a new client has been removed from an existing user
* when any of the above basic triggers occurs

Additional Triggers

In addition to the basic triggers above, there are some additional triggers that are not included in the wildcard trigger (*), and must be subscribed to explicitly.

trigger
typing:appUser when a user starts or stops typing

Manage Webhooks

Smooch exposes REST API methods to:

Create webhook

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks \
     -X POST \
     -d '{"target": "http://example.com/callback", "triggers": ["message:appUser"], "includeClient": true}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.webhooks
    .create('5963c0d619a30a2e00de36b8', {
        target: 'http://example.com/callback',
        triggers: ['message:appUser'],
        includeClient: true
    })
    .then((response) => {
        // async code
    });

Response:

201 CREATED
{
    "webhook": {
        "_id": "55c8d9758590aa1900b9b9f6",
        "includeClient": true,
        "includeFullAppUser": true,
        "triggers": ["message:appUser"],
        "secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
        "target": "http://example.com/callback",
        "version": "v1.1"
    }
}

POST /v1.1/apps/{appId}/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
required
An array of triggers you wish to have the webhook listen to. This property is case sensitive. More details.
includeClient
optional
A boolean specifying whether webhook payloads should include the client information associated with a conversation in webhook events.
includeFullAppUser
optional
A boolean specifying whether webhook payloads should include the complete appUser schema for appUser events.

List webhooks

Request:

  curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks \
       --user 'keyId:keySecret'
smooch.webhooks.list('5963c0d619a30a2e00de36b8').then((response) => {
    // async code
});

Response:

200 OK
{
    "webhooks": [
        {
            "_id": "55c8d9758590aa1900b9b9f6",
            "includeClient": false,
            "includeFullAppUser": true,
            "triggers": ["message:appUser", "message:delivery:failure"],
            "secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
            "target": "http://example.com/callback",
            "version": "v1.1"
        }
    ]
}

GET /v1.1/apps/{appId}/webhooks

List all webhooks configured for a given app.

Get webhook

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks/55c8d9758590aa1900b9b9f6 \
     --user 'keyId:keySecret'
smooch.webhooks.get('5963c0d619a30a2e00de36b8', '55c8d9758590aa1900b9b9f6').then((response) => {
    // async code
});

Response:

200 OK
{
    "webhook": {
        "_id": "55c8d9758590aa1900b9b9f6",
        "includeClient": false,
        "includeFullAppUser": true,
        "triggers": ["message:appUser", "message:delivery:failure"],
        "secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
        "target": "http://example.com/callback",
        "version": "v1.1"
    }
}

GET /v1.1/apps/{appId}/webhooks/{webhookId}

Individual webhooks can be fetched using this API.

Update webhook

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks/55c8d9758590aa1900b9b9f6 \
     -X PUT \
     -d '{"target": "http://example.com/callback", "includeClient": true}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.webhooks
    .update('5963c0d619a30a2e00de36b8', '55c8d9758590aa1900b9b9f6', {
        target: 'http://example.com/callback',
        includeClient: true
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "webhook": {
        "_id": "55c8d9758590aa1900b9b9f6",
        "includeClient": true,
        "includeFullAppUser": true,
        "triggers": ["message:appUser", "message:delivery:failure"],
        "secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
        "target": "http://example.com/callback",
        "version": "v1.1"
    }
}

PUT /v1.1/apps/{appId}/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.
includeClient
optional
A boolean specifying whether webhook payloads should include the client information associated with a conversation in webhook events.
includeFullAppUser
optional
A boolean specifying whether webhook payloads should include the complete appUser schema for appUser events.

Delete webhook

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks/55c8d9758590aa1900b9b9f6 \
     -X DELETE \
     --user 'keyId:keySecret'
smooch.webhooks.delete('5963c0d619a30a2e00de36b8', '55c8d9758590aa1900b9b9f6').then(() => {
    // async code
});

Response:

200 OK

DELETE /v1.1/apps/{appId}/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",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "client": {
        "_id": "5c9d2f34a1d3a2504bc89511",
        "lastSeen": "2019-04-05T18:23:20.791Z",
        "platform": "web",
        "id": "20b2be30cf7e4152865f066930cbb5b2",
        "info": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "raw": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "active": true,
        "primary": true,
        "integrationId": "5c3640f8cd3fa5850931a954"
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "version": "v1.1"
}

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 truncated appUser schema below for details.
conversation A nested object representing the conversation associated with the event. See the truncated conversation schema below for details.
client A nested object representing the current client associated with the conversation of the event. This field is only included when includeClient on webhook settings is set. See the client schema for detail.
version The API version used to create the webhook. See API version 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",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "client": {
        "_id": "5c9d2f34a1d3a2504bc89511",
        "lastSeen": "2019-04-05T18:23:20.791Z",
        "platform": "web",
        "id": "20b2be30cf7e4152865f066930cbb5b2",
        "info": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "raw": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "active": true,
        "primary": true,
        "integrationId": "5c3640f8cd3fa5850931a954"
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "version": "v1.1"
}

The payload for an image message.

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",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "client": {
        "_id": "5c9d2f34a1d3a2504bc89511",
        "lastSeen": "2019-04-05T18:23:20.791Z",
        "platform": "web",
        "id": "20b2be30cf7e4152865f066930cbb5b2",
        "info": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "raw": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "active": true,
        "primary": true,
        "integrationId": "5c3640f8cd3fa5850931a954"
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "version": "v1.1"
}

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",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "client": {
        "_id": "5c9d2f34a1d3a2504bc89511",
        "lastSeen": "2019-04-05T18:23:20.791Z",
        "platform": "web",
        "id": "20b2be30cf7e4152865f066930cbb5b2",
        "info": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "raw": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "active": true,
        "primary": true,
        "integrationId": "5c3640f8cd3fa5850931a954"
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "version": "v1.1"
}

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",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "client": {
        "_id": "5c9d2f34a1d3a2504bc89511",
        "lastSeen": "2019-04-05T18:23:20.791Z",
        "platform": "web",
        "id": "20b2be30cf7e4152865f066930cbb5b2",
        "info": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "raw": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "active": true,
        "primary": true,
        "integrationId": "5c3640f8cd3fa5850931a954"
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "version": "v1.1"
}

The payload for a location message.

Trigger - message:appUser (file)

Payload:

{
    "trigger": "message:appUser",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "messages": [
        {
            "_id": "55c8c1498590aa1900b9b9b1",
            "type": "file",
            "mediaUrl": "https://some-pdf-file.pdf",
            "mediaType": "application/pdf",
            "mediaSize": 123456,
            "role": "appUser",
            "authorId": "c7f6e6d6c3a637261bd9656f",
            "name": "Steve",
            "received": 1444348338.704,
            "source": {
                "type": "android",
                "id": "604018c259285f82a746c44ef0368a7f44d4af6a"
            }
        }
    ],
    "appUser": {
        "_id": "c7f6e6d6c3a637261bd9656f",
        "userId": "bob@example.com",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "client": {
        "_id": "5c9d2f34a1d3a2504bc89511",
        "lastSeen": "2019-04-05T18:23:20.791Z",
        "platform": "web",
        "id": "20b2be30cf7e4152865f066930cbb5b2",
        "info": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "raw": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "active": true,
        "primary": true,
        "integrationId": "5c3640f8cd3fa5850931a954"
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "version": "v1.1"
}

The payload for a file message.

Trigger - message:appUser (file as text - deprecated)

File as text payload:

{
    "trigger": "message:appUser",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "messages": [
        {
            "_id": "55c8c1498590aa1900b9b9b1",
            "type": "text",
            "text": "File upload: https://some-pdf-file.pdf",
            "role": "appUser",
            "authorId": "c7f6e6d6c3a637261bd9656f",
            "name": "Steve",
            "received": 1444348338.704,
            "source": {
                "type": "messenger"
            }
        }
    ],
    "appUser": {
        "_id": "c7f6e6d6c3a637261bd9656f",
        "userId": "bob@example.com",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "client": {
        "_id": "5c9d2f34a1d3a2504bc89511",
        "lastSeen": "2019-04-05T18:23:20.791Z",
        "platform": "web",
        "id": "20b2be30cf7e4152865f066930cbb5b2",
        "info": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "raw": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "active": true,
        "primary": true,
        "integrationId": "5c3640f8cd3fa5850931a954"
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "version": "v1.1"
}

A message webhook of type file will only be sent when the appUser sends a message from the Web, iOS or Android SDKs. For all other channels, a text message webhook will be sent with the file url embedded in the text.

Trigger - message:appMaker (form)

Payload:

{
    "trigger": "message:appMaker",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "messages": [
        {
            "blockChatInput": true,
            "fields": [
                {
                    "type": "text",
                    "name": "full_name",
                    "label": "Your name?",
                    "placeholder": "Type your name...",
                    "minSize": 1,
                    "maxSize": 30,
                    "_id": "5cd1f4c5ba7361ecr43e87e5"
                },
                {
                    "type": "email",
                    "name": "email_address",
                    "label": "Your email?",
                    "placeholder": "email@example.com",
                    "_id": "5cd1f4c5ba1s41e12c0e87e4"
                },
                {
                    "type": "select",
                    "name": "meal_selection",
                    "label": "Your meal?",
                    "selectSize": 1,
                    "options": [
                        {
                            "name": "pizza",
                            "label": "Pizza",
                            "_id": "5cd1f4c5ba7361iu7c0e87e3"
                        },
                        {
                            "name": "tacos",
                            "label": "Tacos",
                            "_id": "5cd1f4c5ba7361e1tr0e87e2"
                        },
                        {
                            "name": "ramen",
                            "label": "Ramen",
                            "_id": "5cd1f4c5ba7361ebvd0e87e1"
                        }
                    ],
                    "_id": "5cd1f4c5ba73bve12c0e87e0"
                }
            ],
            "_id": "55c8c1498590aa1900b9b9b1",
            "type": "form",
            "role": "appMaker",
            "submitted": false,
            "authorId": "2cKU9zRO2DpBWgk764Tfro",
            "avatarUrl": "https://www.gravatar.com/avatar/5e543256c480ac577d30f76f9120eb74.png?s=200&d=mm",
            "received": 1444348338.704,
            "source": {
                "type": "api"
            }
        }
    ],
    "appUser": {
        "_id": "c7f6e6d6c3a637261bd9656f",
        "conversationStarted": true,
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": {}
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "version": "v1.1"
}

The payload for a form message.

Trigger - message:appUser (formResponse)

Payload:

{
    "trigger": "message:appUser",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "messages": [
        {
            "fields": [
                {
                    "type": "text",
                    "name": "full_name",
                    "label": "Your name?",
                    "text": "Ed Wright",
                    "_id": "5cd1f4c5ba7361ecr43e87n1"
                },
                {
                    "type": "email",
                    "name": "email_address",
                    "label": "Your email?",
                    "email": "edw@mail.com",
                    "_id": "5cd1f4c5ba1s41e12c0e87n0"
                },
                {
                    "type": "select",
                    "name": "meal_selection",
                    "label": "Your meal?",
                    "select": [
                        {
                            "name": "ramen",
                            "label": "Ramen",
                            "_id": "5cd1f4c5ba7361ebvd0e87n9"
                        }
                    ],
                    "_id": "5cd1f4c5ba73bve12c0e8740"
                }
            ],
            "_id": "55c8c1498590aa1900b9b9p0",
            "type": "formResponse",
            "role": "appUser",
            "name": "Web User 24p5c1cdl710bf95f2d5ed70",
            "authorId": "c7f6e6d6c3a637261bd9656f",
            "received": 1444348338.909,
            "textFallback": "Your name?: Ed Wright\nYour Email?: edw@mail.com\nYour Meal?: Ramen",
            "source": {
                "type": "web"
            },
            "quotedMessage": {
                "type": "message",
                "content": {
                    "blockChatInput": true,
                    "fields": [
                        {
                            "text": "Ed Wright",
                            "type": "text",
                            "name": "full_name",
                            "label": "Your name?",
                            "placeholder": "Type your name...",
                            "minSize": 1,
                            "maxSize": 30,
                            "_id": "5cd1f4c5ba7361ecr43e87e5"
                        },
                        {
                            "email": "edw@mail.com",
                            "type": "email",
                            "name": "email_address",
                            "label": "Your email?",
                            "placeholder": "email@example.com",
                            "_id": "5cd1f4c5ba1s41e12c0e87e4"
                        },
                        {
                            "select": [
                                {
                                    "name": "ramen",
                                    "label": "Ramen",
                                    "_id": "5cd1f4c5ba7361iu7c0e87e6"
                                }
                            ],
                            "type": "select",
                            "name": "meal_selection",
                            "label": "Your meal?",
                            "selectSize": 1,
                            "options": [
                                {
                                    "name": "pizza",
                                    "label": "Pizza",
                                    "_id": "5cd1f4c5ba7361iu7c0e87e3"
                                },
                                {
                                    "name": "tacos",
                                    "label": "Tacos",
                                    "_id": "5cd1f4c5ba7361e1tr0e87e2"
                                },
                                {
                                    "name": "ramen",
                                    "label": "Ramen",
                                    "_id": "5cd1f4c5ba7361ebvd0e87e1"
                                }
                            ],
                            "_id": "5cd1f4c5ba73bve12c0e87e0"
                        }
                    ],
                    "_id": "55c8c1498590aa1900b9b9b1",
                    "type": "form",
                    "role": "appMaker",
                    "submitted": true,
                    "authorId": "2cKU9zRO2DpBWgk764Tfro",
                    "avatarUrl": "https://www.gravatar.com/avatar/5e543256c480ac577d30f76f9120eb74.png?s=200&d=mm",
                    "received": 1444348338.704,
                    "source": {
                        "type": "api"
                    }
                }
            }
        }
    ],
    "appUser": {
        "_id": "c7f6e6d6c3a637261bd9656f",
        "conversationStarted": true,
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": {}
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "version": "v1.1"
}

The payload for a formResponse message.

AppUser Events

Trigger - appUser:delete

Payload:

{
    "trigger": "appUser:delete",
    "app": {
        "_id": "575040549a38df8fb4eb1e51"
    },
    "appUser": {
        "_id": "de13bee15b51033b34162411",
        "userId": "123",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "version": "v1.1"
}

An appUser:delete webhook triggers when an app user is deleted through the Delete App User endpoint.

appUser:delete event payload schema

Field Description
trigger "appUser:delete"
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 truncated appUser associated with the event. See the truncated appUser schema below for details.
version The API version used to create the webhook. See API version for details.

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": "Yes",
                "payload": "YES"
            }
        }
    ],
    "appUser": {
        "_id": "c7f6e6d6c3a637261bd9656f",
        "userId": "bob@example.com",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "client": {
        "_id": "5c9d2f34a1d3a2504bc89511",
        "lastSeen": "2019-04-05T18:23:20.791Z",
        "platform": "web",
        "id": "20b2be30cf7e4152865f066930cbb5b2",
        "info": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "raw": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "active": true,
        "primary": true,
        "integrationId": "5c3640f8cd3fa5850931a954"
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "version": "v1.1"
}

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 truncated appUser schema below for details.
client A nested object representing the current client associated with the conversation of the event. This field is only included when includeClient on webhook settings is set. See the client schema for detail.
conversation A nested object representing the conversation associated with the event. See the truncated conversation 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.
metadata optional Flat object containing any custom properties associated with the action. See the metadata schema for more information.

Conversation Events

Trigger - conversation:read

Payload:

{
    "trigger": "conversation:read",
    "app": {
        "_id": "57ec2881c47d2d24b0c16427"
    },
    "source": {
        "type": "messenger"
    },
    "appUser": {
        "_id": "7685787bf0e9e8cf56182288",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "client": {
        "_id": "5c9d2f34a1d3a2504bc89511",
        "lastSeen": "2019-04-05T18:23:20.791Z",
        "platform": "web",
        "id": "20b2be30cf7e4152865f066930cbb5b2",
        "info": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "raw": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "active": true,
        "primary": true,
        "integrationId": "5c3640f8cd3fa5850931a954"
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "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 associated with the event. See the truncated appUser schema below for details.
client A nested object representing the current client associated with the conversation of the event. This field is only included when includeClient on webhook settings is set. See the client schema for detail.
conversation A nested object representing the conversation associated with the event. See the truncated conversation schema below for details.
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.
version The API version used to create the webhook. See API version for details.

Trigger - conversation:start

Payload:

{
    "trigger": "conversation:start",
    "app": {
        "_id": "57ec2881c47d2d24b0c16427"
    },
    "source": {
        "type": "messenger"
    },
    "appUser": {
        "_id": "c7f6e6d6c3a637261bd9656f",
        "userId": "bob@example.com",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "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:

Trigger - conversation:referral

Payload:

{
    "trigger": "conversation:referral",
    "app": {
        "_id": "589b7811d626a6d76d6b8555"
    },
    "source": {
        "type": "messenger"
    },
    "appUser": {
        "_id": "4a5f73a36a7b818c2643296f",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "client": {
        "_id": "5c9d2f34a1d3a2504bc89511",
        "lastSeen": "2019-04-05T18:23:20.791Z",
        "platform": "web",
        "id": "20b2be30cf7e4152865f066930cbb5b2",
        "info": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "raw": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "active": true,
        "primary": true,
        "integrationId": "5c3640f8cd3fa5850931a954"
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "referral": {
        "code": "my-ref-code",
        "details": {
            "source": "MESSENGER_CODE",
            "type": "OPEN_THREAD"
        }
    },
    "timestamp": 1495650348.685,
    "version": "v1.1"
}

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 nested object representing the appUser associated with the event. See the truncated appUser schema below for details.
client A nested object representing the current client associated with the conversation of the event. This field is only included when includeClient on webhook settings is set. See the client schema for detail.
conversation A nested object representing the conversation associated with the event. See the truncated conversation schema below for details.
referral Referral information. See referral schema for details.
version The API version used to create the webhook. See API version 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:

Merge Events

Trigger - merge:appUser

Payload:

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

The payload for when two users are merged into one. See the user merging guide for more information about merges, the conditions that can trigger a merge, and what to do in response to a merge event.

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 object. 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.
discardedProperties A nested object with the set of properties that were discarded when merging the two appUsers. This should contain values only if the combined properties exceed the 4KB limit.
version The API version used to create the webhook. See API version for details.
discardedConversationId optional The Id of the discarded conversation, if any.

Message Delivery Events

Delivery events expose the delivery steps that a message takes to be delivered to a user:

See the delivery events guide for more information.

Note that each delivery webhook is guaranteed to trigger at-most-once per message._id and destination.type combination. In other words, it’s possible for a Smooch message to be delivered to many channels, but it can only be delivered once per channel. To understand how Smooch selects the channel(s) to which a message is delivered, see Automatic message delivery.

Delivery event payload schema

Field Description
trigger "message:delivery:channel" or "message:delivery:user" or "message:delivery: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 truncated appUser associated with the event. See the truncated appUser schema below for details.
conversation A nested object representing the conversation associated with the event. See the truncated conversation schema below for details.
destination A nested object representing the destination of the message. See the destination schema below for details.
message An object representing the message associated with the event. See the truncated message schema below for details.
externalMessages optional An array of objects representing the third-party messages associated with the event. See the external message schema below for details. The order of the external messages is not guaranteed to be the same across the different triggers. Note that some channels don’t expose message IDs, in which case this field will be unset.
timestamp A unix timestamp given in seconds, describing when the delivery event occurred.
isFinalEvent A boolean indicating whether the webhook is the final one for the message._id and destination.type pair.
error
optional
A nested object, present in message:delivery:failure event, representing the error associated with the delivery failure. See the error schema below for details.

External message schema

Field Description
id A string representing the ID of the external message.

Error schema

Field Description
code A string representing the error code associated with the error. See below for a list of possible values.
underlyingError optional A object with the error data returned by the channel a message was meant to be delivered to.
message optional The description associated with the error.

If an error cannot be categorized, the code will be uncategorized_error. Otherwise, the error will have a more specific code.

code Description
aborted The delivery wasn’t attempted.
blocked The app user has unsubscribed from the channel.
bad_request The channel rejected the Smooch request because of a bad request.
not_found The channel indicated that the target user cannot be found.
rate_limited The channel has rate-limited the delivery of the message.
service_internal_error The channel has returned a service internal error.
service_unavailable The channel is unavailable. This might indicate that the channel is down.
unauthorized The delivery failed because the integration is not authorized. This might indicate that there is a configuration issue with your integration.
uncategorized_error The channel has marked the message as failed, but Smooch couldn’t map it to a specific error.

Trigger - message:delivery:channel

Payload:

{
    "trigger": "message:delivery:channel",
    "app": {
        "_id": "5a5ccf0d1b4077001a36b11d"
    },
    "appUser": {
        "_id": "b234f6a69d2eea3589f4c24e",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "destination": {
        "type": "twilio"
    },
    "isFinalEvent": false,
    "externalMessages": [
        {
            "id": "SMb0ee6ee1313a4141ba346e368325a04d"
        }
    ],
    "message": {
        "_id": "5baa5b4ab5bebb000ce85589"
    },
    "timestamp": 1537891147.555,
    "version": "v1.1"
}

The message:delivery:channel webhook reports the success to handoff a message to a channel.

If isFinalEvent property of the payload is true, no additional delivery event (message:delivery:*) will be sent for the message._id and destination.type pair.

If isFinalEvent is false, another message:delivery:* webhook with the same message._id and destination.type pair is expected, but not guaranteed.

Trigger - message:delivery:user

Payload:

{
    "trigger": "message:delivery:user",
    "app": {
        "_id": "5a5ccf0d1b4077001a36b11d"
    },
    "appUser": {
        "_id": "b234f6a69d2eea3589f4c24e",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "destination": {
        "type": "twilio"
    },
    "isFinalEvent": true,
    "externalMessages": [
        {
            "id": "SMb0ee6ee1313a4141ba346e368325a04d"
        }
    ],
    "message": {
        "_id": "5baa5b4ab5bebb000ce85589"
    },
    "timestamp": 1537891147.555,
    "version": "v1.1"
}

The message:delivery:user webhook confirms the delivery of a message to the user.

Trigger - message:delivery:failure

Payload:

{
    "trigger": "message:delivery:failure",
    "app": {
        "_id": "575040549a38df8fb4eb1e51"
    },
    "appUser": {
        "_id": "de13bee15b51033b34162411",
        "userId": "123",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "destination": {
        "type": "line"
    },
    "isFinalEvent": true,
    "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."
        }
    },
    "message": {
        "_id": "5baa610db5bebb000ce855d6"
    },
    "timestamp": 1480001711.941,
    "version": "v1.1"
}

The message:delivery:failure webhook reports the failure to deliver a message to a user on the destination channel. If this webhook triggers, it means that the message did not reach the user.

Payment Events

Trigger - payment:success

Payload:

{
    "trigger": "payment:success",
    "app": {
        "_id": "571e3496cb98b3962ce740d7"
    },
    "appUser": {
        "_id": "2b15a54fde9dc2f33f88bc25",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "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,
    "version": "v1.1"
}

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.
conversation A nested object representing the conversation associated with the event. See the truncated conversation 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.
version The API version used to create the webhook. See API version for details.

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.
version The API version used to create the webhook. See API version for details.

Charge schema

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

Trigger - link:success

Payload:

{
    "trigger": "link:success",
    "app": {
        "_id": "58b487c74ebf3ce5d4b38e5f"
    },
    "appUser": {
        "_id": "8215a086b271592e01b74e28",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "channel": "messenger",
    "integrationId": "5a99b74858247c608f64a348",
    "criteria": {
        "phoneNumber": "+15141234567",
        "givenName": "bleep",
        "surname": "bloop"
    },
    "version": "v1.1"
}

The payload for a link app user success.

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.
conversation A nested object representing the conversation associated with the event. See the truncated conversation schema below for details.
channel The channel for which the link succeeded.
integrationId The ID of the integration for which the link succeeded.
criteria The criteria specified to establish the link.
version The API version used to create the webhook. See API version for details.

Trigger - link:match

Payload:

{
    "trigger": "link:match",
    "app": {
        "_id": "58b487c74ebf3ce5d4b38e5f"
    },
    "appUser": {
        "_id": "8215a086b271592e01b74e28",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "channel": "messenger",
    "integrationId": "5a99b74858247c608f64a348",
    "criteria": {
        "phoneNumber": "+15141234567",
        "givenName": "bleep",
        "surname": "bloop"
    },
    "version": "v1.1"
}

The payload for a link app user match.

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.
conversation A nested object representing the conversation associated with the event. See the truncated conversation schema below for details.
channel The channel for which the link matched.
integrationId The ID of the integration 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",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "error": {
        "code": "bad_request",
        "message": "(#100) No matching user found"
    },
    "channel": "messenger",
    "integrationId": "5a99b74858247c608f64a348",
    "criteria": {
        "phoneNumber": "+15141234567",
        "givenName": "bleep",
        "surname": "bloop"
    },
    "version": "v1.1"
}

The payload for a link app user failure.

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.
conversation A nested object representing the conversation associated with the event. See the truncated conversation schema below for details.
channel The channel for which the link failed.
integrationId The ID of the integration 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.

Client Events

Trigger - client:add

Payload:

{
    "trigger": "client:add",
    "app": {
        "_id": "575040549a38df8fb4eb1e51"
    },
    "version": "v1.1",
    "appUser": {
        "_id": "de13bee15b51033b34162411",
        "userId": "123",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "clients": [
        {
            "_id": "5c93cb748f63db54ff3b51dd",
            "status": "active",
            "integrationId": "5a99b74858247c608f64a348",
            "externalId": "1128837457239041",
            "id": "bea02e14-86f4-4711-8ecc-ab717ebf750a",
            "displayName": "Sue Purb",
            "info": {
                "gender": "female",
                "timezone": -5,
                "locale": "en_US",
                "avatarUrl": "https://scontent.xx.fbcdn.net/example.png"
            },
            "lastSeen": "2019-01-14T19:11:17.783Z",
            "linkedAt": "2019-01-14T19:11:17.783Z",
            "primary": true,
            "platform": "messenger",
            "active": true,
            "blocked": false
        }
    ]
}

A client:add webhook triggers when a client is added to an existing appUser. This can occur as a result of a login, channel link, or when an SDK consumes an auth code.

In channel linking cases the client:add event only fires when the link has been completed. For example, if a user declines when prompted to link Facebook Messenger, client:add will not trigger. Link failures such as this can be detected with the link:failure trigger.

Exceptions:

Smooch automatically creates new appUsers upon receipt of their first message. In these cases, a client:add event does not fire. New users created in this way should be recognized via the message:appUser trigger, which includes the client object in the payload.

An existing client might also be moved from one appUser to another as a result of a merge. In this case, a merge:appUser event is signalled in lieu of a client:add event.

client:add event payload schema

Field Description
trigger "client:add"
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 truncated appUser associated with the event. See the truncated appUser schema below for details.
clients An array of client objects that have just been added to the appUser. See the client schema below for details.
version The API version used to create the webhook. See API version for details.

Trigger - client:remove

Payload:

{
    "trigger": "client:remove",
    "app": {
        "_id": "575040549a38df8fb4eb1e51"
    },
    "appUser": {
        "_id": "de13bee15b51033b34162411",
        "userId": "123",
        "conversationStarted": true,
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "clients": [
        {
            "_id": "5c93cb748f63db54ff3b51dd",
            "id": "90e2f396500b451dabdce69f207247d4"
        }
    ],
    "version": "v1.1"
}

A client:remove webhook triggers when a client is removed from an existing appUser. This can happen when a channel is unlinked via the channel API.

A channel link action might also cause an existing third party client to change ownership from one appUser to another. In this case both a client:remove and client:add trigger will be fired.

client:remove event payload schema

Field Description
trigger "client:remove"
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 truncated appUser associated with the event. See the truncated appUser schema below for details.
clients An array of client objects that have just been removed from the appUser. These objects contain the removed client id only.

Typing Events

Trigger - typing:appUser

Payload:

{
    "trigger": "typing:appUser",
    "app": {
        "_id": "5698edbf2a43bd081be982f1"
    },
    "timestamp": 1510848814.349,
    "appUser": {
        "_id": "56bfa6add1683d0e0c7e5956",
        "email": "steve.bob@email.com",
        "surname": "Steve",
        "givenName": "Bob",
        "signedUpAt": "2018-04-02T14:45:46.505Z",
        "properties": { "favoriteFood": "prizza" }
    },
    "client": {
        "_id": "5c9d2f34a1d3a2504bc89511",
        "lastSeen": "2019-04-05T18:23:20.791Z",
        "platform": "web",
        "id": "20b2be30cf7e4152865f066930cbb5b2",
        "info": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "raw": {
            "currentTitle": "Conversation Demo",
            "currentUrl": "https://examples.com/awesomechat",
            "browserLanguage": "en-US",
            "referrer": "",
            "userAgent":
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "URL": "examples.com",
            "sdkVersion": "4.17.12",
            "vendor": "smooch"
        },
        "active": true,
        "primary": true,
        "integrationId": "5c3640f8cd3fa5850931a954"
    },
    "conversation": {
        "_id": "105e47578be874292d365ee8"
    },
    "activity": {
        "type": "typing:stop"
    },
    "source": {
        "type": "ios"
    },
    "version": "v1.1"
}

A typing:appUser webhook triggers when an appUser starts or stops typing a response on a supported channel.

typing:appUser event payload schema

Field Description
trigger "typing:appUser"
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 truncated appUser associated with the event. See the truncated appUser schema below for details.
conversation A nested object representing the conversation associated with the event. See the truncated conversation schema below for details.
client A nested object representing the current client associated with the conversation of the event. This field is only included when includeClient on webhook settings is set. See the client schema for detail.
source A nested object representing the source of the event. See the source schema below for details.
timestamp A unix timestamp given in seconds, describing when Smooch received the event.
activity A nested object representing the type of activity that triggered the event. Contains a field type with value typing:start or typing:stop.
version The API version used to create the webhook. See API version for details.

Securing Smooch Webhooks

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:

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.1/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 associate Smooch users with an external user directory, and to synchronize a single conversation across multiple clients. To understand how this works, see the section covering user authentication.

Profile properties

Profile properties, also referred to as custom properties, are a set of key/value pairs that are specific to your application domain, or use case. These fields are stored under the properties field of an appUser, and can have values of type Number, String, or Boolean. For more information, see the section covering user information management.

Get App User

Request by smoochId:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
     --user 'keyId:keySecret'
smooch.appUsers
    .get({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f'
    })
    .then((response) => {
        // async code
    });

Request by userId:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/steveb@channel5.com \
     --user 'keyId:keySecret'
smooch.appUsers
    .get({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'steveb@channel5.com'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "appUser": {
        "_id": "7494535bff5cef41a15be74d",
        "userId": "steveb@channel5.com",
        "givenName": "Steve",
        "signedUpAt": "2019-01-14T18:55:12.515Z",
        "hasPaymentInfo": false,
        "conversationStarted": false,
        "clients": [
            {
                "_id": "5c93cb748f63db54ff3b51dd",
                "status": "active",
                "lastSeen": "2019-01-14T16:55:59.364Z",
                "platform": "ios",
                "id": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
                "deviceId": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
                "pushNotificationToken": "<0cfc626c 9fed1e3d e9fcb139 e6590cb3 3462f3c8 afd47000 6af2003f 2e3a72a9>",
                "appVersion": "1.0",
                "info": {
                    "appId": "com.rp.ShellApp",
                    "carrier": "Rogers",
                    "buildNumber": "1.0",
                    "devicePlatform": "iPhone8,4",
                    "installer": "Dev",
                    "sdkVersion": "6.11.2",
                    "osVersion": "12.1.2",
                    "appName": "ShellApp",
                    "os": "iOS",
                    "vendor": "smooch"
                },
                "raw": {
                    "appId": "com.rp.ShellApp",
                    "carrier": "Rogers",
                    "buildNumber": "1.0",
                    "devicePlatform": "iPhone8,4",
                    "installer": "Dev",
                    "sdkVersion": "6.11.2",
                    "osVersion": "12.1.2",
                    "appName": "ShellApp",
                    "os": "iOS",
                    "vendor": "smooch"
                },
                "active": true,
                "primary": false,
                "integrationId": "599ad41e49db6e243ad77d2f"
            }
        ],
        "pendingClients": [],
        "properties": {
            "favoriteFood": "prizza"
        }
    }
}

GET /v1.1/apps/{appId}/appusers/{smoochId|userId}

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

Update App User

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
     -X PUT \
     -d '{"givenName": "Steve"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.appUsers
    .update({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        appUser: {
            givenName: 'Steve'
        }
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "appUser": {
        "_id": "7494535bff5cef41a15be74d",
        "userId": "steveb@channel5.com",
        "givenName": "Steve",
        "signedUpAt": "2019-01-14T18:55:12.515Z",
        "hasPaymentInfo": false,
        "conversationStarted": false,
        "clients": [
            {
                "_id": "5c93cb748f63db54ff3b51dd",
                "status": "active",
                "lastSeen": "2019-01-14T16:55:59.364Z",
                "platform": "ios",
                "id": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
                "deviceId": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
                "pushNotificationToken": "<0cfc626c 9fed1e3d e9fcb139 e6590cb3 3462f3c8 afd47000 6af2003f 2e3a72a9>",
                "appVersion": "1.0",
                "info": {
                    "appId": "com.rp.ShellApp",
                    "carrier": "Rogers",
                    "buildNumber": "1.0",
                    "devicePlatform": "iPhone8,4",
                    "installer": "Dev",
                    "sdkVersion": "6.11.2",
                    "osVersion": "12.1.2",
                    "appName": "ShellApp",
                    "os": "iOS",
                    "vendor": "smooch"
                },
                "raw": {
                    "appId": "com.rp.ShellApp",
                    "carrier": "Rogers",
                    "buildNumber": "1.0",
                    "devicePlatform": "iPhone8,4",
                    "installer": "Dev",
                    "sdkVersion": "6.11.2",
                    "osVersion": "12.1.2",
                    "appName": "ShellApp",
                    "os": "iOS",
                    "vendor": "smooch"
                },
                "active": true,
                "primary": false,
                "integrationId": "599ad41e49db6e243ad77d2f"
            }
        ],
        "pendingClients": [],
        "properties": {
            "favoriteFood": "prizza"
        }
    }
}

PUT /v1.1/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 App User Profile

Request by smoochId:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/profile \
     -X DELETE \
     --user 'keyId:keySecret'
smooch.appUsers
    .deleteProfile({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f'
    })
    .then((response) => {
        // async code
    });

Request by userId:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/steveb@channel5.com/profile \
     -X DELETE \
     --user 'keyId:keySecret'
smooch.appUsers
    .deleteProfile({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'steveb@channel5.com'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "appUser": {
        "_id": "7494535bff5cef41a15be74d",
        "userId": "steveb@channel5.com",
        "signedUpAt": "2019-01-14T18:55:12.515Z",
        "hasPaymentInfo": false,
        "conversationStarted": false,
        "clients": [
            {
                "_id": "5c93cb748f63db54ff3b51dd",
                "status": "active",
                "lastSeen": "2019-01-14T16:55:59.364Z",
                "platform": "ios",
                "id": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
                "deviceId": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
                "pushNotificationToken": "<0cfc626c 9fed1e3d e9fcb139 e6590cb3 3462f3c8 afd47000 6af2003f 2e3a72a9>",
                "active": true,
                "primary": false,
                "integrationId": "599ad41e49db6e243ad77d2f"
            }
        ],
        "pendingClients": [],
        "properties": {}
    }
}

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

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

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

Calling this API doesn’t delete the app user’s conversation history. To fully delete the app user, see Delete App User.

Delete App User

Request by smoochId:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
     -X DELETE \
     --user 'keyId:keySecret'
smooch.appUsers
    .delete({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f'
    })
    .then((response) => {
        // async code
    });

Request by userId:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/steveb@channel5.com \
     -X DELETE \
     --user 'keyId:keySecret'
smooch.appUsers
    .delete({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'steveb@channel5.com'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{}

DELETE /v1.1/apps/{appId}/appusers/{smoochId|userId}

Delete an app user, its clients and its conversation history. The app user is considered completely deleted once the appUser:delete webhook is fired.

To only delete an app user’s profile, see Delete App User Profile.

Pre-Create App User

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers \
     -X POST \
     -d '{"userId": "steveb@channel5.com", "givenName": "Steve", "properties": {"favoriteFood": "prizza"}}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.appUsers
    .create({
        appId: '5963c0d619a30a2e00de36b8',
        appUser: {
            userId: 'steveb@channel5.com',
            givenName: 'Steve',
            properties: {
                favoriteFood: 'prizza'
            }
        }
    })
    .then((response) => {
        // async code
    });

Response:

201 CREATED
{
    "appUser": {
        "_id": "f316d285a6642a32adbdcd84",
        "userId": "steveb@channel5.com",
        "givenName": "Steve",
        "signedUpAt": "2019-01-14T18:55:12.515Z",
        "hasPaymentInfo": false,
        "conversationStarted": false,
        "clients": [],
        "pendingClients": [],
        "properties": {
            "favoriteFood": "prizza"
        }
    }
}

POST /v1.1/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.
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 automatically created by the Smooch SDKs or Messaging Channel integrations. 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 login 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.1/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 login with the same userId, they will see their conversation history.

Get App User Channel Entities (Deprecated)

Request:

curl https https://api.smooch.io/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/channels \
    --user 'keyId:keySecret'
smooch.appUsers
    .getChannels({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'deb920657bbc3adc3fec7963'
    })
    .then((response) => {
        //Async code
    });

Response:

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

GET /v1.1/apps/{appId}/appusers/{smoochId|userId}/channels

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

Entity ID Responses

Channel Type Entity ID
messenger
viber
line
wechat
twitter
userId
A string representing a messenger, viber, line, wechat or twitter user ID.
twilio
messagebird
phoneNumber
A string representing a twilio or messageBird phone number.
mailgun address
A string representing an email address for mailgun.
telegram chatId
A string representing the chat ID for telegram.
whatsapp username
A string representing the username of the user for whatsapp.

Get App User Business System IDs

Request:

curl https https://api.smooch.io/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/businesssystems \
    --user 'keyId:keySecret'
smooch.appUsers
    .getBusinessSystems({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'deb920657bbc3adc3fec7963'
    })
    .then((response) => {
        //Async code
    });

Response:

200 OK
{
    "businessSystems": [
        {
            "type": "slack",
            "channelId": "C872AE91B"
        },
        {
            "type": "zendesk",
            "ticketId": "9999"
        },
        {
            "type": "helpscout",
            "conversationId": "123456"
        }
    ]
}

GET /v1.1/apps/{appId}/appusers/{smoochId|userId}/businesssystems

Retrieves all the business systems an appUser’s conversation is connected to.

Business system response properties

Channel Type ID Name
slack channelId
A string representing the Slack channel ID.
zendesk ticketId
A string representing a Zendesk ticket ID.
helpscout conversationId
A string representing the Helpscout conversation ID.

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/channels \
     -X POST \
     -d '{"type": "twilio", "confirmation": {"type": "prompt"}, "phoneNumber": "+15145555555"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.appUsers
    .linkChannel({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'steveb@channel5.com',
        data: {
            type: 'twilio',
            phoneNumber: '+15145555555',
            confirmation: {
                type: 'prompt'
            }
        }
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "appUser": {
        "_id": "7494535bff5cef41a15be74d",
        "userId": "steveb@channel5.com",
        "givenName": "Steve",
        "signedUpAt": "2019-01-14T18:55:12.515Z",
        "hasPaymentInfo": false,
        "conversationStarted": false,
        "clients": [],
        "pendingClients": [
            {
                "_id": "5c93cb748f63db54ff3b51dd",
                "integrationId": "5a3174ee84c71521fa415ca9",
                "id": "4afa71ce-20ea-4971-841f-357630a1f970",
                "platform": "twilio",
                "status": "pending"
            }
        ],
        "properties": {
            "favoriteFood": "prizza"
        }
    }
}

POST /v1.1/apps/{appId}/appusers/{smoochId|userId}/channels

Arguments
type
required
The channel to link. Can be twilio, messagebird, mailgun or whatsapp. The channel messenger is also valid, but since it’s in early access, you need to contact Smooch to enable it.
integrationId
optional
The integration to link. Must match the provided type.
{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.

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.

Immediate

Available on: Twilio, MessageBird, Messenger, Mailgun, WhatsApp

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, MessageBird, Messenger, WhatsApp

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, MessageBird

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’, ‘MessageBird’, ‘Mailgun’ and ‘Messenger’ for now.

Channel type Required entity Extra properties
twilio, messagebird, whatsapp 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}”

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/channels/twilio \
     -X DELETE \
     --user 'keyId:keySecret'
smooch.appUsers
    .unlinkChannel({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'steveb@channel5.com',
        channel: 'twilio'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK

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

Removes the specified channel from the appUser’s clients. The client is considered completely removed once the client:remove webhook is fired.

Get Auth Code

GET /v1.1/apps/{appId}/appusers/{smoochId|userId}/authcode

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/authcode \
     -X GET \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.appUsers
    .getAuthCode({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'deb920657bbc3adc3fec7963'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "authCode": "ac_tXcqhnHSgaZuzeOB8ndiL7A5"
}

Users can begin their communication over a third party channel such as Facebook Messenger. Using an auth code, you can transfer such users' conversations over to an SDK channel hosted on your website or mobile app. The user can then continue their conversation in a medium that offers more freedom for the business to customize the user’s experience.

For more information, see the Channel transfer guide.

GET /v1.1/apps/{appId}/appusers/{smoochId|userId}/linkrequest

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/linkrequest?integrationIds=59dbd737f294ea1fa2734829,59fa19888b1dd03638d2dd54,5a00d5b3002ef2a871aaef98 \
     -X GET \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.appUsers
    .getLinkRequests({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'deb920657bbc3adc3fec7963',
        integrationIds: ['59dbd737f294ea1fa2734829, 59fa19888b1dd03638d2dd54, 5a00d5b3002ef2a871aaef98']
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "linkRequests": [{
        "integrationId": "59dbd737f294ea1fa2734829",
        "type": "messenger",
        "code": "lr_K4DBnWEiWv6LR-CP0j_5FFcl",
        "url": "https://m.me/123456781234567?ref=lr_K4DBnWEiWv6LR-CP0j_5FFcl"
    },
    {
        "integrationId": "59fa19888b1dd03638d2dd54",
        "type": "telegram",
        "code": "lr_Xidl9tTWt6YVXP8SFD3hdUiD",
        "url": "https://telegram.me/your_telegram_bot?start=lr_Xidl9tTWt6YVXP8SFD3hdUiD"
    },
    {
        "integrationId": "5a00d5b3002ef2a871aaef98",
        "type": "viber",
        "code": "lr_6p3awZLOQWk-6AmOYocLeFq5",
        "url": "viber://pa?chatURI=YourViberAccount&context=lr_6p3awZLOQWk-6AmOYocLeFq5"
    }]
}
Query Parameter Description
integrationIds Comma separated list of integration ids.

A user who begins their conversation via one of the Smooch SDKs may wish to transfer the conversation to a different preferred channel. For example, a user may leave you a message on your website and ask to be notified by Facebook as soon as you respond.

The link request API facilitates this transfer. The API will generate a transfer URL designed to work for a given channel type. When a user clicks or taps this link they will be connected to your business presence on the given channel. Smooch embeds a one time code in the URL that allows the channel to be securely linked to the user’s existing Smooch identity. Messages sent over this new channel will also be synchronized with the user’s existing conversation.

Multiple link requests can be made at once so that you may render them as a list of options for the user to choose from.

Link requests are currently supported by Facebook Messenger, Telegram, and Viber channels.

Channel Link URL works on:
Facebook Messenger browser, mobile
Telegram browser, mobile
Viber mobile (Viber app must be installed)

Merge Users

POST /v1.1/apps/{appId}/appusers/merge

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/merge \
     -X POST \
     -d '{"surviving": {"_id": "afa567114fdb04f5da925d6b"}, "discarded": {"_id": "decbf2d33e2940abe873fde3"}}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.appUsers
    .mergeUsers({
        appId: '5963c0d619a30a2e00de36b8',
        props: {
            surviving: {
                _id: 'afa567114fdb04f5da925d6b'
            },
            discarded: {
                _id: 'decbf2d33e2940abe873fde3'
            }
        }
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{}

Force the merge of two specific users, when the business has determined that they represent the same person. See the user merging guide for more information about merges.

When the operation is complete, a merge:appUser webhook event will be fired as confirmation of the merge.

Arguments
surviving
required
Nested object representing the user that will survive at the end of the merge. See merged user schema below.
discarded
required
Nested object representing the user to merge into the surviving user. This user will be deleted as part of the process. See merged user schema below.

Merged User Schema

Arguments
id
required
The _id of the user to merge.

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)
conversationStarted A boolean representing of whether a message has been sent 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.
email
optional
appUser’s email, not included when includeFullAppUser is unset in webhook settings.
surname
optional
appUser’s surname, not included when includeFullAppUser is unset in webhook settings.
givenName
optional
appUser’s give name, not included when includeFullAppUser is unset in webhook settings.
signedUpAt
optional
appUser’s signup time, not included when includeFullAppUser is unset in webhook settings.
properties
optional
appUser’s properties, not included when includeFullAppUser is unset in webhook settings.

Client schema

Client specific info

Field Description
_id The unique ID of the client.
platform The type of integration that the client represents.
status The client status. Indicates if the client is able to receive messages or not. See client status below for available values.
integrationId The ID of the integration that the client was created for.
externalId optional The ID of the user on an external channel. For example, the user’s phone number for Twilio, or their page-scoped user ID for Facebook Messenger. Applies only to non-SDK clients.
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.
deviceId optional A unique identifier for a device if on Web, iOS, or Android.
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 curated Object with properties that vary for each client platform. All keys are optional and not guaranteed to be available.
raw optional An Object with raw properties that vary for each client platform. All keys are optional and not guaranteed to be available. See the raw client info list below for details.
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 If the channel was linked to a pre-existing appUser, a timestamp signifying when the linking occurred. Formatted as yyyy-mm-ddThh:mm:ssZ
id (deprecated) Deprecated. Use _id or deviceId instead.
active (deprecated) Deprecated. Refer to client status instead.
blocked (deprecated) optional Deprecated. Refer to client status instead.

Client Status

A client’s status property indicates whether it is able to receive messages or not. In general, a client will not be able to receive messages unless its status is active.

Status Description
active Indicates that the client is active and able to receive messages.
blocked When the user explicitly unsubscribes from communication from the business, the client will have a blocked status. Attempts to send messages to a blocked client will result in a delivery error.
inactive Indicates an SDK client for which the user has logged out of the device. Clients in inactive state will not receive push notifications on iOS or Android.
pending A client for which a link attempt has been made, but for which the link has not yet been confirmed. Pending clients are ignored when determining where a message will be sent.

Raw client info

Smooch retrieves raw client specific information from each channel and makes it available via the raw field of the client. All keys are optional and not guaranteed to be available.

Facebook Messenger

For Messenger, we retrieve the user’s profile via the user profile API. The response is made available through the raw field.

Field Description
first_name First name
last_name Last name
profile_pic Profile picture
locale Locale of the user on Facebook
timezone Timezone, number relative to GMT
gender Gender
is_payment_enabled Is the user eligible to receive messenger platform payment messages
last_ad_referral Details of the last Messenger Conversation Ad user was referred from

LINE

For LINE, we retrieve the user’s profile via the get profile API. The response is made available through the raw field.

Field Description
displayName Display name
userId User ID
pictureUrl Image URL
statusMessage Status message

Mailgun

For Mailgun, we extract the user’s profile information from incoming “store” webhooks, picking out fields that are relevant to the user’s profile.

Field Description
from The email of the sender.
Reply-To The Reply-To address of the sender.
stripped-signature The sender’s signature, stripped.

MessageBird SMS

For MessageBird, we retrieve the user’s profile via the lookup API. The response is made available through the raw field.

Field Description
href The URL of this lookup.
countryCode The country code for this number in ISO 3166-1 alpha-2 format.
countryPrefix The country calling code for this number.
phoneNumber The phone number in E.164 format without the prefixed plus-sign.
type The type of number. This can be fixed line, mobile, fixed line or mobile, toll free, premium rate, shared cost, voip, personal number, pager, universal access number, voice mail or unknown.
formats A hash containing references to this phone number in several different formats.
hlr The most recent HLR object. If no such HLR objects exists, this hash won’t be returned.

Native Android SDK

For the Android SDK, we gather relevant information about the user through the app and expose it in the raw field.

Field Description
installer The app’s installer package name.
sdkVersion The Smooch SDK version.
appId The Android app’s ID.
wifi Value specifying whether the user has wifi enabled.
radioAccessTechnology The network type being used to access the internet.
carrier The devices’s carrier.
appName The Android app’s name.
devicePlatform Manufacturer and model of the device.
osVersion The device’s OS version.
os The device’s OS.

Native iOS SDK

For the iOS SDK, we gather relevant information about the user through the app and expose it in the raw field.

Field Description
radioAccessTechnology The network type being used to access the internet.
appId The iOS app’s ID.
carrier The devices’s carrier.
buildNumber The app’s build number.
devicePlatform The device platform.
installer The installer of the app.
sdkVersion The Smooch SDK version.
osVersion The device’s OS version.
appName The iOS app’s name.
os The device’s OS.
wifi Value specifying whether the user has wifi enabled.

Telegram

For Telegram, we retrieve the user’s profile via the fetch user API and the fetch user profile photos API. The response is made available through the raw field.

Field Description
id Unique identifier for this user or bot.
first_name User‘s or bot’s first name.
last_name Optional. User‘s or bot’s last name.
username Optional. User‘s or bot’s username.
language_code Optional. IETF language tag of the user’s language.
profile_photos This object represent a user’s profile pictures .

Twilio SMS

For Twilio, we extract the user’s profile information from incoming SMS webhooks, picking out fields that are relevant to the user’s profile.

Field Description
From The phone number of the sender.
FromCity The city of the sender.
FromState The state or province of the sender.
FromZip The postal code of the called sender.
FromCountry The country of the called sender.

Twitter DM

For Twitter, we retrieve the user’s profile via the GET users/show API. The response is made available through the raw field.

Field Description
contributors_enabled Indicates that the user has an account with “contributor mode” enabled, allowing for Tweets issued by the user to be co-authored by another account. Rarely true (this is a legacy field).
created_at The UTC datetime that the user account was created on Twitter.
default_profile When true, indicates that the user has not altered the theme or background of their user profile.
default_profile_image When true, indicates that the user has not uploaded their own profile image and a default image is used instead.
description Nullable. The user-defined UTF-8 string describing their account.
entities Entities which have been parsed out of the url or description fields defined by the user. Read more about User Entities.
favourites_count The number of Tweets this user has liked in the account’s lifetime. British spelling used in the field name for historical reasons.
follow_request_sent Nullable. Perspectival. When true, indicates that the authenticating user has issued a follow request to this protected user account.
following Nullable. Perspectival. Deprecated. When true, indicates that the authenticating user is following this user. Some false negatives are possible when set to “false,” but these false negatives are increasingly being represented as “null” instead.
followers_count The number of followers this account currently has. Under certain conditions of duress, this field will temporarily indicate “0”.
friends_count The number of users this account is following (AKA their “followings”). Under certain conditions of duress, this field will temporarily indicate “0”.
geo_enabled When true, indicates that the user has enabled the possibility of geotagging their Tweets. This field must be true for the current user to attach geographic data when using POST statuses / update.
id The integer representation of the unique identifier for this User. This number is greater than 53 bits and some programming languages may have difficulty/silent defects in interpreting it. Using a signed 64 bit integer for storing this identifier is safe. Use id_str for fetching the identifier to stay on the safe side. See Twitter IDs, JSON and Snowflake.
id_str The string representation of the unique identifier for this User. Implementations should use this rather than the large, possibly un-consumable integer in id.
is_translator When true, indicates that the user is a participant in Twitter’s translator community.
lang The BCP 47 code for the user’s self-declared user interface language. May or may not have anything to do with the content of their Tweets.
listed_count The number of public lists that this user is a member of.
location Nullable. The user-defined location for this account’s profile. Not necessarily a location, nor machine-parseable. This field will occasionally be fuzzily interpreted by the Search service.
name The name of the user, as they’ve defined it. Not necessarily a person’s name. Typically capped at 20 characters, but subject to change.
notifications Nullable. Deprecated. May incorrectly report “false” at times. Indicates whether the authenticated user has chosen to receive this user’s Tweets by SMS.
profile_background_color The hexadecimal color chosen by the user for their background.
profile_background_image_url A HTTP-based URL pointing to the background image the user has uploaded for their profile.
profile_background_image_url_https A HTTPS-based URL pointing to the background image the user has uploaded for their profile.
profile_background_tile When true, indicates that the user’s profile_background_image_url should be tiled when displayed.
profile_banner_url The HTTPS-based URL pointing to the standard web representation of the user’s uploaded profile banner. By adding a final path element of the URL, it is possible to obtain different image sizes optimized for specific displays. For size variants, please see User Profile Images and Banners.
profile_image_url A HTTP-based URL pointing to the user’s profile image. See User Profile Images and Banners.
profile_image_url_https A HTTPS-based URL pointing to the user’s profile image.
profile_link_color The hexadecimal color the user has chosen to display links with in their Twitter UI.
profile_sidebar_border_color The hexadecimal color the user has chosen to display sidebar borders with in their Twitter UI.
profile_sidebar_fill_color The hexadecimal color the user has chosen to display sidebar backgrounds with in their Twitter UI.
profile_text_color The hexadecimal color the user has chosen to display text with in their Twitter UI.
profile_use_background_image When true, indicates the user wants their uploaded background image to be used.
protected When true, indicates that this user has chosen to protect their Tweets. See About Public and Protected Tweets.
screen_name The screen name, handle, or alias that this user identifies themselves with. screen_names are unique but subject to change. Use id_str as a user identifier whenever possible. Typically a maximum of 15 characters long, but some historical accounts may exist with longer names.
status Nullable. If possible, the user’s most recent Tweet or retweet. In some circumstances, this data cannot be provided and this field will be omitted, null, or empty. Perspectival attributes within Tweets embedded within users cannot always be relied upon.
statuses_count The number of Tweets (including retweets) issued by the user.
time_zone Nullable. A string describing the Time Zone this user declares themselves within.
url Nullable. A URL provided by the user in association with their profile.
utc_offset Nullable. The offset from GMT/UTC in seconds.
verified When true, indicates that the user has a verified account. See Verified Accounts.
is_translation_enabled When true, indicates that the user has translation enabled.
has_extended_profile When true, indicates that the user has an extended profile.
translator_type The type of translator the user has enabled.
profile_location Nullable. A URL of the user’s profile location.

Viber

For Viber, we retrieve the user’s profile via the get user details API. The response’s user is made available through the raw field.

Field Description
id Unique Viber user id
name User’s Viber name
avatar URL of the user’s avatar
country User’s country code
language User’s phone language. Will be returned according to the device language
primary_device_os The operating system type and version of the user’s primary device
api_version Max API version, matching the most updated user’s device
viber_version The Viber version installed on the user’s primary device
mcc Mobile country code
mnc Mobile network code
device_type The user’s device type

Web Messenger

For the Web Messenger, we gather relevant information about the user through the browser and expose it in the raw field.

Field Description
currentTitle The title of the page the user is currently on.
currentUrl The URL of the page the user is currently on.
browserLanguage The language the user’s browser is set to.
referrer The referrer for the page the user is on.
userAgent The browser’s user agent string.
URL The domain of the page the user is currently on (ex: docs.smooch.io).
sdkVersion The SDK version for the currently instantiated Web Messenger.

WeChat

For WeChat, we retrieve the user’s profile via the fetch user profile API. The response is made available through the raw field.

Field Description
subscribe Shows whether the user has followed the Official Account. 0: The user is not a follower, and you cannot obtain other information about this user.
openid A unique user ID specific to a given Official Account. A non-follower visiting an Official Account’s web pages can also generate a unique OpenID.
nickname User nickname
sex 1: Male; 2: Female; 0: Not Set
language zh_CN: Simplified Chinese
city City
province Province
country Country
headimgurl Profile photo URL. The last number in the URL shows the size of the square image, which can be 0 (640*640), 46, 64, 96 and 132. This parameter is null if the user hasn’t set a profile photo.
subscribe_time The timestamp when the user follows the Official Account or the last time if the user has followed several times.

WhatsApp

For WhatsApp, we extract the user’s profile information and from ID from inbound message webhooks.

Field Description
from WhatsApp ID of the sender.
profile Nested object containing the profile information of the WhatsApp user. If the user has declined to share their profile with the Business, this field will be unset.

Conversation

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

Post Message

Request (App User):

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -d '{"text":"Just put some vinegar on it", "role": "appUser", "type": "text"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.appUsers
    .sendMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            text: 'Just put some vinegar on it',
            role: 'appUser',
            type: 'text'
        }
    })
    .then((response) => {
        // async code
    });

Request (App Maker):

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -d '{"text":"Just put some vinegar on it", "role": "appMaker", "type": "text"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.appUsers
    .sendMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            type: 'text',
            text: 'Just put some vinegar on it',
            role: 'appMaker'
        }
    })
    .then((response) => {
        // 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
    },
    "extraMessages": [
        {
            "_id": "507f1f77bcf86cd799439011",
            "authorId": "c7f6e6d6c3a637261bd9656f",
            "role": "appMaker",
            "type": "image",
            "name": "Steve",
            "text": "Check out this image!",
            "mediaUrl": "http://example.org/image.jpg",
            "actions": [
                {
                    "text": "More info",
                    "type": "link",
                    "uri": "http://example.org"
                }
            ]
        }
    ],
    "conversation": {
        "_id": "df0ebe56cbeab98589b8bfa7",
        "unreadCount": 0
    }
}

POST /v1.1/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 (either self-hosted or pre-uploaded using the Smooch attachments API) using this API via the image type.

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, location, or form.
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

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 $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages?before=1471995721 \
     --user 'keyId:keySecret'
smooch.appUsers
    .getMessages({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        query: {
            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.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages?after=1471995721"
}

GET /v1.1/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 Single Message

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages/5ad90ba5b74ec11877381f4e \
     -X DELETE \
     --user 'keyId:keySecret'
smooch.appUsers
    .deleteMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        messageId: '5ad90ba5b74ec11877381f4e'
    })
    .then(() => {
        // async code
    });

Response:

200 OK

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

Delete a single message, leaving behind a placeholder with the text [deleted]. Deleted message placeholders will also have a deleted property of true.

If the target message has a mediaUrl that is hosted by Smooch, the media will be deleted as well. Note that files uploaded via the upload attachment API are not associated with any specific appUser and are therefore not subject to deletion by this API. The delete attachment API should be used to remove those files.

Delete All Messages

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X DELETE \
     --user 'keyId:keySecret'
smooch.appUsers
    .deleteMessages({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK

DELETE /v1.1/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.

For deleted messages that have a mediaUrl that is hosted by Smooch, the media will be deleted as well. Note that files uploaded via the upload attachment API are not associated with any specific appUser and are therefore not subject to deletion by this API. The delete attachment API should be used to remove those files.

Conversation Activity

Notify Smooch of different conversation activities. Supported types are typing activity and business read receipt.

Typing Activity

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/conversation/activity \
     -X POST \
     -d '{"role":"appMaker", "type": "typing:start"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.appUsers
    .conversationActivity({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        activityProps: {
            role: 'appMaker',
            type: 'typing:start'
        }
    })
    .then((response) => {
        // async code
    });

Response:

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

POST /v1.1/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 typing 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.

Business Read Receipt

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/conversation/activity \
     -X POST \
     -d '{"role":"appMaker", "type": "conversation:read"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.appUsers
    .conversationActivity({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        activityProps: {
            role: 'appMaker',
            type: 'conversation:read'
        }
    })
    .then((response) => {
        // async code
    });

Response:

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

POST /v1.1/apps/{appId}/appusers/{appUserId|userId}/conversation/activity

Notify Smooch when an app maker has read the user’s messages. The conversation is considered read up to the last message at the time the request was made.

Arguments
role
required
The role of the actor. Must be appMaker.
type
required
Must be conversation:read.

Reset Unread Count

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/conversation/read \
     -X POST \
     --user 'keyId:keySecret'
smooch.conversations.resetUnreadCount('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f').then(() => {
    // async code
});

Response:

200 OK

POST /v1.1/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.

Attachments

You can upload files of any type that can then be used to send a file, image or carousel message to an appUser.

Upload Attachment

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/attachments?access=public&for=message&appUserId=5963c0d619a30a2e00de36b8 \
     -X POST \
     --user 'keyId:keySecret' \
     -H 'content-type: multipart/form-data' \
     -F 'source=@document.pdf;type=application/pdf'
const file = fileInput.files[0];
smooch.attachments
    .create({
        appId: '5963c0d619a30a2e00de36b8',
        props: {
            for: 'message',
            access: 'public',
            appUserId: '5963c0d619a30a2e00de36b8'
        },
        source: file
    })
    .then(() => {
        // async code
    });

Response:

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

POST /v1.1/apps/{appId}/attachments

Upload an attachment to Smooch to use in future messages. Files are uploaded using the multipart/form-data content type. Use the returned mediaUrl to send a file, image or carousel message.

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.
for
optional
Specifies the intended container for the attachment, to enable future automatic attachment deletion. For now, only message is supported. See attachments for messages for details.
appUserId
optional
The appUserId of the user that will receive the attachment. Used in attachments for messages.
userId
optional
The userId of the user that will receive the attachment. Used in attachments for messages.

Delete Attachment

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/attachments/remove \
     -X POST \
     -d '{"mediaUrl": "https://media.smooch.io/apps/c7f6e6d6c3a637261bd9656f/a77caae4cbbd263a0938eba00016b7c8/document.pdf"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.attachments
    .delete({
        appId: '5963c0d619a30a2e00de36b8',
        mediaUrl: 'https://media.smooch.io/apps/c7f6e6d6c3a637261bd9656f/a77caae4cbbd263a0938eba00016b7c8/document.pdf'
    })
    .then(() => {
        // async code
    });

Response:

200 OK
{}

POST /v1.1/apps/{appId}/attachments/remove

Remove an attachment uploaded to Smooch through the upload attachment API.

See Attachments for Messages to have attachments automatically deleted when deleting messages or users.

Arguments
mediaUrl
required
The media URL used for a file or image message.

Attachments for Messages

The attachments API allows you to upload a file for the purpose of sending a message.

Using the for parameter, you can signal to Smooch that your upload will be used to send a message to a user. Knowing this, Smooch will safely delete the attachment when the message or app user is deleted.

Templates

You can create message templates that will allow you to send complex messages such as carousel or list via convenient shorthand. For more information on the application of templates, see our guide.

Create Template

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/templates \
     -X POST \
     --user 'keyId:keySecret' \
     -H 'content-type: application/json' \
     -d '{"name": "my_template", "message": { "role": "appMaker", "type": "text", "text": "Just put some vinegar on it" } } \
smooch.templates
    .create({
        appId: '5963c0d619a30a2e00de36b8',
        props: {
            name: 'my_template',
            message: {
                type: 'text',
                role: 'appMaker',
                text: 'Just put some vinegar on it'
            }
        }
    })
    .then(() => {
        // async code
    });

Response:

201 CREATED
{
    "template": {
        "_id": "5b477234e951d11d6e2efe7e",
        "message": {
            "text": "Just put some vinegar on it",
            "type": "text",
            "role": "appMaker"
        },
        "name": "my_template"
    }
}

POST /v1.1/apps/{appId}/templates

Create a template in Smooch to use when sending messages.

Arguments
name
required
The name you want for your template. Will be used to send templates via the shorthand.
message
required
The message to store in the template. Can contain any arguments as used in the post message API save a few exceptions.

List Templates

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/templates?limit=1&offset=0 \
     -X GET \
     --user 'keyId:keySecret'
smooch.templates
    .list({
        appId: '5963c0d619a30a2e00de36b8',
        props: {
            limit: 1,
            offset: 0
        }
    })
    .then(() => {
        // async code
    });

Response:

200 OK
{
    "templates": [
        {
            "_id": "5b477234e951d11d6e2efe7e",
            "appId": "5ae1de83dd0d4061bf5d581f",
            "message": {
                "role": "appMaker",
                "type": "text",
                "text": "Just put some vinegar on it"
            },
            "name": "my_template"
        }
    ],
    "hasMore": true,
    "offset": 0
}

GET /v1.1/apps/{appId}/templates

List created templates. Response value hasMore will be true if there are more records left to query.

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

Get Template

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/templates/5b477234e951d11d6e2efe7e \
     -X GET \
     --user 'keyId:keySecret' \
smooch.templates.get({
  appId: '5963c0d619a30a2e00de36b8',
  templateId: '5b477234e951d11d6e2efe7e'
).then((response) => {
    // async code
});

Response:

200 OK
{
    "template": {
        "_id": "5b477234e951d11d6e2efe7e",
        "message": {
            "text": "Just put some vinegar on it",
            "type": "text",
            "role": "appMaker"
        },
        "name": "my_template"
    }
}

GET /v1.1/apps/{appId}/templates/{templateId}

Get specific template created in Smooch through the create template API.

Update Template

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/templates/5b477234e951d11d6e2efe7e \
     -X PUT \
     --user 'keyId:keySecret' \
     -H 'content-type: application/json' \
     -d '{"name": "my_updated_template", "message": { "role": "appMaker", "type": "text", "text": "Just put some vinegar on it" } } \
smooch.templates
    .update({
        appId: '5963c0d619a30a2e00de36b8',
        templateId: '5b477234e951d11d6e2efe7e',
        props: {
            name: 'my_updated_template',
            message: {
                type: 'text',
                role: 'appMaker',
                text: 'Just put some vinegar on it'
            }
        }
    })
    .then(() => {
        // async code
    });

Response:

200 OK
{
    "template": {
        "_id": "5b477234e951d11d6e2efe7e",
        "message": {
            "text": "Just put some vinegar on it",
            "type": "text",
            "role": "appMaker"
        },
        "name": "my_updated_template"
    }
}

PUT /v1.1/apps/{appId}/templates/{templateId}

Update a template in Smooch to use when sending messages.

Arguments
name
optional
The name you want for your template. Will be used to send templates via the shorthand.
message
optional
The message to store in the template. Can contain any arguments as used in the post message API save a few exceptions.

Delete Template

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/templates/5b477234e951d11d6e2efe7e \
     -X DELETE \
     --user 'keyId:keySecret'
smooch.templates
    .delete({
        appId: '5963c0d619a30a2e00de36b8',
        templateId: '5b477234e951d11d6e2efe7e'
    })
    .then(() => {
        // async code
    });

Response:

200 OK
{}

DELETE /v1.1/apps/{appId}/templates/{templateId}

Delete template created in Smooch through the create template API.

Template Message Exceptions

Since the act of creating a message template differs slightly from actually sending a message, some arguments that are normally allowed when calling the post message API will be ignored when creating or updating a template.

Ignored
destination To use channel targeting with a template message, specify destination in the POST Message payload.

Message Types

Common Message Properties

Arguments
role
required*
The role of the message, appMaker or appUser.
type
required*
The type of the message.
metadata
optional*
Flat object containing any custom properties associated with the message. See metadata for more information.

Text

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret' \
     -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({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            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. See Common message properties for more information.

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

Image

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret' \
     -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({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            role: 'appMaker',
            type: 'image',
            text: 'Hello!',
            mediaUrl: 'http://example.org/image.jpg',
            actions: [
                {
                    text: 'More info',
                    type: 'link',
                    uri: 'http://example.org'
                }
            ]
        }
    })
    .then((response) => {
        // async code
    });

Response:

201 CREATED
{
    "message": {
        "_id": "57966d21c19c9da00839a5e9",
        "role": "appMaker",
        "type": "image",
        "mediaUrl": "http://example.org/image.jpg",
        "mediaType": "image/jpeg",
        "mediaSize": 1234,
        "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. See Common message properties for more information.

Arguments
text
optional*
The text content of the message.
actions
optional*
Array of message actions.
mediaUrl
required*
The image URL used for the image message.

File

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret' \
     -d '
{
    "role": "appMaker",
    "type": "file",
    "mediaUrl": "http://example.org/document.pdf"
}'
smooch.appUsers
    .sendMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            role: 'appMaker',
            type: 'file',
            mediaUrl: 'http://example.org/document.pdf'
        }
    })
    .then(() => {
        // async code
    });

Response:

201 CREATED
{
    "message": {
        "_id": "57966d21c19c9da00839a5e9",
        "role": "appMaker",
        "type": "file",
        "mediaUrl": "http://example.org/document.pdf",
        "mediaType": "application/pdf",
        "mediaSize": 143212
    }
}
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. See Common message properties for more information.

Arguments
text
optional
Accompanying text or a description of the file.
mediaUrl
required
The URL of the file attachment.

Location

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret' \
     -d '
{
    "role": "appUser",
    "type": "location",
    "coordinates": {
        "lat": 45.5261583,
        "long": -73.595346
    }
}'
smooch.appUsers
    .sendMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            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. See Common message properties for more information.

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.

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret' \
     -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({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            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 message actions. Not all messaging channels fully support carousel messages; currently only Facebook Messenger, LINE, Telegram, Viber, the Web Messenger, the Android SDK and the iOS SDK 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 message actions. See Common message properties for more information.

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

Telegram

Full support, with cards arranged vertically. telegram carousel

LINE

Full support. line carousel

Viber

Full support. viber carousel

Web Messenger

Full support. web carousel

Android

Full support. android carousel

iOS

Full support. ios carousel

All Other Channels

Sample Raw Text Format:

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

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

Text fallback. text fallback

List

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret' \
     -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({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            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 message actions. Not all messaging channels fully support list messages. See Common message properties for more information.

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

Channel Support

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

Facebook Messenger

List messages are supported natively in Facebook Messenger. However, note that 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

LINE

LINE doesn’t support list messages natively. When a list message is sent to a LINE user, the items array will be sent as a carousel message. The actions array will be sent as a separate message.

Telegram

Telegram doesn’t support list messages natively. When a list message is sent to a Telegram user, it will be sent as multiple messages. Each item in the items array will be converted to one message. Another message will be sent with the contents of the actions array if it’s non-empty.

WeChat

WeChat supports native list messages, but it is more limited than other channels. When sending a list message to WeChat users note that:

wechat list

Android, iOS and Web SDK

Our Android, iOS and Web SDK don’t support native list messages. When a SDK receives a list message, it displays the items as a carousel message and the actions are truncated.

All Other Channels

Sample Raw Text Format:

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

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

Text fallback. text fallback

Form

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     -H "authorization: Bearer your-account-jwt" \
     -d '
{
    "role": "appMaker",
    "type": "form",
    "blockChatInput": true,
    "fields": [
        {
            "type": "text",
            "name": "full_name",
            "label": "Your name?",
            "placeholder": "Type your name...",
            "minSize": 1,
            "maxSize": 30
        },
        {
            "type": "email",
            "name": "email_address",
            "label": "Your email?",
            "placeholder": "email@example.com"
        },
        {
            "type": "select",
            "name": "meal_selection",
            "label": "Your meal?",
            "options": [
                {
                    "name": "pizza",
                    "label": "Pizza"
                },
                {
                    "name": "tacos",
                    "label": "Tacos"
                },
                {
                    "name": "ramen",
                    "label": "Ramen"
                }
            ]
        }
    ]
}'
smooch.appUsers
    .sendMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            role: "appMaker",
            type: "form",
            blockChatInput: true
            fields: [
                {
                    type: "text",
                    name: "full_name",
                    label: "Your name?",
                    placeholder: "Type your name...",
                    minSize: 1,
                    maxSize: 30
                },
                {
                    type: "email",
                    name: "email_address",
                    label: "Your email?",
                    placeholder: "email@example.com"
                },
                {
                    type: "select",
                    name: "meal_selection",
                    label: "Your meal?",
                    options: [
                        {
                            name: "pizza",
                            label: "Pizza"
                        },
                        {
                            name: "tacos",
                            label: "Tacos"
                        },
                        {
                            name: "ramen",
                            label: "Ramen"
                        }
                    ]
                }
            ]
        }
    })
    .then(() => {
        // async code
    });

Response:

201 CREATED
{
    "message": {
        "blockChatInput": true,
        "fields": [
            {
                "type": "text",
                "name": "full_name",
                "label": "Your name?",
                "placeholder": "Type your name...",
                "minSize": 1,
                "maxSize": 30,
                "_id": "5cd09442d70f413fp1w2d0f9"
            },
            {
                "type": "email",
                "name": "email_address",
                "label": "You email?",
                "placeholder": "email@example.com",
                "_id": "5cd09442d70f413fp1w2d0f0"
            },
            {
                "type": "select",
                "name": "meal_selection",
                "label": "Your meal?",
                "selectSize": 1,
                "options": [
                    {
                        "name": "pizza",
                        "label": "Pizza",
                        "_id": "5cd09442d70f413fp1w2d0f1"
                    },
                    {
                        "name": "tacos",
                        "label": "Tacos",
                        "_id": "5cd09442d70f413fp1w2d0f2"
                    },
                    {
                        "name": "ramen",
                        "label": "Ramen",
                        "_id": "5cd09442d70f413fp1w2d0f3"
                    }
                ],
                "_id": "5cd09442d70f413fp1w2d0f4"
            }
        ],
        "type": "form",
        "role": "appMaker",
        "received": 1557173314.465,
        "authorId": "7AJ4zpAVxEwKkjCZD2EYKk",
        "avatarUrl": "https://www.gravatar.com/avatar/00000000000000000000000000000000.png?s=200&d=mm",
        "submitted": false,
        "_id": "57966d21c19c9da00839a5e9",
        "source": {
            "type": "api"
        }
    },
    "conversation": {
        "_id": "94eb1cd68c3e072a5ea0e242",
        "appMakerLastRead": 1557173314.465,
        "appUserLastRead": 1557173271.843,
        "unreadCount": 2
    }
}
201 CREATED

A form type message without text or actions. See Common message properties for more information.

Arguments
blockChatInput
optional
Boolean indicating if the Web SDK chat input should be blocked. Defaults to false.
fields
required
Array of field objects to be completed. The array is limited to 20 fields.

Channel Support

Smooch forms are only supported on the Web Messenger.

Field

Fields are included in the fields array of a form type message to specify the fields to be completed.

Arguments
type
required
Specifies the type of field. Options are text, email, select.
name
required
Specifies the name of the field. Each field name must be unique per form. Maximum length of 128 characters.
label
required
Specifies what label the field will be displayed with. Maximum length of 128 characters.
placeholder
optional
Specifies the placeholder text of the field that will be rendered. Maximum length of 128 characters.
minSize
optional
Text field only. Specifies the minimum possible length of the response. Defaults to 1 if not specified.
maxSize
optional
Text field only. Specifies the maximum possible length of the response. Defaults to 128 if not specified.
options
optional
Select field only. Array of option objects that can be selected. The array is limited to 20 options.

Option

Options are included in the options array of a select type field to specify which options are available for selection.

Arguments
name
required
String specifying the name of the option. Field option name must be unique per field. Maximum length of 128 characters.
label
required
String specifying the label that the option will be displayed with on Web Messenger. Maximum length of 128 characters.

Form Response

A formResponse type message is a response to a form type message. See Common message properties for more information.

Arguments
fields
required
Array of field objects that contain the submitted fields.
quotedMessage
required
Object indicating the form message that is being responded to. See quotedMessage for more details.

Channel Support

formResponse type messages are only supported as responses to form messages on Web Messenger and cannot be sent via the API.

Response Field

Fields are found in the fields array of a formResponse type message. They contain the responses the user has inputted or selected.

Arguments
type
required
Specifies the type of field. Options are text, email, select.
name
required
Specifies the name of the field.
label
required
Specifies what label the field will be displayed with.
text
optional
Specifies the response for a text field.
email
optional
Specifies the response for a email field.
select
optional
Array specifying the selected option for a select field.

Message Actions

Actions buttons can be sent through the post message API by including them in the message payload. There are many types of actions, each with its own abilities and limitations. See below for the payloads of each distinct action type. See Common message properties for more information.

A link action will open the provided URI when tapped.

Send link action:

curl $SMOOCH_ROOT/v1.1/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' \
     --user 'keyId:keySecret'
smooch.appUsers
    .sendMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            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
Boolean value indicating whether the action is the default action 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.

Webview

When a webview actions is clicked/tapped, the provided URI will be loaded in a webview. Channels that do not support webviews will open the fallback URI instead. For a deep dive on how to use webviews, see our guide.

Send webview action:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -d '{"text":"Just put some vinegar on it", "role": "appMaker", "type": "text", "actions": [{"type": "webview", "text": "Put vinegar", "uri": "http://example.com", "fallback": "http://example-fallback.com" }]}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.appUsers
    .sendMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            text: 'Just put some vinegar on it',
            role: 'appMaker',
            type: 'text',
            actions: [
                {
                    type: 'webview',
                    text: 'Put vinegar',
                    uri: 'http://example.com',
                    fallback: 'http://example.com'
                }
            ]
        }
    })
    .then(() => {
        // async code
    });
Arguments
text
required
The button text.
type
required
webview
uri
required
The webview URI. This is the URI that will open in the webview when clicking the button.
fallback
required
The webview fallback URI. This is the link that will be opened in channels that do not support webviews.
size
optional
Controls the webview height. Possible values are compact, tall, and full.
default
optional
Boolean value indicating whether the action is the default action 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.
openOnReceive
optional
Boolean value indicating if the webview should open automatically. Only one action per message can be set to true. Currently only supported on the Web Messenger.

Buy

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

Send buy action:

curl $SMOOCH_ROOT/v1.1/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' \
     --user 'keyId:keySecret'
smooch.appUsers
    .sendMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            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 when tapped.

Send postback action:

curl $SMOOCH_ROOT/v1.1/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' \
     --user 'keyId:keySecret'
smooch.appUsers
    .sendMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            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 $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
     -X POST \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
     -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({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            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. Text longer than 20 characters will be truncated on Facebook Messenger, and longer than 40 characters will be truncated on Web Messenger, iOS, and Android.
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.
metadata
optional
Flat object containing any custom properties associated with the action. See the metadata schema for more information.

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 $SMOOCH_ROOT/v1.1/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' \
     --user 'keyId:keySecret'
smooch.appUsers
    .sendMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            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.

Share

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

Send share action:

curl $SMOOCH_ROOT/v1.1/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",
        "actions": [{
            "type": "share"
        }]
    }]
}'
smooch.appUsers
    .sendMessage({
        appId: '5963c0d619a30a2e00de36b8',
        userId: 'c7f6e6d6c3a637261bd9656f',
        message: {
            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.

Extra Channel Options

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

Valid arguments for messenger channel options are as follows:

Arguments
messenger_extensions
optional
For webview type actions, a boolean value indicating whether the URL should be loaded with Messenger Extensions enabled. Default value is false. More Info
webview_share_button
optional
For webview type actions, a string value indicating if the share button should be hidden. Only possible value is hide. More Info

Deprecated arguments for messenger channel options are as follows:

Deprecated
webview_height_ratio
deprecated
Controls the webview height in a link type action. Possible values are compact, tall, and full. More Info Use webview action with size instead
fallback_url
deprecated
If messenger_extensions is true, the URL to use on clients that don’t support Messenger Extensions. More Info Use webview action with fallback instead

Message Items

Message items can be sent through the post message API by including them in the message payload. See Common message properties for more information.

Only carousel and list messages currently support message items.

Arguments
title
required
The title of the carousel item.
actions
required
Array of message actions. At least 1 is required, a maximum of 3 are allowed. link, webview, buy, 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.

Schemas

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.
type "text", "image", "file", "carousel", "location", "list", "form", or "formResponse".
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 name, or an optionally provided appMaker name. In the absence of an appUser name, this logic will be used to determine the message 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.
quotedMessage optional The quoted message, currently only available for WhatsApp and Web Messenger formResponse messages. See the quoted message schema below for details.
avatarUrl optional The URL for an image of the appMaker.
actions optional An array of objects representing the actions associated with the message. See the action schema below for details. The array length is limited by the third party channel. See the Action Buttons guide for more details.
items optional An array of objects representing the items associated with the message. Only present in carousel and list type messages. See the item 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.
mediaSize optional The size (in bytes) for any media attached in the mediaUrl. This will only be provided when available.
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.
deleted optional true if the message serves as a placeholder for one that has been deleted.
fields optional An array of objects representing fields associated with the message. Only present in form and formResponse messages. See the field schema below for details.
submitted optional true if a response has been submitted. form message only.
blockChatInput optional true if the message should block the chat input on Web Messenger. form message only.

Truncated message schema

A truncated version of the message sent with some webhook payloads.

Field Description
_id The unique ID for the message.

Truncated conversation schema

A truncated version of the conversation sent with some webhook payloads.

Field Description
_id The unique ID for the conversation.

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", "api", or any number of other channels.
id optional An identifier used by Smooch for internal purposes.
integrationId optional Identifier indicating which integration the message was sent from. For appUser messages only.
originalMessageId optional Message identifier assigned by the originating channel. Only available for the source schema.
originalMessageTimestamp optional Message timestamp assigned by the originating channel. Only available for the source schema.

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, locationRequest, buy or webview.
uri optional The URI for a link type action, a checkout page for buy type actions. 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). Used for actions of type buy.
currency optional An ISO 4217 standard currency code in lowercase. Used for actions of type buy.
state optional The value offered, or paid representing the payment status of a buy type action.
default
optional
Boolean value indicating whether the action is the default action for a message item in Facebook Messenger. Used for actions of type link.
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.
iconUrl
optional
An icon to render alongside the action text. Used for actions of type reply.
size
optional
The size to display a webview. Used for actions of type webview.
fallback
optional
The fallback uri for channels that don’t support webviews. Used for actions of type webview.

Item schema

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

Field Description
_id A canonical ID.
title The title of the item.
description
optional
The description of the item.
mediaUrl
optional
The image url attached to the item.
mediaType
optional
The MIME type for any image attached in the mediaUrl.
size
optional
The size of the image. compact or large.
actions An array of objects representing the actions associated with the item. At least 1 is required, a maximum of 3 are allowed. See the action schema for details.
metadata
optional
Flat object containing any custom properties associated with the action. See the metadata schema for more information.

Quoted message schema

This table represents the fields you can expect to receive inside quotedMessage data.

Field Description
type The type of quotedMessage. Can be either message, when a complete Smooch message can be provided, or externalMessageId if no Smooch message matched the quoted message.
externalMessageId The external message Id of the quoted message. Only available when type is externalMessageId.
content
optional
The Smooch message corresponding to the quoted message, only available if type is message.

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.

Field schema

This table represents the properties you can expect to receive inside a form or formResponse message field.

Field Description
_id A canonical ID.
type The field type. Either text, email, or select.
name The name of the field. Must be unique per form or formResponse.
label The label of the field. What the field is displayed as on Web Messenger
placeholder optional Placeholder text for the field. form message only.
minSize optional The minimum allowed length for the response for a field of type text. form message only.
maxSize optional The maximum allowed length for the response for a field of type text. form message only.
options optional Array of objects representing options for a field of type select. form message only. See the option schema for more details.
text optional The user response for a field of type text. form and formResponse messages only.
email optional The user response for a field of type email. form and formResponse messages only.
select optional An array of objects representing the response for a field of type select. form and formResponse messages only.

Option schema

This table represents the properties you can expect to receive inside a field option.

Field Description
label The label of the option. What the option is displayed as on Web Messenger.
name The name of the field. Must be unique per field.

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.

Get App Menu

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/menu \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
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.1/apps/{appId}/menu

Get the specified app’s menu.

Update App Menu

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/menu \
     -X PUT \
     -d '{"items": [{"type": "link", "text": "Smooch", "uri": "http://smooch.io"}]}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
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.1/apps/{appId}/menu

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

Delete App Menu

Request:

curl $SMOOCH_ROOT/v1.1/menu \
     -X DELETE \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.menu.remove('5963c0d619a30a2e00de36b8').then(() => {
    // async code
});

Response:

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

DELETE /v1.1/apps/{appId}/menu

Remove the specified app’s menu.

Get Integration Menu

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/menu \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
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.1/apps/{appId}/integrations/{integrationId}/menu

Get the specified integration’s menu.

Update Integration Menu

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/menu \
     -X PUT \
     -d '{"items": [{"type": "link", "text": "Smooch", "uri": "http://smooch.io"}]}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
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.1/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.

Delete Integration Menu

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/menu \
     -X DELETE \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations.menu.delete('55c8d9758590aa1900b9b9f6', '5735dded48011972d621dc02').then(() => {
    // async code
});

Response:

200 OK
{}

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

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

Schema

Persistent Menu 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

Integrations

This set of endpoints is used to configure and manage various front-end messaging channels.

The supported integration types are outlined in the Integration Schemas section.

Smooch exposes REST API methods to:

Create Integration

POST /v1.1/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.

List Integrations

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
       --user 'keyId:keySecret'
smooch.integrations.list({ appId: '55c8d9758590aa1900b9b9f6' }).then((response) => {
    // async code
});

Response:

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

GET /v1.1/apps/{appId}/integrations

Lists all integrations for a given app. This API is paginated. It returns a maximum of 25 integrations by default, and accepts offset and limit query parameters. The maximum limit is 100.

Parameter Description
types String, the list can be filtered to return only integrations of a specific type. More than one value can be specified through comma separation e.g. ?types=twilio,line
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.

Integrations response properties

Each integration will return a set of common properties along with properties specific to its type, see Integrations for more info about properties for a specific type. Common properties are:

Field Description
_id The integration ID.
type The integration type. See integrations for a list of supported types.
status The integration status. Possible values are active, inactive or error. More info.
displayName The integration display name. Omitted if empty.

Integration status

Status Description
active The integration is working correctly.
inactive Additional action is required before this integration can be considered active. Examples are a messenger integration without a page selected or a wechat integration for which Smooch hasn’t received a webhook ping from WeChat. See integrations for detailed steps on how to integrate each channel.
error Smooch received an unexpected error from the channel and should be reviewed.

Get Integration

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02 \
       --user 'keyId:keySecret'
smooch.integrations
    .get({
        appId: '55c8d9758590aa1900b9b9f6',
        integrationId: '5735dded48011972d621dc02'
    })
    .then((response) => {
        // async code
    });

Response:

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

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

Return the specified integration.

Update Integration

Request:

    curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/582dedf230e788746891281a \
        -X PUT \
        -d '{ "displayName": "A human-friendly name" }' \
        -H 'content-type: application/json' \
        --user 'keyId:keySecret'
smooch.integrations
    .update({
        appId: '55c8d9758590aa1900b9b9f6',
        integrationId: '582dedf230e788746891281a',
        props: {
            displayName: 'A human-friendly name'
        }
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "integration": {
        "_id": "582dedf230e788746891281a",
        "displayName": "A human-friendly display name",
        "status": "active",
        "type": "whatsapp",
        "baseUrl": "https://15144441919.whatsapp.ec.url",
        "hsmFallbackLanguage": "fr_CA",
        "username": "smooch",
        "phoneNumber": "15144441919"
    }
}

PUT /v1.1/apps/{appId}/integrations/{integrationId}

The Update Integration endpoint allows you to update active integrations. Some channels allow you to update more properties (see sections below). If updating a specific property is not supported, you must delete the integration and re-create it with the new data.

3rd party channels

The display name can be updated for any integration type, except for FCM, APN and the Web Messenger:

Arguments
displayName A human-friendly name used to identify the integration.
Maximum of 100 characters. May be unset with null or ''.

LINE

Request:

    curl $SMOOCH_ROOT/v.1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735ddfd48011972d621dc0a \
     -X PUT \
     -d '{ "qrCodeUrl": "https://qr-official.line.me/M/1O4fb8.png" }' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .update({
        appId: '55c8d9758590aa1900b9b9f6',
        integrationId: '5735ddfd48011972d621dc0a',
        props: {
            qrCodeUrl: 'https://qr-official.line.me/M/1O4fb8.png'
        }
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "integration": {
        "_id": "5735ddfd48011972d621dc0a",
        "type": "line",
        "status": "active",
        "channelId": "1286564967",
        "qrCodeUrl": "https://qr-official.line.me/M/1O4fb8.png",
        "lineId": "104fb8"
    }
}

LINE integration QR code URLs can be updated or removed.

Arguments
qrCodeUrl URL provided by LINE in the Developer Console. May be unset with ''.

Web Messenger

Request:

    curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/582dedf230e788746891281a \
        -X PUT \
        -d '{ "integrationOrder": ["59fc8466260f48003505228b", "59d79780481d34002b7d3617"], "originWhitelist": ["https://yourdomain.com"], "businessName": "Shoplifter", "brandColor": "00ff00", "fixedIntroPane": true, "conversationColor": "dd00ee", "actionColor": "eeff00", "displayStyle": "button", "prechatCapture": { "enabled": true, "enableEmailLinking": true } }' \
        -H 'content-type: application/json' \
        --user 'keyId:keySecret'
smooch.integrations
    .update({
        appId: '55c8d9758590aa1900b9b9f6',
        integrationId: '582dedf230e788746891281a',
        props: {
            integrationOrder: ['59fc8466260f48003505228b', '59d79780481d34002b7d3617'],
            originWhitelist: ['https://yourdomain.com'],
            businessName: 'Shoplifter',
            brandColor: '00ff00',
            fixedIntroPane: true,
            conversationColor: 'dd00ee',
            backgroundImageUrl: 'https://a-beautiful-tile.png',
            actionColor: 'eeff00',
            displayStyle: 'button',
            prechatCapture: {
                enabled: true,
                enableEmailLinking: true
            }
        }
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "integration": {
        "_id": "582dedf230e788746891281a",
        "type": "web",
        "integrationOrder": ["59fc8466260f48003505228b", "59d79780481d34002b7d3617"],
        "originWhitelist": ["https://yourdomain.com"],
        "businessName": "Shoplifter",
        "brandColor": "00ff00",
        "fixedIntroPane": true,
        "conversationColor": "dd00ee",
        "backgroundImageUrl": "https://a-beautiful-tile.png",
        "actionColor": "eeff00",
        "displayStyle": "button",
        "status": "active",
        "prechatCapture": {
            "enabled": true,
            "enableEmailLinking": true
        }
    }
}

See Web Messenger for more information about the arguments.


WhatsApp

Request:

    curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/582dedf230e788746891281a \
        -X PUT \
        -d '{ "hsmFallbackLanguage": "fr_CA" }' \
        -H 'content-type: application/json' \
        --user 'keyId:keySecret'
smooch.integrations
    .update({
        appId: '55c8d9758590aa1900b9b9f6',
        integrationId: '582dedf230e788746891281a',
        props: {
            hsmFallbackLanguage: 'fr_CA'
        }
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "integration": {
        "status": "active",
        "type": "whatsapp",
        "_id": "582dedf230e788746891281a",
        "baseUrl": "https://15144441919.whatsapp.ec.url",
        "hsmFallbackLanguage": "fr_CA",
        "username": "smooch",
        "phoneNumber": "15144441919"
    }
}

See WhatsApp for more information about the arguments.

Get Integration Profile

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/profile \
       --user 'keyId:keySecret'
smooch.integrations.profile
    .get({
        appId: '55c8d9758590aa1900b9b9f6',
        integrationId: '5735dded48011972d621dc02'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "profile": {
        "about": "Shoplifter is now on WhatsApp, come say hello! 👋",
        "address": "1337 avenue Casgrain, Montréal (Québec) Canada",
        "description": "ShopLifter helps you lift your shop.",
        "email": "info@shoplifter.fun",
        "vertical": "Shop Lifting",
        "websites": ["https://shoplifter.fun"],
        "photoUrl": "https://pps.whatsapp.net/my-image.jpg"
    }
}

GET /v1.1/apps/{appId}/integrations/{integrationId}/profile

Return the specified integration profile.

Update Integration Profile

PUT /v1.1/apps/{appId}/integrations/{integrationId}/profile

The Update Integration Profile endpoint allows you to update the profile information of active integrations. See the sections below for channel specific instructions.

WhatsApp

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/582dedf230e788746891281a/profile \
    -X PUT \
    -d '{ "about": "Shoplifter is now on WhatsApp, come say hello! 👋", "address": "1337 avenue Casgrain, Montréal (Québec) Canada", "description": "ShopLifter helps you lift your shop.", "email": "info@shoplifter.fun", "vertical": "Shop Lifting", "websites": [ "https://shoplifter.fun", "https://docs.shoplifter.fun" ], "photoUrl": "https://assets.brandfolder.com/b6k4f6zh/original/smooch_symbol_rgb.png" }' \
    -H 'content-type: application/json' \
    --user 'keyId:keySecret'
smooch.integrations.profile
    .update({
        appId: '55c8d9758590aa1900b9b9f6',
        integrationId: '582dedf230e788746891281a',
        profile: {
            about: 'Shoplifter is now on WhatsApp, come say hello! 👋',
            address: '1337 avenue Casgrain, Montréal (Québec) Canada',
            description: 'ShopLifter helps you lift your shop.',
            email: 'info@shoplifter.fun',
            vertical: 'Shop Lifting',
            websites: ['https://shoplifter.fun', 'https://docs.shoplifter.fun'],
            photoUrl: 'https://assets.brandfolder.com/b6k4f6zh/original/smooch_symbol_rgb.png'
        }
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
Arguments
about
optional
Text to display in your profile’s About section. Can be used as a status update.
Maximum of 139 characters.
photoUrl
optional
URL where the business' profile photo is hosted.
WhatsApp recommends an image with dimensions of 640x640 and max size of 63KB.

If you want to upload a photo directly, use the Upload Integration Profile Photo API.
address
optional
Address of the business.
Maximum of 256 characters. Cannot be empty when provided.
description
optional
Description of the business.
Maximum of 256 characters. Cannot be empty when provided.
email
optional
Email address to contact the business.
Maximum of 128 characters. Use null or empty string to unset the value.
vertical
optional
Industry of the business.
Maximum of 128 characters. Cannot be empty when provided.
websites
optional
URLs associated with the business.
Maximum of 2 websites, each with a maximum of 256 characters. Must be an array.

See our documentation on WhatsApp Business Profile for more information on the topic.

Upload Integration Profile Photo

PUT /v1.1/apps/{appId}/integrations/{integrationId}/profile/photo

The Upload Integration Profile Photo endpoint allows you to upload a photo to be used for your integration’s profile. While the Update Integration Profile endpoint does take in an optional photoUrl, this endpoint can be used when the photo is not publicly hosted.

WhatsApp

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/582dedf230e788746891281a/profile/photo \
    -X PUT \
    -H 'content-type: multipart/form-data' \
    -F 'source=@document.pdf;type=application/pdf'
    --user 'keyId:keySecret'
// with a file or buffer
smooch.integrations.profile.photo
    .update({
        appId: '55c8d9758590aa1900b9b9f6',
        integrationId: '582dedf230e788746891281a',
        source: fileOrBuffer // File or Buffer
    })
    .then((response) => {
        // async code
    });
// with a file stream of known length
const formData = new FormData();

formData.append('source', fileStream, {
    knownLength: data.contentLength
});

smooch.integrations.profile.photo
    .update({
        appId: '55c8d9758590aa1900b9b9f6',
        integrationId: '582dedf230e788746891281a',
        source: formData
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "photoUrl": "https://pps.whatsapp.net/my-image.jpg"
}
Form Parameters
source
required
The photo source, provided as a readable file buffer or stream.

Delete Integration

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02 \
       -X DELETE \
       --user 'keyId:keySecret'
smooch.integrations
    .delete({
        appId: '55c8d9758590aa1900b9b9f6',
        integrationId: '5735dded48011972d621dc02'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{}

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

Removes the specified integration.

Integration Schemas

Apple Push Notification

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "apn", "certificate": "HjkUD4rWvZj7wSDzA8Hu2hd7ICs274Z=="}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            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');
})

Facebook Messenger

Request:

curl $SMOOCH_ROOT/v1.1/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' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            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:

  1. Take note of your Facebook app ID and secret (apps can be created at developer.facebook.com);
  2. The Facebook app must have been submitted to Facebook for approval with the “manage_pages” (to receive messages through webhook) and “pages_messaging” (to send messages) 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.
displayName
optional
A human-friendly name used to identify the integration. Defaults to Messenger if not specified.
Maximum of 100 characters. May be unset with null or ''.

Firebase Cloud Messaging

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "fcm", "serverKey": "AAAA_hSf4g2J2Q3zDh2DbvSh27dhKlm2", "senderId": "1429457686312"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            type: 'fcm',
            serverKey: 'your-server-key',
            senderId: 'your-sender-id'
        }
    })
    .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.

LINE

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "line", "channelId": "1234567890", channelAccessToken": "lineChannelAccessToken", "channelSecret": "lineChannelSecret", "qrCodeUrl": "https://qr-official.line.me/M/1O4fb8.png"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            type: 'line',
            channelId: '1234567890',
            channelAccessToken: 'lineChannelAccessToken',
            channelSecret: 'lineChannelSecret',
            qrCodeUrl: 'https://qr-official.line.me/M/1O4fb8.png'
        }
    })
    .then((response) => {
        // async code
    });

Response:

201 CREATED
{
    "integration": {
        "_id": "5735ddfd48011972d621dc0a",
        "type": "line",
        "status": "active",
        "channelId": "1286564967",
        "displayName": "LINE",
        "qrCodeUrl": "https://qr-official.line.me/M/1O4fb8.png",
        "lineId": "104fb8"
    }
}

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.

Once you’ve acquired all the required information, call the Create Integration endpoint.

Then, using the returned integration _id, your customer 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}/{integrationId}.

Arguments
type
required
The integration type: line.
channelId
required
LINE Channel ID.
channelSecret
required
LINE Channel Secret.
channelAccessToken
optional
LINE Channel Access Token.
serviceCode
optional
LINE Service Code.
switcherSecret
optional
LINE Switcher Secret.
qrCodeUrl
optional
URL provided by LINE in the Developer Console.
lineId
optional
LINE Basic ID. Is automatically set when qrCodeUrl is updated.
displayName
optional
A human-friendly name used to identify the integration. Defaults to LINE if not specified.
Maximum of 100 characters. May be unset with null or ''.

Mailgun

Request:

curl $SMOOCH_ROOT/v1.1/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' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            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.
hideUnsubscribeLink
optional
A boolean value indicating whether the unsubscribe link should be omitted from outgoing emails. When enabled, it is expected that the business is providing the user a way to unsubscribe by some other means. By default, the unsubscribe link will be included in all outgoing emails.
displayName
optional
A human-friendly name used to identify the integration. Defaults to Mailgun if not specified.
Maximum of 100 characters. May be unset with null or ''.

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

MessageBird

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "messagebird", "accessKey": "9V2iJmd93kFJ390L9495JCl11", "signingKey": "Uu6N09Lkdji3820DJIO89I39sl9dJ", "originator": "12262121021"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            type: 'messagebird',
            accessKey: '9V2iJmd93kFJ390L9495JCl11',
            signingKey: 'Uu6N09Lkdji3820DJIO89I39sl9dJ',
            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, the signingKey and the MessageBird number you would like to use, then call the Create Integration endpoint. The response will include the integration’s _id and webhookSecret, which must be used to configure the webhook in MessageBird.

In the Flow Builder for the MessageBird number you’ve used to integrate, add a new step with the following settings:

Arguments
type
required
The integration type: messagebird.
accessKey
required
The public API key of your MessageBird account.
signingKey
The signing key of your MessageBird account. Used to validate the webhooks' origin.
originator
required
Smooch will receive all messages sent to this phone number.
displayName
optional
A human-friendly name used to identify the integration. Defaults to MessageBird SMS if not specified.
Maximum of 100 characters. May be unset with null or ''.

Telegram

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "telegram", "token": "192033615:AAEuee2FS2JYKWfDlTulfygjaIGJi4s"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            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.
displayName
optional
A human-friendly name used to identify the integration. Defaults to Telegram if not specified.
Maximum of 100 characters. May be unset with null or ''.

Twilio

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "twilio", "accountSid": "ACa1b4c65ee0722712fab89867cb14eac7", "authToken": "160c024303f53049e1e060fd67ca6aefc", "phoneNumberSid": "PN0674df0ecee0c9819bca0ff0bc0a159e"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            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.
displayName
optional
A human-friendly name used to identify the integration. Defaults to Twilio SMS if not specified.
Maximum of 100 characters. May be unset with null or ''.

Twitter DM

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{ "type": "twitter", "tier": "premium", "envName": "your_env_label", "consumerKey": "your_consumer_key", "consumerSecret": "your_consumer_secret", "accessTokenKey": "your_access_token_key", "accessTokenSecret": "your_access_token_secret" }' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            type: 'twitter',
            tier: 'premium',
            envName: 'your_env_label',
            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",
        "tier": "premium",
        "envName": "your_env_label",
        "userId": "0000000000",
        "username": "Mike Mikeson",
        "accessTokenKey": "your_access_token_key",
        "consumerKey": "your_consumer_key"
    }
}

To set up a Twitter integration, please follow the steps outlined in the Twitter Setup Guide.

Arguments
type
required
The integration type: twitter.
tier
required
Your Twitter app’s tier, sandbox, premium or enterprise
envName
optional
The Twitter dev environments label (required for sandbox and premium tiers)
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.
displayName
optional
A human-friendly name used to identify the integration. Defaults to Twitter DM if not specified.
Maximum of 100 characters. May be unset with null or ''.

Viber

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "viber", "token": "df5f8c5233399561-92636b0c5ba30da9-16d4928fc004a72d"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            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.
displayName
optional
A human-friendly name used to identify the integration. Defaults to Viber if not specified.
Maximum of 100 characters. May be unset with null or ''.

Web Messenger

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{ "type": "web", "integrationOrder": ["59fc8466260f48003505228b", "59d79780481d34002b7d3617"], "originWhitelist": ["https://yourdomain.com"], "businessName": "Shoplifter", "brandColor": "00ff00", "conversationColor": "dd00ee", "actionColor": "eeff00", "displayStyle": "button", "buttonWidth": "90", "buttonHeight": "90", "fixedIntroPane": true }' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            type: 'web',
            integrationOrder: ['59fc8466260f48003505228b', '59d79780481d34002b7d3617'],
            businessName: 'Shoplifter',
            brandColor: '00ff00',
            fixedIntroPane: true,
            conversationColor: 'dd00ee',
            backgroundImageUrl: 'https://a-beautiful-tile.png',
            actionColor: 'eeff00',
            displayStyle: 'button',
            buttonWidth: '90',
            buttonHeight: '90',
            prechatCapture: {
                enabled: true,
                enableEmailLinking: false
            }
        }
    })
    .then((response) => {
        // async code
    });

Response:

201 CREATED
{
    "integration": {
        "_id": "582dedf230e788746891281a",
        "type": "web",
        "integrationOrder": ["59fc8466260f48003505228b", "59d79780481d34002b7d3617"],
        "originWhitelist": ["https://yourdomain.com"],
        "businessName": "Shoplifter",
        "brandColor": "00ff00",
        "fixedIntroPane": true,
        "conversationColor": "dd00ee",
        "backgroundImageUrl": "https://a-beautiful-tile.png",
        "actionColor": "eeff00",
        "displayStyle": "button",
        "buttonWidth": "90",
        "buttonHeight": "90",
        "status": "active",
        "prechatCapture": {
            "enabled": true,
            "enableEmailLinking": false
        }
    }
}

To configure a Web Messenger integration, acquire the required information and call the Create Integration endpoint.

Arguments
type
required
The integration type: web.
brandColor
optional
This color will be used in the messenger header and the button or tab in idle state. Must be a 3 or 6-character hexadecimal color.
Default value is 65758e.
fixedIntroPane
optional
When true, the introduction pane will be pinned at the top of the conversation instead of scrolling with it.
Default value is false.
conversationColor
optional
This color will be used for customer messages, quick replies and actions in the footer. Must be a 3 or 6-character hexadecimal color.
Default value is 0099ff.
actionColor
optional
This color will be used for call-to-actions inside your messages. Must be a 3 or 6-character hexadecimal color.
Default value is 0099ff.
displayStyle
optional
Choose how the messenger will appear on your website. Must be either button or tab.
Default value is button.
buttonIconUrl
optional
With the button style Web Messenger, you have the option of selecting your own button icon. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format.
buttonWidth
optional
With the button style Web Messenger, you have the option of specifying the button width. Default value is 58
buttonHeight
optional
With the button style Web Messenger, you have the option of specifying the button height. Default value is 58
integrationOrder
optional
Array of integration IDs, order will be reflected in the Web Messenger. When set, only integrations from this list will be displayed in the Web Messenger. If unset, all integrations will be displayed.
businessName
optional
A custom business name for the Web Messenger.
businessIconUrl
optional
A custom business icon url for the Web Messenger. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format.
backgroundImageUrl
optional
A background image url for the conversation. Image will be tiled to fit the window.
originWhitelist
optional
A list of origins to whitelist. When set, only the origins from this list will be able to initialize the Web Messenger. If unset, all origins are whitelisted.
The elements in the list should follow the serialized-origin format from RFC 6454: scheme "://" host [ ":" port ], where scheme is http or https.
prechatCapture
optional
Object whose properties can be set to specify the add-on’s options. See the guide to learn more about Prechat Capture.

Prechat Capture

Arguments
enabled
optional
Boolean. If true, enables the Prechat Capture add-on when the Web Messenger is initialized. Default value is false.
enableEmailLinking
optional
Boolean. If true and Mailgun is integrated, will automatically link submitted emails. Default value is false.

WeChat

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "wechat", "appId": "ACa1b4c65ee0722712fab89867cb14eac7", "appSecret": "160c024303f53049e1e060fd67ca6aefc"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            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

34.246.106.80

34.246.57.194

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}/{smoochIntegrationId}, 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.
displayName
optional
A human-friendly name used to identify the integration. Defaults to WeChat if not specified.
Maximum of 100 characters. May be unset with null or ''.

WhatsApp

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "whatsapp", "deploymentId" : "55c8d9758590aa1900b9b9aa"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "whatsapp", "baseUrl": "https://15144441919.whatsapp.ec.url", "username": "smooch", "password": "r0cks"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.integrations
    .create({
        appId: '55c8d9758590aa1900b9b9f6',
        props: {
            type: 'whatsapp',
            deploymentId: '55c8d9758590aa1900b9b9aa'
        }
    })
    .then((response) => {
        // async code
    });

Response:

201 CREATED
{
    "integration": {
        "status": "active",
        "type": "whatsapp",
        "_id": "8635ff3a619c1be3bdbafea7",
        "baseUrl": "https://15144441919.whatsapp.ec.url",
        "username": "smooch",
        "phoneNumber": "15144441919"
    }
}

To configure a WhatsApp integration, use your WhatsApp API Client connection information. Smooch can provide WhatsApp API Client hosting for approved brands. See our WhatsApp guide for more details on WhatsApp API Client hosting.

Using Smooch’s WhatsApp API Client hosting

Arguments
type
required
The integration type: whatsapp.
deploymentId
required
The Id of the deployment. The integrationId and the appId will be added to the deployment. Additionally, the deployment’s status will be set to integrated.
hsmFallbackLanguage
optional
Specify a fallback language to use when sending WhatsApp message template using the short hand syntax. Defaults to en_US. See WhatsApp documentation for more info.
displayName
optional
A human-friendly name used to identify the integration. Defaults to WhatsApp if not specified.
Maximum of 100 characters. May be unset with null or ''.

Using plain credentials (deprecated)

Arguments
type
required
The integration type: whatsapp.
baseUrl
required
The API client base url.
username
required
The API client username.
password
required
The API client password.
hsmFallbackLanguage
optional
Specify a fallback language to use when sending WhatsApp message template using the short hand syntax. Defaults to en_US. See WhatsApp documentation for more info.
displayName
optional
A human-friendly name used to identify the integration. Defaults to WhatsApp if not specified.
Maximum of 100 characters. May be unset with null or ''.

Deployments

This set of endpoints is used to create and manage WhatsApp API Client deployments.

Smooch exposes REST API methods to:

Create Deployment

Request:

curl $SMOOCH_ROOT/v1.1/whatsapp/deployments \
     -X POST \
     -d '{"hosting": "smooch"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.deployments.create({ hosting: 'smooch' }).then((response) => {
    // async code
});

Response:

200 OK
{
    "deployment": {
        "_id": "59ba7c0b102fad002852f4fd",
        "status": "starting",
        "hosting": "smooch"
    }
}

POST /v1.1/whatsapp/deployments

Allows you to create a WhatsApp API Client.

Parameter Type Description
hosting
required
String The type of hosting, smooch or self. This parameter will specify whether the API Client will be self hosted or hosted by Smooch.
baseUrl
optional
String Url of the API Client, only required for self hosted deployments.
username
optional
String Username of the API Client, only required for self hosted deployments.
password
optional
String Password of the API Client, only required for self hosted deployments.
callbackUrl
optional
String This url will be called to notify you of updates that occur on the deployment. See Callback URL for more information.

Activate Deployment

curl $SMOOCH_ROOT/v1.1/whatsapp/deployments/55c8d9758590aa1900b9b9f6/activate \
     -X POST \
     -d '{"phoneNumber": "+15146125236", "verifiedNameCertificate": "HjkUD4rWvZj7wSDzA8Hu2hd7ICs274Z==", "method": "voice"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.deployments
    .activate({
        deploymentId: '55c8d9758590aa1900b9b9f6',
        phoneNumber: '+15146125236',
        verifiedNameCertificate: 'HjkUD4rWvZj7wSDzA8Hu2hd7ICs274Z==',
        method: 'voice'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "deployment": {
        "_id": "582dedf230e788746891281a",
        "status": "pending",
        "phoneNumber": "15145555555",
        "hosting": "smooch"
    }
}

POST /v1.1/whatsapp/deployments/{deploymentId}/activate

Allows you to register a valid phone number to your API Client.

Parameter Type Description
phoneNumber
required
String The phone number you are registering. This number should be coming from the WhatsApp Business Account(WABA).
verifiedNameCertificate
required
String The verified name certificate. This certificate should be coming from the WhatsApp Business Account(WABA).
method
required
String The method of receiving your registration code, either voice or sms. If you choose voice, a phone call will be made to the phoneNumber, otherwise a text message will be sent with the confirmation code.
pin
optional
String The 6-digit 2FA PIN protecting the phone number from re-registration. This parameter is only needed for self hosted deployment when the phone number has already been registered.

Confirm Phone Number

curl $SMOOCH_ROOT/v1.1/whatsapp/deployments/55c8d9758590aa1900b9b9f6/code/confirm \
     -X POST \
     -d '{"code": "123456"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.deployments
    .confirmCode({
        deploymentId: '55c8d9758590aa1900b9b9f6',
        code: '123456'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "deployment": {
        "_id": "582dedf230e788746891281a",
        "status": "registered",
        "phoneNumber": "15145555555",
        "hosting": "smooch"
    }
}

POST /v1.1/whatsapp/deployments/{deploymentId}/code/confirm

Allows you to complete the registration process by confirming the code you received through the method chosen in the Activate Deployment endpoint. Once you have completed the registration process, you can use this deployment to create a WhatsApp integration, see WhatsApp integration schema for more information.

Parameter Type Description
code
required
String The code received through the method chosen in the Activate Deployment section.

Get Deployment

curl $SMOOCH_ROOT/v1.1/whatsapp/deployments/55c8d9758590aa1900b9b9f6 \
     --user 'keyId:keySecret'
smooch.deployments
    .get({
        deploymentId: '55c8d9758590aa1900b9b9f6'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "deployment": {
        "_id": "582dedf230e788746891281a",
        "status": "pending",
        "phoneNumber": "15145555555",
        "hosting": "smooch"
    }
}

GET /v1.1/whatsapp/deployments/{deploymentId}

Allows you to retrieve the information of a deployment. See deployment status for more information.

List Deployments

curl $SMOOCH_ROOT/v1.1/whatsapp/deployments \
     --user 'keyId:keySecret'
smooch.deployments.list().then((response) => {
    // async code
});

Response:

200 OK
{
    "deployments": [
        {
            "_id": "582dedf230e788746891281a",
            "status": "starting",
            "hosting": "smooch"
        },
        {
            "_id": "582dedf230e788746891281b",
            "status": "registered",
            "phoneNumber": "5141111111",
            "hosting": "smooch"
        },
        {
            "_id": "582dedf230e788746891281c",
            "status": "unregistered",
            "hosting": "smooch"
        }
    ]
}

GET /v1.1/whatsapp/deployments/

Allows you to retrieve all the deployments associated to your account. See deployment status for more information.

Delete Deployment

curl $SMOOCH_ROOT/v1.1/whatsapp/deployments/55c8d9758590aa1900b9b9f6 \
     -X DELETE \
     --user 'keyId:keySecret'
smooch.deployments
    .delete({
        deploymentId: '55c8d9758590aa1900b9b9f6'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "deployment": {
        "_id": "582dedf230e788746891281a",
        "status": "deleting",
        "hosting": "smooch",
        "phoneNumber": "15145555555",
        "callbackUrl": "https://examples.com/awesomechat",
        "callbackSecret": "aleCvbmPkvK2kDOsUispNXSd"
    }
}

DELETE /v1.1/whatsapp/deployments/{deploymentId}

Allows you to delete a deployment. This will also delete the WhatsApp API client and put the associated phone number in an ‘offline’ state in the WhatsApp Business Account (WABA). The number can then be used at a later date to create another WhatsApp API client.

Deployment Status

The status of a deployment is updated as it moves through the creation and activation phases. Here are the possible statuses:

Parameter Description
starting The initial status after calling the Create Deployment.
unregistered The deployment status will be set to unregistered once it has been sucessfully deployed.
pending The deployment status will be set to pending once you call the Activate Deployment with a new phone number.
registered The deployment status will be set to registered once you call the Activate Deployment with a phone number that has already been confirmed, or if you call the Confirm Code.
deleting The deployment status will be set to deleting once the Delete Deployment endpoint has been called. Once the deletion process is completed, the deployment is removed from the deployments list.
integrated The deployment status will be set to integrated once the deploymentId is used to create a WhatsApp integration.

Callback URL

The callback url specified in the Create Deployment endpoint will be called once the deployment has been deployed or deleted. Depending on the action, an event will be attached to the call, event:ready or event:deleted. See Secure Smooch Webhooks for more information.

Event Description
ready Called when the deployment is ready to be activated after you call the Create Deployment endpoint.
deleted Called when the deployment status is successfully deleted after you call the Delete Deployment endpoint.

Account Provisioning

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

Authentication

Account Provisioning endpoints require account scope. See the authorization and authentication sections for information.

A user account API key (key id that starts with act_) can access all account provisioning routes. You can create an account key by going to your account page.

A service account API key (key id that starts with svc_) may be used to manage apps, but not service accounts or service account keys.

Key Type Authorized Methods
act All Core and Account Provisioning methods.
svc All Core methods, App Management methods, and App Keys methods.

Service Accounts

Service Account schema and endpoints used for provisioning service accounts. A service account represents an API user, with its own set of credentials, that only has access to a certain subset of apps. For software makers that create apps on behalf of separate customers or businesses, service accounts can be used to generate and distribute credentials that only have access to a single business' data.

Create Service Account

Request:

curl $SMOOCH_ROOT/v1.1/serviceaccounts \
     -X POST \
     -d '{"name": "My Service Account"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.serviceAccounts
    .create({
        name: 'My Service Account'
    })
    .then((response) => {
        // async code
    });

Response:

201 CREATED
{
    "serviceAccount": {
        "_id": "5a71d7419b3ad47012a5dde2",
        "name": "My Service Account"
    }
}

POST /v1.1/serviceaccounts

Creates a new service account. The response body will include the service account’s _id, which can be used to manage the service account’s API keys.

Arguments
name
required
A friendly name for the service account. Must be unique.

List Service Accounts

Request:

  curl $SMOOCH_ROOT/v1.1/serviceaccounts \
       --user 'keyId:keySecret'
smooch.serviceAccounts.list().then((response) => {
    // async code
});

Response:

200 OK
{
    "serviceAccounts": [
        {
            "_id": "5a71d7419b3ad47012a5dde2",
            "name": "My Service Account"
        }
    ],
    "hasMore": false,
    "offset": 0
}

GET /v1.1/serviceaccounts

Lists all service accounts. This API is paginated. It returns a maximum of 25 service accounts by default, and accepts offset and limit query parameters. The maximum 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 Service Account

Request:

curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2 \
     --user 'keyId:keySecret'
smooch.serviceAccounts.get('5a71d7419b3ad47012a5dde2').then((response) => {
    // async code
});

Response:

200 OK
{
    "serviceAccount": {
        "_id": "5a71d7419b3ad47012a5dde2",
        "name": "My Service Account"
    }
}

GET /v1.1/serviceaccounts/{serviceAccountId}

Fetches an individual service account.

Update Service Account

Request:

curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2 \
     -X PUT \
     -d '{"name": "My New Service Account"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.serviceAccounts
    .update('5a71d7419b3ad47012a5dde2', {
        name: 'My New Service Account'
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "serviceAccount": {
        "_id": "5a71d7419b3ad47012a5dde2",
        "name": "My New Service Account"
    }
}

PUT /v1.1/serviceaccounts/{serviceAccountId}

Updates a service account.

Arguments
name
required
A friendly name for the service account. Must be unique.

Delete Service Account

Request:

  curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2 \
       -X DELETE \
       --user 'keyId:keySecret'
smooch.serviceAccounts.delete('5a71d7419b3ad47012a5dde2').then((response) => {
    // async code
});

Response:

200 OK
{}

DELETE /v1.1/serviceaccounts/{serviceAccountId}

Removes the specified service account. A service account that still has access to one or more apps cannot be deleted - you must delete the apps first.

Schema

Service Account schema

The schema describes the fields you can expect to be associated with a service account.

Field Description
_id A canonical ID that can be used to retrieve the service account.
name The friendly name of the service account.

Service Account Keys

This set of endpoints is used to provision and revoke API keys for a service account. A service account can have a maximum of 10 keys.

Create Service Account Key

Request:

curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys \
     -X POST \
     -d '{"name": "key1"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.serviceAccounts.keys.create('5a71d7419b3ad47012a5dde2', 'key1').then((response) => {
    // async code
});

Response:

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

POST /v1.1/serviceaccounts/{serviceAccountId}/keys

Creates an API key for the specified service account. 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 service account.

Arguments
name
required
A friendly identifier for the API key.

List Service Account Keys

Request:

  curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys \
       --user 'keyId:keySecret'
smooch.serviceAccounts.keys.list('5a71d7419b3ad47012a5dde2').then((response) => {
    // async code
});

Response:

200 OK
{
    "keys": [
        {
            "secret": "TDCu5Y_ajUSHPfI-7nT3bzvZ",
            "name": "key1",
            "_id": "svc_5808ba5cedf3b5931970e054"
        },
        {
            "secret": "Civ5oydK4UTwSPNsHbxJVYV2",
            "name": "key2",
            "_id": "svc_5a71d7639b3ad47012a5dde3"
        }
    ]
}

GET /v1.1/serviceaccounts/{serviceAccountId}/keys

Lists all API keys for a given service account.

Get Service Account Key

Request:

  curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys/svc_5808ba5cedf3b5931970e054 \
       --user 'keyId:keySecret'
smooch.serviceAccounts.keys.get('5a71d7419b3ad47012a5dde2', 'svc_5808ba5cedf3b5931970e054').then((response) => {
    // async code
});

Response:

200 OK
{
    "key": {
        "secret": "TDCu5Y_ajUSHPfI-7nT3bzvZ",
        "name": "key1",
        "_id": "svc_5808ba5cedf3b5931970e054"
    }
}

GET /v1.1/serviceaccounts/{serviceAccountId}/keys/{keyId}

Returns an API key.

Delete Service Account Key

Request:

  curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys/svc_5808ba5cedf3b5931970e054 \
       -X DELETE \
       --user 'keyId:keySecret'
smooch.serviceAccounts.keys.delete('5a71d7419b3ad47012a5dde2', 'svc_5808ba5cedf3b5931970e054').then((response) => {
    // async code
});

Response:

200 OK
{}

DELETE /v1.1/serviceaccounts/{serviceAccountId}/keys/{keyId}

Removes an API key.

Get Service Account JWT

Request:

  curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys/svc_5808ba5cedf3b5931970e054/jwt \
       --user 'keyId:keySecret'
smooch.serviceAccounts.keys.getJwt('5a71d7419b3ad47012a5dde2', 'svc_5808ba5cedf3b5931970e054').then((response) => {
    // async code
});

Response:

200 OK
{
    "jwt":
        "eyJraWQiOiJzdmNfNTgwOGJhNWNlZGYzYjU5MzE5NzBlMDU0IiwiYWxnIjoiSFMyNTYifQ.eyJzY29wZSI6ImFjY291bnQifQ.C_DaxSuIOc6smKbNHo0cIF0eAtRj_sCsNcR5bCLFji4"
}

GET /v1.1/serviceaccounts/{serviceAccountId}/keys/{keyId}/jwt

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

Apps

App schema and endpoints used for provisioning Smooch apps.

Create App

Request:

curl $SMOOCH_ROOT/v1.1/apps \
     -X POST \
     -d '{"name": "My App", "settings": {"maskCreditCardNumbers": false, "useAnimalNames": true}}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.apps
    .create({
        name: 'My App',
        settings: {
            maskCreditCardNumbers: false,
            echoPostback: false,
            useAnimalNames: true
        },
        metadata: {
            foo: 'bar'
        }
    })
    .then((response) => {
        // async code
    });

Response:

201 CREATED
{
    "app": {
        "_id": "55c8d9758590aa1900b9b9f6",
        "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
        "name": "My App",
        "settings": {
            "echoPostback": false,
            "maskCreditCardNumbers": false,
            "useAnimalNames": true
        },
        "metadata": {
            "foo": "bar"
        }
    }
}

POST /v1.1/apps

Creates a new app. The response body will include the app’s _id, which can be used to initialize the Web, iOS and Android clients.

When using service account credentials, the service account is automatically granted access to the app.

Arguments
name
required
The User facing name of the app.
settings
optional
Customizable app settings (see app settings).
metadata
optional
Flat object containing any custom properties associated with the app. See app metadata for more information.

List Apps

Request:

  curl $SMOOCH_ROOT/v1.1/apps \
       --user 'keyId:keySecret'
smooch.apps.list().then((response) => {
    // async code
});

Response:

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

GET /v1.1/apps

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

When using service account credentials, only apps for which the service account has access are returned.

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.
serviceAccountId When specified, lists only the apps that the service account has access to.

Get App

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6 \
     --user 'keyId:keySecret'
smooch.apps.get('55c8d9758590aa1900b9b9f6').then((response) => {
    // async code
});

Response:

200 OK
{
    "app": {
        "_id": "55c8d9758590aa1900b9b9f6",
        "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
        "name": "My App",
        "settings": {
            "maskCreditCardNumbers": true,
            "echoPostback": false,
            "useAnimalNames": false
        }
    }
}

GET /v1.1/apps/{appId}

Fetches an individual app.

Update App

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6 \
     -X PUT \
     -d '{"name": "My New App", "settings": {"maskCreditCardNumbers": false, "useAnimalNames": true, "echoPostback": true}}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.apps
    .update('55c8d9758590aa1900b9b9f6', {
        name: 'My New App',
        settings: {
            maskCreditCardNumbers: false,
            echoPostback: true,
            useAnimalNames: true
        },
        metadata: {
            foo: 'bar'
        }
    })
    .then((response) => {
        // async code
    });

Response:

200 OK
{
    "app": {
        "_id": "55c8d9758590aa1900b9b9f6",
        "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
        "name": "My New App",
        "settings": {
            "maskCreditCardNumbers": false,
            "echoPostback": true,
            "useAnimalNames": true
        },
        "metadata": {
            "foo": "bar"
        }
    }
}

PUT /v1.1/apps/{appId}

Updates an app.

Arguments
name
optional
The User facing name of the app.
settings
optional
Customizable app settings (see app settings).
metadata
optional
Flat object containing any custom properties associated with the app. See app metadata for more information.

Delete App

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6 \
       -X DELETE \
       --user 'keyId:keySecret'
smooch.apps.delete('55c8d9758590aa1900b9b9f6').then((response) => {
    // async code
});

Response:

200 OK
{}

DELETE /v1.1/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 retrieve the Smooch app. Also used to initialize Smooch’s Mobile and Web SDKs.
appToken (deprecated) A public token used to initialize older versions of the Smooch Mobile and Web SDKs.
name The friendly name of the app.
settings Customizable app settings (see app settings).
metadata Flat object containing any custom properties associated with the app. See app metadata for more information.

App metadata

Data representing an optional flat object sent as an argument of a POST or PUT App API call containing additional properties associated with the app. Metadata properties can have values of type string, number, boolean, or null and is limited to 4KB in size. Both keys and values are accounted for this size limitation and an error will be returned if an app is in the process of being created or updated and metadata goes over the size limit.

Truncated app schema

A truncated version of the app sent with webhook payloads.

Field Description
_id A canonical ID that can be used to retrieve the Smooch app. Also used to initialize Smooch’s Mobile and Web SDKs.

App settings

Apps have a number of settings that can be used to customize specific behaviors.

Field Description
conversationRetentionSeconds
optional
Number of seconds of inactivity before a conversation’s messages will be automatically deleted. See below.
maskCreditCardNumbers
optional
A boolean specifying whether credit card numbers should be masked when sent through Smooch.
useAnimalNames
optional
A boolean specifying whether animal names should be used for unnamed users. See the user naming guide for details.
echoPostback
optional
A boolean specifying whether a message should be added to the conversation history when a postback button is clicked. See below.

Conversation Retention Seconds

The conversationRetentionSeconds setting dictates a period of time after which an inactive conversation will have its messages deleted. The deletion behavior is similar to when an appUser’s messages are deleted, meaning the messages will be deleted, but the appUser and any associated channels will remain. There is a separate API that can be used to fully delete an appUser. As long as a conversation continues to receive regular activity, messages will not expire. Activities that will prevent message expiration include:

If conversationRetentionSeconds is left unset, no automatic message deletion will take place. The setting may be set to 0 in order to disable automatic message deletion upon new message activity. If nonzero, the minimum setting is 1 hour (3600 seconds).

Echo Postbacks

echoPostback controls whether a message should be added to the conversation history when a postback button is clicked. When enabled, An appUser message is silently added to the conversation, without a corresponding message:appUser webhook being triggered.

The echoPostback setting works with any channel that supports postback actions natively (including Facebook Messenger, Twitter DM, Telegram, LINE and all Smooch SDKs). In some channels Smooch offers partial support for postback buttons via text fallback. For these channels, the user needs to answer with a message matching the postback action text. In this case, the user’s message will always be added to the conversation history.

App Keys

This set of endpoints is used to provision and revoke API keys for a Smooch app. An app can have a maximum of 10 keys.

Create App Key

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys \
     -X POST \
     -d '{"name": "key1"}' \
     -H 'content-type: application/json' \
     --user 'keyId:keySecret'
smooch.apps.keys.create('55c8d9758590aa1900b9b9f6', 'key1').then((response) => {
    // async code
});

Response:

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

POST /v1.1/apps/{appId}/keys

Creates an API 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 API key.

List App Keys

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys \
       --user 'keyId:keySecret'
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.1/apps/{appId}/keys

Lists all API keys for a given app.

Get App Key

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34 \
       --user 'keyId:keySecret'
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.1/apps/{appId}/keys/{keyId}

Returns an API key.

Delete App Key

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34 \
       -X DELETE \
       --user 'keyId:keySecret'
smooch.apps.keys.delete('55c8d9758590aa1900b9b9f6', 'app_5723a347f82ba0516cb4ea34').then((response) => {
    // async code
});

Response:

200 OK
{}

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

Removes an API key.

Get App JWT

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34/jwt \
       --user 'keyId:keySecret'
smooch.apps.keys.getJwt('55c8d9758590aa1900b9b9f6', 'app_5723a347f82ba0516cb4ea34').then((response) => {
    // async code
});

Response:

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

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

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

Smooch Connect

Introduction

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

Add to Smooch Button

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

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

Add to Smooch

Sample Application

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

The source code is available here.

OAuth Endpoints

Authorize

Request:

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

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

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

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

Success Response

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

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

Error Response

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

Error Codes

Error Code Delivery Method Description
access_denied 302 The user denied access

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.1/appusers/\* Yes
/v1.1/webhooks/\* Yes
/v1.1/apps/\* No
/v1.1/integrations/\* No
/v1.1/menu/\* No

Revoke Access

Request:

curl -X DELETE https://api.smooch.io/oauth/authorization \
     -H 'authorization: Bearer your-access-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.

Changelog

v1.1

Released 2018-10-02

Webhooks

AppUsers

Conversation