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.

The API also facilitates 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({
    jwt: 'some-jwt',
});

// Use EU region
const smooch = new SmoochCore({
    jwt: 'some-jwt',
    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.

When configuring an API host, make sure to always use https. Some API clients can have unexpected behaviour when following redirects from http to https.

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. To ensure the best experience for your users, 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 uses JSON Web Tokens (JWTs) to authenticate server-to-server calls. See below for more details on how to sign a JWT.

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

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

JWTs issued with 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.

JWTs issued with 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.

An additional scope of appUser can also be used to authenticate users when using one of the Smooch native SDK integrations. For information on how and when to use this scope, see the guide for authenticating users.

Authentication

# Calling GET /v1.1/appusers using a JWT
curl $SMOOCH_ROOT/v1.1/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'authorization: Bearer your-jwt'

// Initializing Smooch Core with a JWT in the browser
var smooch = new SmoochCore({
    jwt: 'your-jwt'
});

// Initializing Smooch Core with a JWT in Node.js
var smooch = new SmoochCore({
    keyId: 'your-key-id',
    secret: 'your-secret',
    scope: 'app', // account or app
});

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

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

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

JWT header:

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

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

JWT payload with account scope:

{
    "scope": "account"
}

JWT payload with app scope claim:

{
    "scope": "app"
}

Scope

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

JWT with account scope example

const jwt = require('jsonwebtoken');

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

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

JWT with app scope example

const jwt = require('jsonwebtoken');

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

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

The account scope grants access to all apps, users, and conversations associated with a given Smooch account, or service account. The account scope is reserved for server-to-server scenarios. The account scope JWT is signed with either an account secret key (act_), or a service account secret key (svc_).
The app scope grants access to all users, and conversations within a given Smooch app. The app scope is reserved for server-to-server scenarios. The app scope JWT is signed with an app secret key (app_).

Resource Paths

Resource path with account scope token example

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'authorization: Bearer your-account-jwt'

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

Resource path with app scope token example

curl $SMOOCH_ROOT/v1.1/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'authorization: Bearer your-app-jwt'

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

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

Webhooks

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

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
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
List webhooks
Get webhook
Update webhook
Delete webhook

Create webhook

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks \
     -X POST \
     -d '{"target": "http://example.com/callback", "triggers": ["message:appUser"]}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.webhooks.create('5963c0d619a30a2e00de36b8', {
    target: 'http://example.com/callback',
    triggers: ['message:appUser']
}).then((response) => {
    // async code
});

Response:

201 CREATED

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

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.

If you try to create a webhook on a target already used by another webhook, the existing webhook will be updated by merging the triggers and a 200 HTTP status will be returned.

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.

The triggers property is supported as optional in our v1 API.

List webhooks

Request:

  curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks \
       -H 'authorization: Bearer your-account-jwt'

smooch.webhooks.list('5963c0d619a30a2e00de36b8').then((response) => {
    // async code
});

Response:

200 OK

