Core
Introduction
Welcome to the Smooch API. The API allows you to craft entirely unique messaging experiences for your app and website as well as talk to any backend or external service.
The Smooch API is designed according to REST principles.
The API accepts JSON in request bodies and requires that the content-type: application/json
header be specified for all such requests. The API will always respond with an object. Depending on context, resources may be returned as single objects or as arrays of objects, nested within the response object.
In some cases, the API will also facilitate cross-origin resource sharing so that it can be called from a web application.
Regions
# Use US region (default)
export SMOOCH_ROOT=https://api.smooch.io
# Use EU region
export SMOOCH_ROOT=https://api.eu-1.smooch.io
// Use US region (default)
const smooch = new SmoochCore({
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.
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.
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.
Header
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. Theaccount
scope is reserved for server-to-server scenarios. Theaccount
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. Theapp
scope is reserved for server-to-server scenarios. Theapp
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 |
appUser:delete | when an app user is deleted through the Delete App User endpoint |
conversation:read | when a user reads a conversation |
conversation:referral | when a user scans a Messenger code, clicks an ad on Facebook or scans a WeChat QR code |
postback | when a user clicks on a postback action |
merge:appUser | when two or more users are merged into one |
payment:success | when a payment is successfully received from a channel |
link:success | when a new channel is successfully linked to a user |
link:failure | when a user link fails |
link:match | when a user is successfully matched to an external system |
client:add | when a new client has been added to an existing user |
client:remove | when a new client has been removed from an existing user |
* | when any of the above basic triggers occurs |
Additional Triggers
In addition to the basic triggers above, there are some additional triggers that are not included in the wildcard trigger (*
), and must be subscribed to explicitly.
trigger | |
---|---|
typing:appUser | when a user starts or stops typing |
Manage Webhooks
Smooch exposes REST API methods to:
Create webhook
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks \
-X POST \
-d '{"target": "http://example.com/callback", "triggers": ["message:appUser"]}' \
-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",
"version": "v1.1"
}
}
POST /v1.1/apps/{appId}/webhooks
Create a webhook for the specified app. The response body will include a secret which will be transmitted with each webhook invocation and can be used to verify the authenticity of the caller.
Alternatively, you can use the Webhooks integration in the Smooch dashboard to easily create a webhook.
Arguments | |
---|---|
target required |
URL to be called when the webhook is triggered. |
triggers required |
An array of triggers you wish to have the webhook listen to. This property is case sensitive. More details. |
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
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a text message.
Message event payload schema
Field | Description |
---|---|
trigger | "message:appUser" , or "message:appMaker" |
app | A nested object representing the Smooch app associated with the event. See the truncated app schema below for details. |
messages | An array of objects representing the messages associated with the event. See the message schema below for details. |
appUser | A nested object representing the appUser associated with the event. See the truncated appUser schema below for details. |
conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
version | The API version used to create the webhook. See API version for details. |
Trigger - message:appUser
(image)
Payload:
{
"trigger": "message:appUser",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"messages": [
{
"_id": "55c8c1498590aa1900b9b9b1",
"type": "image",
"mediaUrl": "http://www.tacobueno.com/media/1338/partytacolarge.png?quality=65",
"role": "appUser",
"authorId": "c7f6e6d6c3a637261bd9656f",
"name": "Steve",
"received": 1444348338.704,
"source": {
"type": "messenger"
}
}
],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
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
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a carousel message.
Trigger - message:appMaker
(list)
Payload:
{
"trigger": "message:appMaker",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"messages": [
{
"items": [
{
"title": "Tacos",
"description": "Beef and cheese... Mhm...",
"size": "large",
"mediaUrl": "http://www.tacobueno.com/media/1338/partytacolarge.png?quality=65",
"mediaType": "image/png",
"_id": "5887c9117e4de029005f1fc7",
"actions": [
{
"text": "Oh yeah!",
"payload": "TACOS",
"_id": "5887c9117e4de029005f1fc8",
"type": "postback"
}
]
}
],
"actions": [
{
"text": "More Choices!",
"payload": "MORE",
"_id": "5887c9a37e4de029005f1fce",
"type": "postback"
}
],
"type": "list",
"role": "appMaker",
"received": 1485293841.303,
"authorId": "2cKU9zRO2DpBWgk764Tfro",
"avatarUrl": "https://www.gravatar.com/avatar/5e543256c480ac577d30f76f9120eb74.png?s=200&d=mm",
"_id": "5887c9117e4de029005f1fc6",
"source": {
"type": "api"
}
}
],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a list message.
Trigger - message:appUser
(location)
Payload:
{
"trigger": "message:appUser",
"app": {
"_id": "55fafea8bf8fd41a00357805"
},
"messages": [
{
"text": "Location shared:\nhttps://maps.google.com/maps?q=45.5261583,-73.595346",
"authorId": "76293a38b24c5cca43e79415",
"received": 1485292067.601,
"type": "location",
"coordinates": {
"lat": 45.5261583,
"long": -73.595346
},
"role": "appUser",
"_id": "5887c22356c66904009ad602",
"source": {
"type": "messenger"
}
}
],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a location message.
Trigger - message:appUser
(file)
Payload:
{
"trigger": "message:appUser",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"messages":[{
"_id": "55c8c1498590aa1900b9b9b1",
"type": "file",
"mediaUrl": "https://some-pdf-file.pdf",
"mediaType": "application/pdf",
"mediaSize": 123456,
"role": "appUser",
"authorId": "c7f6e6d6c3a637261bd9656f",
"name": "Steve",
"received": 1444348338.704,
"source": {
"type": "android",
"id": "604018c259285f82a746c44ef0368a7f44d4af6a"
}
}],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a file message.
Trigger - message:appUser
(file as text - deprecated)
File as text payload:
{
"trigger": "message:appUser",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"messages":[{
"_id": "55c8c1498590aa1900b9b9b1",
"type": "text",
"text": "File upload: https://some-pdf-file.pdf",
"role": "appUser",
"authorId": "c7f6e6d6c3a637261bd9656f",
"name": "Steve",
"received": 1444348338.704,
"source": {
"type": "messenger"
}
}],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
A message webhook of type file
will only be sent when the appUser sends a message from the Web, iOS or Android SDKs.
For all other channels, a text
message webhook will be sent with the file url embedded in the text.
AppUser Events
Trigger - appUser:delete
Payload:
{
"trigger": "appUser:delete",
"app": {
"_id": "575040549a38df8fb4eb1e51"
},
"appUser": {
"_id": "de13bee15b51033b34162411",
"userId": "123",
"conversationStarted": true
},
"version": "v1.1"
}
An appUser:delete
webhook triggers when an app user is deleted through the Delete App User endpoint.
appUser:delete event payload schema
Field | Description |
---|---|
trigger | "appUser:delete" |
app | A nested object representing the Smooch app associated with the event. See the truncated app schema below for details. |
appUser | A nested object representing the truncated appUser associated with the event. See the truncated appUser schema below for details. |
version | The API version used to create the webhook. See API version for details. |
Postback Events
Trigger - postback
Payload:
{
"trigger": "postback",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"postbacks":[{
"message": {
"_id": "55c8c1498590aa1900b9b9b1",
"text": "Do you want to see more options?",
"type": "text",
"role": "appMaker",
"authorId": "c7f6e6d6c3a637261bd9656f",
"name": "LunchBot",
"received": 1444348338.704,
"source": {
"type": "slack"
},
"actions": [{
"_id": "571530ee4fae94c32b78b170",
"type": "postback",
"text": "Yes",
"payload": "YES"
}]
},
"action": {
"_id": "571530ee4fae94c32b78b170",
"type": "postback",
"text": "Yes",
"payload": "YES"
}
}],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for when a user taps a postback button.
Postbacks originating from a persistent menu do not have messages associated with them, and so omit the message
property.
Postback event payload schema
Field | Description |
---|---|
trigger | "postback" |
app | A nested object representing the Smooch app associated with the event. See the truncated app schema below for details. |
postbacks | An array of objects representing the postbacks associated with the event. See the postback schema below for details. |
appUser | A nested object representing the appUser associated with the event. See the truncated appUser schema below for details. |
conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
Postback schema
Field | Description |
---|---|
message optional | A nested object representing the message associated with the postback action. See the message schema below for details (Not present in postback payloads triggered by persistent menu items). |
action | A nested object representing the postback action. See the action schema below for details. |
metadata optional | Flat object containing any custom properties associated with the action. See the metadata schema for more information. |
Conversation Events
Trigger - conversation:read
Payload:
{
"trigger": "conversation:read",
"app": {
"_id": "57ec2881c47d2d24b0c16427"
},
"source": {
"type": "messenger"
},
"appUser": {
"_id": "7685787bf0e9e8cf56182288",
"conversationStarted": true
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"timestamp": 1480349392.103
}
The payload for when a user reads a conversation.
Conversation event payload schema
Field | Description |
---|---|
trigger | "conversation:read" , or "conversation:start" |
app | A nested object representing the Smooch app associated with the event. See the truncated app schema below for details. |
source | A nested object representing the source of the event. See the source schema below for details. |
appUser | A nested object representing the appUser associated with the event. See the truncated appUser schema below for details. |
conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
timestamp | A unix timestamp given in seconds, describing when Smooch received the event. |
referral | Referral information. Only present for WeChat and Messenger. See referral schema for details. |
version | The API version used to create the webhook. See API version for details. |
Trigger - conversation:start
Payload:
{
"trigger": "conversation:start",
"app": {
"_id": "57ec2881c47d2d24b0c16427"
},
"source": {
"type": "messenger"
},
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"timestamp": 1480349392.103
}
The payload for when a user opts in to start receiving messages. conversation:start
is only available on a sub set of channels. Channel capabilities lists which channel currently supports it. Also, note that conversation:start
won’t be triggered when a user is linking a second channel via the Web Messenger.
The conversation:start
event can contain a referral property in the following circumstances:
- 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
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"referral": {
"code": "my-ref-code",
"details": {
"source": "MESSENGER_CODE",
"type": "OPEN_THREAD"
}
},
"timestamp": 1495650348.685,
"version": "v1.1"
}
Conversation referral payload schema
Field | Description |
---|---|
trigger | "conversation:referral" |
app | A nested object representing the Smooch app associated with the event. See the truncated app schema below for details. |
source | A nested object representing the source of the event. See the source schema below for details. |
appUser | A nested object representing the appUser associated with the event. See the truncated appUser schema below for details. |
conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
referral | Referral information. See referral schema for details. |
version | The API version used to create the webhook. See API version for details. |
The payload for when a user is referred to a conversation. This payload will be sent when a user performs the following actions:
- 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
}],
"version": "v1.1"
}
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.
Delivery event payload schema
Field | Description |
---|---|
trigger | "message:delivery:channel" or "message:delivery:user" or "message:delivery:failure" |
app | A nested object representing the Smooch app associated with the event. See the truncated app schema below for details. |
appUser | A nested object representing the truncated appUser associated with the event. See the truncated appUser schema below for details. |
conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
destination | A nested object representing the destination of the message. See the destination schema below for details. |
message | An object representing the message associated with the event. See the truncated message schema below for details. |
externalMessages optional | An array of objects representing the third-party messages associated with the event. See the external message schema below for details. The order of the external messages is not guaranteed to be the same across the different triggers. Note that some channels don’t expose message IDs, in which case this field will be unset. |
timestamp | A unix timestamp given in seconds, describing when the delivery event occurred. |
isFinalEvent | A boolean indicating whether the webhook is the final one for the message._id and destination.type pair. |
error optional |
A nested object, present in message:delivery:failure event, representing the error associated with the delivery failure. See the error schema below for details. |
External message schema
Field | Description |
---|---|
id | A string representing the ID of the external message. |
Error schema
Field | Description |
---|---|
code | A string representing the error code associated with the error. See below for a list of possible values. |
underlyingError optional | A object with the error data returned by the channel a message was meant to be delivered to. |
message optional | The description associated with the error. |
If an error cannot be categorized, the code
will be uncategorized_error
. Otherwise, the error will have a more specific code.
code | Description |
---|---|
aborted | The delivery wasn’t attempted. |
blocked | The app user has unsubscribed from the channel. |
bad_request | The channel rejected the Smooch request because of a bad request. |
not_found | The channel indicated that the target user cannot be found. |
rate_limited | The channel has rate-limited the delivery of the message. |
service_internal_error | The channel has returned a service internal error. |
service_unavailable | The channel is unavailable. This might indicate that the channel is down. |
unauthorized | The delivery failed because the integration is not authorized. This might indicate that there is a configuration issue with your integration. |
uncategorized_error | The channel has marked the message as failed, but Smooch couldn’t map it to a specific error. |
Trigger - message:delivery:channel
Payload:
{
"trigger": "message:delivery:channel",
"app": {
"_id": "5a5ccf0d1b4077001a36b11d"
},
"appUser": {
"_id": "b234f6a69d2eea3589f4c24e"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"destination": {
"type": "twilio"
},
"isFinalEvent": false,
"externalMessages": [
{
"id": "SMb0ee6ee1313a4141ba346e368325a04d"
}
],
"message": {
"_id": "5baa5b4ab5bebb000ce85589"
},
"timestamp": 1537891147.555,
"version": "v1.1"
}
The message:delivery:channel
webhook reports the success to handoff a message to a channel.
If isFinalEvent
property of the payload is true
, no additional delivery event (message:delivery:*
) will be sent for the message._id
and destination.type
pair.
If isFinalEvent
is false
, another message:delivery:*
webhook with the same message._id
and destination.type
pair is expected, but not guaranteed.
Trigger - message:delivery:user
Payload:
{
"trigger": "message:delivery:user",
"app": {
"_id": "5a5ccf0d1b4077001a36b11d"
},
"appUser": {
"_id": "b234f6a69d2eea3589f4c24e"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"destination": {
"type": "twilio"
},
"isFinalEvent": true,
"externalMessages": [
{
"id": "SMb0ee6ee1313a4141ba346e368325a04d"
}
],
"message": {
"_id": "5baa5b4ab5bebb000ce85589"
},
"timestamp": 1537891147.555,
"version": "v1.1"
}
The message:delivery:user
webhook confirms the delivery of a message to the user.
Trigger - message:delivery:failure
Payload:
{
"trigger": "message:delivery:failure",
"app": {
"_id": "575040549a38df8fb4eb1e51"
},
"appUser": {
"_id": "de13bee15b51033b34162411",
"userId": "123"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"destination": {
"type": "line"
},
"isFinalEvent": true,
"error": {
"code": "unauthorized",
"underlyingError": {
"message":
"Authentication failed due to the following reason: invalid token. Confirm that the access token in the authorization header is valid."
}
},
"message": {
"_id": "5baa610db5bebb000ce855d6"
},
"timestamp": 1480001711.941,
"version": "v1.1"
}
The message:delivery:failure
webhook reports the failure to deliver a message to a user on the destination channel. If this webhook triggers, it means that the message did not reach the user.
Payment Events
Trigger - payment:success
Payload:
{
"trigger": "payment:success",
"app": {
"_id": "571e3496cb98b3962ce740d7"
},
"appUser": {
"_id": "2b15a54fde9dc2f33f88bc25"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"payments": [
{
"source": {
"type": "messenger"
},
"message": {
"text": "Just put some vinegar on it",
"actions": [
{
"text": "Buy vinegar",
"amount": 1000,
"currency": "usd",
"state": "paid",
"_id": "5877fd5624fe8fd934d7c2f3",
"uri": "https://app.smooch.io/checkout/5877fd5624fe8fd934d7c2f3",
"type": "buy"
}
],
"type": "text",
"role": "appMaker",
"received": 1484258646.823,
"authorId": "5X8AJwvpy0taCkPDniC5la",
"avatarUrl": "https://www.gravatar.com/image.jpg",
"_id": "5877fd5624fe8fd934d7c2f2",
"source": {
"type": "api"
}
},
"action": {
"text": "Buy vinegar",
"amount": 1000,
"currency": "usd",
"state": "paid",
"_id": "5877fd5624fe8fd934d7c2f3",
"uri": "https://app.smooch.io/checkout/5877fd5624fe8fd934d7c2f3",
"type": "buy"
},
"charge": {
"id": "ch_19dPrCHQ7f2U7NYSZ45OspXT"
}
}
],
"timestamp": 1484258666.455,
"version": "v1.1"
}
The payload for when a payment is received.
Payment event payload schema
Field | Description |
---|---|
trigger | "payment:success" |
app | A nested object representing the Smooch app associated with the event. See the truncated app schema below for details. |
appUser | A nested object representing the appUser associated with the event. See the truncated appUser schema below for details. |
conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
payments | An array of objects representing the payments associated with the event. See the payment schema below for details. |
timestamp | A unix timestamp given in seconds, describing when Smooch received confirmation of the payment. |
version | The API version used to create the webhook. See API version for details. |
Payment schema
Field | Description |
---|---|
source | A nested object describing the source of the event. See the source schema for details. |
message | A nested object representing the appMaker message associated with the postback action. See the message schema below for details (Not present in postback payloads triggered by persistent menu items). |
action | A nested of object representing the buy action associated with the event. See the action schema below for details. |
charge | A nested of object representing the Stripe charge associated with the event. See the charge schema below for details. |
version | The API version used to create the webhook. See API version for details. |
Charge schema
Field | Description |
---|---|
id | The stripe ID of the charge event. See the Stripe docs for more information. |
Link Events
Trigger - link:success
Payload:
{
"trigger": "link:success",
"app": {
"_id": "58b487c74ebf3ce5d4b38e5f"
},
"appUser": {
"_id": "8215a086b271592e01b74e28"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"channel": "messenger",
"integrationId": "5a99b74858247c608f64a348",
"criteria": {
"phoneNumber": "+15141234567",
"givenName": "bleep",
"surname": "bloop"
},
"version": "v1.1"
}
The payload for a link app user success.
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. |
conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
channel | The channel for which the link succeeded. |
integrationId | The ID of the integration for which the link succeeded. |
criteria | The criteria specified to establish the link. |
version | The API version used to create the webhook. See API version for details. |
Trigger - link:match
Payload:
{
"trigger": "link:match",
"app": {
"_id": "58b487c74ebf3ce5d4b38e5f"
},
"appUser": {
"_id": "8215a086b271592e01b74e28"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"channel": "messenger",
"integrationId": "5a99b74858247c608f64a348",
"criteria": {
"phoneNumber": "+15141234567",
"givenName": "bleep",
"surname": "bloop"
},
"version": "v1.1"
}
The payload for a link app user match.
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. |
conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
channel | The channel for which the link matched. |
integrationId | The ID of the integration for which the link matched. |
criteria | The criteria specified to establish the link. |
Trigger - link:failure
Payload:
{
"trigger": "link:failure",
"app": {
"_id": "58b487c74ebf3ce5d4b38e5f"
},
"appUser": {
"_id": "8215a086b271592e01b74e28"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"error": {
"code": "bad_request",
"message": "(#100) No matching user found"
},
"channel": "messenger",
"integrationId": "5a99b74858247c608f64a348",
"criteria": {
"phoneNumber": "+15141234567",
"givenName": "bleep",
"surname": "bloop"
},
"version": "v1.1"
}
The payload for a link app user failure.
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. |
conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
channel | The channel for which the link failed. |
integrationId | The ID of the integration for which the link failed. |
criteria | The criteria specified to establish the link. |
error | A nested object representing the error associated with the link failure. See the error schema below for details. |
Client Events
Trigger - client:add
Payload:
{
"trigger": "client:add",
"app": {
"_id": "575040549a38df8fb4eb1e51"
},
"version": "v1.1",
"appUser": {
"_id": "de13bee15b51033b34162411",
"userId": "123",
"conversationStarted": true
},
"clients": [
{
"integrationId": "5a99b74858247c608f64a348",
"id": "bea02e14-86f4-4711-8ecc-ab717ebf750a",
"displayName": "Sue Purb",
"info": {
"gender": "female",
"timezone": -5,
"locale": "en_US",
"avatarUrl": "https://scontent.xx.fbcdn.net/example.png"
},
"lastSeen": "2019-01-14T19:11:17.783Z",
"linkedAt": "2019-01-14T19:11:17.783Z",
"primary": true,
"platform": "messenger",
"active": true,
"blocked": false
}
]
}
A client:add
webhook triggers when a client is added to an existing appUser. This can occur as a result of a login, channel link, or when an SDK consumes an auth code.
In channel linking cases the client:add
event only fires when the link has been completed. For example, if a user declines when prompted to link Facebook Messenger, client:add
will not trigger. Link failures such as this can be detected with the link:failure trigger.
Exceptions:
Smooch automatically creates new appUsers upon receipt of their first message. In these cases, a client:add
event does not fire. New users created in this way should be recognized via the message:appUser trigger, which includes the client object in the payload.
An existing client might also be moved from one appUser to another as a result of a merge. In this case, a merge:appUser event is signalled in lieu of a client:add
event.
client:add event payload schema
Field | Description |
---|---|
trigger | "client:add" |
app | A nested object representing the Smooch app associated with the event. See the truncated app schema below for details. |
appUser | A nested object representing the truncated appUser associated with the event. See the truncated appUser schema below for details. |
clients | An array of client objects that have just been added to the appUser. See the client schema below for details. |
version | The API version used to create the webhook. See API version for details. |
Trigger - client:remove
Payload:
{
"trigger": "client:remove",
"app": {
"_id": "575040549a38df8fb4eb1e51"
},
"appUser": {
"_id": "de13bee15b51033b34162411",
"userId": "123",
"conversationStarted": true
},
"clients": [{
"id": "90e2f396500b451dabdce69f207247d4"
}],
"version": "v1.1"
}
A client:remove
webhook triggers when a client is removed from an existing appUser. This can happen when a channel is unlinked via the channel API.
A channel link action might also cause an existing third party client to change ownership from one appUser to another. In this case both a client:remove
and client:add
trigger will be fired.
client:remove event payload schema
Field | Description |
---|---|
trigger | "client:remove" |
app | A nested object representing the Smooch app associated with the event. See the truncated app schema below for details. |
appUser | A nested object representing the truncated appUser associated with the event. See the truncated appUser schema below for details. |
clients | An array of client objects that have just been removed from the appUser. These objects contain the removed client id only. |
Typing Events
Trigger - typing:appUser
Payload:
{
"trigger": "typing:appUser",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"timestamp": 1510848814.349,
"appUser": {
"_id": "56bfa6add1683d0e0c7e5956"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"activity": {
"type": "typing:stop"
},
"source": {
"type": "ios"
},
"version": "v1.1"
}
A typing:appUser
webhook triggers when an appUser starts or stops typing a response on a supported channel.
typing:appUser event payload schema
Field | Description |
---|---|
trigger | "typing:appUser" |
app | A nested object representing the Smooch app associated with the event. See the truncated app schema below for details. |
appUser | A nested object representing the truncated appUser associated with the event. See the truncated appUser schema below for details. |
conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
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.
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": "7494535bff5cef41a15be74d",
"userId": "steveb@channel5.com",
"givenName": "Steve",
"signedUpAt": "2019-01-14T18:55:12.515Z",
"hasPaymentInfo": false,
"conversationStarted": false,
"clients": [
{
"lastSeen": "2019-01-14T16:55:59.364Z",
"platform": "ios",
"id": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
"pushNotificationToken": "<0cfc626c 9fed1e3d e9fcb139 e6590cb3 3462f3c8 afd47000 6af2003f 2e3a72a9>",
"appVersion": "1.0",
"info": {
"appId": "com.rp.ShellApp",
"carrier": "Rogers",
"buildNumber": "1.0",
"devicePlatform": "iPhone8,4",
"installer": "Dev",
"sdkVersion": "6.11.2",
"osVersion": "12.1.2",
"appName": "ShellApp",
"os": "iOS",
"vendor": "smooch"
},
"raw": {
"appId": "com.rp.ShellApp",
"carrier": "Rogers",
"buildNumber": "1.0",
"devicePlatform": "iPhone8,4",
"installer": "Dev",
"sdkVersion": "6.11.2",
"osVersion": "12.1.2",
"appName": "ShellApp",
"os": "iOS",
"vendor": "smooch"
},
"active": true,
"primary": false,
"integrationId": "599ad41e49db6e243ad77d2f"
}
],
"pendingClients": [],
"properties": {
"favoriteFood": "prizza"
}
}
}
GET /v1.1/apps/{appId}/appusers/{smoochId|userId}
Retrieve a specific app user. Like all other /v1.1/apps/{appId}/appusers/
paths, an app user can be identified using either the smoochId
or the userId
.
Update App User
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
-X PUT \
-d '{"givenName": "Steve"}' \
-H 'content-type: application/json' \
-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": "7494535bff5cef41a15be74d",
"userId": "steveb@channel5.com",
"givenName": "Steve",
"signedUpAt": "2019-01-14T18:55:12.515Z",
"hasPaymentInfo": false,
"conversationStarted": false,
"clients": [
{
"lastSeen": "2019-01-14T16:55:59.364Z",
"platform": "ios",
"id": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
"pushNotificationToken": "<0cfc626c 9fed1e3d e9fcb139 e6590cb3 3462f3c8 afd47000 6af2003f 2e3a72a9>",
"appVersion": "1.0",
"info": {
"appId": "com.rp.ShellApp",
"carrier": "Rogers",
"buildNumber": "1.0",
"devicePlatform": "iPhone8,4",
"installer": "Dev",
"sdkVersion": "6.11.2",
"osVersion": "12.1.2",
"appName": "ShellApp",
"os": "iOS",
"vendor": "smooch"
},
"raw": {
"appId": "com.rp.ShellApp",
"carrier": "Rogers",
"buildNumber": "1.0",
"devicePlatform": "iPhone8,4",
"installer": "Dev",
"sdkVersion": "6.11.2",
"osVersion": "12.1.2",
"appName": "ShellApp",
"os": "iOS",
"vendor": "smooch"
},
"active": true,
"primary": false,
"integrationId": "599ad41e49db6e243ad77d2f"
}
],
"pendingClients": [],
"properties": {
"favoriteFood": "prizza"
}
}
}
PUT /v1.1/apps/{appId}/appusers/{smoochId|userId}
Update an app user’s basic profile information and specify custom profile data via properties
. This API is additive; only the specific fields specified in the request body, and only the specific JSON sub-fields included in the properties
field will be updated. In other words, omitting a field will not delete that field.
Arguments | |
---|---|
givenName optional |
The user’s given name (first name). |
surname optional |
The user’s surname (last name). |
email optional |
The user’s email address. |
signedUpAt optional |
The date at which the user signed up. Must be ISO 8601 time format (YYYY-MM-DDThh:mm:ss.sssZ ). |
properties optional |
A flat object containing custom defined user properties. |
Delete App User Profile
Request by smoochId:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/profile \
-X DELETE \
-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": "7494535bff5cef41a15be74d",
"userId": "steveb@channel5.com",
"signedUpAt": "2019-01-14T18:55:12.515Z",
"hasPaymentInfo": false,
"conversationStarted": false,
"clients": [
{
"lastSeen": "2019-01-14T16:55:59.364Z",
"platform": "ios",
"id": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
"pushNotificationToken": "<0cfc626c 9fed1e3d e9fcb139 e6590cb3 3462f3c8 afd47000 6af2003f 2e3a72a9>",
"active": true,
"primary": false,
"integrationId": "599ad41e49db6e243ad77d2f"
}
],
"pendingClients": [],
"properties": {}
}
}
DELETE /v1.1/apps/{appId}/appusers/{smoochId|userId}/profile
Delete an app user’s profile. Calling this API will clear givenName
, surname
, email
and every custom property for the specified app user.
For every client owned by the app user, it will also clear displayName
, avatarUrl
and any channel specific information stored in the info
and raw
fields.
Calling this API doesn’t delete the app user’s conversation history. To fully delete the app user, see Delete App User.
Delete App User
Request by smoochId:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
-X DELETE \
-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": "f316d285a6642a32adbdcd84",
"userId": "steveb@channel5.com",
"givenName": "Steve",
"signedUpAt": "2019-01-14T18:55:12.515Z",
"hasPaymentInfo": false,
"conversationStarted": false,
"clients": [],
"pendingClients": [],
"properties": {
"favoriteFood": "prizza"
}
}
}
POST /v1.1/apps/{appId}/appusers
Arguments | |
---|---|
userId required |
A unique identifier for the app user. The userId can be used to link a user to the same conversation across multiple clients. |
givenName optional |
The user’s given name (first name). |
surname optional |
The user’s surname (last name). |
email optional |
The user’s email address. |
signedUpAt optional |
The date at which the user signed up. Must be ISO 8601 time format (YYYY-MM-DDThh:mm:ss.sssZ ). |
properties optional |
A flat object containing custom defined user properties. |
In the vast majority of cases app users will be automatically created by the Smooch SDKs or Messaging Channel integrations. In some cases however it might be necessary to pre-create an app user object before that user runs your app for the first time. This API facilitates this scenario. A userId
must be specified so that a future login
call made from a device can use the same userId
to link the device to the pre-created app user.
Suppose for example you begin a conversation with an end user bob@example.com
over email and you wish to transfer this conversation history over into Smooch once that user logs in to your app. To facilitate this, you can call POST /v1.1/apps/{appId}/appusers
to pre-create a Smooch identity with userId
bob@example.com
, to which you can import that existing conversation history. After Bob signs in to your app and your app calls login
with the same userId
, they will see their conversation history.
Get App User Channel Entities
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",
"integrationId": "5a3174ee84c71521fa415ca9"
},
{
"type": "messenger",
"userId": "198273192387",
"integrationId": "5a33dfd13dd25731cb1bf3cf"
}
]
}
GET /v1.1/apps/{appId}/appusers/{smoochId|userId}/channels
Retrieves all of the app user’s channel entity Ids.
Entity ID Responses
Channel Type | Entity ID |
---|---|
messenger viber line |
userId A string representing a messenger, viber, line, wechat or twitter user ID. |
twilio messagebird |
phoneNumber A string representing a twilio or messageBird phone number. |
mailgun | address A string representing an email address for mailgun. |
telegram | chatId A string representing the chat ID for telegram. |
username A string representing the username of the user for whatsapp. |
Get App User Business System IDs
Request:
curl https https://api.smooch.io/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/businesssystems \
-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": "helpscout",
"conversationId": "123456"
}
]
}
GET /v1.1/apps/{appId}/appusers/{smoochId|userId}/businesssystems
Retrieves all the business systems an appUser’s conversation is connected to.
Business system response properties
Channel Type | ID Name |
---|---|
slack | channelId A string representing the Slack channel ID. |
zendesk | ticketId A string representing a Zendesk ticket ID. |
helpscout | conversationId A string representing the Helpscout conversation ID. |
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": "7494535bff5cef41a15be74d",
"userId": "steveb@channel5.com",
"givenName": "Steve",
"signedUpAt": "2019-01-14T18:55:12.515Z",
"hasPaymentInfo": false,
"conversationStarted": false,
"clients": [],
"pendingClients": [
{
"integrationId": "5a3174ee84c71521fa415ca9",
"id": "4afa71ce-20ea-4971-841f-357630a1f970",
"platform": "twilio"
}
],
"properties": {
"favoriteFood": "prizza"
}
}
}
POST /v1.1/apps/{appId}/appusers/{smoochId|userId}/channels
Arguments | |
---|---|
type required |
The channel to link. Can be twilio , messagebird , mailgun or whatsapp . The channel messenger is also valid, but since it’s in early access, you need to contact Smooch to enable it. |
integrationId optional |
The integration to link. Must match the provided type . |
{entity} required |
The required entity for linking. This is different for each channel. |
confirmation required |
The confirmation option for linking. |
primary optional |
Default is true . Flag indicating whether the client will become the primary once linking is complete. |
Some extra arguments are supported depending on the selected type.
Linking allows users to continue conversations on their preferred channels. An appUser’s linked channels will be found in the clients
field.
When a link request is first made, the channel will be added to the pendingClients
field. At this point, the API call will be considered a success and a response will be returned.
Future updates on the status of the link request can be tracked by listening to the link:match, link:success and link:failure webhooks.
Linking confirmation
The confirmation option allows you to specify the strategy used to initiate a link with the target user.
Arguments | |
---|---|
type required |
The type of confirmation. Types include immediate, userActivity or prompt. |
message |
The message used to reach out to the user. Must be a valid message object as per the post message API. |
Immediate
Available on: Twilio
, MessageBird
, Messenger
, Mailgun
, WhatsApp
If you specify an immediate
confirmation, Smooch will not wait for the user to confirm the link before converting the pending client to a full client. On a successful link, the link:success webhook will be triggered.
If the message
property is provided, Smooch will attempt to deliver it to the channel prior to completing the link. Successfully sending this message will trigger a link:match webhook. Failure to deliver this message will result in a link:failure webhook, and the pending client will be removed from the user.
User activity
Available on: Twilio
, MessageBird
, Messenger
, WhatsApp
If you specify a userActivity
confirmation, Smooch will wait for the user to confirm the link before converting the pending client to a full client. If the user performs an activity acknowledging the message was received (for example accepting the message request on Facebook Messenger), the link:success webhook will be triggered.
The message
property is mandatory for this confirmation type. Smooch will attempt to deliver it to the channel prior to listening for the user’s activity. This is a good opportunity to welcome the user to the new channel and invite them to begin messaging you there. Successfully sending this message will trigger a link:match webhook. Failure to deliver this message will result in a link:failure webhook, and the pending client will be removed from the user.
Prompt
Available on: Twilio
, MessageBird
If you specify a prompt confirmation, the user will be prompted to either accept or deny your link request. The message sent to prompt the user can’t be customized.
Successfully sending the prompt will trigger a link:match webhook. Failure to deliver this message or a denial of the prompt will result in a link:failure webhook, and the pending client will be removed from the user.
Linkable channels and entities
Given that there is no way for you to provide Smooch with the necessary ID to connect LINE, WeChat or Telegram, we have limited the API to accept ‘Twilio’, ‘MessageBird’, ‘Mailgun’ and ‘Messenger’ for now.
Channel type | Required entity | Extra properties |
---|---|---|
twilio , messagebird , whatsapp |
phoneNumber A String of the appUser’s phone number. It must contain the + prefix and the country code.Examples of valid phone numbers: +1 212-555-2368 , +12125552368 , +1 212 555 2368 .Examples of invalid phone numbers: 212 555 2368 , 1 212 555 2368 . |
|
messenger |
phoneNumber A String of the appUser’s phone number. It must contain the + prefix and the country code.Examples of valid phone numbers: +1 212-555-2368 , +12125552368 , +1 212 555 2368 .Examples of invalid phone numbers: 212 555 2368 , 1 212 555 2368 . |
givenName and surname may be specified as additional criteria to increase the likelihood of a match. |
mailgun |
address A String of the appUser’s email address |
subject may be specified to set the subject for the outgoing email. Default subject : “New message from {appName}” |
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.
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. |
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 |
---|---|
platform | The type of integration that the client represents. |
integrationId | The ID of the integration that the client was created for. |
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. |
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. |
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 channel and makes it available via the raw
field of the client.
All keys are optional and not guaranteed to be available.
Facebook Messenger
For Messenger, we retrieve the user’s profile via the user profile API.
The response is made available through the raw
field.
Field | Description |
---|---|
first_name | First name |
last_name | Last name |
profile_pic | Profile picture |
locale | Locale of the user on Facebook |
timezone | Timezone, number relative to GMT |
gender | Gender |
is_payment_enabled | Is the user eligible to receive messenger platform payment messages |
last_ad_referral | Details of the last Messenger Conversation Ad user was referred from |
LINE
For LINE, we retrieve the user’s profile via the get profile API.
The response is made available through the raw
field.
Field | Description |
---|---|
displayName | Display name |
userId | User ID |
pictureUrl | Image URL |
statusMessage | Status message |
Mailgun
For Mailgun, we extract the user’s profile information from incoming “store” webhooks, picking out fields that are relevant to the user’s profile.
Field | Description |
---|---|
from | The email of the sender. |
Reply-To | The Reply-To address of the sender. |
stripped-signature | The sender’s signature, stripped. |
MessageBird SMS
For MessageBird, we retrieve the user’s profile via the lookup API.
The response is made available through the raw
field.
Field | Description |
---|---|
href | The URL of this lookup. |
countryCode | The country code for this number in ISO 3166-1 alpha-2 format. |
countryPrefix | The country calling code for this number. |
phoneNumber | The phone number in E.164 format without the prefixed plus-sign. |
type | The type of number. This can be fixed line, mobile, fixed line or mobile, toll free, premium rate, shared cost, voip, personal number, pager, universal access number, voice mail or unknown. |
formats | A hash containing references to this phone number in several different formats. |
hlr | The most recent HLR object. If no such HLR objects exists, this hash won’t be returned. |
Native Android SDK
For the Android SDK, we gather relevant information about the user through the app and expose it in the raw
field.
Field | Description |
---|---|
installer | The app’s installer package name. |
sdkVersion | The Smooch SDK version. |
appId | The Android app’s ID. |
wifi | Value specifying whether the user has wifi enabled. |
radioAccessTechnology | The network type being used to access the internet. |
carrier | The devices’s carrier. |
appName | The Android app’s name. |
devicePlatform | Manufacturer and model of the device. |
osVersion | The device’s OS version. |
os | The device’s OS. |
Native iOS SDK
For the iOS SDK, we gather relevant information about the user through the app and expose it in the raw
field.
Field | Description |
---|---|
radioAccessTechnology | The network type being used to access the internet. |
appId | The iOS app’s ID. |
carrier | The devices’s carrier. |
buildNumber | The app’s build number. |
devicePlatform | The device platform. |
installer | The installer of the app. |
sdkVersion | The Smooch SDK version. |
osVersion | The device’s OS version. |
appName | The iOS app’s name. |
os | The device’s OS. |
wifi | Value specifying whether the user has wifi enabled. |
Telegram
For Telegram, we retrieve the user’s profile via the fetch user API and the fetch user profile photos API.
The response is made available through the raw
field.
Field | Description |
---|---|
id | Unique identifier for this user or bot. |
first_name | User‘s or bot’s first name. |
last_name | Optional. User‘s or bot’s last name. |
username | Optional. User‘s or bot’s username. |
language_code | Optional. IETF language tag of the user’s language. |
profile_photos | This object represent a user’s profile pictures . |
Twilio SMS
For Twilio, we extract the user’s profile information from incoming SMS webhooks, picking out fields that are relevant to the user’s profile.
Field | Description |
---|---|
From | The phone number of the sender. |
FromCity | The city of the sender. |
FromState | The state or province of the sender. |
FromZip | The postal code of the called sender. |
FromCountry | The country of the called sender. |
Twitter DM
For Twitter, we retrieve the user’s profile via the GET users/show API.
The response is made available through the raw
field.
Field | Description |
---|---|
contributors_enabled | Indicates that the user has an account with “contributor mode” enabled, allowing for Tweets issued by the user to be co-authored by another account. Rarely true (this is a legacy field). |
created_at | The UTC datetime that the user account was created on Twitter. |
default_profile | When true, indicates that the user has not altered the theme or background of their user profile. |
default_profile_image | When true, indicates that the user has not uploaded their own profile image and a default image is used instead. |
description | Nullable. The user-defined UTF-8 string describing their account. |
entities | Entities which have been parsed out of the url or description fields defined by the user. Read more about User Entities. |
favourites_count | The number of Tweets this user has liked in the account’s lifetime. British spelling used in the field name for historical reasons. |
follow_request_sent | Nullable. Perspectival. When true, indicates that the authenticating user has issued a follow request to this protected user account. |
following | Nullable. Perspectival. Deprecated. When true, indicates that the authenticating user is following this user. Some false negatives are possible when set to “false,” but these false negatives are increasingly being represented as “null” instead. |
followers_count | The number of followers this account currently has. Under certain conditions of duress, this field will temporarily indicate “0”. |
friends_count | The number of users this account is following (AKA their “followings”). Under certain conditions of duress, this field will temporarily indicate “0”. |
geo_enabled | When true, indicates that the user has enabled the possibility of geotagging their Tweets. This field must be true for the current user to attach geographic data when using POST statuses / update. |
id | The integer representation of the unique identifier for this User. This number is greater than 53 bits and some programming languages may have difficulty/silent defects in interpreting it. Using a signed 64 bit integer for storing this identifier is safe. Use id_str for fetching the identifier to stay on the safe side. See Twitter IDs, JSON and Snowflake. |
id_str | The string representation of the unique identifier for this User. Implementations should use this rather than the large, possibly un-consumable integer in id. |
is_translator | When true, indicates that the user is a participant in Twitter’s translator community. |
lang | The BCP 47 code for the user’s self-declared user interface language. May or may not have anything to do with the content of their Tweets. |
listed_count | The number of public lists that this user is a member of. |
location | Nullable. The user-defined location for this account’s profile. Not necessarily a location, nor machine-parseable. This field will occasionally be fuzzily interpreted by the Search service. |
name | The name of the user, as they’ve defined it. Not necessarily a person’s name. Typically capped at 20 characters, but subject to change. |
notifications | Nullable. Deprecated. May incorrectly report “false” at times. Indicates whether the authenticated user has chosen to receive this user’s Tweets by SMS. |
profile_background_color | The hexadecimal color chosen by the user for their background. |
profile_background_image_url | A HTTP-based URL pointing to the background image the user has uploaded for their profile. |
profile_background_image_url_https | A HTTPS-based URL pointing to the background image the user has uploaded for their profile. |
profile_background_tile | When true, indicates that the user’s profile_background_image_url should be tiled when displayed. |
profile_banner_url | The HTTPS-based URL pointing to the standard web representation of the user’s uploaded profile banner. By adding a final path element of the URL, it is possible to obtain different image sizes optimized for specific displays. For size variants, please see User Profile Images and Banners. |
profile_image_url | A HTTP-based URL pointing to the user’s profile image. See User Profile Images and Banners. |
profile_image_url_https | A HTTPS-based URL pointing to the user’s profile image. |
profile_link_color | The hexadecimal color the user has chosen to display links with in their Twitter UI. |
profile_sidebar_border_color | The hexadecimal color the user has chosen to display sidebar borders with in their Twitter UI. |
profile_sidebar_fill_color | The hexadecimal color the user has chosen to display sidebar backgrounds with in their Twitter UI. |
profile_text_color | The hexadecimal color the user has chosen to display text with in their Twitter UI. |
profile_use_background_image | When true, indicates the user wants their uploaded background image to be used. |
protected | When true, indicates that this user has chosen to protect their Tweets. See About Public and Protected Tweets. |
screen_name | The screen name, handle, or alias that this user identifies themselves with. screen_names are unique but subject to change. Use id_str as a user identifier whenever possible. Typically a maximum of 15 characters long, but some historical accounts may exist with longer names. |
status | Nullable. If possible, the user’s most recent Tweet or retweet. In some circumstances, this data cannot be provided and this field will be omitted, null, or empty. Perspectival attributes within Tweets embedded within users cannot always be relied upon. |
statuses_count | The number of Tweets (including retweets) issued by the user. |
time_zone | Nullable. A string describing the Time Zone this user declares themselves within. |
url | Nullable. A URL provided by the user in association with their profile. |
utc_offset | Nullable. The offset from GMT/UTC in seconds. |
verified | When true, indicates that the user has a verified account. See Verified Accounts. |
is_translation_enabled | When true, indicates that the user has translation enabled. |
has_extended_profile | When true, indicates that the user has an extended profile. |
translator_type | The type of translator the user has enabled. |
profile_location | Nullable. A URL of the user’s profile location. |
Viber
For Viber, we retrieve the user’s profile via the get user details API.
The response’s user
is made available through the raw
field.
Field | Description |
---|---|
id | Unique Viber user id |
name | User’s Viber name |
avatar | URL of the user’s avatar |
country | User’s country code |
language | User’s phone language. Will be returned according to the device language |
primary_device_os | The operating system type and version of the user’s primary device |
api_version | Max API version, matching the most updated user’s device |
viber_version | The Viber version installed on the user’s primary device |
mcc | Mobile country code |
mnc | Mobile network code |
device_type | The user’s device type |
Web Messenger
For the Web Messenger, we gather relevant information about the user through the browser and expose it in the raw
field.
Field | Description |
---|---|
currentTitle | The title of the page the user is currently on. |
currentUrl | The URL of the page the user is currently on. |
browserLanguage | The language the user’s browser is set to. |
referrer | The referrer for the page the user is on. |
userAgent | The browser’s user agent string. |
URL | The domain of the page the user is currently on (ex: docs.smooch.io). |
sdkVersion | The SDK version for the currently instantiated Web Messenger. |
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. |
For WhatsApp, we extract the user’s profile
information and from
ID from inbound message webhooks.
Field | Description |
---|---|
from | WhatsApp ID of the sender. |
profile | Nested object containing the profile information of the WhatsApp user. If the user has declined to share their profile with the Business, this field will be unset. |
Conversation
When the first message is sent to an app user or received from an app user, a conversation is automatically created for them. The conversation and messages for a given app user can be retrieved and created by way of the /v1.1/apps/{appId}/appusers/
API.
Post Message
Request (App User):
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-d '{"text":"Just put some vinegar on it", "role": "appUser", "type": "text"}' \
-H 'content-type: application/json' \
-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.
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 |
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
}
}
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, 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. |
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. |
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
Common Message Properties
Arguments | |
---|---|
role required* |
The role of the message, appMaker or appUser . |
type required* |
The type of the message. |
metadata optional* |
Flat object containing any custom properties associated with the message. See metadata for more information. |
Text
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-H 'content-type: application/json' \
-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. See Common message properties for more information.
Arguments | |
---|---|
text required* |
The text content of the message. Optional only if actions are provided. |
actions optional* |
Array of message actions. |
Image
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-H 'content-type: application/json' \
-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. See Common message properties for more information.
Arguments | |
---|---|
text optional* |
The text content of the message. |
actions optional* |
Array of message actions. |
mediaUrl required* |
The image URL used for the image message. |
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. See Common message properties for more information.
Arguments | |
---|---|
text optional |
Accompanying text or a description of the file. |
mediaUrl required |
The URL of the file attachment. |
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. See Common message properties for more information.
Arguments | |
---|---|
coordinates required |
The coordinates of the location. See Coordinates. |
Coordinates
Arguments | |
---|---|
lat required |
A floating point value representing the latitude of the location. |
long required |
A floating point value representing the longitude of the location. |
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. See Common message properties for more information.
Arguments | |
---|---|
items required* |
Array of message items. The array is limited to 10 items. |
displaySettings optional |
Settings to adjust the carousel layout. See Display Settings. |
Display Settings
A business can modify a carousel message layout by including an optional displaySettings
object. Supported settings are:
Arguments | |
---|---|
imageAspectRatio optional |
Specifies how to display all carousel images. Valid values are horizontal (default) and square . |
Channel Support
Smooch will deliver carousel messages to users across all messaging channels regardless of whether or not a given channel can natively render a carousel message UI. For channels that don’t render carousels, a raw text representation is sent. In the future, the Smooch API will expand to support new messaging app carousel experiences as they become available. For current messaging channels, carousel messages will render in the following ways:
Facebook Messenger
Full support.
Telegram
Full support, with cards arranged vertically.
LINE
Full support.
Viber
Full support.
Web Messenger
Full support.
Android
Full support.
iOS
Full support.
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. See Common message properties for more information.
- 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.
LINE
LINE doesn’t support list messages natively. When a list message is sent to a LINE user, the items
array will be sent as a carousel message. The actions
array will be sent as a separate message.
Telegram
Telegram doesn’t support list messages natively. When a list message is sent to a Telegram user, it will be sent as multiple messages. Each item in the items
array will be converted to one message. Another message will be sent with the contents of the actions
array if it’s non-empty.
WeChat 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 onelink
action. If there is alink
action with adefault
set totrue
, it will be given priority. Otherwise, the firstlink
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.
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. See Common message properties for more information.
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. |
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. |
openOnReceive optional |
Boolean value indicating if the webview should open automatically. Only one action per message can be set to true . Currently only supported on the Web Messenger. |
Buy
A buy action will prompt the user to purchase an item.
Send buy action:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-d '{"text":"Just put some vinegar on it", "role": "appMaker", "type": "text", "actions": [{"type": "buy", "text": "Buy vinegar", "amount": 1000 }]}' \
-H 'content-type: application/json' \
-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. |
Facebook Messenger
Web Messenger
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. |
Share
Actions in a message item may also include a share button.
Send share action:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-H 'content-type: application/json' \
-H "authorization: Bearer your-account-jwt" \
-d '
{
"role": "appMaker",
"type": "carousel",
"items": [{
"title": "Title",
"description": "Description",
"mediaUrl": "http://example.org/image.jpg",
"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
});
Arguments | |
---|---|
type required |
share |
metadata optional |
Flat object containing any custom properties associated with the action. See the metadata schema for more information. |
Extra Channel Options
For features that are not yet supported natively by the Smooch platform, or are specific to a certain channel implementation, the Extra Channel Options
schema allows the caller to specify certain parameters that will be passed directly to the channel API.
Extra channel options exist for the following channels:
Arguments | |
---|---|
messenger optional |
An object conforming to the Messenger Extra Channel Options Schema. |
Messenger Extra Channel Options Schema
Valid arguments for messenger channel options are as follows:
Arguments | |
---|---|
messenger_extensions optional |
For webview type actions, a boolean value indicating whether the URL should be loaded with Messenger Extensions enabled. Default value is false . More Info |
webview_share_button optional |
For webview type actions, a string value indicating if the share button should be hidden. Only possible value is hide . More Info |
Deprecated arguments for messenger channel options are as follows:
Deprecated | ||
---|---|---|
webview_height_ratio deprecated |
Controls the webview height in a link type action. Possible values are compact , tall , and full . More Info |
Use webview action with size instead |
fallback_url deprecated |
If messenger_extensions is true , the URL to use on clients that don’t support Messenger Extensions. More Info |
Use webview action with fallback instead |
Message Items
Message items can be sent through the post message API by including them in the message payload. See Common message properties for more information.
Only carousel and list messages currently support message items.
Arguments | |
---|---|
title required |
The title of the carousel item. |
actions required |
Array of message actions. At least 1 is required, a maximum of 3 are allowed. link , webview , buy , postback and share actions are supported. |
description optional |
The text description, or subtitle. |
mediaUrl optional |
The image URL to be shown in the carousel/list item. |
size optional |
The size of the image to be shown in the carousel/list item (Only top item of Facebook Messenger carousel supported). Choose from compact and large . |
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. |
Truncated conversation schema
A truncated version of the conversation sent with some webhook payloads.
Field | Description |
---|---|
_id | The unique ID for the conversation. |
Source/Destination schema
Data representing the source or destination of a message, whether an appUser or appMaker message.
Field | Description |
---|---|
type | An identifier for the channel from which a message originated. May include one of "web" , "ios" , "android" , "messenger" , "viber" , "telegram" , "wechat" , "line" , "twilio" , "api" , or any number of other channels. |
id optional | An identifier used by Smooch for internal purposes. |
integrationId optional | Identifier indicating which integration the message was sent from. For appUser messages only. |
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.
Persistent Menus
Smooch provides an API to set persistent menus on messaging channels that support custom menus in their chat UIs (Facebook Messenger and WeChat). Menus can be configured on a per-app basis and on a per-integration basis.
Get App Menu
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/menu \
-H 'content-type: application/json' \
-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.
Update App Menu
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/menu \
-X PUT \
-d '{"items": [{"type": "link", "text": "Smooch", "uri": "http://smooch.io"}]}' \
-H 'content-type: application/json' \
-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.
Delete App Menu
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.
Get Integration 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.
Update Integration Menu
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/menu \
-X PUT \
-d '{"items": [{"type": "link", "text": "Smooch", "uri": "http://smooch.io"}]}' \
-H 'content-type: application/json' \
-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.
Delete Integration Menu
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
Persistent Menu Schema
Arguments | |
---|---|
items required |
A list of menu items. See menu items for more detail. |
settings optional |
An optional object for menu settings. See menu settings for more detail. |
Menu Items Schema
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. |
Menu Settings Schema
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
- Get integration profile
- 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",
"displayName": "Friendly octopus"
},
{
"_id": "5735ddf948011972d621dc08",
"type": "twilio",
"phoneNumberSid": "PN0674df0ecee0c9819bca0ff0bc0a159e",
"phoneNumber": "+15146125236",
"name": "Mike's Account",
"accountSid": "ACa1b4c65ee0722712fab89867cb14eac7",
"status": "active"
},
{
"_id": "5735ddfb48011972d621dc09",
"type": "telegram",
"username": "mikes_smooch_bot",
"status": "active"
},
{
"_id": "5735ddfd48011972d621dc0a",
"type": "line",
"mid": "uf0c0bc1813d372ac5af4c5b5faee9923",
"channelId": "1462776483",
"botName": "Mike Bot",
"status": "active"
}
],
"hasMore": false,
"offset": 0
}
GET /v1.1/apps/{appId}/integrations
Lists all integrations for a given app. This API is paginated. It returns a maximum of 25 integrations by default, and accepts offset
and limit
query parameters. The maximum limit is 100.
Parameter | Description |
---|---|
types |
String, the list can be filtered to return only integrations of a specific type. More than one value can be specified through comma separation e.g. ?types=twilio,line |
limit |
Integer, the number of records to return (maximum 100, default 25). |
offset |
Integer, the number of initial records to skip before picking records to return. |
Integrations response properties
Each integration will return a set of common properties along with properties specific to its type, see Integrations for more info about properties for a specific type. Common properties are:
Field | Description |
---|---|
_id | The integration ID. |
type | The integration type. See integrations for a list of supported types. |
status | The integration status. Possible values are active , inactive or error . More info. |
displayName | The integration display name. Omitted if empty. |
Integration status
Status | Description |
---|---|
active | The integration is working correctly. |
inactive | Additional action is required before this integration can be considered active. Examples are a messenger integration without a page selected or a wechat integration for which Smooch hasn’t received a webhook ping from WeChat. See integrations for detailed steps on how to integrate each channel. |
error | Smooch received an unexpected error from the channel and should be reviewed. |
Get Integration
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02 \
-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. Some channels allow you to update more properties (see sections below). If updating a specific property is not supported, you must delete the integration and re-create it with the new data.
3rd party channels
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/582dedf230e788746891281a \
-X PUT \
-d '{ "displayName": "A human-friendly name" }' \
-H 'content-type: application/json' \
-H 'authorization: Bearer your-account-jwt'
smooch.integrations.update({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '582dedf230e788746891281a',
props: {
displayName: 'A human-friendly name'
}
}).then((response) => {
// async code
});
Response:
200 OK
{
"integration": {
"_id": "582dedf230e788746891281a",
"displayName": "A human-friendly display name",
"status": "active",
"type": "whatsapp",
"baseUrl": "https://15144441919.whatsapp.ec.url",
"hsmFallbackLanguage": "fr_CA",
"username": "smooch",
"phoneNumber": "15144441919"
}
}
The display name can be updated for any integration type, except for FCM, APN and the Web Messenger:
Arguments | |
---|---|
displayName | A human-friendly name used to identify the integration. Maximum of 100 characters. May be unset with null or '' . |
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.
Get Integration Profile
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/profile \
-H 'authorization: Bearer your-account-jwt'
smooch.integrations.profile.get({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '5735dded48011972d621dc02'
}).then((response) => {
// async code
});
Response:
200 OK
{
"profile": {
"about": "Shoplifter is now on WhatsApp, come say hello! 👋",
"address": "1337 avenue Casgrain, Montréal (Québec) Canada",
"description": "ShopLifter helps you lift your shop.",
"email": "info@shoplifter.fun",
"vertical": "Shop Lifting",
"websites": [
"https://shoplifter.fun"
],
"photoUrl": "https://api.smooch.io/v1.1/icons/whatsapp/55c8d9758590aa1900b9b9f6/5735dded48011972d621dc02"
}
}
GET /v1.1/apps/{appId}/integrations/{integrationId}/profile
Return the specified integration profile.
Update Integration Profile
PUT /v1.1/apps/{appId}/integrations/{integrationId}/profile
The Update Integration Profile endpoint allows you to update the profile information of active integrations. See the sections below for channel specific instructions.
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. |
photoUrl optional |
URL where the business' profile photo is hosted. WhatsApp recommends an image with dimensions of 640x640 and max size of 63KB. |
address optional |
Address of the business. Maximum of 256 characters. Cannot be empty when provided. |
description optional |
Description of the business. Maximum of 256 characters. Cannot be empty when provided. |
email optional |
Email address to contact the business. Maximum of 128 characters. Cannot be empty when provided. |
vertical optional |
Industry of the business. Maximum of 128 characters. Cannot be empty when provided. |
websites optional |
URLs associated with the business. Maximum of 2 websites, each with a maximum of 256 characters. Must be an array. |
See our documentation on WhatsApp Business Profile for more information on the topic.
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'
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. |
displayName optional |
A human-friendly name used to identify the integration. Defaults to Messenger if not specified.Maximum of 100 characters. May be unset with null or '' . |
Firebase Cloud Messaging
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "fcm", "serverKey": "AAAA_hSf4g2J2Q3zDh2DbvSh27dhKlm2", "senderId": "1429457686312"}' \
-H 'content-type: application/json' \
-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. |
serviceCode optional |
LINE Service Code. |
switcherSecret optional |
LINE Switcher Secret. |
displayName optional |
A human-friendly name used to identify the integration. Defaults to LINE if not specified.Maximum of 100 characters. May be unset with null or '' . |
Mailgun
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "mailgun", "apiKey": "key-f265hj32f0sd897lqd2j5keb96784043", "domain": "sandbox123.mailgun.org", "incomingAddress": "mytestemail@sandbox123.mailgun.org"}' \
-H 'content-type: application/json' \
-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. |
displayName optional |
A human-friendly name used to identify the integration. Defaults to Mailgun if not specified.Maximum of 100 characters. May be unset with null or '' . |
Note: The incomingAddress
must have the same domain as the one specified in the domain
parameter.
MessageBird
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "messagebird", "accessKey": "9V2iJmd93kFJ390L9495JCl11", "signingKey": "Uu6N09Lkdji3820DJIO89I39sl9dJ", "originator": "12262121021"}' \
-H 'content-type: application/json' \
-H 'authorization: Bearer your-account-jwt'
smooch.integrations.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'messagebird',
accessKey: '9V2iJmd93kFJ390L9495JCl11',
signingKey: 'Uu6N09Lkdji3820DJIO89I39sl9dJ',
originator: '12262121021'
}
}).then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"type": "messagebird",
"webhookSecret": "72ade38394d1da51566cede33bd1e67e",
"originator": "12262121021",
"_id": "594850b82e4a8e5e04ef2a11"
}
}
To configure a MessageBird integration, acquire the accessKey
, the signingKey
and the MessageBird number you would like to use, then call the Create Integration endpoint. The response will include the integration’s _id
and webhookSecret
, which must be used to configure the webhook in MessageBird.
In the Flow Builder for the MessageBird number you’ve used to integrate, add a new step with the following settings:
- 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 toPOST
. - Then, using the integration
_id
andwebhookSecret
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 theSet 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. |
signingKey |
The signing key of your MessageBird account. Used to validate the webhooks' origin. |
originator required |
Smooch will receive all messages sent to this phone number. |
displayName optional |
A human-friendly name used to identify the integration. Defaults to MessageBird SMS if not specified.Maximum of 100 characters. May be unset with null or '' . |
Telegram
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "telegram", "token": "192033615:AAEuee2FS2JYKWfDlTulfygjaIGJi4s"}' \
-H 'content-type: application/json' \
-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. |
displayName optional |
A human-friendly name used to identify the integration. Defaults to Telegram if not specified.Maximum of 100 characters. May be unset with null or '' . |
Twilio
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "twilio", "accountSid": "ACa1b4c65ee0722712fab89867cb14eac7", "authToken": "160c024303f53049e1e060fd67ca6aefc", "phoneNumberSid": "PN0674df0ecee0c9819bca0ff0bc0a159e"}' \
-H 'content-type: application/json' \
-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. |
displayName optional |
A human-friendly name used to identify the integration. Defaults to Twilio SMS if not specified.Maximum of 100 characters. May be unset with null or '' . |
Twitter DM
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{ "type": "twitter", "tier": "premium", "envName": "your_env_label", "consumerKey": "your_consumer_key", "consumerSecret": "your_consumer_secret", "accessTokenKey": "your_access_token_key", "accessTokenSecret": "your_access_token_secret" }' \
-H 'content-type: application/json' \
-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. |
displayName optional |
A human-friendly name used to identify the integration. Defaults to Twitter DM if not specified.Maximum of 100 characters. May be unset with null or '' . |
Viber
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "viber", "token": "df5f8c5233399561-92636b0c5ba30da9-16d4928fc004a72d"}' \
-H 'content-type: application/json' \
-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. |
displayName optional |
A human-friendly name used to identify the integration. Defaults to Viber if not specified.Maximum of 100 characters. May be unset with null or '' . |
Web Messenger
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{ "type": "web", "integrationOrder": ["59fc8466260f48003505228b", "59d79780481d34002b7d3617"], "originWhitelist": ["https://yourdomain.com"], "businessName": "Shoplifter", "brandColor": "00ff00", "conversationColor": "dd00ee", "actionColor": "eeff00", "displayStyle": "button", "buttonWidth": "90", "buttonHeight": "90", "fixedIntroPane": true }' \
-H 'content-type: application/json' \
-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 . |
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. |
displayName optional |
A human-friendly name used to identify the integration. Defaults to WeChat if not specified.Maximum of 100 characters. May be unset with null or '' . |
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. |
displayName optional |
A human-friendly name used to identify the integration. Defaults to WhatsApp if not specified.Maximum of 100 characters. May be unset with null or '' . May be unset with null or '' . |
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 maximum of 25 service accounts by default, and accepts offset
and limit
query parameters. The maximum limit is 100.
Parameter | Description |
---|---|
limit |
Integer, the number of records to return (maximum 100, default 25). |
offset |
Integer, the number of initial records to skip before picking records to return. |
Get Service Account
Request:
curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2 \
-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,
echoPostback: false,
useAnimalNames: true
},
metadata: {
foo: 'bar'
}
}).then((response) => {
// async code
});
Response:
201 CREATED
{
"app": {
"_id": "55c8d9758590aa1900b9b9f6",
"appToken": "3s58wwlgx8xqbidgyyvzunoyw",
"name": "My App",
"settings": {
"echoPostback": false,
"maskCreditCardNumbers": false,
"useAnimalNames": true
},
"metadata": {
"foo": "bar"
}
}
}
POST /v1.1/apps
Creates a new app. The response body will include the app’s _id
, which can be used to initialize the Web, iOS and Android clients.
When using service account credentials, the service account is automatically granted access to the app.
Arguments | |
---|---|
name required |
The User facing name of the app. |
settings optional |
Customizable app settings (see app settings). |
metadata optional |
Flat object containing any custom properties associated with the app. See app metadata for more information. |
List Apps
Request:
curl $SMOOCH_ROOT/v1.1/apps \
-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,
"echoPostback": false,
"useAnimalNames": false
}
}],
"hasMore": false,
"offset": 0
}
GET /v1.1/apps
Lists all apps configured. This API is paginated. It returns a maximum of 25 apps by default, and accepts offset
and limit
query parameters. The maximum limit is 100.
When using service account credentials, only apps for which the service account has access are returned.
Parameter | Description |
---|---|
limit |
Integer, the number of records to return (maximum 100, default 25). |
offset |
Integer, the number of initial records to skip before picking records to return. |
serviceAccountId |
When specified, lists only the apps that the service account has access to. |
Get App
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6 \
-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,
"echoPostback": false,
"useAnimalNames": false
}
}
}
GET /v1.1/apps/{appId}
Fetches an individual app.
Update App
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6 \
-X PUT \
-d '{"name": "My New App", "settings": {"maskCreditCardNumbers": false, "useAnimalNames": true, "echoPostback": true}}' \
-H 'content-type: application/json' \
-H 'authorization: Bearer your-account-token'
smooch.apps.update('55c8d9758590aa1900b9b9f6', {
name: 'My New App',
settings: {
maskCreditCardNumbers: false,
echoPostback: true,
useAnimalNames: true
},
metadata: {
foo: 'bar'
}
}).then((response) => {
// async code
});
Response:
200 OK
{
"app": {
"_id": "55c8d9758590aa1900b9b9f6",
"appToken": "3s58wwlgx8xqbidgyyvzunoyw",
"name": "My New App",
"settings": {
"maskCreditCardNumbers": false,
"echoPostback": true,
"useAnimalNames": true
},
"metadata": {
"foo": "bar"
}
}
}
PUT /v1.1/apps/{appId}
Updates an app.
Arguments | |
---|---|
name optional |
The User facing name of the app. |
settings optional |
Customizable app settings (see app settings). |
metadata optional |
Flat object containing any custom properties associated with the app. See app metadata for more information. |
Delete App
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6 \
-X DELETE \
-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. |
echoPostback optional | A boolean specifying whether a message should be added to the conversation history when a postback button is clicked. See below. |
Conversation Retention Seconds
The conversationRetentionSeconds
setting dictates a period of time after which an inactive conversation will have its messages deleted. The deletion behavior is similar to when an appUser
’s messages are deleted, meaning the messages will be deleted, but the appUser
and any associated channels will remain. There is a separate API that can be used to fully delete an appUser
. As long as a conversation continues to receive regular activity, messages will not expire. Activities that will prevent message expiration include:
- 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).
Echo Postbacks
echoPostback
controls whether a message should be added to the conversation history when a postback button is clicked. When enabled, An appUser message is silently added to the conversation, without a corresponding message:appUser
webhook being triggered.
The echoPostback
setting works with any channel that supports postback actions natively (including Facebook Messenger, Twitter DM, Telegram, LINE and all Smooch SDKs). In some channels Smooch offers partial support for postback buttons via text fallback. For these channels, the user needs to answer with a message matching the postback action text. In this case, the user’s message will always be added to the conversation history.
App Keys
This set of endpoints is used to provision and revoke 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. Usemessage:appUser
andmessage:appMaker
instead triggers
is now a required property when creating a webhookmessage:appUser
events supportfile
messages. Previous versions sent them astext
messagespostback
,conversation:start
,message:appUser
andmessage: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
anddelivery:failure
webhook triggers which are replaced bymessage:delivery:channel
andmessage:delivery:failure
respectively message:delivery:channel
triggers when messages are delivered to SDKs.message:delivery:failure
can be triggered after amessage: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 onemessage
and only contain an_id
property. - New properties
isFinalEvent
andexternalMessages
are included in these new webhook payloads.
- Removed
AppUsers
- API responses no longer include a
devices
array and acredentialRequired
property.devices
has been renamed toclients
long ago and it was kept in API responses for backward compatibility - Link App User To Channel
confirmation
is now a required propertyskipConfirmation
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