{
  "webhooks": [
    {
      "_id": "55c8d9758590aa1900b9b9f6",
      "triggers": [
        "message: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 \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

200 OK

{
  "webhook": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "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"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.webhooks.update('5963c0d619a30a2e00de36b8', '55c8d9758590aa1900b9b9f6', {
    target: 'http://example.com/callback'
}).then((response) => {
    // async code
});

Response:

200 OK

{
  "webhook": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "triggers": [
      "message: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.

Delete webhook

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks/55c8d9758590aa1900b9b9f6 \
     -X DELETE \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

200 OK

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

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

Webhooks created with the v1 API will return the full appUser schema instead of the truncated version.

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

The payload for an image message.

Trigger - `message:appMaker` (carousel)

Payload:

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

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

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

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

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

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.

This is the behavior for webhooks created with our v1 API, newer API versions will send them as file type messages

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",
        "properties": {},
        "signedUpAt": "2015-10-06T03:38:02.346Z",
        "clients": [
          {
            "active": true,
            "id": "5A7F8343-DF41-46A8-96EC-8583FCB422FB",
            "lastSeen": "2016-03-09T19:09:01.431Z",
            "platform": "messenger"
          }
        ]
    }
}

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

Postback event payload schema

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

Webhooks created with the v1 API will return the full appUser schema instead of the truncated version.

Postback schema

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

Conversation Events

Trigger - `conversation:read`

Payload:

{
  "trigger": "conversation:read",
  "app": {
    "_id": "57ec2881c47d2d24b0c16427"
  },
  "source": {
    "type": "messenger"
  },
  "appUser": {
    "_id": "7685787bf0e9e8cf56182288",
    "conversationStarted": true
  },
  "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.
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.

Webhooks created with the v1 API will return the full appUser schema instead of the truncated version for “conversation:start” events.

Trigger - `conversation:start`

Payload:

{
    "trigger": "conversation:start",
    "app": {
        "_id": "57ec2881c47d2d24b0c16427"
    },
    "source": {
        "type": "messenger"
    },
    "appUser": {
        "_id": "c7f6e6d6c3a637261bd9656f",
        "userId": "bob@example.com",
        "conversationStarted": true
    },
    "timestamp": 1480349392.103
}

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

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

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

Trigger - `conversation:referral`

Payload:

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

Conversation referral payload schema

Field	Description
trigger	`"conversation:referral"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
source	A nested object representing the source of the event. See the source schema below for details.
appUser	A truncated appUser schema object
referral	Referral information. See referral schema for details.
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:

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

Merge Events

Trigger - `merge:appUser`

Payload:

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

The payload for when two users are merged into one.

Merge events payload

Field	Description
trigger	`"merge:appUser"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
surviving	A nested object with the truncated appUser that now represents the merged appUser objects. See the truncated appUser schema below for details.
discarded	An array of objects with the truncated appUsers that were unified into `surviving` appUser object. See the truncated appUser schema below for details.
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 are going over the 4KB limit.
version	The API version used to create the webhook. See API version for details.

Message Delivery Events

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

Channel delivery confirmation The message is delivered to the channel (e.g. WhatsApp), represented by the message:delivery:channel trigger.
User delivery confirmation The message is delivered to the user, represented by the message:delivery:user trigger.
Delivery failure The message could not be delivered (either to the channel or to the user), represented by the message:delivery:failure trigger.

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.

The delivery:success and delivery:failure triggers are only supported in v1 of the API, and have been removed in v1.1 and later. See the v1.1 changelog for more details.

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 appUser 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"
    },
    "destination": {
        "type": "twilio"
    },
    "isFinalEvent": false,
    "externalMessages": [
        {
            "id": "SMb0ee6ee1313a4141ba346e368325a04d"
        }
    ],
    "message": {
        "_id": "5baa5b4ab5bebb000ce85589"
    },
    "timestamp": 1537891147.555
}

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"
    },
    "destination": {
        "type": "twilio"
    },
    "isFinalEvent": true,
    "externalMessages": [
        {
            "id": "SMb0ee6ee1313a4141ba346e368325a04d"
        }
    ],
    "message": {
        "_id": "5baa5b4ab5bebb000ce85589"
    },
    "timestamp": 1537891147.555
}

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"
    },
    "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
}

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"
    },
    "payments": [
        {
            "source": {
                "type": "messenger"
            },
            "message": {
                "text": "Just put some vinegar on it",
                "actions": [
                    {
                        "text": "Buy vinegar",
                        "amount": 1000,
                        "currency": "usd",
                        "state": "paid",
                        "_id": "5877fd5624fe8fd934d7c2f3",
                        "uri": "https://app.smooch.io/checkout/5877fd5624fe8fd934d7c2f3",
                        "type": "buy"
                    }
                ],
                "type": "text",
                "role": "appMaker",
                "received": 1484258646.823,
                "authorId": "5X8AJwvpy0taCkPDniC5la",
                "avatarUrl": "https://www.gravatar.com/image.jpg",
                "_id": "5877fd5624fe8fd934d7c2f2",
                "source": {
                    "type": "api"
                }
            },
            "action": {
                "text": "Buy vinegar",
                "amount": 1000,
                "currency": "usd",
                "state": "paid",
                "_id": "5877fd5624fe8fd934d7c2f3",
                "uri": "https://app.smooch.io/checkout/5877fd5624fe8fd934d7c2f3",
                "type": "buy"
            },
            "charge": {
                "id": "ch_19dPrCHQ7f2U7NYSZ45OspXT"
            }
        }
    ],
    "timestamp": 1484258666.455
}

The payload for when a payment is received.

Payment event payload schema

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

Link Events

Trigger - `link:success`

Payload:

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

The payload for a link app user success.

Link success event payload schema

Field	Description
trigger	`"link:success"`
app	A nested object representing the Smooch app associated with the event. See the truncated app schema below for details.
appUser	A nested object representing the appUser associated with the event. See the truncated appUser schema below for details.
channel	The channel for which the link succeeded.
criteria	The criteria specified to establish the link.
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"
    },
    "channel": "messenger",
    "criteria": {
        "phoneNumber": "+15141234567",
        "givenName": "bleep",
        "surname": "bloop"
    }
}

The payload for a link app user match.

Link match event payload schema

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

Trigger - `link:failure`

Payload:

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

The payload for a link app user failure.

Link failure event payload schema

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

Client Events

Trigger - `client:add`

Payload:

{
    "trigger": "client:add",
    "app": {
        "_id": "575040549a38df8fb4eb1e51"
    },
    "appUser": {
        "_id": "de13bee15b51033b34162411",
        "userId": "123",
        "conversationStarted": true
    },
    "clients": [{
        "platform": "web",
        "id": "90e2f396500b451dabdce69f207247d4",
        "lastSeen": "2017-11-15T22:33:12.935Z",
        "active": true,
        "primary": true
    }]
}

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 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
    },
    "clients": [{
        "id": "90e2f396500b451dabdce69f207247d4"
    }]
}

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 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"
    },
    "activity": {
        "type": "typing:stop"
    },
    "source": {
        "type": "ios"
    }
}

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 appUser schema below for details.
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 a webhook

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

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

Retry Policy

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

Non-recoverable Errors

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

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

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.

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

Profile properties

Profile properties are limited to 4KB per users. Both key and values are accounted for in this size limitation. An error will be returned if an app user is in the process of being created or updated and the custom properties are going over the size limit.

Get App User

Request by smoochId:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
     -H 'authorization: Bearer your-account-jwt'

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 \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

200 OK

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

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' \
     -H 'authorization: Bearer your-account-jwt'

smooch.appUsers.update({
    appId: '5963c0d619a30a2e00de36b8',
    userId: 'c7f6e6d6c3a637261bd9656f',
    appUser: {
        givenName: 'Steve'
    }
}).then((response) => {
    // async code
});

Response:

200 OK

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

PUT /v1.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 \
     -H 'authorization: Bearer your-account-jwt'

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 \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

200 OK

{
    "appUser": {
        "_id": "deb920657bbc3adc3fec7963",
        "userId": "steveb@channel5.com",
        "signedUpAt": "2015-10-08T23:52:11.677Z",
        "properties": {},
        "conversationStarted": true,
        "clients": [
          {
            "active": true,
            "appVersion": "1.0",
            "id": "5A7F8343-DF41-46A8-96EC-8583FCB422FB",
            "lastSeen": "2016-03-09T19:09:01.431Z",
            "platform": "ios",
            "pushNotificationToken": "<...>"
          }
        ]
    }
}

DELETE /v1.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 \
     -H 'authorization: Bearer your-account-jwt'

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 \
     -H 'authorization: Bearer your-account-jwt'

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.

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' \
     -H 'authorization: Bearer your-account-jwt'

smooch.appUsers.create({
    appId: '5963c0d619a30a2e00de36b8',
    appUser: {
        userId: 'steveb@channel5.com',
        givenName: 'Steve',
        properties: {
            favoriteFood: 'prizza'
        }
    }
}).then((response) => {
    // async code
});

Response:

201 CREATED

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

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.

The credentialRequired property is still supported in our v1 API.

Get App User Channel Entities

Request:

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

smooch.appUsers.getChannels({
    appId: '5963c0d619a30a2e00de36b8',
    userId: 'deb920657bbc3adc3fec7963'
}).then((response) => {
    //Async code
});

Response:

200 OK

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

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	userId A string representing a messenger, viber, line, or wechat 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.

Get App User Business System IDs

Request:

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

smooch.appUsers.getBusinessSystems({
    appId: '5963c0d619a30a2e00de36b8',
    userId: 'deb920657bbc3adc3fec7963'
}).then((response) => {
    //Async code
});

Response:

200 OK

{
    "businessSystems": [
        {
            "type": "slack",
            "channelId": "C872AE91B"
        },
        {
            "type": "zendesk",
            "ticketId": "9999"
        },
        {
            "type": "hipchat",
            "roomId": 1337
        },
        {
            "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.
hipchat	roomId An integer representing the Hipchat room ID.
helpscout	conversationId A string representing the Helpscout conversation ID.

Link App User To Channel

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' \
     -H 'authorization: Bearer your-account-jwt'

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": "deb920657bbc3adc3fec7963",
        "userId": "steveb@channel5.com",
        "givenName": "Steve",
        "signedUpAt": "2015-10-08T23:52:11.677Z",
        "properties": {
          "favoriteFood": "prizza"
        },
        "conversationStarted": false,
        "clients": [],
        "pendingClients": [
            {
                "id": "d383f9f4-c8d2-42dd-9f7c-f525fad6849d",
                "platform": "twilio",
                "displayName": "+15145555555"
            }
        ]
    }
}

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

Arguments
type required	The channel to link. Can be `twilio`, `messagebird` or `mailgun`. The channel `messenger` is also valid, but since it’s in early access, you need to contact Smooch to enable it.
{entity} required	The required entity for linking. This is different for each channel.
confirmation required	The confirmation option for linking.
primary optional	Default is `true`. Flag indicating whether the client will become the primary once linking is complete.

Some extra arguments are supported depending on the selected type.

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

When a link request is first made, the channel will be added to the pendingClients field. At this point, the API call will be considered a success and a response will be returned. Future updates on the status of the link request can be tracked by listening to the link:match, link:success and link:failure webhooks.

The skipConfirmation flag is still supported in our v1 API. Note that it’s accepted for twilio linking only.

The confirmation property is supported as optional in our v1 API.

Linking confirmation

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

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

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

Immediate

Available on: Twilio, MessageBird, Messenger, Mailgun

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

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

User activity

Available on: Twilio, MessageBird, Messenger

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

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

Prompt

Available on: Twilio, 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	phoneNumber A String of the appUser’s phone number. It must contain the `+` prefix and the country code. Examples of valid phone numbers: `+1 212-555-2368`, `+12125552368`, `+1 212 555 2368`. Examples of invalid phone numbers: `212 555 2368`, `1 212 555 2368`.
messenger	phoneNumber A String of the appUser’s phone number. It must contain the `+` prefix and the country code. Examples of valid phone numbers: `+1 212-555-2368`, `+12125552368`, `+1 212 555 2368`. Examples of invalid phone numbers: `212 555 2368`, `1 212 555 2368`.	`givenName` and `surname` may be specified as additional criteria to increase the likelihood of a match.
mailgun	address A String of the appUser’s email address	`subject` may be specified to set the subject for the outgoing email. Default `subject`: “New message from {appName}”

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

Unlink App User From Channel

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/channels/twilio \
     -X DELETE \
     -H 'authorization: Bearer your-account-jwt'

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.

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' \
     -H 'authorization: Bearer your-account-jwt'

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 Link Requests

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' \
     -H 'authorization: Bearer your-account-jwt'

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.

A link request code and url is only valid for 1 month. Only one pending link request can be active per appUser per integration. Generating a new link request will invalidate any existing pending link request issued for that appUser and integration.

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)

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.

The credentialRequired and devices properties are still included in payloads from our v1 API.

Truncated app user schema

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

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

Client schema

Client specific info

Field	Description
active	If active is `false` then the appUser is not logged in to the client and signifies that the appUser will not receive APN or FCM notifications. This pertains to the SDKs.
platform	Includes one of `"web"`, `"ios"`, `"android"`, `"messenger"`, `"viber"`, `"telegram"`, `"wechat"`, `"line"`, `"twilio"`, and `"other"`, or any number of other platforms.
primary	Boolean indicating if the platform is the appUser’s primary channel. The primary channel is the user’s most active channel and the preferred delivery channel for the appMaker’s messages.
id	A unique identifier for a device if on Web, iOS, or Android, or a client on other channels.
displayName optional	The appUser’s display name as provided by the client.
avatarUrl optional	The URI for an appUser’s avatar, as provided by the client.
info optional	A flat 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
blocked optional	A boolean representing whether the appUser has unsubscribe from the channel or not.

Raw client info

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

The list of fields below is an overview of what you can expect in the raw field and is provided as a convenience. We recommend following the links to the official specification for each channel for a complete definition.

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

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

Twitter

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.

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.

Twilio

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.

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 .

MessageBird

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.

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.

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.

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.

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.

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' \
     -H 'authorization: Bearer your-account-jwt'

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' \
     -H 'authorization: Bearer your-account-jwt'

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 using this API via the image type. Alternatively, you may also upload images to the conversation directly using the /images endpoint.

It’s possible that a request to this endpoint generates multiple messages. For example, when sending a template message. If additional messages end up being created in this way, they will be returned in the extraMessages key. The message key always contains one message.

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

The type property is supported as optional in our v1 API.

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 \
     -H 'authorization: Bearer your-account-jwt'

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 \
     -H 'authorization: Bearer your-account-jwt'

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 \
     -H 'authorization: Bearer your-account-jwt'

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.

Upload and Send Image (Deprecated)

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/images \
     -X POST \
     -H 'authorization: Bearer your-account-jwt' \
     -H 'content-type: multipart/form-data' \
     -F 'source=@screenshot.jpg;type=image/jpeg' \
     -F 'role=appUser' \
     -F 'name=Steve'

// Frontend version
var file = fileInput.files[0];
smooch.appUsers.uploadImage('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f', file,
{
    text: 'Just put some vinegar on it',
    role: 'appUser'

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

// Not yet supported on Node.

Response:

201 CREATED

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

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

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

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

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

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' \
     -H 'authorization: Bearer your-account-jwt'

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' \
     -H 'authorization: Bearer your-account-jwt'

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 \
     -H 'authorization: Bearer your-account-jwt'

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 \
     -H 'authorization: Bearer your-account-jwt' \
     -H 'content-type: multipart/form-data' \
     -F 'source=@document.pdf;type=application/pdf'

var file = fileInput.files[0];
smooch.attachments.create({
  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 and mediaType 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.

If the for parameter is not provided, it is assumed that the attachment will be used across multiple messages, and therefore will not be deleted when any of the sent messages are deleted.

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' \
     -H 'authorization: Bearer your-account-jwt'

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 \
     -H 'authorization: Bearer your-account-jwt' \
     -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 \
     -H 'authorization: Bearer your-account-jwt'

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 \
     -H 'authorization: Bearer your-account-jwt' \

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 \
     -H 'authorization: Bearer your-account-jwt' \
     -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.

At least one of name or message is required for the update.

Delete Template

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/templates/5b477234e951d11d6e2efe7e \
     -X DELETE \
     -H 'authorization: Bearer your-account-jwt'

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

Text

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

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' \
     -H 'authorization: Bearer your-account-jwt' \
     -d '
{
    "role": "appMaker",
    "type": "image",
    "text": "Hello!",
    "mediaUrl": "http://example.org/image.jpg",
    "actions": [{
        "text": "More info",
        "type": "link",
        "uri": "http://example.org"
    }]
}'

smooch.appUsers.sendMessage({
    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.

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.
mediaType optional	The media type is defined here, for example `image/jpeg`. If `mediaType` is not specified, the media type will be resolved with the `mediaUrl`.

File

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": "file",
    "mediaUrl": "http://example.org/document.pdf",
    "mediaType": "application/pdf"
}'

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

Response:

201 CREATED

{
  "message": {
    "_id": "57966d21c19c9da00839a5e9",
    "role": "appMaker",
    "type": "file",
    "mediaUrl": "http://example.org/document.pdf",
    "mediaType": "application/pdf",
    "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.

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

Location

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

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

Coordinates

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

Carousel

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

Arguments
items required*	Array of message items. The array is limited to 10 items.
displaySettings optional	Settings to adjust the carousel layout. See Display Settings.

Display Settings

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

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

Channel Support

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

Facebook Messenger

Full support. messenger carousel

Full support, with cards arranged vertically. telegram carousel

LINE

Full support. line carousel

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.

List

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

Facebook Messenger and WeChat have native support.
For LINE and our Android, iOS and Web SDK, Smooch converts list messages to carousel.
On Telegram and Twitter, Smooch converts list messages to multiple rich messages.
On all other platforms, Smooch converts list messages to raw text.

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

Each items.actions supports one link action. If there is a link action with a default set to true, it will be given priority. Otherwise, the first link action will be used.
items.description is displayed when there is no image, or when there is only one item included in the message.
actions are truncated.
The length of the items array is truncated to the first 8 items.

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.

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.

Message actions can only be attached to messages with a role of appMaker.

Link

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' \
     -H 'authorization: Bearer your-account-jwt'

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.

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

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' \
     -H 'authorization: Bearer your-account-jwt'

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.

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' \
     -H 'authorization: Bearer your-account-jwt'

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' \
     -H 'authorization: Bearer your-account-jwt'

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' \
     -H 'authorization: Bearer your-account-jwt'
     -d '
{
    "text":"Which do you prefer?",
    "role": "appMaker",
    "type": "text",
    "actions": [{
        "type": "reply",
        "text": "Tacos",
        "iconUrl": "http://example.org/taco.png",
        "payload": "TACOS"
    }, {
        "type": "reply",
        "text": "Burritos",
        "iconUrl": "http://example.org/burrito.png",
        "payload": "BURRITOS"
    }]
}'

smooch.appUsers.sendMessage({
    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.
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.

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

Facebook Messenger Facebook Messenger reply icons

Web Messenger Web Messenger reply icons

Location Request

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

Send locationRequest action:

curl $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' \
     -H 'authorization: Bearer your-account-jwt'

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.

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

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

Send share action:

curl $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",
        "mediaType": "image/jpeg",
        "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.

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`.
mediaType optional	If a `mediaUrl` was specified, the media type is defined here, for example `image/jpeg`. If `mediaType` is not specified, the media type will be resolved with the `mediaUrl`.

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"`, or `"list"`.
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.
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.
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.

Truncated message schema

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

Field	Description
_id	The unique ID for the message.

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.

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

Referral schema

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

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

Referral details schema

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

Metadata schema

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

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

Persistent Menus

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

Request:

curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/menu \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

200 OK

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

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

Get the specified app’s 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' \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

200 OK

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

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

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

Request:

curl $SMOOCH_ROOT/v1.1/menu \
     -X DELETE \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

200 OK

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

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

Remove the specified app’s menu.

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/menu \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

200 OK

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

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

Get the specified integration’s 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' \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

200 OK

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

PUT /v1.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.

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/menu \
     -X DELETE \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

200 OK

{}

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

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

Schema

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

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

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

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

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

Integrations

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

Each supported integration type is provided in its corresponding section (e.g Apple Push Notification).

Manage Integrations

Smooch exposes REST API methods to:

Create integration
List integrations
Get integration
Update integration
Update integration profile
Delete integration

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 \
       -H 'authorization: Bearer your-account-jwt'

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

Response:

200 OK

{
  "integrations": [
    {
      "_id": "582dedf230e788746891281a",
      "type": "messenger",
      "pageId": "841556169307254",
      "appId": "1674554616147204",
      "status": "active"
    },
    {
      "_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"
    }
  ]
}

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

Lists all integrations for a given app.

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

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.

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 \
       -H 'authorization: Bearer your-account-jwt'

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

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

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

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" }' \
        -H 'content-type: application/json' \
        -H 'authorization: Bearer your-account-jwt'

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'
  }
}).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"
  }
}

See Web Messenger for more information about the arguments.

Request:

    curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/582dedf230e788746891281a \
        -X PUT \
        -d '{ "hsmFallbackLanguage": "fr_CA" }' \
        -H 'content-type: application/json' \
        -H 'authorization: Bearer your-account-jwt'

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.

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.

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' \
    -H 'authorization: Bearer your-account-jwt'

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.
address optional	Address of the business. Maximum of 256 characters. Can be unset with `null`.
description optional	Description of the business. Maximum of 256 characters. Can be unset with `null`.
email optional	Email address to contact the business. Maximum of 128 characters. Can be unset with `null`.
vertical optional	Industry of the business. Maximum of 128 characters. Can be unset with `null`.
websites optional	URLs associated with the business. Maximum of 2 websites, each with a maximum of 256 characters. Can be unset with `null`.
photoUrl optional	URL where the business' profile photo is hosted. WhatsApp recommends an image with dimensions of 640x640 and max size of 63KB.

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

Delete Integration

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02 \
       -X DELETE \
       -H 'authorization: Bearer your-account-jwt'

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.

Apple Push Notification

Request:

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

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' \
     -H 'authorization: Bearer your-account-jwt'

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:

Take note of your Facebook app ID and secret (apps can be created at developer.facebook.com);
The Facebook app must have been submitted to Facebook for approval with the “manage_pages” (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.

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' \
     -H 'authorization: Bearer your-account-jwt'

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": "1286564967", channelAccessToken": "jZak8gGEYxfy1gIxk869osf2SuT6o11rtLqZQnAx9TiKE7eFXwgnnL58dtwOd1ON9e11GPTDfq+b4hson3dvvYAnAaAnbXYjj1rCUIzgxAa4xVZwGqyS+2rzpswZnGhAuMBWQxCMsF9dwztolUr01wdB04t89/1O/w1cDnyilFU=", "channelSecret": "b85cff984b26eac4297917abd365c4d6"' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

201 CREATED

{
    "integration": {
      "_id": "5735ddfd48011972d621dc0a",
      "type": "line",
      "status": "active",
      "channelId": "1286564967"
    }
}

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.

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' \
     -H 'authorization: Bearer your-account-jwt'

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.

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": "V0oSoktDijjGiAof265hj32fh", "originator": "12262121021"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

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

Response:

201 CREATED

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

To configure a MessageBird integration, acquire the accessKey and the MessageBird number you would like to use, then call the Create Integration endpoint. 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:

Create a new Call HTTP endpoint with SMS flow.
Select your desired SMS number for Incoming SMS.
Click on Forward to URL and set its method to POST.
Then, using the integration _id and webhookSecret returned from the create integration call, enter the following into the URL field: https://app.smooch.io/api/messagebird/webhooks/{appId}/{integrationId}/{webhookSecret}
Select application/json for the Set Content-Type header field.
Save and publish your changes.

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

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "telegram", "token": "192033615:AAEuee2FS2JYKWfDlTulfygjaIGJi4s"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.create({
    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.

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' \
     -H 'authorization: Bearer your-account-jwt'

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.

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' \
     -H 'authorization: Bearer your-account-jwt'

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.

Viber

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "viber", "token": "df5f8c5233399561-92636b0c5ba30da9-16d4928fc004a72d"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.create({
    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.

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' \
     -H 'authorization: Bearer your-account-jwt'

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'
    }
}).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"
  }
}

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

WeChat

Request:

curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
     -X POST \
     -d '{"type": "wechat", "appId": "ACa1b4c65ee0722712fab89867cb14eac7", "appSecret": "160c024303f53049e1e060fd67ca6aefc"}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.create({
    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

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.

Request:

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' \
     -H 'authorization: Bearer your-account-jwt'

smooch.integrations.create({
    appId: '55c8d9758590aa1900b9b9f6',
    props: {
        type: 'whatsapp',
        baseUrl: 'https://15144441919.whatsapp.ec.url',
        username: 'smooch',
        password: 'r0cks'
    }
}).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.

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.

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 an account scoped JWT. For more details about signing JWTs, see the authorization section.

A JWT signed with an account key (act_) can access all account provisioning routes. You can create an account key by going to your account page.

A JWT signed with a service account key (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' \
     -H 'authorization: Bearer your-account-token'

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

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

List Service Accounts

Request:

  curl $SMOOCH_ROOT/v1.1/serviceaccounts \
       -H 'authorization: Bearer your-account-token'

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 max of 25 service accounts by default, and accepts offset and limit query parameters. The max limit is 100.

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

Get Service Account

Request:

curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2 \
     -H 'authorization: Bearer your-account-token'

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' \
     -H 'authorization: Bearer your-account-token'

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 \
       -H 'authorization: Bearer your-account-token'

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 secret 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' \
     -H 'authorization: Bearer your-account-token'

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 a secret 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 secret key.

List Service Account Keys

Request:

  curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys \
       -H 'authorization: Bearer your-account-token'

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 secret keys for a given service account.

Get Service Account Key

Request:

  curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys/svc_5808ba5cedf3b5931970e054 \
       -H 'authorization: Bearer your-account-token'

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 a secret key.

Delete Service Account Key

Request:

  curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys/svc_5808ba5cedf3b5931970e054 \
       -X DELETE \
       -H 'authorization: Bearer your-account-token'

smooch.serviceAccounts.keys.delete('5a71d7419b3ad47012a5dde2', 'svc_5808ba5cedf3b5931970e054').then((response) => {
    // async code
});

Response:

200 OK

{}

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

Removes a secret key.

Get Service Account JWT

Request:

  curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys/svc_5808ba5cedf3b5931970e054/jwt \
       -H 'authorization: Bearer your-account-token'

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' \
     -H 'authorization: Bearer your-account-token'

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

Response:

201 CREATED

{
  "app": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
    "name": "My App",
    "settings": {
      "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 \
       -H 'authorization: Bearer your-account-token'

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

Response:

200 OK

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

GET /v1.1/apps

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

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 \
     -H 'authorization: Bearer your-account-token'

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

Response:

200 OK

{
  "app": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
    "name": "My App",
    "settings": {
      "maskCreditCardNumbers": true,
      "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}}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-token'

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

Response:

200 OK

{
  "app": {
    "_id": "55c8d9758590aa1900b9b9f6",
    "appToken": "3s58wwlgx8xqbidgyyvzunoyw",
    "name": "My New App",
    "settings": {
      "maskCreditCardNumbers": false,
      "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 \
       -H 'authorization: Bearer your-account-token'

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.

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:

A message is added to the conversation
A postback event is triggered

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

App Keys

This set of endpoints is used to provision and revoke secret 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' \
     -H 'authorization: Bearer your-account-token'

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

Response:

201 CREATED

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

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

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

Arguments
name required	A friendly identifier for the secret key.

List App Keys

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys \
       -H 'authorization: Bearer your-account-token'

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

Response:

200 OK

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

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

Lists all secret keys for a given app.

Get App Key

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34 \
       -H 'authorization: Bearer your-account-token'

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

Response:

200 OK

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

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

Returns a secret key.

Delete App Key

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34 \
       -X DELETE \
       -H 'authorization: Bearer your-account-token'

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

Response:

200 OK

{}

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

Removes a secret key.

Get App JWT

Request:

  curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34/jwt \
       -H 'authorization: Bearer your-account-token'

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

Response:

200 OK

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

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

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

Webhooks include a version property
Removed support for message trigger. Use message:appUser and message:appMaker instead
triggers is now a required property when creating a webhook
message:appUser events support file messages. Previous versions sent them as text messages
postback, conversation:start, message:appUser and message:appMaker events now include truncated appUser schema
New message delivery webhooks have been introduced, described below. See the Delivery Events guide for more details:
- Removed delivery:success and delivery:failure webhook triggers which are replaced by message:delivery:channel and message:delivery:failure respectively
- message:delivery:channel triggers when messages are delivered to SDKs.
- message:delivery:failure can be triggered after a message:delivery:channel event if a message cannot be delivered to the user.
- message:delivery:user is a new trigger that allows to confirm the delivery of a message to a user for channels that support it.
- The payloads used to include a list of messages. They now only include one message and only contain an _id property.
- New properties isFinalEvent and externalMessages are included in these new webhook payloads.

AppUsers

API responses no longer include a devices array and a credentialRequired property. devices has been renamed to clients long ago and it was kept in API responses for backward compatibility
Link App User To Channel
- confirmation is now a required property
- skipConfirmation property is no longer supported
Pre-Create App User
- credentialRequired is no longer supported

Conversation

type is now a required property when posting a message

Core

Introduction

Regions

API Version

API Libraries

Postman Collection

Errors

Rate Limits

Request Size Limits

Authorization

Authentication

Header

Scope

Resource Paths

Webhooks

Webhook triggers

Basic Triggers

Additional Triggers

Manage Webhooks

Create webhook

List webhooks

Get webhook

Update webhook

Delete webhook

Message Events

Trigger - message:appUser (text)

Message event payload schema

Trigger - message:appUser (image)

Trigger - message:appMaker (carousel)

Trigger - message:appMaker (list)

Trigger - message:appUser (location)

Trigger - message:appUser (file)

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

Postback Events

Trigger - postback

Postback event payload schema

Postback schema

Conversation Events

Trigger - conversation:read

Conversation event payload schema

Trigger - conversation:start

Trigger - conversation:referral

Conversation referral payload schema

Merge Events

Trigger - merge:appUser

Merge events payload

Message Delivery Events

Delivery event payload schema

External message schema

Error schema

Trigger - message:delivery:channel

Trigger - message:delivery:user

Trigger - message:delivery:failure

Payment Events

Trigger - payment:success

Payment event payload schema

Payment schema

Charge schema

Link Events

Trigger - link:success

Link success event payload schema

Trigger - link:match

Link match event payload schema

Trigger - link:failure

Link failure event payload schema

Client Events

Trigger - client:add

client:add event payload schema

Trigger - client:remove

client:remove event payload schema

Typing Events

Trigger - typing:appUser

typing:appUser event payload schema

Securing a webhook

Retry Policy

Non-recoverable Errors

App User

userId

Profile properties

Get App User

Trigger - `message:appUser` (text)

Trigger - `message:appUser` (image)

Trigger - `message:appMaker` (carousel)

Trigger - `message:appMaker` (list)

Trigger - `message:appUser` (location)

Trigger - `message:appUser` (file)

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

Trigger - `postback`

Trigger - `conversation:read`

Trigger - `conversation:start`

Trigger - `conversation:referral`

Trigger - `merge:appUser`

Trigger - `message:delivery:channel`

Trigger - `message:delivery:user`

Trigger - `message:delivery:failure`

Trigger - `payment:success`

Trigger - `link:success`

Trigger - `link:match`

Trigger - `link:failure`

Trigger - `client:add`

Trigger - `client:remove`

Trigger - `typing:appUser`