Core
Introduction
Welcome to the Sunshine Conversations 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 Sunshine Conversations API is designed according to REST principles.
The API accepts JSON in request bodies and requires that the content-type: application/json header be specified for all such requests. The API will always respond with an object. Depending on context, resources may be returned as single objects or as arrays of objects, nested within the response object.
In some cases, the API will also facilitate cross-origin resource sharing so that it can be called from a web application.
Regions
# Use US region (default)
export SMOOCH_ROOT=https://api.smooch.io
# Use EU region
export SMOOCH_ROOT=https://api.eu-1.smooch.io
// Use US region (default)
const smooch = new SmoochCore({
keyId: 'your-key-id',
secret: 'your-secret',
scope: 'app' // account or app
});
// Use EU region
const smooch = new SmoochCore({
keyId: 'your-key-id',
secret: 'your-secret',
scope: 'app', // account or app
serviceUrl: 'https://api.eu-1.smooch.io'
});
Sunshine Conversations is available in the following regions. Each Sunshine Conversations 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 Sunshine Conversations, including instructions on how to upgrade to the latest version, visit our docs.
API Libraries
Sunshine Conversations provides official API libraries for JavaScript, Ruby, Python and Java. These helpful libraries wrap calls to the API and can make interfacing with Sunshine Conversations easier.
Postman Collection
In addition to api libraries, Sunshine Conversations 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"
}
}
Sunshine Conversations 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 | Sunshine Conversations 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
Sunshine Conversations APIs are subject to rate limiting. If the rate limit is exceeded Sunshine Conversations 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 Sunshine Conversations as intended will not encounter them, however usage spikes do occur and encountering a rate limit may be unavoidable. In order to avoid production outages, when calling the Sunshine Conversations 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. Sunshine Conversations will not change your rate limit, but we would like to understand your use case and perhaps offer suggestions.
Conversation Size Limits
Conversations are limited to 30,000 messages. Once you reach this maximum, a 423 Locked HTTP status code is returned when trying to post a new message. To allow more messages to be sent to the affected conversation, you must delete all messages to make room.
If your use case involves conversations that could exceed this limit, please contact us. We will not extend your limit, but we want to understand your use case better.
Request Size Limits
The Sunshine Conversations 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 Sunshine Conversations API.
Sunshine Conversations allows basic authentication or JSON Web Tokens (JWTs) as authentication methods for server-to-server calls. See below for more details.
There are two different authorization scopes available - app and account.
| Scope | Authorized Methods |
|---|---|
| app | All Core methods |
| account | All Core and Account Provisioning methods |
The app scope can be used to access any of the Sunshine Conversations Core APIs on behalf of a single app, or any app user related to that app.
The account scope can be used to access any of the Sunshine Conversations Core and Account Provisioning APIs on behalf of the account owner, any app belonging to the account, or any app user related to those apps.
Authentication
To authenticate requests to the API, you will need an API key, composed of a key id and a secret.
For an overview of how authentication works in Sunshine Conversations and instructions on how to generate an API key, see the guide.
API requests can be authenticated in two ways:
- With Basic authentication you can make requests using an API key directly.
- With JSON Web Tokens (JWTs) you sign tokens with an API key, which are then used to authenticate with the API. See When to Use JWTs? to learn if JWTs are relevant for your usage.
Before using an API key in produciton, make sure to familiarize yourself with best practices on how to securely handle credentials.
Basic Authentication
# Calling GET /v1/appusers using basic authentication
curl $SMOOCH_ROOT/v1/appusers/c7f6e6d6c3a637261bd9656f \
--user keyId:secret
API requests can be authenticated with basic authentication using an API key. The key id is used as the username and the secret as the password.
The scope of access is determined by the owner of the API key. See the guide for more details.
JWTs
# Calling GET /v1.1/appusers using a JWT
curl $SMOOCH_ROOT/v1.1/appusers/c7f6e6d6c3a637261bd9656f \
-H 'authorization: Bearer your-jwt'
// Initializing Sunshine Conversations Core in Node.js
var smooch = new SmoochCore({
keyId: 'your-key-id',
secret: 'your-secret',
scope: 'app' // account or app
});
JSON Web Tokens (JWTs) are an industry standard authentication method. The full specification is described here, and a set of supported JWT libraries for a variety of languages and platforms can be found at http://jwt.io. To summarize, a JWT is composed of a header, a payload, and a signature. The payload contains information called claims which describe the subject to whom the token was issued.
The JWT itself is transmitted via the HTTP authorization header. The token should be prefixed with “Bearer” followed by a space. For example: Bearer your-jwt.
To generate a JWT, you need an API key, which is composed of a key ID and a secret. The key ID is included in a JWT’s header, as the kid property, while the secret is used to sign the JWT.
For more in-depth coverage, see the guide.
Header
JWT header:
{
"alg": "HS256",
"typ": "JWT",
"kid": "act_5963ceb97cde542d000dbdb1"
}
The JWT header must contain the key id (kid) of the API key that is used to sign it. The algorithm (alg) used should be HS256. Unsigned JWTs are not accepted.
Payload
JWT payload with
accountscope:
{
"scope": "account"
}
JWT payload with
appscope claim:
{
"scope": "app"
}
The JWT payload must include a scope claim which specifies the caller’s scope of access.
-
account-scoped JWTs must be generated with an API key associated with a Sunshine Conversations account (act_) or service account (svc_). -
app-scoped JWTs can be generated with an API key associated with an app (app_).
Resource Paths
Resource path with account scope API key example
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
--user 'keyId:keySecret'
smooch.appUsers
.get({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f'
})
.then((response) => {
// async code
});
Resource path with app scope API key example
curl $SMOOCH_ROOT/v1.1/appusers/c7f6e6d6c3a637261bd9656f \
--user 'keyId:keySecret'
smooch.appUsers
.get({
userId: 'c7f6e6d6c3a637261bd9656f'
})
.then((response) => {
// async code
});
The app resource is implicitly defined when using basic authentication or JWTs with app API keys. However, most Sunshine Conversations REST API users will use an account scoped API key to authenticate their calls to the API, and will thus provide the full resource path in the URL. Accordingly, the API call examples in these docs will reflect the full resource path.
Webhooks
Webhooks are a fantastic way to extend the Sunshine Conversations platform beyond the built-in feature set. You can use webhooks to build your own Sunshine Conversations 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 Sunshine Conversations 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 |
| notification:delivery:channel | when a notification is successfully delivered to a customer channel |
| notification:delivery:user | when a notification is successfully delivered to the user’s device |
| notification:delivery:failure | when a notification 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:start | when a user opts in to start receiving messages |
| 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:block | when a client has been marked as blocked |
| 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
Sunshine Conversations exposes REST API methods to:
Create webhook
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks \
-X POST \
-d '{"target": "http://example.com/callback", "triggers": ["message:appUser"], "includeClient": true}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.webhooks
.create('5963c0d619a30a2e00de36b8', {
target: 'http://example.com/callback',
triggers: ['message:appUser'],
includeClient: true
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"webhook": {
"_id": "55c8d9758590aa1900b9b9f6",
"includeClient": true,
"includeFullAppUser": true,
"triggers": ["message:appUser"],
"secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
"target": "http://example.com/callback",
"version": "v1.1"
}
}
POST /v1.1/apps/{appId}/webhooks
Create a webhook for the specified app. The response body will include a secret which will be transmitted with each webhook invocation and can be used to verify the authenticity of the caller.
Alternatively, you can use the Webhooks integration in the Sunshine Conversations dashboard to easily create a webhook.
| Arguments | |
|---|---|
| target required |
URL to be called when the webhook is triggered. |
| triggers required |
An array of triggers you wish to have the webhook listen to. This property is case sensitive. More details. |
| includeClient optional |
A boolean specifying whether webhook payloads should include the client information associated with a conversation in webhook events. |
| includeFullAppUser optional |
A boolean specifying whether webhook payloads should include the complete appUser schema for appUser events. |
List webhooks
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks \
--user 'keyId:keySecret'
smooch.webhooks.list('5963c0d619a30a2e00de36b8').then((response) => {
// async code
});
Response:
200 OK
{
"webhooks": [
{
"_id": "55c8d9758590aa1900b9b9f6",
"includeClient": false,
"includeFullAppUser": true,
"triggers": ["message:appUser", "message:delivery:failure"],
"secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
"target": "http://example.com/callback",
"version": "v1.1"
}
]
}
GET /v1.1/apps/{appId}/webhooks
List all webhooks configured for a given app.
Get webhook
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks/55c8d9758590aa1900b9b9f6 \
--user 'keyId:keySecret'
smooch.webhooks.get('5963c0d619a30a2e00de36b8', '55c8d9758590aa1900b9b9f6').then((response) => {
// async code
});
Response:
200 OK
{
"webhook": {
"_id": "55c8d9758590aa1900b9b9f6",
"includeClient": false,
"includeFullAppUser": true,
"triggers": ["message:appUser", "message:delivery:failure"],
"secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
"target": "http://example.com/callback",
"version": "v1.1"
}
}
GET /v1.1/apps/{appId}/webhooks/{webhookId}
Individual webhooks can be fetched using this API.
Update webhook
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks/55c8d9758590aa1900b9b9f6 \
-X PUT \
-d '{"target": "http://example.com/callback", "includeClient": true}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.webhooks
.update('5963c0d619a30a2e00de36b8', '55c8d9758590aa1900b9b9f6', {
target: 'http://example.com/callback',
includeClient: true
})
.then((response) => {
// async code
});
Response:
200 OK
{
"webhook": {
"_id": "55c8d9758590aa1900b9b9f6",
"includeClient": true,
"includeFullAppUser": true,
"triggers": ["message:appUser", "message:delivery:failure"],
"secret": "8564b3e6a8b20a4bdb68b05d9ea97aace9bc5936",
"target": "http://example.com/callback",
"version": "v1.1"
}
}
PUT /v1.1/apps/{appId}/webhooks/{webhookId}
Use this API to update your existing webhooks.
| Arguments | |
|---|---|
| target optional |
URL to be called when the webhook is triggered. |
| triggers optional |
The triggers you wish to have the webhook listen to. The default trigger is message. This property is case sensitive. More details. |
| includeClient optional |
A boolean specifying whether webhook payloads should include the client information associated with a conversation in webhook events. |
| includeFullAppUser optional |
A boolean specifying whether webhook payloads should include the complete appUser schema for appUser events. |
Delete webhook
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/webhooks/55c8d9758590aa1900b9b9f6 \
-X DELETE \
--user 'keyId:keySecret'
smooch.webhooks.delete('5963c0d619a30a2e00de36b8', '55c8d9758590aa1900b9b9f6').then(() => {
// async code
});
Response:
200 OK
DELETE /v1.1/apps/{appId}/webhooks/{webhookId}
Deletes the specified webhook.
Message Events
Trigger - message:appUser (text)
Payload:
{
"trigger": "message:appUser",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"messages": [
{
"_id": "55c8c1498590aa1900b9b9b1",
"type": "text",
"text": "Hi! Do you have time to chat?",
"role": "appUser",
"authorId": "c7f6e6d6c3a637261bd9656f",
"name": "Steve",
"received": 1444348338.704,
"source": {
"type": "messenger"
}
}
],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"client": {
"_id": "5c9d2f34a1d3a2504bc89511",
"lastSeen": "2019-04-05T18:23:20.791Z",
"platform": "web",
"id": "20b2be30cf7e4152865f066930cbb5b2",
"info": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"raw": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"active": true,
"primary": true,
"integrationId": "5c3640f8cd3fa5850931a954"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a text message.
Message event payload schema
| Field | Description |
|---|---|
| trigger | "message:appUser", or "message:appMaker" |
| app | A nested object representing the Sunshine Conversations 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. |
| recentNotifications optional | An array of objects representing the contextual notifications associated with the event. See the message schema below for details. |
| client optional | A nested object representing the client associated with the message. This field is only included when the message has an associated client, the trigger is "message:appUser" and includeClient on webhook settings is set to true. See the client schema 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,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"client": {
"_id": "5c9d2f34a1d3a2504bc89511",
"lastSeen": "2019-04-05T18:23:20.791Z",
"platform": "web",
"id": "20b2be30cf7e4152865f066930cbb5b2",
"info": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"raw": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"active": true,
"primary": true,
"integrationId": "5c3640f8cd3fa5850931a954"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"recentNotifications": [
{
"_id": "5c8a5b90fa8624128cc5ba32",
"role": "appMaker",
"type": "text",
"text": "This is a sample notification.",
"authorId": "00udkjb3sjnQkjH2n0h7",
"avatarUrl": "https://www.gravatar.com/avatar/00000000000000000000000000000000.png?s=200&d=mm",
"received": 1552571280.984,
"source": {
"type": "notification"
}
}
],
"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,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a carousel message.
Trigger - message:appMaker (list)
Payload:
{
"trigger": "message:appMaker",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"messages": [
{
"items": [
{
"title": "Tacos",
"description": "Beef and cheese... Mhm...",
"size": "large",
"mediaUrl": "http://www.tacobueno.com/media/1338/partytacolarge.png?quality=65",
"mediaType": "image/png",
"_id": "5887c9117e4de029005f1fc7",
"actions": [
{
"text": "Oh yeah!",
"payload": "TACOS",
"_id": "5887c9117e4de029005f1fc8",
"type": "postback"
}
]
}
],
"actions": [
{
"text": "More Choices!",
"payload": "MORE",
"_id": "5887c9a37e4de029005f1fce",
"type": "postback"
}
],
"type": "list",
"role": "appMaker",
"received": 1485293841.303,
"authorId": "2cKU9zRO2DpBWgk764Tfro",
"avatarUrl": "https://www.gravatar.com/avatar/5e543256c480ac577d30f76f9120eb74.png?s=200&d=mm",
"_id": "5887c9117e4de029005f1fc6",
"source": {
"type": "api"
}
}
],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a list message.
Trigger - message:appUser (location)
Payload:
{
"trigger": "message:appUser",
"app": {
"_id": "55fafea8bf8fd41a00357805"
},
"messages": [
{
"text": "Location shared:\nhttps://maps.google.com/maps?q=45.5261583,-73.595346",
"authorId": "76293a38b24c5cca43e79415",
"received": 1485292067.601,
"type": "location",
"coordinates": {
"lat": 45.5261583,
"long": -73.595346
},
"role": "appUser",
"_id": "5887c22356c66904009ad602",
"source": {
"type": "messenger"
}
}
],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"client": {
"_id": "5c9d2f34a1d3a2504bc89511",
"lastSeen": "2019-04-05T18:23:20.791Z",
"platform": "web",
"id": "20b2be30cf7e4152865f066930cbb5b2",
"info": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"raw": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"active": true,
"primary": true,
"integrationId": "5c3640f8cd3fa5850931a954"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a location message.
Trigger - message:appUser (file)
Payload:
{
"trigger": "message:appUser",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"messages": [
{
"_id": "55c8c1498590aa1900b9b9b1",
"type": "file",
"mediaUrl": "https://some-pdf-file.pdf",
"mediaType": "application/pdf",
"mediaSize": 123456,
"role": "appUser",
"authorId": "c7f6e6d6c3a637261bd9656f",
"name": "Steve",
"received": 1444348338.704,
"source": {
"type": "android",
"id": "604018c259285f82a746c44ef0368a7f44d4af6a"
}
}
],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"client": {
"_id": "5c9d2f34a1d3a2504bc89511",
"lastSeen": "2019-04-05T18:23:20.791Z",
"platform": "web",
"id": "20b2be30cf7e4152865f066930cbb5b2",
"info": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"raw": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"active": true,
"primary": true,
"integrationId": "5c3640f8cd3fa5850931a954"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a file message.
Trigger - message:appUser (file as text - deprecated)
File as text payload:
{
"trigger": "message:appUser",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"messages": [
{
"_id": "55c8c1498590aa1900b9b9b1",
"type": "text",
"text": "File upload: https://some-pdf-file.pdf",
"role": "appUser",
"authorId": "c7f6e6d6c3a637261bd9656f",
"name": "Steve",
"received": 1444348338.704,
"source": {
"type": "messenger"
}
}
],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"client": {
"_id": "5c9d2f34a1d3a2504bc89511",
"lastSeen": "2019-04-05T18:23:20.791Z",
"platform": "web",
"id": "20b2be30cf7e4152865f066930cbb5b2",
"info": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"raw": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"active": true,
"primary": true,
"integrationId": "5c3640f8cd3fa5850931a954"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
A message webhook of type file will only be sent when the appUser sends a message from the Web, iOS or Android SDKs.
For all other channels, a text message webhook will be sent with the file url embedded in the text.
Trigger - message:appMaker (form)
Payload:
{
"trigger": "message:appMaker",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"messages": [
{
"blockChatInput": true,
"fields": [
{
"type": "text",
"name": "full_name",
"label": "Your name?",
"placeholder": "Type your name...",
"minSize": 1,
"maxSize": 30,
"_id": "5cd1f4c5ba7361ecr43e87e5"
},
{
"type": "email",
"name": "email_address",
"label": "Your email?",
"placeholder": "email@example.com",
"_id": "5cd1f4c5ba1s41e12c0e87e4"
},
{
"type": "select",
"name": "meal_selection",
"label": "Your meal?",
"selectSize": 1,
"options": [
{
"name": "pizza",
"label": "Pizza",
"_id": "5cd1f4c5ba7361iu7c0e87e3"
},
{
"name": "tacos",
"label": "Tacos",
"_id": "5cd1f4c5ba7361e1tr0e87e2"
},
{
"name": "ramen",
"label": "Ramen",
"_id": "5cd1f4c5ba7361ebvd0e87e1"
}
],
"_id": "5cd1f4c5ba73bve12c0e87e0"
}
],
"_id": "55c8c1498590aa1900b9b9b1",
"type": "form",
"role": "appMaker",
"submitted": false,
"authorId": "2cKU9zRO2DpBWgk764Tfro",
"avatarUrl": "https://www.gravatar.com/avatar/5e543256c480ac577d30f76f9120eb74.png?s=200&d=mm",
"received": 1444348338.704,
"source": {
"type": "api"
}
}
],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"conversationStarted": true,
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": {}
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a form message.
Trigger - message:appUser (formResponse)
Payload:
{
"trigger": "message:appUser",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"messages": [
{
"fields": [
{
"type": "text",
"name": "full_name",
"label": "Your name?",
"text": "Ed Wright",
"_id": "5cd1f4c5ba7361ecr43e87n1"
},
{
"type": "email",
"name": "email_address",
"label": "Your email?",
"email": "edw@mail.com",
"_id": "5cd1f4c5ba1s41e12c0e87n0"
},
{
"type": "select",
"name": "meal_selection",
"label": "Your meal?",
"select": [
{
"name": "ramen",
"label": "Ramen",
"_id": "5cd1f4c5ba7361ebvd0e87n9"
}
],
"_id": "5cd1f4c5ba73bve12c0e8740"
}
],
"_id": "55c8c1498590aa1900b9b9p0",
"type": "formResponse",
"role": "appUser",
"name": "Web User 24p5c1cdl710bf95f2d5ed70",
"authorId": "c7f6e6d6c3a637261bd9656f",
"received": 1444348338.909,
"textFallback": "Your name?: Ed Wright\nYour Email?: edw@mail.com\nYour Meal?: Ramen",
"source": {
"type": "web"
},
"quotedMessage": {
"type": "message",
"content": {
"blockChatInput": true,
"fields": [
{
"text": "Ed Wright",
"type": "text",
"name": "full_name",
"label": "Your name?",
"placeholder": "Type your name...",
"minSize": 1,
"maxSize": 30,
"_id": "5cd1f4c5ba7361ecr43e87e5"
},
{
"email": "edw@mail.com",
"type": "email",
"name": "email_address",
"label": "Your email?",
"placeholder": "email@example.com",
"_id": "5cd1f4c5ba1s41e12c0e87e4"
},
{
"select": [
{
"name": "ramen",
"label": "Ramen",
"_id": "5cd1f4c5ba7361iu7c0e87e6"
}
],
"type": "select",
"name": "meal_selection",
"label": "Your meal?",
"selectSize": 1,
"options": [
{
"name": "pizza",
"label": "Pizza",
"_id": "5cd1f4c5ba7361iu7c0e87e3"
},
{
"name": "tacos",
"label": "Tacos",
"_id": "5cd1f4c5ba7361e1tr0e87e2"
},
{
"name": "ramen",
"label": "Ramen",
"_id": "5cd1f4c5ba7361ebvd0e87e1"
}
],
"_id": "5cd1f4c5ba73bve12c0e87e0"
}
],
"_id": "55c8c1498590aa1900b9b9b1",
"type": "form",
"role": "appMaker",
"submitted": true,
"authorId": "2cKU9zRO2DpBWgk764Tfro",
"avatarUrl": "https://www.gravatar.com/avatar/5e543256c480ac577d30f76f9120eb74.png?s=200&d=mm",
"received": 1444348338.704,
"source": {
"type": "api"
}
}
}
}
],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"conversationStarted": true,
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": {}
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for a formResponse message.
AppUser Events
Trigger - appUser:delete
Payload:
{
"trigger": "appUser:delete",
"app": {
"_id": "575040549a38df8fb4eb1e51"
},
"appUser": {
"_id": "de13bee15b51033b34162411",
"userId": "123",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"version": "v1.1"
}
An appUser:delete webhook triggers when an app user is deleted through the Delete App User endpoint.
appUser:delete event payload schema
| Field | Description |
|---|---|
| trigger | "appUser:delete" |
| app | A nested object representing the Sunshine Conversations app associated with the event. See the truncated app schema below for details. |
| appUser | A nested object representing the truncated appUser associated with the event. See the truncated appUser schema below for details. |
| version | The API version used to create the webhook. See API version for details. |
Postback Events
Trigger - postback
Payload:
{
"trigger": "postback",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"postbacks": [
{
"message": {
"_id": "55c8c1498590aa1900b9b9b1",
"text": "Do you want to see more options?",
"type": "text",
"role": "appMaker",
"authorId": "c7f6e6d6c3a637261bd9656f",
"name": "LunchBot",
"received": 1444348338.704,
"source": {
"type": "slack"
},
"actions": [
{
"_id": "571530ee4fae94c32b78b170",
"type": "postback",
"text": "Yes",
"payload": "YES"
}
]
},
"action": {
"_id": "571530ee4fae94c32b78b170",
"type": "postback",
"text": "Yes",
"payload": "YES"
}
}
],
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"client": {
"_id": "5c9d2f34a1d3a2504bc89511",
"lastSeen": "2019-04-05T18:23:20.791Z",
"platform": "web",
"id": "20b2be30cf7e4152865f066930cbb5b2",
"info": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"raw": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"active": true,
"primary": true,
"integrationId": "5c3640f8cd3fa5850931a954"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"version": "v1.1"
}
The payload for when a user taps a postback button.
Postbacks originating from a persistent menu do not have messages associated with them, and so omit the message property.
Postback event payload schema
| Field | Description |
|---|---|
| trigger | "postback" |
| app | A nested object representing the Sunshine Conversations app associated with the event. See the truncated app schema below for details. |
| postbacks | An array of objects representing the postbacks associated with the event. See the postback schema below for details. |
| appUser | A nested object representing the appUser associated with the event. See the truncated appUser schema below for details. |
| client | A nested object representing the current client associated with the conversation of the event. This field is only included when includeClient on webhook settings is set. See the client schema for detail. |
| conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
Postback schema
| Field | Description |
|---|---|
| message optional | A nested object representing the message associated with the postback action. See the message schema below for details (Not present in postback payloads triggered by persistent menu items). |
| action | A nested object representing the postback action. See the action schema below for details. |
| metadata optional | Flat object containing any custom properties associated with the action. See the metadata schema for more information. |
Conversation Events
Trigger - conversation:read
Payload:
{
"trigger": "conversation:read",
"app": {
"_id": "57ec2881c47d2d24b0c16427"
},
"source": {
"type": "messenger"
},
"appUser": {
"_id": "7685787bf0e9e8cf56182288",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"client": {
"_id": "5c9d2f34a1d3a2504bc89511",
"lastSeen": "2019-04-05T18:23:20.791Z",
"platform": "web",
"id": "20b2be30cf7e4152865f066930cbb5b2",
"info": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"raw": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"active": true,
"primary": true,
"integrationId": "5c3640f8cd3fa5850931a954"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"timestamp": 1480349392.103
}
The payload for when a user reads a conversation.
Conversation event payload schema
| Field | Description |
|---|---|
| trigger | "conversation:read", or "conversation:start" |
| app | A nested object representing the Sunshine Conversations app associated with the event. See the truncated app schema below for details. |
| source | A nested object representing the source of the event. See the source schema below for details. |
| appUser | A nested object representing the appUser associated with the event. See the truncated appUser schema below for details. |
| client | A nested object representing the current client associated with the conversation of the event. This field is only included when includeClient on webhook settings is set. See the client schema for detail. |
| conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
| timestamp | A unix timestamp given in seconds, describing when Sunshine Conversations received the event. |
| referral | Referral information. Only present for WeChat, Messenger, Telegram and Viber. See referral schema for details. |
| version | The API version used to create the webhook. See API version for details. |
Trigger - conversation:start
Payload:
{
"trigger": "conversation:start",
"app": {
"_id": "57ec2881c47d2d24b0c16427"
},
"source": {
"type": "messenger"
},
"appUser": {
"_id": "c7f6e6d6c3a637261bd9656f",
"userId": "bob@example.com",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"timestamp": 1480349392.103
}
The payload for when a user opts in to start receiving messages. conversation:start is only available on a subset 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 event will be triggered when:
- startConversation method or equivalent is called from an SDK API on any platform.
-
/startcommand has been sent to a Telegram bot. - A user clicks the
Get Startedmessage in Messenger. - A user follows the business on LINE.
- A subscribe event is sent in WeChat.
- When a user opens a conversation with a bot using the message button in Viber.
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,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"client": {
"_id": "5c9d2f34a1d3a2504bc89511",
"lastSeen": "2019-04-05T18:23:20.791Z",
"platform": "web",
"id": "20b2be30cf7e4152865f066930cbb5b2",
"info": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"raw": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"active": true,
"primary": true,
"integrationId": "5c3640f8cd3fa5850931a954"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"referral": {
"code": "my-ref-code",
"details": {
"source": "MESSENGER_CODE",
"type": "OPEN_THREAD"
}
},
"timestamp": 1495650348.685,
"version": "v1.1"
}
Conversation referral payload schema
| Field | Description |
|---|---|
| trigger | "conversation:referral" |
| app | A nested object representing the Sunshine Conversations app associated with the event. See the truncated app schema below for details. |
| source | A nested object representing the source of the event. See the source schema below for details. |
| appUser | A nested object representing the appUser associated with the event. See the truncated appUser schema below for details. |
| client | A nested object representing the current client associated with the conversation of the event. This field is only included when includeClient on webhook settings is set. See the client schema for detail. |
| conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
| referral | Referral information. See referral schema for details. |
| version | The API version used to create the webhook. See API version for details. |
The payload for when a user is referred to a conversation. This payload will be sent when a user performs the following actions:
- 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. See the user merging guide for more information about merges, the conditions that can trigger a merge, and what to do in response to a merge event.
Merge events payload
| Field | Description |
|---|---|
| trigger | "merge:appUser" |
| app | A nested object representing the Sunshine Conversations app associated with the event. See the truncated app schema below for details. |
| surviving | A nested object with the truncated appUser that now represents the merged appUser object. See the truncated appUser schema below for details. |
| discarded | An array of objects with the truncated appUsers that were unified into surviving appUser object. See the truncated appUser schema below for details. |
| discardedProperties | A nested object with the set of properties that were discarded when merging the two appUsers. This should contain values only if the combined properties exceed the 4KB limit. |
| version | The API version used to create the webhook. See API version for details. |
| discardedConversationId optional | The Id of the discarded conversation, if any. |
Message Delivery Events
Delivery events expose the delivery steps that a message takes to be delivered to a user:
- Channel delivery confirmation The message is delivered to the channel (e.g. WhatsApp), represented by the
message:delivery:channeltrigger. - User delivery confirmation The message is delivered to the user, represented by the
message:delivery:usertrigger. - Delivery failure The message could not be delivered (either to the channel or to the user), represented by the
message:delivery:failuretrigger.
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 Sunshine Conversations message to be delivered to many channels, but it can only be delivered once per channel. To understand how Sunshine Conversations 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 Sunshine Conversations 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 Sunshine Conversations request because of a bad request. |
| delivery_timeout | This is triggered when we’ve been trying to deliver the message for too long, we haven’t necessarily encountered errors, but have been rate limited or backed off for too long. Applies only for delivery events on whatsapp. |
| not_found | The channel indicated that the target user cannot be found. |
| rate_limited | The channel has rate-limited the delivery of the message. For whatsapp delivery events, this is triggered when the throttling queue is full and we can’t accept more messages. |
| 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. |
| template_unavailable | The provided message template is unusable or does not exist. Applies only for delivery events on whatsapp. |
| too_many_errors | This is triggered when we encountered too many errors from the WhatsApp API Client after repeatedly trying to deliver the message. Applies only for delivery events on whatsapp. |
| 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 Sunshine Conversations couldn’t map it to a specific error. |
Trigger - message:delivery:channel
Payload:
{
"trigger": "message:delivery:channel",
"app": {
"_id": "5a5ccf0d1b4077001a36b11d"
},
"appUser": {
"_id": "b234f6a69d2eea3589f4c24e",
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"destination": {
"type": "twilio"
},
"isFinalEvent": false,
"externalMessages": [
{
"id": "SMb0ee6ee1313a4141ba346e368325a04d"
}
],
"message": {
"_id": "5baa5b4ab5bebb000ce85589"
},
"timestamp": 1537891147.555,
"version": "v1.1"
}
The message:delivery:channel webhook reports the success to handoff a message to a channel.
If isFinalEvent property of the payload is true, no additional delivery event (message:delivery:*) will be sent for the message._id and destination.type pair.
If isFinalEvent is false, another message:delivery:* webhook with the same message._id and destination.type pair is expected, but not guaranteed.
Trigger - message:delivery:user
Payload:
{
"trigger": "message:delivery:user",
"app": {
"_id": "5a5ccf0d1b4077001a36b11d"
},
"appUser": {
"_id": "b234f6a69d2eea3589f4c24e",
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"destination": {
"type": "twilio"
},
"isFinalEvent": true,
"externalMessages": [
{
"id": "SMb0ee6ee1313a4141ba346e368325a04d"
}
],
"message": {
"_id": "5baa5b4ab5bebb000ce85589"
},
"timestamp": 1537891147.555,
"version": "v1.1"
}
The message:delivery:user webhook confirms the delivery of a message to the user.
Trigger - message:delivery:failure
Payload:
{
"trigger": "message:delivery:failure",
"app": {
"_id": "575040549a38df8fb4eb1e51"
},
"appUser": {
"_id": "de13bee15b51033b34162411",
"userId": "123",
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"destination": {
"type": "line"
},
"isFinalEvent": true,
"error": {
"code": "unauthorized",
"underlyingError": {
"message": "Authentication failed due to the following reason: invalid token. Confirm that the access token in the authorization header is valid."
}
},
"message": {
"_id": "5baa610db5bebb000ce855d6"
},
"timestamp": 1480001711.941,
"version": "v1.1"
}
The message:delivery:failure webhook reports the failure to deliver a message to a user on the destination channel. If this webhook triggers, it means that the message did not reach the user.
Notification Delivery Events
Trigger - notification:delivery:channel
Payload:
{
"trigger": "notification:delivery:channel",
"app": {
"_id": "5babc57a79ace012bba4781a"
},
"version": "v1.1",
"timestamp": 1480001440.731,
"destination": {
"type": "messagebird|twilio|whatsapp",
"integrationId": "5b354bdab42a1d61143ccc26",
"destinationId": "+15145555555"
},
"isFinalEvent": false,
"externalMessages": [
{
"id": "a121392f-7dd3-4bdb-8844-fa3rd2ac7f72"
}
],
"notification": {
"_id": "e361392f-7dd3-4bdb-8844-d0d002ac7f72"
},
"matchResult": {
"appUser": {
"_id": "5b354bdab42a1d61143ccc26",
"conversationStarted": true
},
"conversation": {
"_id": "075354bdab42a1d61143cc362"
},
"client": {
"integrationId": "5b354bdab42a1d61143ccc26",
"externalId": "15145555555",
"id": "e6eb2653-e143-4c1a-be58-bdd6afgh35ff",
"displayName": "+1 514-555-5555",
"status": "active",
"raw": {
"profile": {
"name": "Some Person"
},
"from": "15145555555"
},
"lastSeen": "2024-03-15T20:19:23.851Z",
"linkedAt": "2024-02-28T16:02:10.219Z",
"_id": "65df5902e111c3e8f8edee28",
"platform": "whatsapp",
"active": true,
"blocked": false,
"primary": true
}
}
}
The payload for a notification channel delivery
Notification event payload schema
| Field | Description |
|---|---|
| trigger | "notification:delivery:channel", or "notification:delivery:failure", or "notification:delivery:user" |
| app | A nested object representing the Sunshine Conversations app associated with the event. See the truncated app schema below for details. |
| version | The API version used to create the webhook. See API version for details. |
| timestamp | A unix timestamp given in seconds, describing when the notification delivery event occurred. |
| destination | A nested object representing the destination of the notification. See the destination schema below for details. |
| isFinalEvent | A boolean indicating whether the webhook is the final one for the notification._id and destination.type pair. |
| 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. |
| notification | An object representing the notification associated with the event. See the truncated message schema below for details. |
| matchResult optional | An object representing the appUser and conversation associated with the notification. |
| error optional |
A nested object, present in notification:delivery:failure event, representing the error associated with the delivery failure. See the error schema below for details. |
Trigger - notification:delivery:failure
Payload:
{
"trigger": "notification:delivery:failure",
"app": {
"_id": "5babc57a79ace012bba4781a"
},
"version": "v1.1",
"timestamp": 1480001440.731,
"destination": {
"type": "messagebird|twilio|whatsapp",
"integrationId": "5b354bdab42a1d61143ccc26",
"destinationId": "+15145555555"
},
"isFinalEvent": true,
"externalMessages": [
{
"id": "a121392f-7dd3-4bdb-8844-fa3rd2ac7f72"
}
],
"notification": {
"_id": "e361392f-7dd3-4bdb-8844-d0d002ac7f72"
},
"matchResult": {
"appUser": {
"_id": "5b354bdab42a1d61143ccc26",
"conversationStarted": true
},
"conversation": {
"_id": "075354bdab42a1d61143cc362"
},
"client": {
"integrationId": "5b354bdab42a1d61143ccc26",
"externalId": "15145555555",
"id": "e6eb2653-e143-4c1a-be58-bdd6afgh35ff",
"displayName": "+1 514-555-5555",
"status": "active",
"raw": {
"profile": {
"name": "Some Person"
},
"from": "15145555555"
},
"lastSeen": "2024-03-15T20:19:23.851Z",
"linkedAt": "2024-02-28T16:02:10.219Z",
"_id": "65df5902e111c3e8f8edee28",
"platform": "whatsapp",
"active": true,
"blocked": false,
"primary": true
}
},
"error": {
"code": "bad_request",
"underlyingError": {
"status": 400,
"message": "This is an error message."
}
}
}
The payload for a notification delivery failure.
Trigger - notification:delivery:user
Payload:
{
"trigger": "notification:delivery:user",
"app": {
"_id": "5babc57a79ace012bba4781a"
},
"version": "v1.1",
"timestamp": 1480001440.731,
"isFinalEvent": true,
"destination": {
"type": "messagebird|twilio|whatsapp",
"integrationId": "5b354bdab42a1d61143ccc26",
"destinationId": "15145555555"
},
"externalMessages": [
{
"id": "a121392f-7dd3-4bdb-8844-fa3rd2ac7f72"
}
],
"notification": {
"_id": "e361392f-7dd3-4bdb-8844-d0d002ac7f72"
},
"matchResult": {
"appUser": {
"_id": "5b354bdab42a1d61143ccc26",
"userId": "bob@email.com",
"conversationStarted": true
},
"conversation": {
"_id": "075354bdab42a1d61143cc362"
},
"client": {
"integrationId": "5b354bdab42a1d61143ccc26",
"externalId": "15145555555",
"id": "e6eb2653-e143-4c1a-be58-bdd6afgh35ff",
"displayName": "+1 514-555-5555",
"status": "active",
"raw": {
"profile": {
"name": "Some Person"
},
"from": "15145555555"
},
"lastSeen": "2024-03-15T20:19:23.851Z",
"linkedAt": "2024-02-28T16:02:10.219Z",
"_id": "65df5902e111c3e8f8edee28",
"platform": "whatsapp",
"active": true,
"blocked": false,
"primary": true
}
}
}
The payload for a notification user delivery.
Payment Events
Trigger - payment:success
Payload:
{
"trigger": "payment:success",
"app": {
"_id": "571e3496cb98b3962ce740d7"
},
"appUser": {
"_id": "2b15a54fde9dc2f33f88bc25",
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"payments": [
{
"source": {
"type": "messenger"
},
"message": {
"text": "Just put some vinegar on it",
"actions": [
{
"text": "Buy vinegar",
"amount": 1000,
"currency": "usd",
"state": "paid",
"_id": "5877fd5624fe8fd934d7c2f3",
"uri": "https://app.smooch.io/checkout/5877fd5624fe8fd934d7c2f3",
"type": "buy"
}
],
"type": "text",
"role": "appMaker",
"received": 1484258646.823,
"authorId": "5X8AJwvpy0taCkPDniC5la",
"avatarUrl": "https://www.gravatar.com/image.jpg",
"_id": "5877fd5624fe8fd934d7c2f2",
"source": {
"type": "api"
}
},
"action": {
"text": "Buy vinegar",
"amount": 1000,
"currency": "usd",
"state": "paid",
"_id": "5877fd5624fe8fd934d7c2f3",
"uri": "https://app.smooch.io/checkout/5877fd5624fe8fd934d7c2f3",
"type": "buy"
},
"charge": {
"id": "ch_19dPrCHQ7f2U7NYSZ45OspXT"
}
}
],
"timestamp": 1484258666.455,
"version": "v1.1"
}
The payload for when a payment is received.
Payment event payload schema
| Field | Description |
|---|---|
| trigger | "payment:success" |
| app | A nested object representing the Sunshine Conversations 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 Sunshine Conversations 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",
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"channel": "messenger",
"integrationId": "5a99b74858247c608f64a348",
"criteria": {
"phoneNumber": "+15141234567",
"givenName": "bleep",
"surname": "bloop"
},
"version": "v1.1"
}
The payload for a link app user success.
Link success event payload schema
| Field | Description |
|---|---|
| trigger | "link:success" |
| app | A nested object representing the Sunshine Conversations app associated with the event. See the truncated app schema below for details. |
| appUser | A nested object representing the appUser associated with the event. See the truncated appUser schema below for details. |
| conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
| channel | The channel for which the link succeeded. |
| integrationId | The ID of the integration for which the link succeeded. |
| criteria | The criteria specified to establish the link. |
| version | The API version used to create the webhook. See API version for details. |
Trigger - link:match
Payload:
{
"trigger": "link:match",
"app": {
"_id": "58b487c74ebf3ce5d4b38e5f"
},
"appUser": {
"_id": "8215a086b271592e01b74e28",
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"channel": "messenger",
"integrationId": "5a99b74858247c608f64a348",
"criteria": {
"phoneNumber": "+15141234567",
"givenName": "bleep",
"surname": "bloop"
},
"version": "v1.1"
}
The payload for a link app user match.
Link match event payload schema
| Field | Description |
|---|---|
| trigger | "link:match" |
| app | A nested object representing the Sunshine Conversations app associated with the event. See the truncated app schema below for details. |
| appUser | A nested object representing the appUser associated with the event. See the truncated appUser schema below for details. |
| conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
| channel | The channel for which the link matched. |
| integrationId | The ID of the integration for which the link matched. |
| criteria | The criteria specified to establish the link. |
Trigger - link:failure
Payload:
{
"trigger": "link:failure",
"app": {
"_id": "58b487c74ebf3ce5d4b38e5f"
},
"appUser": {
"_id": "8215a086b271592e01b74e28",
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"error": {
"code": "bad_request",
"message": "(#100) No matching user found"
},
"channel": "messenger",
"integrationId": "5a99b74858247c608f64a348",
"criteria": {
"phoneNumber": "+15141234567",
"givenName": "bleep",
"surname": "bloop"
},
"version": "v1.1"
}
The payload for a link app user failure.
Link failure event payload schema
| Field | Description |
|---|---|
| trigger | "link:failure" |
| app | A nested object representing the Sunshine Conversations app associated with the event. See the truncated app schema below for details. |
| appUser | A nested object representing the appUser associated with the event. See the truncated appUser schema below for details. |
| conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
| channel | The channel for which the link failed. |
| integrationId | The ID of the integration for which the link failed. |
| criteria | The criteria specified to establish the link. |
| error | A nested object representing the error associated with the link failure. See the error schema below for details. |
Client Events
Trigger - client:add
Payload:
{
"trigger": "client:add",
"app": {
"_id": "575040549a38df8fb4eb1e51"
},
"version": "v1.1",
"appUser": {
"_id": "de13bee15b51033b34162411",
"userId": "123",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"clients": [
{
"_id": "5c93cb748f63db54ff3b51dd",
"status": "active",
"integrationId": "5a99b74858247c608f64a348",
"externalId": "1128837457239041",
"id": "bea02e14-86f4-4711-8ecc-ab717ebf750a",
"displayName": "Sue Purb",
"info": {
"gender": "female",
"timezone": -5,
"locale": "en_US",
"avatarUrl": "https://scontent.xx.fbcdn.net/example.png"
},
"lastSeen": "2019-01-14T19:11:17.783Z",
"linkedAt": "2019-01-14T19:11:17.783Z",
"primary": true,
"platform": "messenger",
"active": true,
"blocked": false
}
]
}
A client:add webhook triggers when a client is added to an existing appUser. This can occur as a result of a login, channel link, or when an SDK consumes an auth code.
In channel linking cases the client:add event only fires when the link has been completed. For example, if a user declines when prompted to link Facebook Messenger, client:add will not trigger. Link failures such as this can be detected with the link:failure trigger.
Exceptions:
Sunshine Conversations 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 Sunshine Conversations 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:block
Payload:
{
"trigger": "client:block",
"app": {
"_id": "575040549a38df8fb4eb1e51"
},
"version": "v1.1",
"appUser": {
"_id": "de13bee15b51033b34162411",
"userId": "123",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"clients": [
{
"integrationId": "5a956b91ff15f2001a64ca14",
"externalId": "oCP-Gs8oBIY-bapnMf_CCCCCCCCC",
"id": "dea42bef-7610-4815-bcf3-111111111111",
"displayName": "Steve Bob",
"status": "blocked",
"info": {
"subscribeTime": 1529423042,
"language": "en",
"sex": 0
},
"raw": {
"qr_scene_str": "",
"qr_scene": 0,
"subscribe_scene": "ADD_SCENE_QR_CODE",
"tagid_list": [],
"groupid": 0,
"remark": "",
"subscribe_time": 1529423042,
"headimgurl": "",
"country": "",
"province": "",
"city": "",
"language": "en",
"sex": 0,
"nickname": "Steve Bob",
"openid": "oCP-Gs8oBIY-bapnMf_CCCCCCCCC",
"subscribe": 1
},
"lastSeen": "2020-11-06T14:21:59.533Z",
"linkedAt": "2018-09-19T16:04:39.571Z",
"_id": "5ba27397d2d95b000ba4011e",
"platform": "wechat",
"blocked": true,
"active": false,
"primary": true
}
]
}
A client:block webhook triggers when a client’s status changes to "blocked". Clients are blocked when a user blocks the business in a third-party application.
Supported on:
- LINE
- Twitter DM
- Viber
client:block event payload schema
| Field | Description |
|---|---|
| trigger | "client:block" |
| app | A nested object representing the Sunshine Conversations 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 been blocked. See the client schema below for details. |
| version | The API version used to create the webhook. See API version for details. |
Trigger - client:remove
Payload:
{
"trigger": "client:remove",
"app": {
"_id": "575040549a38df8fb4eb1e51"
},
"appUser": {
"_id": "de13bee15b51033b34162411",
"userId": "123",
"conversationStarted": true,
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"clients": [
{
"_id": "5c93cb748f63db54ff3b51dd",
"id": "90e2f396500b451dabdce69f207247d4"
}
],
"version": "v1.1"
}
A client:remove webhook triggers when a client is removed from an existing appUser. This can happen when a channel is unlinked via the channel API.
A channel link action might also cause an existing third party client to change ownership from one appUser to another. In this case both a client:remove and client:add trigger will be fired.
client:remove event payload schema
| Field | Description |
|---|---|
| trigger | "client:remove" |
| app | A nested object representing the Sunshine Conversations app associated with the event. See the truncated app schema below for details. |
| appUser | A nested object representing the truncated appUser associated with the event. See the truncated appUser schema below for details. |
| clients | An array of client objects that have just been removed from the appUser. These objects contain the removed client id only. |
Typing Events
Trigger - typing:appUser
Payload:
{
"trigger": "typing:appUser",
"app": {
"_id": "5698edbf2a43bd081be982f1"
},
"timestamp": 1510848814.349,
"appUser": {
"_id": "56bfa6add1683d0e0c7e5956",
"email": "steve.bob@email.com",
"surname": "Steve",
"givenName": "Bob",
"signedUpAt": "2018-04-02T14:45:46.505Z",
"properties": { "favoriteFood": "prizza" }
},
"client": {
"_id": "5c9d2f34a1d3a2504bc89511",
"lastSeen": "2019-04-05T18:23:20.791Z",
"platform": "web",
"id": "20b2be30cf7e4152865f066930cbb5b2",
"info": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"raw": {
"currentTitle": "Conversation Demo",
"currentUrl": "https://examples.com/awesomechat",
"browserLanguage": "en-US",
"referrer": "",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
"URL": "examples.com",
"sdkVersion": "4.17.12",
"vendor": "smooch"
},
"active": true,
"primary": true,
"integrationId": "5c3640f8cd3fa5850931a954"
},
"conversation": {
"_id": "105e47578be874292d365ee8"
},
"activity": {
"type": "typing:stop"
},
"source": {
"type": "ios"
},
"version": "v1.1"
}
A typing:appUser webhook triggers when an appUser starts or stops typing a response on a supported channel.
typing:appUser event payload schema
| Field | Description |
|---|---|
| trigger | "typing:appUser" |
| app | A nested object representing the Sunshine Conversations app associated with the event. See the truncated app schema below for details. |
| appUser | A nested object representing the truncated appUser associated with the event. See the truncated appUser schema below for details. |
| conversation | A nested object representing the conversation associated with the event. See the truncated conversation schema below for details. |
| client | A nested object representing the current client associated with the conversation of the event. This field is only included when includeClient on webhook settings is set. See the client schema for detail. |
| source | A nested object representing the source of the event. See the source schema below for details. |
| timestamp | A unix timestamp given in seconds, describing when Sunshine Conversations 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 Sunshine Conversations Webhooks
When a webhook is created, a shared secret will be generated for it. The secret can be used to determine the veracity of a request to your webhook route. It is included as an X-API-Key header with each webhook request sent to the target URL.
That secret is available in the response to the POST request used to generate the webhook, or through a GET request to the webhook route.
Retry policy
A webhook call will be attempted up to 5 times over a 15 minute window. The attempts will happen 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 Sunshine Conversations 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: Sunshine Conversations should not be calling the target.
- 404: The target doesn’t exist.
- 406: The target exists, and rejected the 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, email, and avatarUrl 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 Sunshine Conversations users with an external user directory, and to synchronize a single conversation across multiple clients. To understand how this works, see the section covering user authentication.
Profile properties
Profile properties, also referred to as custom properties, are a set of key/value pairs that are specific to your application domain, or use case. These fields are stored under the properties field of an appUser, and can have values of type Number, String, or Boolean. For more information, see the section covering user information management.
Get App User
Request by smoochId:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
--user 'keyId:keySecret'
smooch.appUsers
.get({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f'
})
.then((response) => {
// async code
});
Request by userId:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/steveb@channel5.com \
--user 'keyId:keySecret'
smooch.appUsers
.get({
appId: '5963c0d619a30a2e00de36b8',
userId: 'steveb@channel5.com'
})
.then((response) => {
// async code
});
Response:
200 OK
{
"appUser": {
"_id": "7494535bff5cef41a15be74d",
"userId": "steveb@channel5.com",
"givenName": "Steve",
"signedUpAt": "2019-01-14T18:55:12.515Z",
"hasPaymentInfo": false,
"conversationStarted": false,
"clients": [
{
"_id": "5c93cb748f63db54ff3b51dd",
"status": "active",
"lastSeen": "2019-01-14T16:55:59.364Z",
"platform": "ios",
"id": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
"deviceId": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
"pushNotificationToken": "<0cfc626c 9fed1e3d e9fcb139 e6590cb3 3462f3c8 afd47000 6af2003f 2e3a72a9>",
"appVersion": "1.0",
"info": {
"appId": "com.rp.ShellApp",
"carrier": "Rogers",
"buildNumber": "1.0",
"devicePlatform": "iPhone8,4",
"installer": "Dev",
"sdkVersion": "6.11.2",
"osVersion": "12.1.2",
"appName": "ShellApp",
"os": "iOS",
"vendor": "smooch"
},
"raw": {
"appId": "com.rp.ShellApp",
"carrier": "Rogers",
"buildNumber": "1.0",
"devicePlatform": "iPhone8,4",
"installer": "Dev",
"sdkVersion": "6.11.2",
"osVersion": "12.1.2",
"appName": "ShellApp",
"os": "iOS",
"vendor": "smooch"
},
"active": true,
"primary": false,
"integrationId": "599ad41e49db6e243ad77d2f"
}
],
"pendingClients": [],
"properties": {
"favoriteFood": "prizza"
}
}
}
GET /v1.1/apps/{appId}/appusers/{smoochId|userId}
Retrieve a specific app user. Like all other /v1.1/apps/{appId}/appusers/ paths, an app user can be identified using either the smoochId or the userId.
Update App User
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
-X PUT \
-d '{"givenName": "Steve"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.appUsers
.update({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
appUser: {
givenName: 'Steve'
}
})
.then((response) => {
// async code
});
Response:
200 OK
{
"appUser": {
"_id": "7494535bff5cef41a15be74d",
"userId": "steveb@channel5.com",
"givenName": "Steve",
"signedUpAt": "2019-01-14T18:55:12.515Z",
"hasPaymentInfo": false,
"conversationStarted": false,
"clients": [
{
"_id": "5c93cb748f63db54ff3b51dd",
"status": "active",
"lastSeen": "2019-01-14T16:55:59.364Z",
"platform": "ios",
"id": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
"deviceId": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
"pushNotificationToken": "<0cfc626c 9fed1e3d e9fcb139 e6590cb3 3462f3c8 afd47000 6af2003f 2e3a72a9>",
"appVersion": "1.0",
"info": {
"appId": "com.rp.ShellApp",
"carrier": "Rogers",
"buildNumber": "1.0",
"devicePlatform": "iPhone8,4",
"installer": "Dev",
"sdkVersion": "6.11.2",
"osVersion": "12.1.2",
"appName": "ShellApp",
"os": "iOS",
"vendor": "smooch"
},
"raw": {
"appId": "com.rp.ShellApp",
"carrier": "Rogers",
"buildNumber": "1.0",
"devicePlatform": "iPhone8,4",
"installer": "Dev",
"sdkVersion": "6.11.2",
"osVersion": "12.1.2",
"appName": "ShellApp",
"os": "iOS",
"vendor": "smooch"
},
"active": true,
"primary": false,
"integrationId": "599ad41e49db6e243ad77d2f"
}
],
"pendingClients": [],
"properties": {
"favoriteFood": "prizza"
}
}
}
PUT /v1.1/apps/{appId}/appusers/{smoochId|userId}
Update an app user’s basic profile information and specify custom profile data via properties. This API is additive; only the specific fields specified in the request body, and only the specific JSON sub-fields included in the properties field will be updated. In other words, omitting a field will not delete that field. To delete a sub-field in the properties field, set its value to null in the request body.
| 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. |
| avatarUrl optional |
The URL for the user’s avatar. |
| 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. These properties can be deleted by setting their value to null. |
Delete App User Profile
Request by smoochId:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/profile \
-X DELETE \
--user 'keyId:keySecret'
smooch.appUsers
.deleteProfile({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f'
})
.then((response) => {
// async code
});
Request by userId:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/steveb@channel5.com/profile \
-X DELETE \
--user 'keyId:keySecret'
smooch.appUsers
.deleteProfile({
appId: '5963c0d619a30a2e00de36b8',
userId: 'steveb@channel5.com'
})
.then((response) => {
// async code
});
Response:
200 OK
{
"appUser": {
"_id": "7494535bff5cef41a15be74d",
"userId": "steveb@channel5.com",
"signedUpAt": "2019-01-14T18:55:12.515Z",
"hasPaymentInfo": false,
"conversationStarted": false,
"clients": [
{
"_id": "5c93cb748f63db54ff3b51dd",
"status": "active",
"lastSeen": "2019-01-14T16:55:59.364Z",
"platform": "ios",
"id": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
"deviceId": "F272EB80-D512-4C19-9AC0-BD259DAEAD91",
"pushNotificationToken": "<0cfc626c 9fed1e3d e9fcb139 e6590cb3 3462f3c8 afd47000 6af2003f 2e3a72a9>",
"active": true,
"primary": false,
"integrationId": "599ad41e49db6e243ad77d2f"
}
],
"pendingClients": [],
"properties": {}
}
}
DELETE /v1.1/apps/{appId}/appusers/{smoochId|userId}/profile
Delete an app user’s profile. Calling this API will clear givenName, surname, email, avatarUrl and every custom property for the specified app user.
For every client owned by the app user, it will also clear displayName, avatarUrl and any channel specific information stored in the info and raw fields.
Calling this API doesn’t delete the app user’s conversation history. To fully delete the app user, see Delete App User.
Delete App User
Request by smoochId:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
-X DELETE \
--user 'keyId:keySecret'
smooch.appUsers
.delete({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f'
})
.then((response) => {
// async code
});
Request by userId:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/steveb@channel5.com \
-X DELETE \
--user 'keyId:keySecret'
smooch.appUsers
.delete({
appId: '5963c0d619a30a2e00de36b8',
userId: 'steveb@channel5.com'
})
.then((response) => {
// async code
});
Response:
200 OK
{}
DELETE /v1.1/apps/{appId}/appusers/{smoochId|userId}
Delete an app user, its clients and its conversation history. The app user is considered completely deleted once the appUser:delete webhook is fired.
To only delete an app user’s profile, see Delete App User Profile.
Pre-Create App User
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers \
-X POST \
-d '{"userId": "steveb@channel5.com", "givenName": "Steve", "properties": {"favoriteFood": "prizza"}}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.appUsers
.create({
appId: '5963c0d619a30a2e00de36b8',
appUser: {
userId: 'steveb@channel5.com',
givenName: 'Steve',
properties: {
favoriteFood: 'prizza'
}
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"appUser": {
"_id": "f316d285a6642a32adbdcd84",
"userId": "steveb@channel5.com",
"givenName": "Steve",
"signedUpAt": "2019-01-14T18:55:12.515Z",
"hasPaymentInfo": false,
"conversationStarted": false,
"clients": [],
"pendingClients": [],
"properties": {
"favoriteFood": "prizza"
}
}
}
POST /v1.1/apps/{appId}/appusers
| Arguments | |
|---|---|
| userId required |
A unique identifier for the app user. The userId can be used to link a user to the same conversation across multiple clients. |
| givenName optional |
The user’s given name (first name). |
| surname optional |
The user’s surname (last name). |
| email optional |
The user’s email address. |
| avatarUrl optional |
The URL for the user’s avatar. |
| 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 Sunshine Conversations 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 Sunshine Conversations once that user logs in to your app. To facilitate this, you can call POST /v1.1/apps/{appId}/appusers to pre-create a Sunshine Conversations identity with userId bob@example.com, to which you can import that existing conversation history. After Bob signs in to your app and your app calls login with the same userId, they will see their conversation history.
Get App User Channel Entities (Deprecated)
Request:
curl https https://api.smooch.io/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/channels \
--user 'keyId:keySecret'
smooch.appUsers
.getChannels({
appId: '5963c0d619a30a2e00de36b8',
userId: 'deb920657bbc3adc3fec7963'
})
.then((response) => {
//Async code
});
Response:
200 OK
{
"channels": [
{
"type": "twilio",
"phoneNumber": "+15145555555",
"integrationId": "5a3174ee84c71521fa415ca9"
},
{
"type": "messenger",
"userId": "198273192387",
"integrationId": "5a33dfd13dd25731cb1bf3cf"
}
]
}
GET /v1.1/apps/{appId}/appusers/{smoochId|userId}/channels
Retrieves all of the app user’s channel entity Ids.
Entity ID Responses
| Channel Type | Entity ID |
|---|---|
| messenger viber line |
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. |
| 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 \
--user 'keyId:keySecret'
smooch.appUsers
.getBusinessSystems({
appId: '5963c0d619a30a2e00de36b8',
userId: 'deb920657bbc3adc3fec7963'
})
.then((response) => {
//Async code
});
Response:
200 OK
{
"businessSystems": [
{
"type": "slack",
"channelId": "C872AE91B"
},
{
"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. |
| 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": "immediate"}, "phoneNumber": "15101231234"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.appUsers
.linkChannel({
appId: '5963c0d619a30a2e00de36b8',
userId: '+5145555555',
data: {
type: 'twilio',
confirmation: {
type: 'immediate'
},
phoneNumber: '15101231234'
}
})
.then((response) => {
// async code
});
Response:
200 OK
{
"appUser": {
"_id": "7494535bff5cef41a15be74d",
"userId": "+5145555555",
"givenName": "Steve",
"signedUpAt": "2019-01-14T18:55:12.515Z",
"hasPaymentInfo": false,
"conversationStarted": false,
"clients": [],
"pendingClients": [
{
"_id": "5c93cb748f63db54ff3b51dd",
"integrationId": "5a3174ee84c71521fa415ca9",
"id": "4afa71ce-20ea-4971-841f-357630a1f970",
"platform": "twilio",
"status": "pending"
}
],
"properties": {
"favoriteFood": "pizza"
}
}
}
POST /v1.1/apps/{appId}/appusers/{smoochId|userId}/channels
| Arguments | |
|---|---|
| type required |
The channel to link. Can be twilio, messagebird, or whatsapp. |
| integrationId optional |
The integration to link. Must match the provided type. Required when there are multiple integrations matching the passed 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, WhatsApp
If you specify an immediate confirmation, Sunshine Conversations 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, Sunshine Conversations 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 and WhatsApp
If you specify a userActivity confirmation, Sunshine Conversations 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 prompt via SMS), the link:success webhook will be triggered.
The message property is mandatory for this confirmation type. Sunshine Conversations 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 Sunshine Conversations with the necessary ID to connect LINE, WeChat or Telegram, we have limited the API to accept ‘Twilio’, WhatsApp, and ‘MessageBird’ 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. |
Unlink App User From Channel
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/channels/twilio \
-X DELETE \
--user 'keyId:keySecret'
smooch.appUsers
.unlinkChannel({
appId: '5963c0d619a30a2e00de36b8',
userId: 'steveb@channel5.com',
channel: 'twilio'
})
.then((response) => {
// async code
});
Response:
200 OK
DELETE /v1.1/apps/{appId}/appusers/{smoochId|userId}/channels/{channel}
Removes the specified channel from the appUser’s clients. The client is considered completely removed once the client:remove webhook is fired.
Get Auth Code
GET /v1.1/apps/{appId}/appusers/{smoochId|userId}/authcode
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/deb920657bbc3adc3fec7963/authcode \
-X GET \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.appUsers
.getAuthCode({
appId: '5963c0d619a30a2e00de36b8',
userId: 'deb920657bbc3adc3fec7963'
})
.then((response) => {
// async code
});
Response:
200 OK
{
"authCode": "ac_tXcqhnHSgaZuzeOB8ndiL7A5"
}
Users can begin their communication over a third party channel such as Facebook Messenger. Using an auth code, you can transfer such users’ conversations over to an SDK channel hosted on your website or mobile app. The user can then continue their conversation in a medium that offers more freedom for the business to customize the user’s experience.
For more information, see the Channel transfer guide.
Get 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' \
--user 'keyId:keySecret'
smooch.appUsers
.getLinkRequests({
appId: '5963c0d619a30a2e00de36b8',
userId: 'deb920657bbc3adc3fec7963',
integrationIds: [
'59dbd737f294ea1fa2734829, 59fa19888b1dd03638d2dd54, 5a00d5b3002ef2a871aaef98, 8635ff3a619c1be3bdbafea7'
]
})
.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"
},
{
"integrationId": "8635ff3a619c1be3bdbafea7",
"type": "whatsapp",
"code": "2224145698",
"url": "https://wa.me/15144441919?text=2224145698%20is%20my%20code,%20I%20want%20to%20continue%20my%20conversation%20on%20WhatsApp.",
"qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAApQAAAKUCAAAAACfpPfgAAALLElEQVR42u3aQY4bMQwEQP//05sXBIjAbkreVB8Fe0yJJV+Gnx+Rx=="
}]
}
| Query Parameter | Description |
|---|---|
| integrationIds | Comma separated list of integration ids. |
A user who begins their conversation via one of the Sunshine Conversations 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. Sunshine Conversations embeds a one time code in the URL that allows the channel to be securely linked to the user’s existing Sunshine Conversations 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, Viber, and WhatsApp channels.
| Channel | Link URL works on: |
|---|---|
| Facebook Messenger | browser, mobile |
| Telegram | browser, mobile |
| Viber | mobile (Viber app must be installed) |
| browser, mobile (WhatsApp must be installed) |
Merge Users
POST /v1.1/apps/{appId}/appusers/merge
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/merge \
-X POST \
-d '{"surviving": {"_id": "afa567114fdb04f5da925d6b"}, "discarded": {"_id": "decbf2d33e2940abe873fde3"}}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.appUsers
.mergeUsers({
appId: '5963c0d619a30a2e00de36b8',
props: {
surviving: {
_id: 'afa567114fdb04f5da925d6b'
},
discarded: {
_id: 'decbf2d33e2940abe873fde3'
}
}
})
.then((response) => {
// async code
});
Response:
200 OK
{}
Force the merge of two specific users, when the business has determined that they represent the same person. See the user merging guide for more information about merges.
When the operation is complete, a merge:appUser webhook event will be fired as confirmation of the merge.
| Arguments | |
|---|---|
| surviving required |
Nested object representing the user that will survive at the end of the merge. See merged user schema below. |
| discarded required |
Nested object representing the user to merge into the surviving user. This user will be deleted as part of the process. See merged user schema below. |
Merged User Schema
| Arguments | |
|---|---|
| id required |
The _id of the user to merge. |
Schema
App user schema
The appUser schema describes the appUser data sent in webhook payloads, and in GET appUser responses.
| Field | Description |
|---|---|
| _id | A canonical ID that can be used to retrieve the appUser. |
| userId optional | An optional ID that if specified can also be used to retreive the appUser. |
| properties | A flat object of optional properties set by the app maker. |
| signedUpAt | A datetime string with the format yyyy-mm-ddThh:mm:ssZ representing the moment an appUser was created. |
| clients | An array of objects representing the clients associated with the appUser. See the client schema below for details. |
| pendingClients | As clients, but containing linked clients which have not been confirmed yet (i.e. Twilio SMS) |
| conversationStarted | A boolean representing of whether a message has been sent or not. |
| givenName optional | An optional given name. |
| surname optional | An optional surname. |
| email optional | An optional email address. |
| avatarUrl optional | An optional URL for an avatar. |
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. |
| givenName optional |
appUser’s give name, not included when includeFullAppUser is unset in webhook settings. |
| surname optional |
appUser’s surname, not included when includeFullAppUser is unset in webhook settings. |
| email optional |
appUser’s email, not included when includeFullAppUser is unset in webhook settings. |
| avatarUrl optional |
URL for appUser’s avatar, not included when includeFullAppUser is unset in webhook settings. |
| signedUpAt optional |
appUser’s signup time, not included when includeFullAppUser is unset in webhook settings. |
| properties optional |
appUser’s properties, not included when includeFullAppUser is unset in webhook settings. |
Client schema
Client specific info
| Field | Description |
|---|---|
| _id | The unique ID of the client. |
| platform | The type of integration that the client represents. |
| status | The client status. Indicates if the client is able to receive messages or not. See client status below for available values. |
| integrationId | The ID of the integration that the client was created for. |
| pushNotificationToken | The token used for push notifications for Android and iOS SDK clients. |
| externalId optional | The ID of the user on an external channel. For example, the user’s phone number for Twilio, or their page-scoped user ID for Facebook Messenger. Applies only to non-SDK clients. |
| primary | Boolean indicating if the platform is the appUser’s primary channel. The primary channel is the user’s most active channel and the preferred delivery channel for the appMaker’s messages. |
| deviceId optional | A unique identifier for a device if on Web, iOS, or Android. |
| displayName optional | The appUser’s display name as provided by the client. |
| avatarUrl optional | The URL 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 | A timestamp signifying when the client was added to the user. Formatted as yyyy-mm-ddThh:mm:ssZ |
| id (deprecated) | Deprecated. Use _id or deviceId instead. |
| active (deprecated) | Deprecated. Refer to client status instead. |
| blocked (deprecated) optional | Deprecated. Refer to client status instead. |
Client Status
A client’s status property indicates whether it is able to receive messages or not. In general, a client will not be able to receive messages unless its status is active.
| Status | Description |
|---|---|
| active | Indicates that the client is active and able to receive messages. |
| blocked | When the user explicitly unsubscribes from communication from the business, the client will have a blocked status. Attempts to send messages to a blocked client will result in a delivery error. |
| inactive | Indicates an SDK client for which the user has logged out of the device. Clients in inactive state will not receive push notifications on iOS or Android. |
| pending | A client for which a link attempt has been made, but for which the link has not yet been confirmed. Pending clients are ignored when determining where a message will be sent. |
Raw client info
Sunshine Conversations 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 |
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 Sunshine Conversations 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 Sunshine Conversations 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 /2/users/:id API.
The response is made available through the raw field.
All properties are nested under data.
| Field | Description |
|---|---|
| data | Top level field that contains all of the raw data returned by the API. |
| data.id | Unique identifier of this user. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers. |
| data.name | The friendly name of this user, as shown on their profile. profile. |
| data.username | The Twitter handle (screen name) of this user. profile. |
| data.location | The location specified in the user’s profile, if the user provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries. |
| data.profile_image_url | The URL to the profile image for this user, as shown on the user’s profile. |
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' \
--user 'keyId:keySecret'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
text: 'Just put some vinegar on it',
role: 'appUser',
type: 'text'
}
})
.then((response) => {
// async code
});
Request (App Maker):
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-d '{"text":"Just put some vinegar on it", "role": "appMaker", "type": "text"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
type: 'text',
text: 'Just put some vinegar on it',
role: 'appMaker'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"message": {
"_id": "55c8c1498590aa1900b9b9b1",
"authorId": "c7f6e6d6c3a637261bd9656f",
"role": "appMaker",
"type": "text",
"name": "Steve",
"text": "Just put some vinegar on it",
"avatarUrl": "https://www.gravatar.com/image.jpg",
"received": 1439220041.586
},
"extraMessages": [
{
"_id": "507f1f77bcf86cd799439011",
"authorId": "c7f6e6d6c3a637261bd9656f",
"role": "appMaker",
"type": "image",
"name": "Steve",
"text": "Check out this image!",
"mediaUrl": "http://example.org/image.jpg",
"actions": [
{
"text": "More info",
"type": "link",
"uri": "http://example.org"
}
]
}
],
"conversation": {
"_id": "df0ebe56cbeab98589b8bfa7",
"unreadCount": 0
}
}
POST /v1.1/apps/{appId}/appusers/{smoochId|userId}/messages
Post a message to or from the app user. If the app user does not yet have a conversation, one will be created automatically. Messages must have a role of either appUser or appMaker.
A message must also have a type specifying the type of message you’re trying to send.
Images can be posted by URL (either self-hosted or pre-uploaded using the Sunshine Conversations attachments API) using this API via the image type.
| Arguments | |
|---|---|
| role required |
The role of the individual posting the message. Can be either appUser or appMaker. |
| type required |
The type of the message being posted. Can be text, image, file, carousel, list, location, or form. |
| subroles optional |
A string array that indicates the author’s subtypes. Messages with the appMaker role that include AI will assume that an AI generated the message and will postfix a disclaimer to the message text sent to the customer. For 3rd party channels, the disclaimer is applied for text, image, file message types. |
| 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. In app maker messages this field is typically used to identify them for the rendering of the avatar in the app user client. If the email of the Sunshine Conversations account is used, the configured profile avatar will be used. Otherwise, any gravatar matching the specified email will be used as the message avatar. In app user messages the avatarUrl present in the user’s profile is the default used when one is not provided directly in the message. Like for app maker messages, a gravatar fetched based on the email is the last fallback. |
| avatarUrl optional |
The URL of the desired message avatar image. This field will override an avatar URL present in an app user’s profile or one 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 |
| messageSchema optional |
When messageSchema is set to "whatsapp", a message key is required and is expected to conform to the native WhatsApp schema for sending message templates. For more details, consult the documentation for sending message templates on WhatsApp. |
| message optional |
A nested object conforming to the native WhatsApp schema for sending message templates. Only supported when messageSchema is passed with value "whatsapp". When specified, the resulting Sunshine Conversations message will be constructed automatically from this payload. Any conflicting message content passed at the root of the request body will be ignored (i.e. the type of the message, and any type dependant fields). |
Channel Targeting
Using channel targeting, a business can bypass the automatic delivery logic and select a specific channel type (or integration ID) instead. 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. |
If the user does not have a client linked to the targeted channel, a 404 client_not_found error will be returned.
Get Messages
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages?before=1471995721 \
--user 'keyId:keySecret'
smooch.appUsers
.getMessages({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
query: {
before: 1471995721
}
})
.then((response) => {
// async code
});
Response
200 OK
{
"conversation": {
"_id": "df0ebe56cbeab98589b8bfa7",
"unreadCount": 0
},
"messages": [
{
"_id": "55c8c1498590aa1900b9b9b1",
"authorId": "c7f6e6d6c3a637261bd9656f",
"role": "appUser",
"name": "Steve",
"text": "Just put some vinegar on it",
"avatarUrl": "https://www.gravatar.com/image.jpg",
"received": 1439220041.586
}
],
"next": "https://api.smooch.io/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages?after=1471995721"
}
GET /v1.1/apps/{appId}/appusers/{smoochId|userId}/messages
Get the specified app user’s conversation history with a limit of 100 messages, if it exists. If a conversation has not yet been created for the specified app user, 404 will be returned.
Pagination
The API endpoint for retrieving messages of a conversation has a limit of a 100 messages. The before and after parameters will have to be specified to indicate which range of messages to return. These parameters are mutually exclusive. If neither is specified, then the most recent 100 messages will be returned.
| Parameter | Description |
|---|---|
before |
Timestamp of message. The API will return 100 messages before the specified timestamp (excluding any messages with the provided timestamp). |
after |
Timestamp of message. The API will return 100 messages after the specified timestamp (excluding any messages with the provided timestamp). |
Delete Single Message
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages/5ad90ba5b74ec11877381f4e \
-X DELETE \
--user 'keyId:keySecret'
smooch.appUsers
.deleteMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
messageId: '5ad90ba5b74ec11877381f4e'
})
.then(() => {
// async code
});
Response:
200 OK
DELETE /v1.1/apps/{appId}/appusers/{smoochId|userId}/messages/{messageId}
Delete a single message, leaving behind a placeholder with both text and authorId set to [deleted]. Deleted message placeholders will also have a deleted property of true.
If the target message has a mediaUrl that is hosted by Sunshine Conversations, the media will be deleted as well. Note that files uploaded via the upload attachment API are not associated with any specific appUser and are therefore not subject to deletion by this API. The delete attachment API should be used to remove those files.
Delete All Messages
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X DELETE \
--user 'keyId:keySecret'
smooch.appUsers
.deleteMessages({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f'
})
.then((response) => {
// async code
});
Response:
200 OK
DELETE /v1.1/apps/{appId}/appusers/{smoochId|userId}/messages
Clears the message history for a user, permanently deleting all messages, but leaving any connections to Messaging Channels and Business Systems intact. These connections allow for the conversation to continue in the future, while still being associated to the same appUser.
For deleted messages that have a mediaUrl that is hosted by Sunshine Conversations, the media will be deleted as well. Note that files uploaded via the upload attachment API are not associated with any specific appUser and are therefore not subject to deletion by this API. The delete attachment API should be used to remove those files.
Conversation Activity
Notify Sunshine Conversations of different conversation activities. Supported types are typing activity and business read receipt.
Typing Activity
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/conversation/activity \
-X POST \
-d '{"role":"appMaker", "type": "typing:start"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.appUsers
.conversationActivity({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
activityProps: {
role: 'appMaker',
type: 'typing:start'
}
})
.then((response) => {
// async code
});
Response:
200 OK
{
"conversation": {
"_id": "df0ebe56cbeab98589b8bfa7",
"unreadCount": 0,
"appMakerLastRead": 1511382207.32
}
}
POST /v1.1/apps/{appId}/appusers/{appUserId|userId}/conversation/activity
Notify Sunshine Conversations when an app maker starts or stops typing a response.
| Arguments | |
|---|---|
| role required |
The role of the actor. Must be appMaker. |
| type required |
The type of typing activity to trigger. Must be either typing:start or typing:stop. |
| name optional |
The name of the app maker that starts or stops typing a response. |
| avatarUrl optional |
The avatar URL of the app maker that starts typing a response. |
Business Read Receipt
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/conversation/activity \
-X POST \
-d '{"role":"appMaker", "type": "conversation:read"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.appUsers
.conversationActivity({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
activityProps: {
role: 'appMaker',
type: 'conversation:read'
}
})
.then((response) => {
// async code
});
Response:
200 OK
{
"conversation": {
"_id": "df0ebe56cbeab98589b8bfa7",
"unreadCount": 0,
"appMakerLastRead": 1511382207.32
}
}
POST /v1.1/apps/{appId}/appusers/{appUserId|userId}/conversation/activity
Notify Sunshine Conversations when an app maker has read the user’s messages. The conversation is considered read up to the last message at the time the request was made.
| Arguments | |
|---|---|
| role required |
The role of the actor. Must be appMaker. |
| type required |
Must be conversation:read. |
Reset Unread Count
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/conversation/read \
-X POST \
--user 'keyId:keySecret'
smooch.conversations.resetUnreadCount('5963c0d619a30a2e00de36b8', 'c7f6e6d6c3a637261bd9656f').then(() => {
// async code
});
Response:
200 OK
POST /v1.1/apps/{appId}/appusers/{appUserId|userId}/conversation/read
Reset the unread count of the conversation to 0. If the conversation has not yet been created for the specified app user 404 will be returned.
Notification
Send notifications to your customers using their channel specific id (for example, a phone number), even without first creating a user and a conversation. See our Outbound Messaging Guide for more details on the Notification API.
Post Notification
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/notifications \
-X POST \
-d '{
"destination": {
"integrationId": "5e1f438bf99fb467810c0ab9",
"destinationId": "+15145555333"
},
"author": {
"role": "appMaker"
},
"message": {
"type": "text",
"text": "Check this out!"
}
}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.notifications
.postNotification({
appId: '5963c0d619a30a2e00de36b8',
notification: {
destination: {
integrationId: '5e1f438bf99fb467810c0ab9',
destinationId: '+15145555333'
},
author: {
role: 'appMaker'
},
message: {
type: 'text',
text: 'Check this out!'
}
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"notification": {
"_id": "5e0h438bf06fa498510c1ab39"
}
}
Error Response:
{
"error": {
"code": "payment_required",
"description": "Your account has exceeded the free plan limits and must be upgraded to a paid plan to continue"
}
}
POST /v1.1/apps/{appId}/notifications
Post a notification to a user using their channel specific id. This will vary depending on the targeted user channel.
Notifications must include an author role of appMaker.
| Arguments | |
|---|---|
| destination required |
An object containing id of the integration used to send the notification and the channel specific id of the user to send the notification to. (e.g. WhatsApp Phone Number). |
| author required |
An object containing role (the only accepted value is appMaker), email, name and avatarUrl. Required if messageSchema is provided. |
| messageSchema optional |
When messageSchema is set to "whatsapp", the passed message key is expected to conform to the native WhatsApp schema for sending message templates. For more details, consult the documentation for how to start conversations on WhatsApp. |
| message required |
The notification message to send. When messageSchema is not specified, message follows the Sunshine Conversations Message schema, like post message but without the destination. When messageSchema is specified, message follows a schema defined by a third-party API. If the author object is not provided, role must be included in the message object. |
| 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. When messageSchema is specified, metadata must be provided here instead of in the message. |
Attachments
You can upload files of any type that can then be used to send a file, image or carousel message to an appUser.
Upload Attachment
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/attachments?access=public&for=message&appUserId=5963c0d619a30a2e00de36b8 \
-X POST \
--user 'keyId:keySecret' \
-H 'content-type: multipart/form-data' \
-F 'source=@document.pdf;type=application/pdf'
const file = fileInput.files[0];
smooch.attachments
.create({
appId: '5963c0d619a30a2e00de36b8',
props: {
for: 'message',
access: 'public',
appUserId: '5963c0d619a30a2e00de36b8'
},
source: file
})
.then(() => {
// async code
});
Response:
201 CREATED
{
"mediaUrl": "https://media.smooch.io/apps/5963c0d619a30a2e00de36b8/conversation/c7f6e6d6c3a637261bd9656f/a77caae4cbbd263a0938eba00016b7c8/document.pdf",
"mediaType": "application/pdf"
}
POST /v1.1/apps/{appId}/attachments
Upload an attachment to Sunshine Conversations to use in future messages. Files are uploaded using the multipart/form-data content type. Use the returned mediaUrl to send a file, image or carousel message.
| Form Parameters | |
|---|---|
| source required |
The attachment data, provided as a readable file stream. |
| Query Parameters | |
|---|---|
| access required |
The access level for the attachment. Currently the only available access level is public. |
| for optional |
Specifies the intended container for the attachment, to enable automatic attachment deletion (on deletion of associated message, conversation or appUser). For now, only message is supported. See attachments for messages for details. |
| appUserId optional |
The appUserId of the user that will receive the attachment. Used in attachments for messages. |
| userId optional |
The userId of the user that will receive the attachment. Used in attachments for messages. |
Delete Attachment
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/attachments/remove \
-X POST \
-d '{"mediaUrl": "https://media.smooch.io/apps/c7f6e6d6c3a637261bd9656f/a77caae4cbbd263a0938eba00016b7c8/document.pdf"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.attachments
.delete({
appId: '5963c0d619a30a2e00de36b8',
mediaUrl: 'https://media.smooch.io/apps/c7f6e6d6c3a637261bd9656f/a77caae4cbbd263a0938eba00016b7c8/document.pdf'
})
.then(() => {
// async code
});
Response:
200 OK
{}
POST /v1.1/apps/{appId}/attachments/remove
Remove an attachment uploaded to Sunshine Conversations 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 Sunshine Conversations that your upload will be used to send a message to a user.
Knowing this, Sunshine Conversations will safely delete the attachment when the message or app user is deleted.
Templates
You can create message templates that will allow you to send complex messages such as carousel or list via convenient shorthand.
For more information on the application of templates, see our guide.
Create Template
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/templates \
-X POST \
--user 'keyId:keySecret' \
-H 'content-type: application/json' \
-d '{"name": "my_template", "message": { "role": "appMaker", "type": "text", "text": "Just put some vinegar on it" } } \
smooch.templates
.create({
appId: '5963c0d619a30a2e00de36b8',
props: {
name: 'my_template',
message: {
type: 'text',
role: 'appMaker',
text: 'Just put some vinegar on it'
}
}
})
.then(() => {
// async code
});
Response:
201 CREATED
{
"template": {
"_id": "5b477234e951d11d6e2efe7e",
"message": {
"text": "Just put some vinegar on it",
"type": "text",
"role": "appMaker"
},
"name": "my_template"
}
}
POST /v1.1/apps/{appId}/templates
Create a template in Sunshine Conversations to use when sending messages.
| Arguments | |
|---|---|
| name required |
The name you want for your template. Will be used to send templates via the shorthand. |
| message required |
The message to store in the template. Can contain any arguments as used in the post message API save a few exceptions. |
List Templates
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/templates?limit=1&offset=0 \
-X GET \
--user 'keyId:keySecret'
smooch.templates
.list({
appId: '5963c0d619a30a2e00de36b8',
props: {
limit: 1,
offset: 0
}
})
.then(() => {
// async code
});
Response:
200 OK
{
"templates": [
{
"_id": "5b477234e951d11d6e2efe7e",
"appId": "5ae1de83dd0d4061bf5d581f",
"message": {
"role": "appMaker",
"type": "text",
"text": "Just put some vinegar on it"
},
"name": "my_template"
}
],
"hasMore": true,
"offset": 0
}
GET /v1.1/apps/{appId}/templates
List created templates.
Response value hasMore will be true if there are more records left to query.
| Query Parameters | |
|---|---|
| limit optional |
Integer, the number of records to return (maximum 100, default 25). |
| offset optional |
Integer, the number of initial records to skip before picking records to return. |
Get Template
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/templates/5b477234e951d11d6e2efe7e \
-X GET \
--user 'keyId:keySecret' \
smooch.templates.get({
appId: '5963c0d619a30a2e00de36b8',
templateId: '5b477234e951d11d6e2efe7e'
).then((response) => {
// async code
});
Response:
200 OK
{
"template": {
"_id": "5b477234e951d11d6e2efe7e",
"message": {
"text": "Just put some vinegar on it",
"type": "text",
"role": "appMaker"
},
"name": "my_template"
}
}
GET /v1.1/apps/{appId}/templates/{templateId}
Get specific template created in Sunshine Conversations through the create template API.
Update Template
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/templates/5b477234e951d11d6e2efe7e \
-X PUT \
--user 'keyId:keySecret' \
-H 'content-type: application/json' \
-d '{"name": "my_updated_template", "message": { "role": "appMaker", "type": "text", "text": "Just put some vinegar on it" } } \
smooch.templates
.update({
appId: '5963c0d619a30a2e00de36b8',
templateId: '5b477234e951d11d6e2efe7e',
props: {
name: 'my_updated_template',
message: {
type: 'text',
role: 'appMaker',
text: 'Just put some vinegar on it'
}
}
})
.then(() => {
// async code
});
Response:
200 OK
{
"template": {
"_id": "5b477234e951d11d6e2efe7e",
"message": {
"text": "Just put some vinegar on it",
"type": "text",
"role": "appMaker"
},
"name": "my_updated_template"
}
}
PUT /v1.1/apps/{appId}/templates/{templateId}
Update a template in Sunshine Conversations to use when sending messages.
| Arguments | |
|---|---|
| name optional |
The name you want for your template. Will be used to send templates via the shorthand. |
| message optional |
The message to store in the template. Can contain any arguments as used in the post message API save a few exceptions. |
Delete Template
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/templates/5b477234e951d11d6e2efe7e \
-X DELETE \
--user 'keyId:keySecret'
smooch.templates
.delete({
appId: '5963c0d619a30a2e00de36b8',
templateId: '5b477234e951d11d6e2efe7e'
})
.then(() => {
// async code
});
Response:
200 OK
{}
DELETE /v1.1/apps/{appId}/templates/{templateId}
Delete template created in Sunshine Conversations through the create template API.
Template Message Exceptions
Since the act of creating a message template differs slightly from actually sending a message, some arguments that are normally allowed when calling the post message API will be ignored when creating or updating a template.
| Ignored | |
|---|---|
| destination | To use channel targeting with a template message, specify destination in the POST Message payload. |
Message Types
Common Message Properties
| Arguments | |
|---|---|
| role required |
The role of the message, appMaker or appUser. |
| type required |
The type of the message. |
| metadata optional |
Flat object containing any custom properties associated with the message. See metadata for more information. |
Text
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-H 'content-type: application/json' \
--user 'keyId:keySecret' \
-d '
{
"role": "appMaker",
"type": "text",
"text": "Hello!",
"metadata": {
"lang": "en-ca",
"items": 3
},
"actions": [{
"text": "More info",
"type": "link",
"uri": "http://example.org",
"metadata": {
"buttonIntent": "more"
}
}]
}'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
role: 'appMaker',
type: 'text',
text: 'Hello!',
metadata: {
lang: 'en-ca',
items: 3
},
actions: [
{
text: 'More info',
type: 'link',
uri: 'http://example.org',
metadata: {
buttonIntent: 'moreInfo'
}
}
]
}
})
.then(() => {
// async code
});
Response:
201 CREATED
{
"message": {
"_id": "57966d21c19c9da00839a5e9",
"role": "appMaker",
"type": "text",
"metadata": {
"items": 3,
"lang": "en-ca"
},
"actions": [
{
"_id": "57966d22c19c9da00839a5ec",
"text": "More info",
"type": "link",
"uri": "http://example.org",
"metadata": {
"buttonIntent": "moreInfo"
}
}
]
}
}
201 CREATED
A text type message is a message that is sent with text and/or actions. See Common message properties for more information.
| Arguments | |
|---|---|
| text required* |
The text content of the message. Optional only if actions are provided. Maximum length of 4096 characters. |
| actions optional* |
Array of message actions. |
Image
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-H 'content-type: application/json' \
--user 'keyId:keySecret' \
-d '
{
"role": "appMaker",
"type": "image",
"text": "Hello!",
"mediaUrl": "http://example.org/image.jpg",
"altText": "A tasty pizza",
"actions": [{
"text": "More info",
"type": "link",
"uri": "http://example.org"
}]
}'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
role: 'appMaker',
type: 'image',
text: 'Hello!',
altText: 'A tasty pizza',
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,
"altText": "A tasty pizza",
"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 | |
|---|---|
| mediaUrl required |
The image URL used for the image message. |
| text optional |
The text content of the message. Maximum length of 4096 characters. |
| altText optional |
An optional description of the image for accessibility purposes. The field will be saved by default with the file name as the value. |
| actions optional |
Array of message actions. |
File
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-H 'content-type: application/json' \
--user 'keyId:keySecret' \
-d '
{
"role": "appMaker",
"type": "file",
"mediaUrl": "http://example.org/document.pdf",
"altText": "Summary of your order",
}'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
role: 'appMaker',
type: 'file',
mediaUrl: 'http://example.org/document.pdf',
altText: 'Summary of your order'
}
})
.then(() => {
// async code
});
Response:
201 CREATED
{
"message": {
"_id": "57966d21c19c9da00839a5e9",
"role": "appMaker",
"type": "file",
"mediaUrl": "http://example.org/document.pdf",
"mediaType": "application/pdf",
"mediaSize": 143212,
"altText": "Summary of your order"
}
}
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 Sunshine Conversations before sending the message. See Common message properties for more information.
| Arguments | |
|---|---|
| mediaUrl required |
The URL of the file attachment. |
| text optional |
Accompanying text or a description of the file. Maximum length of 4096 characters. |
| altText optional |
An optional description of the file for accessibility purposes. The field will be saved by default with the file name as the value. |
Location
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-H 'content-type: application/json' \
--user 'keyId:keySecret' \
-d '
{
"role": "appUser",
"type": "location",
"coordinates": {
"lat": 45.5261583,
"long": -73.595346
},
"location": {
"address": "5333 avenue Casgrain",
"name": "Zendesk Montréal"
}
}'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
role: 'appUser',
type: 'location',
coordinates: {
lat: 45.5261583,
long: -73.595346
},
location: {
address: '5333 avenue Casgrain',
name: 'Zendesk Montréal'
}
}
})
.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
},
"location": {
"address": "5333 avenue Casgrain",
"name": "Zendesk Montréal"
}
"role": "appUser",
"_id": "5887c22356c66904009ad602",
"source": {
"type": "messenger"
}
}
}
201 CREATED
A location type message includes the coordinates (latitude and longitude) of a location and an optional location object which can include the name and address of the 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. |
| location optional |
Information about the location. See Location Information. |
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. |
Location Information
| Arguments | |
|---|---|
| address optional |
A string representing the address of the location. |
| name optional |
A string representing the name of the location. |
Carousel
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-H 'content-type: application/json' \
--user 'keyId:keySecret' \
-d '
{
"role": "appMaker",
"type": "carousel",
"items": [{
"title": "Tacos",
"description": "Description",
"mediaUrl": "http://example.org/image.jpg",
"actions": [{
"text": "Select",
"type": "postback",
"payload": "TACOS"
}, {
"text": "More info",
"type": "link",
"uri": "http://example.org"
}]
}, {
"title": "Ramen",
"description": "Description",
"mediaUrl": "http://example.org/image.jpg",
"actions": [{
"text": "Select",
"type": "postback",
"payload": "RAMEN"
}, {
"text": "More info",
"type": "link",
"uri": "http://example.org"
}]
}]
}'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
role: 'appMaker',
type: 'carousel',
items: [
{
title: 'Tacos',
description: 'Description',
mediaUrl: 'http://example.org/image.jpg',
actions: [
{
text: 'Select',
type: 'postback',
payload: 'TACOS'
},
{
text: 'More info',
type: 'link',
uri: 'http://example.org'
}
]
},
{
title: 'Ramen',
description: 'Description',
mediaUrl: 'http://example.org/image.jpg',
actions: [
{
text: 'Select',
type: 'postback',
payload: 'RAMEN'
},
{
text: 'More info',
type: 'link',
uri: 'http://example.org'
}
]
}
]
}
})
.then(() => {
// async code
});
Response:
201 CREATED
{
"message": {
"_id": "57966d21c19c9da00839a5e9",
"role": "appMaker",
"type": "carousel",
"items": [
{
"_id": "57966d21c19c9da00839a5ea",
"title": "Tacos",
"description": "Description",
"mediaUrl": "http://example.org/image.jpg",
"mediaType": "image/jpeg",
"actions": [
{
"_id": "57966d22c19c9da00839a5eb",
"text": "Select",
"type": "postback",
"payload": "TACOS"
},
{
"_id": "57966d22c19c9da00839a5ec",
"text": "More info",
"type": "link",
"uri": "http://example.org"
}
]
},
{
"_id": "57966d22c19c9da00839a5ed",
"title": "Ramen",
"description": "Description",
"mediaUrl": "http://example.org/image.jpg",
"mediaType": "image/jpeg",
"actions": [
{
"_id": "57966d31c19c9da00839a5ee",
"text": "Select",
"type": "postback",
"payload": "RAMEN"
},
{
"_id": "57966d31c19c9da00839a5ef",
"text": "More info",
"type": "link",
"uri": "http://example.org"
}
]
}
]
}
}
201 CREATED
Carousel messages are a horizontally scrollable set of items that may each contain text, an image, and message actions. Not all messaging channels fully support carousel messages; currently only Facebook Messenger, LINE, Telegram, Viber, the Web Messenger, the Android SDK and the iOS SDK cover the full functionality. For all other platforms a carousel message is rendered as raw text. The raw text fallback does not include any images or postback message actions. See Common message properties for more information.
| Arguments | |
|---|---|
| items required |
Array of message items. The array is limited to 10 items. |
| displaySettings optional |
Settings to adjust the carousel layout. See Display Settings. |
Display Settings
A business can modify a carousel message layout by including an optional displaySettings object. Supported settings are:
| Arguments | |
|---|---|
| imageAspectRatio optional |
Specifies how to display all carousel images. Valid values are horizontal (default) and square. |
Channel Support
Sunshine Conversations 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 Sunshine Conversations 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' \
--user 'keyId:keySecret' \
-d '
{
"role": "appMaker",
"type": "list",
"items": [
{
"title": "Tacos",
"description": "Beef and cheese... Mhm...",
"size": "large",
"mediaUrl": "https://www.tacojohns.com/globalassets/2016-tacos-menu/taco-bravo---436x420.jpg",
"actions": [
{
"text": "Oh yeah!",
"type": "postback",
"payload": "TACOS"
}
]
},
{
"title": "Burritos",
"description": "Beefier and cheesier... Mhm...",
"mediaUrl": "http://www.tacobueno.com/media/1381/beefbob.png?quality=65",
"actions": [
{
"text": "Burritooo!",
"type": "postback",
"payload": "BURRITOS"
},
{
"text": "Burritooo!",
"type": "link",
"uri": "http://burritos.com",
"default": true
}
]
}
],
"actions": [
{
"text": "More Choices!",
"type": "postback",
"payload": "MORE"
}
]
}'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
role: 'appMaker',
type: 'list',
items: [
{
title: 'Tacos',
description: 'Beef and cheese... Mhm...',
size: 'large',
mediaUrl: 'https://www.tacojohns.com/globalassets/2016-tacos-menu/taco-bravo---436x420.jpg',
actions: [
{
text: 'Oh yeah!',
type: 'postback',
payload: 'TACOS'
}
]
},
{
title: 'Burritos',
description: 'Beefier and cheesier... Mhm...',
mediaUrl: 'http://www.tacobueno.com/media/1381/beefbob.png?quality=65',
actions: [
{
text: 'Burritooo!',
type: 'postback',
payload: 'BURRITOS'
},
{
text: 'Burritooo!',
type: 'link',
uri: 'http://burritos.com',
default: true
}
]
}
],
actions: [
{
text: 'More Choices!',
type: 'postback',
payload: 'MORE'
}
]
}
})
.then(() => {
// async code
});
Response:
201 CREATED
{
"message": {
"type": "list",
"role": "appMaker",
"received": 1480021430.242,
"text": "1. Tacos\nBeef and cheese... Mhm...\n\n\n2. Burritos\nBeefier and cheesier... Mhm...\nBurritooo!: http://burritos.com",
"authorId": "7AJ4zpAVxEwKkjCZD2EYKk",
"avatarUrl": "https://www.gravatar.com/avatar/5e543256c480ac577d30f76f9120eb74.png?s=200&d=mm",
"_id": "583755b6be483684d148602b",
"source": {
"type": "api"
},
"items": [
{
"title": "Tacos",
"description": "Beef and cheese... Mhm...",
"size": "large",
"mediaUrl": "https://www.tacojohns.com/globalassets/2016-tacos-menu/taco-bravo---436x420.jpg",
"mediaType": "image/jpeg",
"_id": "583755b6be483684d1486033",
"actions": [
{
"text": "Oh yeah!",
"payload": "TACOS",
"_id": "583755b6be483684d1486034",
"uri": "",
"type": "postback"
}
]
},
{
"title": "Burritos",
"description": "Beefier and cheesier... Mhm...",
"mediaUrl": "http://www.tacobueno.com/media/1381/beefbob.png?quality=65",
"mediaType": "image/png",
"_id": "583755b6be483684d1486030",
"actions": [
{
"text": "Burritooo!",
"payload": "BURRITOS",
"_id": "583755b6be483684d1486032",
"uri": "",
"type": "postback"
},
{
"text": "Burritooo!",
"default": true,
"_id": "583755b6be483684d1486031",
"uri": "http://burritos.com",
"type": "link"
}
]
}
],
"actions": [
{
"text": "More Choices!",
"payload": "MORE",
"_id": "583755b6be483684d1486035",
"uri": "",
"type": "postback"
}
]
},
"conversation": {
"unreadCount": 1,
"_id": "94eb1cd68c3e072a5ea0e242"
}
}
201 CREATED
List messages are a vertically scrollable set of items that may each contain text, an image, and message actions. Not all messaging channels fully support list messages. See Common message properties for more information.
- Facebook Messenger has native support.
- For LINE and our Android, iOS and Web SDK, Sunshine Conversations converts list messages to carousel.
- On WhatsApp, Telegram and Twitter, Sunshine Conversations converts list messages to multiple rich messages.
- On all other platforms, Sunshine Conversations 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
Sunshine Conversations 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 Sunshine Conversations 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.
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.
Form
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-H 'content-type: application/json' \
-H "authorization: Bearer your-account-jwt" \
-d '
{
"role": "appMaker",
"type": "form",
"blockChatInput": true,
"fields": [
{
"type": "text",
"name": "full_name",
"label": "Your name?",
"placeholder": "Type your name...",
"minSize": 1,
"maxSize": 30
},
{
"type": "email",
"name": "email_address",
"label": "Your email?",
"placeholder": "email@example.com"
},
{
"type": "select",
"name": "meal_selection",
"label": "Your meal?",
"options": [
{
"name": "pizza",
"label": "Pizza"
},
{
"name": "tacos",
"label": "Tacos"
},
{
"name": "ramen",
"label": "Ramen"
}
]
}
]
}'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
role: "appMaker",
type: "form",
blockChatInput: true
fields: [
{
type: "text",
name: "full_name",
label: "Your name?",
placeholder: "Type your name...",
minSize: 1,
maxSize: 30
},
{
type: "email",
name: "email_address",
label: "Your email?",
placeholder: "email@example.com"
},
{
type: "select",
name: "meal_selection",
label: "Your meal?",
options: [
{
name: "pizza",
label: "Pizza"
},
{
name: "tacos",
label: "Tacos"
},
{
name: "ramen",
label: "Ramen"
}
]
}
]
}
})
.then(() => {
// async code
});
Response:
201 CREATED
{
"message": {
"blockChatInput": true,
"fields": [
{
"type": "text",
"name": "full_name",
"label": "Your name?",
"placeholder": "Type your name...",
"minSize": 1,
"maxSize": 30,
"_id": "5cd09442d70f413fp1w2d0f9"
},
{
"type": "email",
"name": "email_address",
"label": "You email?",
"placeholder": "email@example.com",
"_id": "5cd09442d70f413fp1w2d0f0"
},
{
"type": "select",
"name": "meal_selection",
"label": "Your meal?",
"selectSize": 1,
"options": [
{
"name": "pizza",
"label": "Pizza",
"_id": "5cd09442d70f413fp1w2d0f1"
},
{
"name": "tacos",
"label": "Tacos",
"_id": "5cd09442d70f413fp1w2d0f2"
},
{
"name": "ramen",
"label": "Ramen",
"_id": "5cd09442d70f413fp1w2d0f3"
}
],
"_id": "5cd09442d70f413fp1w2d0f4"
}
],
"type": "form",
"role": "appMaker",
"received": 1557173314.465,
"authorId": "7AJ4zpAVxEwKkjCZD2EYKk",
"avatarUrl": "https://www.gravatar.com/avatar/00000000000000000000000000000000.png?s=200&d=mm",
"submitted": false,
"_id": "57966d21c19c9da00839a5e9",
"source": {
"type": "api"
}
},
"conversation": {
"_id": "94eb1cd68c3e072a5ea0e242",
"appMakerLastRead": 1557173314.465,
"appUserLastRead": 1557173271.843,
"unreadCount": 2
}
}
201 CREATED
A form type message without text or actions. See Common message properties for more information.
| Arguments | |
|---|---|
| blockChatInput optional |
Boolean indicating if the Web SDK chat input should be blocked. Defaults to false. |
| fields required |
Array of field objects to be completed. The array is limited to 100 fields. |
Channel Support
Sunshine Conversations forms are only supported on the Web Messenger.
Field
Fields are included in the fields array of a form type message to specify the fields to be completed.
| Arguments | |
|---|---|
| type required |
Specifies the type of field. Options are text, email, select. |
| name required |
Specifies the name of the field. Each field name must be unique per form. Maximum length of 128 characters. |
| label required |
Specifies what label the field will be displayed with. Maximum length of 128 characters. |
| placeholder optional |
Specifies the placeholder text of the field that will be rendered. Maximum length of 128 characters. |
| minSize optional |
Text field only. Specifies the minimum possible length of the response. Defaults to 1 if not specified. |
| maxSize optional |
Text field only. Specifies the maximum possible length of the response. Defaults to 128 if not specified. |
| options optional |
Select field only. Array of option objects that can be selected. The array is limited to 20 options. |
Option
Options are included in the options array of a select type field to specify which options are available for selection.
| Arguments | |
|---|---|
| name required |
String specifying the name of the option. Field option name must be unique per field. Maximum length of 128 characters. |
| label required |
String specifying the label that the option will be displayed with on Web Messenger. Maximum length of 128 characters. |
Form Response
A formResponse type message is a response to a form type message. See Common message properties for more information.
| Arguments | |
|---|---|
| fields required |
Array of field objects that contain the submitted fields. |
| quotedMessage required |
Object indicating the form message that is being responded to. See quotedMessage for more details. |
Channel Support
formResponse type messages are only supported as responses to form messages on Web Messenger and cannot be sent via the API.
Response Field
Fields are found in the fields array of a formResponse type message. They contain the responses the user has inputted or selected.
| Arguments | |
|---|---|
| type required |
Specifies the type of field. Options are text, email, select. |
| name required |
Specifies the name of the field. |
| label required |
Specifies what label the field will be displayed with. |
| text optional |
Specifies the response for a text field. |
| email optional |
Specifies the response for a email field. |
| select optional |
Array specifying the selected option for a select field. |
Message Actions
Actions buttons can be sent through the post message API by including them in the message payload. There are many types of actions, each with its own abilities and limitations. See below for the payloads of each distinct action type. See Common message properties for more information.
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' \
--user 'keyId:keySecret'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
text: 'Just put some vinegar on it',
role: 'appMaker',
type: 'text',
actions: [
{
type: 'link',
text: 'Put vinegar',
uri: 'http://example.com'
}
]
}
})
.then(() => {
// async code
});
| Arguments | |
|---|---|
| text required |
The button text. |
| type required |
link |
| uri required |
The action URI. This is the link that will be used in the clients when clicking the button. |
| default optional |
Boolean value indicating whether the action is the default action for a message item in Facebook Messenger. |
| metadata optional |
Flat object containing any custom properties associated with the action. See the metadata schema for more information. |
| extraChannelOptions optional |
Extra options to pass directly to the channel API. See Extra Channel Options. |
Webview
When a webview actions is clicked/tapped, the provided URI will be loaded in a webview.
Channels that do not support webviews will open the fallback URI instead.
For a deep dive on how to use webviews, see our guide.
Send webview action:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-d '{"text":"Just put some vinegar on it", "role": "appMaker", "type": "text", "actions": [{"type": "webview", "text": "Put vinegar", "uri": "http://example.com", "fallback": "http://example-fallback.com" }]}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
text: 'Just put some vinegar on it',
role: 'appMaker',
type: 'text',
actions: [
{
type: 'webview',
text: 'Put vinegar',
uri: 'http://example.com',
fallback: 'http://example.com'
}
]
}
})
.then(() => {
// async code
});
| Arguments | |
|---|---|
| text required |
The button text. |
| type required |
webview |
| uri required |
The webview URI. This is the URI that will open in the webview when clicking the button. |
| fallback required |
The webview fallback URI. This is the link that will be opened in channels that do not support webviews. |
| size optional |
Controls the webview height. Possible values are compact, tall, and full. |
| default optional |
Boolean value indicating whether the action is the default action for a message item in Facebook Messenger. |
| metadata optional |
Flat object containing any custom properties associated with the action. See the metadata schema for more information. |
| extraChannelOptions optional |
Extra options to pass directly to the channel API. See Extra Channel Options. |
| openOnReceive optional |
Boolean value indicating if the webview should open automatically. Only one action per message can be set to true. Currently only supported on the Web Messenger. |
Buy
A buy action will prompt the user to purchase an item.
Send buy action:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-d '{"text":"Just put some vinegar on it", "role": "appMaker", "type": "text", "actions": [{"type": "buy", "text": "Buy vinegar", "amount": 1000 }]}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
text: 'Just put some vinegar on it',
role: 'appMaker',
type: 'text',
actions: [
{
type: 'buy',
text: 'Buy vinegar',
amount: 8000
}
]
}
})
.then(() => {
// async code
});
| Arguments | |
|---|---|
| text required |
The button text. |
| type required |
buy |
| amount required |
The amount being charged. It needs to be specified in cents and is an integer (9.99\$ -> 999). |
| currency optional |
The currency of the amount being charged (USD, CAD, etc.). If not specified, it would use the default one set in your account. See supported currencies. |
| metadata optional |
Flat object containing any custom properties associated with the action. See the metadata schema for more information. |
Postback
A postback action will post the action payload to the server when tapped.
Send postback action:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-d '{"text":"Just put some vinegar on it", "role": "appMaker", "type": "text", "actions": [{"type": "postback", "text": "Send vinegar", "payload": "buy_vinegar" }]}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
text: 'Just put some vinegar on it',
role: 'appMaker',
type: 'text',
actions: [
{
type: 'postback',
text: 'Buy vinegar',
payload: 'buy_vinegar'
}
]
}
})
.then(() => {
// async code
});
| Arguments | |
|---|---|
| text required |
The button text. |
| type required |
postback |
| payload required |
A string payload to help you identify the action context. You can also use metadata for more complex needs. |
| metadata optional |
Flat object containing any custom properties associated with the action. See the metadata schema for more information. |
Reply
A reply action will echo the user’s choice as a message.
You may optionally specify an iconUrl which will render as an icon for each option.
Send reply action:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f/messages \
-X POST \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
-d '
{
"text":"Which do you prefer?",
"role": "appMaker",
"type": "text",
"actions": [{
"type": "reply",
"text": "Tacos",
"iconUrl": "http://example.org/taco.png",
"payload": "TACOS"
}, {
"type": "reply",
"text": "Burritos",
"iconUrl": "http://example.org/burrito.png",
"payload": "BURRITOS"
}]
}'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
text: 'Which do you prefer?',
type: 'text',
role: 'appMaker',
actions: [
{
type: 'reply',
text: 'Tacos',
iconUrl: 'http://example.org/taco.png',
payload: 'TACOS'
},
{
type: 'reply',
text: 'Burritos',
iconUrl: 'http://example.org/burrito.png',
payload: 'BURRITOS'
}
]
}
})
.then(() => {
// async code
});
| Arguments | |
|---|---|
| text required |
The button text. Text longer than 20 characters will be truncated on Facebook Messenger, and longer than 40 characters will be truncated on Web Messenger, iOS, and Android. |
| type required |
reply |
| payload required |
A string payload to help you identify the action context. Used when posting the reply. You can also use metadata for more complex needs. |
| iconUrl optional |
An icon to render next to the reply option. |
| metadata optional |
Flat object containing any custom properties associated with the action. See the metadata schema for more information. |
Facebook Messenger
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' \
--user 'keyId:keySecret'
smooch.appUsers
.sendMessage({
appId: '5963c0d619a30a2e00de36b8',
userId: 'c7f6e6d6c3a637261bd9656f',
message: {
text: 'Where are you?',
role: 'appMaker',
type: 'text',
actions: [
{
type: 'locationRequest',
text: 'Send Location'
}
]
}
})
.then(() => {
// async code
});
| Arguments | |
|---|---|
| text required |
The button text. |
| type required |
locationRequest |
| metadata optional |
Flat object containing any custom properties associated with the action. See the metadata schema for more information. |
Extra Channel Options
For features that are not yet supported natively by the Sunshine Conversations 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 and postback actions are supported. |
| description optional |
The text description, or subtitle. |
| mediaUrl optional |
The image URL to be shown in the carousel/list item. When this parameter is included in requests, a valid media URL must be provided. |
| altText optional |
An optional description of the image for accessibility purposes. The field will be saved by default with the file name as the value. |
| size optional |
The size of the image to be shown in the carousel/list item (Only top item of Facebook Messenger carousel supported). Choose from compact and large. |
Schemas
Message schema
This table represents the fields you can expect to receive in a webhook payload’s message, or in the response to a GET Messages API call.
| Field | Description |
|---|---|
| _id | The unique ID for the message. |
| type | "text", "image", "file", "carousel", "location", "list", "form", or "formResponse". |
| text | The message text. |
| role | The role of the message sender. "appUser", "appMaker", or "whisper". |
| subroles | An array of strings that indicates the author’s subtypes. Messages with the "appMaker" role that includes "AI" will assume that an AI generated the message and will postfix a disclaimer to the message text sent to the customer. For 3rd party channels, the disclaimer is applied for "text", "image", and "file" message types. |
| 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 Sunshine Conversations received the message. |
| source | A nested object describing the source of the message. See the source schema below for details. |
| quotedMessage optional | The quoted message, currently only available for WhatsApp and Web Messenger formResponse messages. See the quoted message schema below for details. |
| avatarUrl optional | The URL for an image of the appMaker. |
| actions optional | An array of objects representing the actions associated with the message. See the action schema below for details. The array length is limited by the third party channel. See the Action Buttons guide for more details. |
| items optional | An array of objects representing the items associated with the message. Only present in carousel and list type messages. See the item schema below for details. |
| mediaUrl optional | The URL for media, such as an image, attached to the message. |
| mediaType optional | The MIME type for any media attached in the mediaUrl. |
| mediaSize optional | The size (in bytes) for any media attached in the mediaUrl. This will only be provided when available. |
| coordinates optional | A nested object describing the coordinates sent by an appUser. Only present in a "location" type message. See the coordinates schema below for details. |
| deleted optional | true if the message serves as a placeholder for one that has been deleted. |
| fields optional | An array of objects representing fields associated with the message. Only present in form and formResponse messages. See the field schema below for details. |
| submitted optional | true if a response has been submitted. form message only. |
| blockChatInput optional | true if the message should block the chat input on Web Messenger. form message only. |
| payload optional | The payload of a reply button response message. |
| metadata optional | Flat object containing any custom properties associated with the message. See metadata for more information. |
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. |
| metadata optional | Flat object containing custom properties. Strings, numbers and booleans are the only supported format that can be passed to metadata. The metadata is limited to 4KB in size. |
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", "notification", or any other channel. |
| id optional | An identifier used by Sunshine Conversations for internal purposes. |
| destinationId optional | Identifier indicating destination the message was sent to. |
| correctedDestinationId optional | Identifier indicating corrected destination (phone number) the message was sent to. For WhatsApp messages only. |
| integrationId optional | Identifier indicating which integration the message was sent from. For appUser messages only. |
| originalMessageId optional | Message identifier assigned by the originating channel. Only available for the source schema. |
| originalMessageTimestamp optional | Message timestamp assigned by the originating channel. Only available for the source schema. |
Coordinates schema
Data representing a location sent by the appUser.
| Field | Description |
|---|---|
| _id | The unique ID of the coordinates item. |
| lat | Global latitude. |
| long | Global longitude. |
Action schema
This table represents the fields you can expect to receive nested inside postback or message data, in a webhook payload, or in the response to a GET Messages API call.
| Field | Description |
|---|---|
| _id | A canonical ID. |
| type | link, reply, postback, locationRequest, buy or webview. |
| uri optional | The URI for a link type action, a checkout page for buy type actions. May also be an empty string. |
| text optional | The button text. |
| payload optional | The payload of a postback or reply button. |
| amount optional | An integer representing an amount of money in hundredths of a dollar (or equivalent in other currencies). Used for actions of type buy. |
| currency optional | An ISO 4217 standard currency code in lowercase. Used for actions of type buy. |
| state optional | The value offered, or paid representing the payment status of a buy type action. |
| default optional |
Boolean value indicating whether the action is the default action for a message item in Facebook Messenger. Used for actions of type link. |
| metadata optional |
Flat object containing any custom properties associated with the action. See the metadata schema for more information. |
| extraChannelOptions optional |
Extra options to pass directly to the channel API. See Extra Channel Options. |
| iconUrl optional |
An icon to render alongside the action text. Used for actions of type reply. |
| size optional |
The size to display a webview. Used for actions of type webview. |
| fallback optional |
The fallback uri for channels that don’t support webviews. Used for actions of type webview. |
Item schema
This table represents the fields you can expect to receive nested inside message data, in a webhook payload, or in the response to a GET Messages API call.
| Field | Description |
|---|---|
| _id | A canonical ID. |
| title | The title of the item. |
| description optional |
The description of the item. |
| mediaUrl optional |
The image url attached to the item. |
| mediaType optional |
The MIME type for any image attached in the mediaUrl. |
| size optional |
The size of the image. compact or large. |
| actions | An array of objects representing the actions associated with the item. At least 1 is required, a maximum of 3 are allowed. See the action schema for details. |
| metadata optional |
Flat object containing any custom properties associated with the action. See the metadata schema for more information. |
Quoted message schema
This table represents the fields you can expect to receive inside quotedMessage data.
| Field | Description |
|---|---|
| type | The type of quotedMessage. Can be either message, when a complete Sunshine Conversations message can be provided, or externalMessageId if no Sunshine Conversations message matched the quoted message. |
| externalMessageId | The external message Id of the quoted message. Only available when type is externalMessageId. |
| content optional |
The Sunshine Conversations message corresponding to the quoted message, only available if type is message. |
Referral schema
Data representing a referral object when a user is referred to a conversation via a Messenger code, clicking a conversion ad on Facebook, using a Telegram bot deep link, using Viber bot deep link or scanning a parametric QR code event on WeChat.
| Field | Description |
|---|---|
| code | The referral’s identifier. Available in referrals from WeChat, Telegram, Viber 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 or PUT API call containing additional properties associated with the message or app. The metadata is limited to 4KB in size. In the case of messages, the 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. Updating the metadata is not additive; all the fields omitted will be deleted.
Field schema
This table represents the properties you can expect to receive inside a form or formResponse message field.
| Field | Description |
|---|---|
| _id | A canonical ID. |
| type | The field type. Either text, email, or select. |
| name | The name of the field. Must be unique per form or formResponse. |
| label | The label of the field. What the field is displayed as on Web Messenger |
| placeholder optional | Placeholder text for the field. form message only. |
| minSize optional | The minimum allowed length for the response for a field of type text. form message only. |
| maxSize optional | The maximum allowed length for the response for a field of type text. form message only. |
| options optional | Array of objects representing options for a field of type select. form message only. See the option schema for more details. |
| text optional | The user response for a field of type text. form and formResponse messages only. |
| email optional | The user response for a field of type email. form and formResponse messages only. |
| select optional | An array of objects representing the response for a field of type select. form and formResponse messages only. |
Option schema
This table represents the properties you can expect to receive inside a field option.
| Field | Description |
|---|---|
| label | The label of the option. What the option is displayed as on Web Messenger. |
| name | The name of the field. Must be unique per field. |
Persistent Menus
Sunshine Conversations 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. If you plan on having more than 25 integrations in your app, the per-integration endpoints should be used.
Get App Menu
Request:
curl $SMOOCH_ROOT/v1.1/apps/5963c0d619a30a2e00de36b8/menu \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.menu.get('5963c0d619a30a2e00de36b8', '5963c0d619a30a2e00de36b8').then(() => {
// async code
});
Response:
200 OK
{
"menu": {
"items": [
{
"type": "link",
"text": "Sunshine Conversations",
"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": "Sunshine Conversations", "uri": "http://smooch.io"}]}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.menu
.configure('5963c0d619a30a2e00de36b8', {
items: [
{
type: 'link',
text: 'Sunshine Conversations',
uri: 'http://smooch.io'
}
]
})
.then(() => {
// async code
});
Response:
200 OK
{
"menu": {
"items": [
{
"type": "link",
"text": "Sunshine Conversations",
"uri": "http://smooch.io",
"_id": "57b331fbf1c6aeba1f940dc7"
}
]
}
}
PUT /v1.1/apps/{appId}/menu
Configure the specified app’s menu. See the persistent menu schema for possible options.
Delete App Menu
Request:
curl $SMOOCH_ROOT/v1.1/menu \
-X DELETE \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.menu.remove('5963c0d619a30a2e00de36b8').then(() => {
// async code
});
Response:
200 OK
{
"menu": {
"items": []
}
}
DELETE /v1.1/apps/{appId}/menu
Remove the specified app’s menu.
Get Integration Menu
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/menu \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations.menu.get('55c8d9758590aa1900b9b9f6', '5735dded48011972d621dc02').then(() => {
// async code
});
Response:
200 OK
{
"menu": {
"items": [
{
"type": "link",
"text": "Sunshine Conversations",
"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": "Sunshine Conversations", "uri": "http://smooch.io"}]}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations.menu
.update('55c8d9758590aa1900b9b9f6', '5735dded48011972d621dc02', {
items: [
{
type: 'link',
text: 'Sunshine Conversations',
uri: 'http://smooch.io'
}
]
})
.then(() => {
// async code
});
Response:
200 OK
{
"menu": {
"items": [
{
"type": "link",
"text": "Sunshine Conversations",
"uri": "http://smooch.io",
"_id": "57b331fbf1c6aeba1f940dc7"
}
]
}
}
PUT /v1.1/apps/{appId}/integrations/{integrationId}/menu
Set the specified integration’s menu, overriding the app menu if configured. See the persistent menu schema for possible options.
Delete Integration Menu
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/menu \
-X DELETE \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations.menu.delete('55c8d9758590aa1900b9b9f6', '5735dded48011972d621dc02').then(() => {
// async code
});
Response:
200 OK
{}
DELETE /v1.1/apps/{appId}/integrations/{integrationId}/menu
Remove the specified integration’s menu, falling back to the app menu if configured.
Schema
Persistent Menu Schema
| Arguments | |
|---|---|
| items required |
A list of menu items. See menu items for more detail. |
| settings optional |
An optional object for menu settings. See menu settings for more detail. |
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 Sunshine Conversations’ 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.
The supported integration types are outlined in the Integration Schemas section.
Sunshine Conversations exposes REST API methods to:
- Create integration
- List integrations
- Get integration
- Update integration
- Get integration profile
- Update integration profile
- Upload integration profile photo
- 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 Integration Schemas for channel specific instructions.
List Integrations
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
--user 'keyId:keySecret'
smooch.integrations.list({ appId: '55c8d9758590aa1900b9b9f6' }).then((response) => {
// async code
});
Response:
200 OK
{
"integrations": [
{
"_id": "582dedf230e788746891281a",
"type": "messenger",
"pageId": "841556169307254",
"appId": "1674554616147204",
"status": "active",
"displayName": "Friendly octopus"
},
{
"_id": "5735ddf948011972d621dc08",
"type": "twilio",
"phoneNumberSid": "PN0674df0ecee0c9819bca0ff0bc0a159e",
"phoneNumber": "+15146125236",
"name": "Mike's Account",
"accountSid": "ACa1b4c65ee0722712fab89867cb14eac7",
"status": "active"
},
{
"_id": "5735ddfb48011972d621dc09",
"type": "telegram",
"username": "mikes_smooch_bot",
"status": "active"
},
{
"_id": "5735ddfd48011972d621dc0a",
"type": "line",
"mid": "uf0c0bc1813d372ac5af4c5b5faee9923",
"channelId": "1462776483",
"botName": "Mike Bot",
"status": "active"
}
],
"hasMore": false,
"offset": 0
}
GET /v1.1/apps/{appId}/integrations
Lists all integrations for a given app. This API is paginated. It returns a maximum of 25 integrations by default, and accepts offset and limit query parameters. The maximum limit is 100.
| Parameter | Description |
|---|---|
types |
String, the list can be filtered to return only integrations of a specific type. More than one value can be specified through comma separation e.g. ?types=twilio,line |
limit |
Integer, the number of records to return (maximum 100, default 25). |
offset |
Integer, the number of initial records to skip before picking records to return. |
Integrations response properties
Each integration will return a set of common properties along with properties specific to its type, see Integrations for more info about properties for a specific type. Common properties are:
| Field | Description |
|---|---|
| _id | The integration ID. |
| type | The integration type. See integrations for a list of supported types. |
| status | The integration status. Possible values are active, inactive or error. More info. |
| displayName | The integration display name. Omitted if empty. |
Integration status
| Status | Description |
|---|---|
| active | The integration is working correctly. |
| inactive | Additional action is required before this integration can be considered active. Examples are a messenger integration without a page selected or a wechat integration for which Sunshine Conversations hasn’t received a webhook ping from WeChat. See integrations for detailed steps on how to integrate each channel. |
| error | Sunshine Conversations received an unexpected error from the channel and should be reviewed. |
Get Integration
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02 \
--user 'keyId:keySecret'
smooch.integrations
.get({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '5735dded48011972d621dc02'
})
.then((response) => {
// async code
});
Response:
200 OK
{
"integration": {
"_id": "582dedf230e788746891281a",
"type": "messenger",
"pageId": "841556169307254",
"appId": "1674554616147204",
"status": "active"
}
}
GET /v1.1/apps/{appId}/integrations/{integrationId}
Return the specified integration.
Update Integration
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/582dedf230e788746891281a \
-X PUT \
-d '{ "displayName": "A human-friendly name" }' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.update({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '582dedf230e788746891281a',
props: {
displayName: 'A human-friendly name'
}
})
.then((response) => {
// async code
});
Response:
200 OK
{
"integration": {
"_id": "582dedf230e788746891281a",
"displayName": "A human-friendly display name",
"status": "active",
"type": "whatsapp",
"baseUrl": "https://15144441919.whatsapp.ec.url",
"hsmFallbackLanguage": "fr_CA",
"username": "smooch",
"phoneNumber": "15144441919"
}
}
PUT /v1.1/apps/{appId}/integrations/{integrationId}
The Update Integration endpoint allows you to update active integrations. Some channels allow you to update more properties (see sections below). If updating a specific property is not supported, you must delete the integration and re-create it with the new data.
3rd party channels
The display name can be updated for any integration type, except for FCM, APN and the Web Messenger:
| Arguments | |
|---|---|
| displayName | A human-friendly name used to identify the integration. Maximum of 100 characters. May be unset with null or ''. |
LINE
Request:
curl $SMOOCH_ROOT/v.1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735ddfd48011972d621dc0a \
-X PUT \
-d '{ "qrCodeUrl": "https://qr-official.line.me/M/1O4fb8.png" }' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.update({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '5735ddfd48011972d621dc0a',
props: {
qrCodeUrl: 'https://qr-official.line.me/M/1O4fb8.png'
}
})
.then((response) => {
// async code
});
Response:
200 OK
{
"integration": {
"_id": "5735ddfd48011972d621dc0a",
"type": "line",
"status": "active",
"channelId": "1286564967",
"qrCodeUrl": "https://qr-official.line.me/M/1O4fb8.png",
"lineId": "104fb8"
}
}
LINE integration QR code URLs can be updated or removed.
| Arguments | |
|---|---|
| qrCodeUrl | URL provided by LINE in the Developer Console. May be unset with ''. |
Web Messenger
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/582dedf230e788746891281a \
-X PUT \
-d '{ "integrationOrder": ["59fc8466260f48003505228b", "59d79780481d34002b7d3617"], "originWhitelist": ["https://yourdomain.com"], "businessName": "Shoplifter", "brandColor": "00ff00", "fixedIntroPane": true, "conversationColor": "dd00ee", "actionColor": "eeff00", "displayStyle": "button", "prechatCapture": { "enabled": true, "enableEmailLinking": true, "fields": [ { "type": "email", "name": "email", "label": "Email", "placeholder": "your@email.com" }, { "type": "text", "name": "company-website", "label": "Company website", "placeholder": "mycompany.com" }, { "type": "select", "name": "company-size", "label": "Company size", "placeholder": "Choose a number...", "options": [ { "name": "1-10", "label": "1-10 employees" }, { "name": "11-50", "label": "11-50 employees" }, { "name": "51+", "label": "51+ employees" } ] } ] } }' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.update({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '582dedf230e788746891281a',
props: {
integrationOrder: ['59fc8466260f48003505228b', '59d79780481d34002b7d3617'],
originWhitelist: ['https://yourdomain.com'],
businessName: 'Shoplifter',
brandColor: '00ff00',
fixedIntroPane: true,
conversationColor: 'dd00ee',
backgroundImageUrl: 'https://a-beautiful-tile.png',
actionColor: 'eeff00',
displayStyle: 'button',
prechatCapture: {
avatarUrl: 'http://domain.com/images/avatar.png',
enabled: true,
enableEmailLinking: true,
fields: [
{
type: 'email',
name: 'email',
label: 'Email',
placeholder: 'your@email.com'
},
{
type: 'text',
name: 'company-website',
label: 'Company website',
placeholder: 'mycompany.com'
},
{
type: 'select',
name: 'company-size',
label: 'Company size',
placeholder: 'Choose a number...',
options: [
{
name: '1-10',
label: '1-10 employees'
},
{
name: '11-50',
label: '11-50 employees'
},
{
name: '51+',
label: '51+ employees'
}
]
}
]
}
}
})
.then((response) => {
// async code
});
Response:
200 OK
{
"integration": {
"_id": "582dedf230e788746891281a",
"type": "web",
"integrationOrder": ["59fc8466260f48003505228b", "59d79780481d34002b7d3617"],
"originWhitelist": ["https://yourdomain.com"],
"businessName": "Shoplifter",
"brandColor": "00ff00",
"fixedIntroPane": true,
"conversationColor": "dd00ee",
"backgroundImageUrl": "https://a-beautiful-tile.png",
"actionColor": "eeff00",
"displayStyle": "button",
"status": "active",
"prechatCapture": {
"avatarUrl": "http://domain.com/images/avatar.png",
"enabled": true,
"enableEmailLinking": true,
"fields": [
{
"type": "email",
"name": "email",
"label": "Email",
"placeholder": "your@email.com"
},
{
"type": "text",
"name": "company-website",
"label": "Company website",
"placeholder": "mycompany.com"
},
{
"type": "select",
"name": "company-size",
"label": "Company size",
"placeholder": "Choose a number...",
"options": [
{
"name": "1-10",
"label": "1-10 employees"
},
{
"name": "11-50",
"label": "11-50 employees"
},
{
"name": "51+",
"label": "51+ employees"
}
]
}
]
}
}
}
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' \
--user 'keyId:keySecret'
smooch.integrations
.update({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '582dedf230e788746891281a',
props: {
hsmFallbackLanguage: 'fr_CA'
}
})
.then((response) => {
// async code
});
Response:
200 OK
{
"integration": {
"status": "active",
"type": "whatsapp",
"_id": "582dedf230e788746891281a",
"baseUrl": "https://15144441919.whatsapp.ec.url",
"hsmFallbackLanguage": "fr_CA",
"username": "smooch",
"phoneNumber": "15144441919"
}
}
See WhatsApp for more information about the arguments.
Using hsmFallbackLanguage (deprecated)
Get Integration Profile
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02/profile \
--user 'keyId:keySecret'
smooch.integrations.profile
.get({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '5735dded48011972d621dc02'
})
.then((response) => {
// async code
});
Response:
200 OK
{
"profile": {
"about": "Shoplifter is now on WhatsApp, come say hello! 👋",
"address": "1337 avenue Casgrain, Montréal (Québec) Canada",
"description": "ShopLifter helps you lift your shop.",
"email": "info@shoplifter.fun",
"vertical": "Shop Lifting",
"websites": ["https://shoplifter.fun"],
"photoUrl": "https://pps.whatsapp.net/my-image.jpg"
}
}
GET /v1.1/apps/{appId}/integrations/{integrationId}/profile
Return the specified integration profile.
Update Integration Profile
PUT /v1.1/apps/{appId}/integrations/{integrationId}/profile
The Update Integration Profile endpoint allows you to update the profile information of active integrations. See the sections below for channel specific instructions.
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/582dedf230e788746891281a/profile \
-X PUT \
-d '{ "about": "Shoplifter is now on WhatsApp, come say hello! 👋", "address": "1337 avenue Casgrain, Montréal (Québec) Canada", "description": "ShopLifter helps you lift your shop.", "email": "info@shoplifter.fun", "vertical": "Shop Lifting", "websites": [ "https://shoplifter.fun", "https://docs.shoplifter.fun" ], "photoUrl": "https://assets.brandfolder.com/b6k4f6zh/original/smooch_symbol_rgb.png" }' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations.profile
.update({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '582dedf230e788746891281a',
profile: {
about: 'Shoplifter is now on WhatsApp, come say hello! 👋',
address: '1337 avenue Casgrain, Montréal (Québec) Canada',
description: 'ShopLifter helps you lift your shop.',
email: 'info@shoplifter.fun',
vertical: 'Shop Lifting',
websites: ['https://shoplifter.fun', 'https://docs.shoplifter.fun'],
photoUrl: 'https://assets.brandfolder.com/b6k4f6zh/original/smooch_symbol_rgb.png'
}
})
.then((response) => {
// async code
});
Response:
200 OK
| Arguments | |
|---|---|
| about optional |
Text to display in your profile’s About section. Can be used as a status update. Maximum of 139 characters. |
| photoUrl optional |
URL where the business’ profile photo is hosted. WhatsApp recommends an image with dimensions of 640x640 and max size of 63KB. If you want to upload a photo directly, use the Upload Integration Profile Photo API. |
| address optional |
Address of the business. Maximum of 256 characters. Cannot be empty when provided. |
| description optional |
Description of the business. Maximum of 256 characters. Cannot be empty when provided. |
| email optional |
Email address to contact the business. Maximum of 128 characters. Use null or empty string to unset the value. |
| vertical optional |
Industry of the business. Maximum of 128 characters. Cannot be empty when provided. |
| websites optional |
URLs associated with the business. Maximum of 2 websites, each with a maximum of 256 characters. Must be an array. |
See our documentation on WhatsApp Business Profile for more information on the topic.
Upload Integration Profile Photo
PUT /v1.1/apps/{appId}/integrations/{integrationId}/profile/photo
The Upload Integration Profile Photo endpoint allows you to upload a photo to be used for your integration’s profile. While the Update Integration Profile endpoint does take in an optional photoUrl, this endpoint can be used when the photo is not publicly hosted.
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/582dedf230e788746891281a/profile/photo \
-X PUT \
-H 'content-type: multipart/form-data' \
-F 'source=@document.pdf;type=application/pdf'
--user 'keyId:keySecret'
// with a file or buffer
smooch.integrations.profile.photo
.update({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '582dedf230e788746891281a',
source: fileOrBuffer // File or Buffer
})
.then((response) => {
// async code
});
// with a file stream of known length
const formData = new FormData();
formData.append('source', fileStream, {
knownLength: data.contentLength
});
smooch.integrations.profile.photo
.update({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '582dedf230e788746891281a',
source: formData
})
.then((response) => {
// async code
});
Response:
200 OK
{
"photoUrl": "https://pps.whatsapp.net/my-image.jpg"
}
| Form Parameters | |
|---|---|
| source required |
The photo source, provided as a readable file buffer or stream. |
Delete Integration
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations/5735dded48011972d621dc02 \
-X DELETE \
--user 'keyId:keySecret'
smooch.integrations
.delete({
appId: '55c8d9758590aa1900b9b9f6',
integrationId: '5735dded48011972d621dc02'
})
.then((response) => {
// async code
});
Response:
200 OK
{}
DELETE /v1.1/apps/{appId}/integrations/{integrationId}
Removes the specified integration.
Integration Schemas
Apple Push Notifications
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "apn", "certificate": "HjkUD4rWvZj7wSDzA8Hu2hd7ICs274Z=="}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'apn',
certificate: 'HjkUD4rWvZj7wSDzA8Hu2hd7ICs274Z=='
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"type": "apn",
"_id": "58878a8842fadcdb7b70b74c",
"production": true,
"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. |
| production optional |
The APN environment to connect to (Production, if true, or Sandbox). true/false Defaults to value inferred from certificate if not specified. |
| autoUpdateBadge optional |
Use the unread count of the conversation as the application badge. true/false |
| canUserCreateMoreConversations optional |
Allow users to create more than one conversation on the Apple Push Notification integration. 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');
})
Apple Business Chat
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{ "type": "apple", "displayName": "Apple Business Chat", "businessId": "your_business_chat_id", "apiSecret": "your_apple_api_secret", "mspId": "your_apple_messaging_service_provider_id"
}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'apple',
businessId: 'your_business_chat_id',
apiSecret: 'your_apple_api_secret',
mspId: 'your_apple_messaging_service_provider_id'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "5f2c658de27df75eb42d7f33",
"status": "active",
"type": "apple",
"displayName": "ABC",
"businessId": "your_business_chat_id",
"mspId": "your_apple_messaging_service_provider_id",
"cspId": "your_apple_messaging_service_provider_id"
}
}
To configure an Apple Business Chat integration, acquire the required information and call the Create Integration endpoint.
| Arguments | |
|---|---|
| type required |
The integration type: apple. |
| businessId required |
Apple Business Chat ID |
| apiSecret required |
Your Apple API secret which is tied to your Messaging Service Provider. |
| mspId required |
Your Messaging Service Provider ID. |
| displayName optional |
A friendly name used to identify the integration. Defaults to ABC if not specified.Maximum of 100 characters. May be unset with null or ''. |
Facebook Messenger
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{ "type": "messenger", "pageAccessToken": "your_access_token", "appId": "your_fb_app_id", "appSecret": "your_fb_app_secret"
}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'messenger',
pageAccessToken: 'your_access_token',
appId: 'your_fb_app_id',
appSecret: 'your_fb_app_secret'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "582dedf230e788746891281a",
"type": "messenger",
"pageId": "841556169307254",
"appId": "1674554616147204"
}
}
Facebook Messenger setup steps:
- 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 Meta for app review with the “pages_manage_metadata” (to retrieve Page Access Tokens for the Pages and apps that the app user administers and to set a 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", "projectId": "your-project-34def", clientEmail: "firebase-adminsdk-0a1bc@your-project-34def.iam.gserviceaccount.com", "privateKey": "-----BEGIN PRIVATE KEY-----\nXYZ...-----END PRIVATE KEY-----\n" }' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'fcm',
projectId: 'your-project-id',
clientEmail: 'your-client-email',
privateKey: 'your-private-key'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "5876a3d4abf286d0c0af1467",
"type": "fcm",
"projectId": "your-project-34def",
"clientEmail": "firebase-adminsdk-0a1bc@your-project-34def.iam.gserviceaccount.com"
}
}
To configure a Firebase Cloud Messaging integration, first visit the Firebase Console.
Generate a private key from the Service accounts tab in the settings.
Copy the project_id, client_email and private_key from the generated JSON file and call the create integrations endpoint with this data.
| Arguments | |
|---|---|
| type required |
The integration type: fcm. |
| projectId required |
Your project ID from your generated private key file. |
| clientEmail required |
Your client email from your generated private key file. |
| privateKey required |
Your private key from your generated private key file. |
| serverKey deprecated |
Your server key from the fcm console. |
| senderId deprecated |
Your sender id from the fcm console. |
| canUserCreateMoreConversations optional |
Allow users to create more than one conversation on the Firebase Cloud Messaging integration. true/false |
Instagram Direct
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{ "type": "instagram", "pageAccessToken": "your_page_access_token", "appId": "your_fb_app_id", "appSecret": "your_fb_app_secret"
}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'instagram',
pageAccessToken: 'your_page_access_token',
appId: 'your_fb_app_id',
appSecret: 'your_fb_app_secret'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "5fa44add2582ba8058c10d8b",
"status": "active",
"type": "instagram",
"displayName": "Instagram Direct",
"appId": "223944225326121",
"pageName": "Instagram Page",
"businessId": "17841444303043201",
"pageId": "106731941223392"
}
}
Instagram Direct 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 Meta for app review with the “pages_manage_metadata” (to retrieve Page Access Tokens for the Pages and apps that the app user administers and to set a webhook), “instagram_basic”, and “instagram_manage_messages” (to retrieve basic Instagram account information and send messages) permissions.
In order to integrate an Instagram Direct 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 Facebook app ID and secret and the user’s page access token.
| Arguments | |
|---|---|
| type required |
The integration type: instagram. |
| 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 Instagram Direct if not specified.Maximum of 100 characters. May be unset with null or ''. |
LINE
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "line", "channelId": "1234567890", channelAccessToken": "lineChannelAccessToken", "channelSecret": "lineChannelSecret", "qrCodeUrl": "https://qr-official.line.me/M/1O4fb8.png"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'line',
channelId: '1234567890',
channelAccessToken: 'lineChannelAccessToken',
channelSecret: 'lineChannelSecret',
qrCodeUrl: 'https://qr-official.line.me/M/1O4fb8.png'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "5735ddfd48011972d621dc0a",
"type": "line",
"status": "active",
"channelId": "1286564967",
"displayName": "LINE",
"qrCodeUrl": "https://qr-official.line.me/M/1O4fb8.png",
"lineId": "104fb8"
}
}
For LINE, each of your customers will need to manually configure a webhook in their LINE configuration page that will point to Sunshine Conversations 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 optional |
LINE Channel ID. |
| channelSecret optional |
LINE Channel Secret. |
| channelAccessToken optional |
LINE Channel Access Token. |
| serviceCode optional |
LINE Service Code. |
| switcherSecret optional |
LINE Switcher Secret. |
| qrCodeUrl optional |
URL provided by LINE in the Developer Console. |
| lineId optional |
LINE Basic ID. Is automatically set when qrCodeUrl is updated. |
| displayName optional |
A human-friendly name used to identify the integration. Defaults to LINE if not specified.Maximum of 100 characters. May be unset with null or ''. |
Note: The channelId and channelSecret can be omitted to enable the niche use case of integrating LINE to setup a webhook before receiving the channelId and channelSecret back from LINE.
MessageBird
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "messagebird", "accessKey": "9V2iJmd93kFJ390L9495JCl11", "signingKey": "Uu6N09Lkdji3820DJIO89I39sl9dJ", "originator": "12262121021"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'messagebird',
accessKey: '9V2iJmd93kFJ390L9495JCl11',
signingKey: 'Uu6N09Lkdji3820DJIO89I39sl9dJ',
originator: '12262121021'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"type": "messagebird",
"webhookSecret": "72ade38394d1da51566cede33bd1e67e",
"originator": "12262121021",
"_id": "594850b82e4a8e5e04ef2a11"
}
}
To configure a MessageBird integration, acquire the accessKey, the signingKey and the MessageBird number you would like to use, then call the Create Integration endpoint. The response will include the integration’s _id and webhookSecret, which must be used to configure the webhook in MessageBird.
In the Flow Builder for the MessageBird number you’ve used to integrate, add a new step with the following settings:
- Create a new
Call HTTP endpoint with SMSflow. - Select your desired SMS number for
Incoming SMS. - Click on
Forward to URLand set its method toPOST. - Then, using the integration
_idandwebhookSecretreturned from the create integration call, enter the following into the URL field:https://app.smooch.io/api/messagebird/webhooks/{appId}/{integrationId}/{webhookSecret} - Select
application/jsonfor theSet Content-Type headerfield. - 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 |
Sunshine Conversations will receive all messages sent to this phone number. |
| displayName optional |
A human-friendly name used to identify the integration. Defaults to MessageBird SMS if not specified.Maximum of 100 characters. May be unset with null or ''. |
Telegram
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "telegram", "token": "192033615:AAEuee2FS2JYKWfDlTulfygjaIGJi4s"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'telegram',
token: '192033615:AAEuee2FS2JYKWfDlTulfygjaIGJi4s'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "5735ddfb48011972d621dc09",
"type": "telegram",
"username": "mikes_smooch_bot"
}
}
To configure a Telegram integration, acquire the required information from the user and call the Create Integration endpoint.
| Arguments | |
|---|---|
| type required |
The integration type: telegram. |
| token required |
Telegram Bot Token. |
| displayName optional |
A human-friendly name used to identify the integration. Defaults to Telegram if not specified.Maximum of 100 characters. May be unset with null or ''. |
Twilio
Using a Phone Number
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "twilio", "accountSid": "ACa1b4c65ee0722712fab89867cb14eac7", "authToken": "160c024303f53049e1e060fd67ca6aefc", "phoneNumberSid": "PN0674df0ecee0c9819bca0ff0bc0a159e"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'twilio',
accountSid: 'ACa1b4c65ee0722712fab89867cb14eac7',
authToken: '160c024303f53049e1e060fd67ca6aefc',
phoneNumberSid: 'PN0674df0ecee0c9819bca0ff0bc0a159e'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "5735ddf948011972d621dc08",
"type": "twilio",
"phoneNumberSid": "PN0674df0ecee0c9819bca0ff0bc0a159e",
"phoneNumber": "+15146125236",
"name": "Mike's Account",
"accountSid": "ACa1b4c65ee0722712fab89867cb14eac7"
}
}
To configure a Twilio integration with a phoneNumberSid, 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 ''. |
Using a Messaging Service
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "twilio", "accountSid": "ACa1b4c65ee0722712fab89867cb14eac7", "authToken": "160c024303f53049e1e060fd67ca6aefc", "messagingServiceSid": "MG9752274e9e519418a7406176694466fa"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'twilio',
accountSid: 'ACa1b4c65ee0722712fab89867cb14eac7',
authToken: '160c024303f53049e1e060fd67ca6aefc',
messagingServiceSid: 'MGba643a17bb629e4bd8ab4d537ee2800d'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "603ab6cd6f2fa0619daf36a6",
"type": "twilio",
"displayName": "Twilio SMS 2",
"name": "Mike's Account",
"messagingServiceName": "Mike's Messaging Service",
"accountSid": "ACa1b4c65ee0722712fab89867cb14eac7",
"messagingServiceSid": "MGba643a17bb629e4bd8ab4d537ee2800d"
}
}
To configure a Twilio integration with a messagingServiceSid, 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. |
| messagingServiceSid required |
SID for specific messaging service number. |
| displayName optional |
A human-friendly name used to identify the integration. Defaults to Twilio SMS if not specified.Maximum of 100 characters. May be unset with null or ''. |
Twitter DM
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{ "type": "twitter", "tier": "premium", "envName": "your_env_label", "consumerKey": "your_consumer_key", "consumerSecret": "your_consumer_secret", "accessTokenKey": "your_access_token_key", "accessTokenSecret": "your_access_token_secret" }' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'twitter',
tier: 'premium',
envName: 'your_env_label',
consumerKey: 'your_consumer_key',
consumerSecret: 'your_consumer_secret',
accessTokenKey: 'your_access_token_key',
accessTokenSecret: 'your_access_token_secret'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "58ecfde7e2aa9fda95fa122c",
"type": "twitter",
"tier": "premium",
"envName": "your_env_label",
"userId": "0000000000",
"username": "Mike Mikeson",
"accessTokenKey": "your_access_token_key",
"consumerKey": "your_consumer_key"
}
}
To set up a Twitter integration, please follow the steps outlined in the Twitter Setup Guide.
| Arguments | |
|---|---|
| type required |
The integration type: twitter. |
| tier required |
Your Twitter app’s tier, sandbox, premium or enterprise |
| envName optional |
The Twitter dev environments label (required for sandbox and premium tiers) |
| consumerKey required |
The consumer key for your Twitter app. |
| consumerSecret required |
The consumer key secret for your Twitter app. |
| accessTokenKey required |
The access token key obtained from your user via oauth. |
| accessTokenSecret required |
The access token secret obtained from your user via oauth. |
| displayName optional |
A human-friendly name used to identify the integration. Defaults to Twitter DM if not specified.Maximum of 100 characters. May be unset with null or ''. |
Viber
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "viber", "token": "df5f8c5233399561-92636b0c5ba30da9-16d4928fc004a72d"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'viber',
token: 'df5f8c5233399561-926...'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "5818fa177682fcb51368635d",
"type": "viber",
"uri": "MikesBusiness"
}
}
To configure a Viber integration, acquire the Viber Public Account token from the user and call the Create Integration endpoint.
| Arguments | |
|---|---|
| type required |
The integration type: viber. |
| token required |
Viber Public Account token. |
| displayName optional |
A human-friendly name used to identify the integration. Defaults to Viber if not specified.Maximum of 100 characters. May be unset with null or ''. |
Web Messenger
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{ "type": "web", "integrationOrder": ["59fc8466260f48003505228b", "59d79780481d34002b7d3617"], "originWhitelist": ["https://yourdomain.com"], "businessName": "Shoplifter", "brandColor": "00ff00", "conversationColor": "dd00ee", "actionColor": "eeff00", "displayStyle": "button", "buttonWidth": "90", "buttonHeight": "90", "fixedIntroPane": true }' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'web',
integrationOrder: ['59fc8466260f48003505228b', '59d79780481d34002b7d3617'],
businessName: 'Shoplifter',
brandColor: '00ff00',
fixedIntroPane: true,
conversationColor: 'dd00ee',
backgroundImageUrl: 'https://a-beautiful-tile.png',
actionColor: 'eeff00',
displayStyle: 'button',
buttonWidth: '90',
buttonHeight: '90',
prechatCapture: {
avatarUrl: 'http://domain.com/images/avatar.png',
enabled: true,
enableEmailLinking: false,
fields: [
{
type: 'email',
name: 'email',
label: 'Email',
placeholder: 'your@email.com'
},
{
type: 'text',
name: 'company-website',
label: 'Company website',
placeholder: 'mycompany.com'
},
{
type: 'select',
name: 'company-size',
label: 'Company size',
placeholder: 'Choose a number...',
options: [
{
name: '1-10',
label: '1-10 employees'
},
{
name: '11-50',
label: '11-50 employees'
},
{
name: '51+',
label: '51+ employees'
}
]
}
]
}
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "582dedf230e788746891281a",
"type": "web",
"integrationOrder": ["59fc8466260f48003505228b", "59d79780481d34002b7d3617"],
"originWhitelist": ["https://yourdomain.com"],
"businessName": "Shoplifter",
"brandColor": "00ff00",
"fixedIntroPane": true,
"conversationColor": "dd00ee",
"backgroundImageUrl": "https://a-beautiful-tile.png",
"actionColor": "eeff00",
"displayStyle": "button",
"buttonWidth": "90",
"buttonHeight": "90",
"status": "active",
"prechatCapture": {
"avatarUrl": "http://domain.com/images/avatar.png",
"enabled": true,
"enableEmailLinking": false,
"fields": [
{
"type": "email",
"name": "email",
"label": "Email",
"placeholder": "your@email.com"
},
{
"type": "text",
"name": "company-website",
"label": "Company website",
"placeholder": "mycompany.com"
},
{
"type": "select",
"name": "company-size",
"label": "Company size",
"placeholder": "Choose a number...",
"options": [
{
"name": "1-10",
"label": "1-10 employees"
},
{
"name": "11-50",
"label": "11-50 employees"
},
{
"name": "51+",
"label": "51+ employees"
}
]
}
]
}
}
}
To configure a Web Messenger integration, acquire the required information and call the Create Integration endpoint.
| Arguments | |
|---|---|
| type required |
The integration type: web. |
| brandColor optional |
This color will be used in the messenger header and the button or tab in idle state. Must be a 3 or 6-character hexadecimal color. Default value is 65758e. |
| fixedIntroPane optional |
When true, the introduction pane will be pinned at the top of the conversation instead of scrolling with it. Default value is false. |
| conversationColor optional |
This color will be used for customer messages, quick replies and actions in the footer. Must be a 3 or 6-character hexadecimal color. Default value is 0099ff. |
| actionColor optional |
This color will be used for call-to-actions inside your messages. Must be a 3 or 6-character hexadecimal color. Default value is 0099ff. |
| displayStyle optional |
Choose how the messenger will appear on your website. Must be either button or tab. Default value is button. |
| buttonIconUrl optional |
With the button style Web Messenger, you have the option of selecting your own button icon. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format. |
| buttonWidth optional |
With the button style Web Messenger, you have the option of specifying the button width. Default value is 58 |
| buttonHeight optional |
With the button style Web Messenger, you have the option of specifying the button height. Default value is 58 |
| integrationOrder optional |
Array of integration IDs, order will be reflected in the Web Messenger. When set, only integrations from this list will be displayed in the Web Messenger. If unset, all integrations will be displayed. |
| businessName optional |
A custom business name for the Web Messenger. |
| businessIconUrl optional |
A custom business icon url for the Web Messenger. The image must be at least 200 x 200 pixels and must be in either JPG, PNG, or GIF format. |
| backgroundImageUrl optional |
A background image url for the conversation. Image will be tiled to fit the window. |
| originWhitelist optional |
A list of origins to whitelist. When set, only the origins from this list will be able to initialize the Web Messenger. If unset, all origins are whitelisted. The elements in the list should follow the serialized-origin format from RFC 6454: scheme "://" host [ ":" port ], where scheme is http or https. |
| prechatCapture optional |
Object whose properties can be set to specify the add-on’s options. See the guide to learn more about Prechat Capture. |
| canUserCreateMoreConversations optional |
Allow users to create more than one conversation on the Web Messenger integration. true/false |
| canUserSeeConversationList optional |
Allow users to see the conversation list on the Web Messenger integration. true/false |
Prechat Capture
| Arguments | |
|---|---|
| avatarUrl optional |
String. Sets the URL of the avatar to use for the automatic reply to the prechat capture messages. Default value is undefined. |
| enabled optional |
Boolean. If true, enables the Prechat Capture add-on when the Web Messenger is initialized. Default value is false. |
| enableEmailLinking optional |
Boolean. If true and Mailgun is integrated, will automatically link submitted emails. Default value is false. |
| fields optional |
Array of Fields. Overrides the default Prechat Capture fields to define a custom form. Default value is undefined. |
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "wechat", "appId": "ACa1b4c65ee0722712fab89867cb14eac7", "appSecret": "160c024303f53049e1e060fd67ca6aefc"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'wechat',
appId: 'ACa1b4c65ee0722712fab89867cb14eac7',
appSecret: '160c024303f53049e1e060fd67ca6aefc'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"_id": "5735ddfd48011972d621dc0a",
"type": "wechat",
"appId": "c69175d6d125b772b",
"webhookSecret": "3889794ab2fd4a70940a97c4b4a6372e"
}
}
To configure a WeChat integration, browse to the Develop section of the WeChat dashboard and add the following IP addresses to the whitelist, separated by new lines. This must be done before calling the Create Integration endpoint.
34.224.190.28
52.6.201.31
52.0.232.16
34.246.106.80
34.246.57.194
From the same page, acquire the WeChat App ID and App Secret from the customer and call the Create Integration endpoint.
In their WeChat dashboard, the customer must set the “URL” field to https://app.smooch.io/api/wechat/webhooks/{smoochAppId}/{smoochIntegrationId}, and set the “Token” field to the value of the webhookSecret found in the response to the call to the Create Integration endpoint.
| Arguments | |
|---|---|
| type required |
The integration type: wechat. |
| appId required |
WeChat App ID. |
| appSecret required |
WeChat App Secret. |
| encodingAesKey optional |
AES Encoding Key. |
| displayName optional |
A human-friendly name used to identify the integration. Defaults to WeChat if not specified.Maximum of 100 characters. May be unset with null or ''. |
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "whatsapp", "deploymentId" : "55c8d9758590aa1900b9b9aa"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/integrations \
-X POST \
-d '{"type": "whatsapp", "baseUrl": "https://15144441919.whatsapp.ec.url", "username": "smooch", "password": "r0cks"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations
.create({
appId: '55c8d9758590aa1900b9b9f6',
props: {
type: 'whatsapp',
deploymentId: '55c8d9758590aa1900b9b9aa'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"integration": {
"status": "active",
"type": "whatsapp",
"_id": "8635ff3a619c1be3bdbafea7",
"baseUrl": "https://15144441919.whatsapp.ec.url",
"username": "smooch",
"phoneNumber": "15144441919"
}
}
To configure a WhatsApp integration, use your WhatsApp API Client connection information. Sunshine Conversations can provide WhatsApp API Client hosting for approved brands. See our WhatsApp guide for more details on WhatsApp API Client hosting.
Using Sunshine Conversations’ WhatsApp API Client hosting
| Arguments | |
|---|---|
| type required |
The integration type: whatsapp. |
| deploymentId required |
The Id of the deployment. The integrationId and the appId will be added to the deployment. Additionally, the deployment’s status will be set to integrated. |
| hsmFallbackLanguage (deprecated) 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. |
| accountId optional |
The business ID associated with the WhatsApp account. In combination with accountManagementAccessToken, it’s used for Message Template Reconstruction. |
| accountManagementAccessToken optional |
An access token associated with the accountId used to query the WhatsApp Account Management API. In combination with accountId, it’s used for Message Template Reconstruction. |
| displayName optional |
A human-friendly name used to identify the integration. Defaults to WhatsApp if not specified.Maximum of 100 characters. May be unset with null or ''. |
Using plain credentials (deprecated)
Using hsmFallbackLanguage (deprecated)
| Arguments | |
|---|---|
| type required |
The integration type: whatsapp. |
| baseUrl required |
The API client base url. |
| username required |
The API client username. |
| password required |
The API client password. |
| hsmFallbackLanguage optional |
Specify a fallback language to use when sending WhatsApp message template using the short hand syntax. Defaults to en_US. See WhatsApp documentation for more info. |
| displayName optional |
A human-friendly name used to identify the integration. Defaults to WhatsApp if not specified.Maximum of 100 characters. May be unset with null or ''. |
Deployments (deprecated)
This set of endpoints is used to create and manage WhatsApp API Client deployments.
Sunshine Conversations exposes REST API methods to:
- Create Deployment
- Activate Deployment
- Confirm Phone Number
- Get Deployment
- List Deployments
- Delete Deployment
- Backup Deployment
Create Deployment
Request:
curl $SMOOCH_ROOT/v1.1/whatsapp/deployments \
-X POST \
-d '{"hosting": "smooch"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.deployments.create({ hosting: 'smooch' }).then((response) => {
// async code
});
Response:
200 OK
{
"deployment": {
"_id": "59ba7c0b102fad002852f4fd",
"status": "starting",
"hosting": "smooch"
}
}
POST /v1.1/whatsapp/deployments
Allows you to create a WhatsApp API Client.
| Parameter | Type | Description |
|---|---|---|
| hosting required |
String | The type of hosting, smooch or self. This parameter will specify whether the API Client will be self hosted or hosted by Sunshine Conversations. |
| baseUrl optional |
String | Url of the API Client, only required for self hosted deployments. |
| username optional |
String | Username of the API Client, only required for self hosted deployments. |
| password optional |
String | Password of the API Client, only required for self hosted deployments. |
| callbackUrl optional |
String | This url will be called to notify you of updates that occur on the deployment. See Callback URL for more information. |
Activate Deployment
curl $SMOOCH_ROOT/v1.1/whatsapp/deployments/55c8d9758590aa1900b9b9f6/activate \
-X POST \
-d '{"phoneNumber": "+15146125236", "verifiedNameCertificate": "HjkUD4rWvZj7wSDzA8Hu2hd7ICs274Z==", "method": "voice"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.deployments
.activate({
deploymentId: '55c8d9758590aa1900b9b9f6',
phoneNumber: '+15146125236',
verifiedNameCertificate: 'HjkUD4rWvZj7wSDzA8Hu2hd7ICs274Z==',
method: 'voice'
})
.then((response) => {
// async code
});
Response:
200 OK
{
"deployment": {
"_id": "582dedf230e788746891281a",
"status": "pending",
"phoneNumber": "15145555555",
"hosting": "smooch"
}
}
POST /v1.1/whatsapp/deployments/{deploymentId}/activate
Allows you to register a valid phone number to your API Client.
| Parameter | Type | Description |
|---|---|---|
| phoneNumber required |
String | The phone number you are registering. This number should be coming from the WhatsApp Business Account(WABA). |
| verifiedNameCertificate required |
String | The verified name certificate. This certificate should be coming from the WhatsApp Business Account(WABA). |
| method required |
String | The method of receiving your registration code, either voice or sms. If you choose voice, a phone call will be made to the phoneNumber, otherwise a text message will be sent with the confirmation code. |
| pin optional |
String | The 6-digit 2FA PIN protecting the phone number from re-registration. This parameter is only needed for self hosted deployment when the phone number has already been registered. |
Confirm Phone Number
curl $SMOOCH_ROOT/v1.1/whatsapp/deployments/55c8d9758590aa1900b9b9f6/code/confirm \
-X POST \
-d '{"code": "123456"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.deployments
.confirmCode({
deploymentId: '55c8d9758590aa1900b9b9f6',
code: '123456'
})
.then((response) => {
// async code
});
Response:
200 OK
{
"deployment": {
"_id": "582dedf230e788746891281a",
"status": "registered",
"phoneNumber": "15145555555",
"hosting": "smooch"
}
}
POST /v1.1/whatsapp/deployments/{deploymentId}/code/confirm
Allows you to complete the registration process by confirming the code you received through the method chosen in the Activate Deployment endpoint. Once you have completed the registration process, you can use this deployment to create a WhatsApp integration, see WhatsApp integration schema for more information.
| Parameter | Type | Description |
|---|---|---|
| code required |
String | The code received through the method chosen in the Activate Deployment section. |
Get Deployment
curl $SMOOCH_ROOT/v1.1/whatsapp/deployments/55c8d9758590aa1900b9b9f6 \
--user 'keyId:keySecret'
smooch.deployments
.get({
deploymentId: '55c8d9758590aa1900b9b9f6'
})
.then((response) => {
// async code
});
Response:
200 OK
{
"deployment": {
"_id": "582dedf230e788746891281a",
"status": "pending",
"phoneNumber": "15145555555",
"hosting": "smooch"
}
}
GET /v1.1/whatsapp/deployments/{deploymentId}
Allows you to retrieve the information of a deployment. See deployment status for more information.
List Deployments
curl $SMOOCH_ROOT/v1.1/whatsapp/deployments \
--user 'keyId:keySecret'
smooch.deployments.list().then((response) => {
// async code
});
Response:
200 OK
{
"deployments": [
{
"_id": "582dedf230e788746891281a",
"status": "starting",
"hosting": "smooch"
},
{
"_id": "582dedf230e788746891281b",
"status": "registered",
"phoneNumber": "5141111111",
"hosting": "smooch"
},
{
"_id": "582dedf230e788746891281c",
"status": "unregistered",
"hosting": "smooch"
}
]
}
GET /v1.1/whatsapp/deployments/
Allows you to retrieve all the deployments associated to your account. See deployment status for more information.
Delete Deployment
curl $SMOOCH_ROOT/v1.1/whatsapp/deployments/55c8d9758590aa1900b9b9f6 \
-X DELETE \
--user 'keyId:keySecret'
smooch.deployments
.delete({
deploymentId: '55c8d9758590aa1900b9b9f6'
})
.then((response) => {
// async code
});
Response:
200 OK
{
"deployment": {
"_id": "582dedf230e788746891281a",
"status": "deleting",
"hosting": "smooch",
"phoneNumber": "15145555555",
"callbackUrl": "https://examples.com/awesomechat",
"callbackSecret": "aleCvbmPkvK2kDOsUispNXSd"
}
}
DELETE /v1.1/whatsapp/deployments/{deploymentId}
Allows you to delete a deployment. This will also delete the WhatsApp API client and put the associated phone number in an ‘offline’ state in the WhatsApp Business Account (WABA). The number can then be used at a later date to create another WhatsApp API client.
Backup Deployment
curl $SMOOCH_ROOT/v1.1/whatsapp/deployments/55c8d9758590aa1900b9b9f6/backup \
-X POST \
-d '{"password": "NXDnF76XY2cyFDJd"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
Response:
200 OK
{
"data": "ENCRYPTED_BACKUP",
"pin": "1234"
}
POST /v1.1/whatsapp/deployments/{deploymentId}/backup
Allows you to backup the configuration of your deployment.
| Parameter | Type | Description |
|---|---|---|
| password required |
String | The password to use when encrypting the data. Needs to be at least 12 characters. |
Deployment Status
The status of a deployment is updated as it moves through the creation and activation phases. Here are the possible statuses:
| Parameter | Description |
|---|---|
| starting | The initial status after calling the Create Deployment. |
| unregistered | The deployment status will be set to unregistered once it has been sucessfully deployed. |
| pending | The deployment status will be set to pending once you call the Activate Deployment with a new phone number. |
| registered | The deployment status will be set to registered once you call the Activate Deployment with a phone number that has already been confirmed, or if you call the Confirm Code. |
| deleting | The deployment status will be set to deleting once the Delete Deployment endpoint has been called. Once the deletion process is completed, the deployment is removed from the deployments list. |
| integrated | The deployment status will be set to integrated once the deploymentId is used to create a WhatsApp integration. |
Callback URL
The callback url specified in the Create Deployment endpoint will be called once the deployment has been deployed or deleted. Depending on the action, an event will be attached to the call, event:ready or event:deleted. See Secure Sunshine Conversations Webhooks for more information.
| Event | Description |
|---|---|
| ready | Called when the deployment is ready to be activated after you call the Create Deployment endpoint. |
| deleted | Called when the deployment status is successfully deleted after you call the Delete Deployment endpoint. |
WhatsApp Message Templates
Use these endpoints to manage WhatsApp Message Templates.
Sunshine Conversations exposes REST API methods to:
Create Message Template
Request:
curl $SMOOCH_ROOT/v1.1/apps/5ee8d14978eb23ee8c7673f8/integrations/5f11bbcacf4320b66dc26c2a/messageTemplates \
-X POST \
-d '{ "category":"UTILITY",
"name":"shipping_notification",
"language":"en_US" }' \
"components": [{"type": "BODY", "text": "Your order shipped!"}],
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations.messageTemplates
.create({
appId: '564f55ccc2aa7a2200db1e2a',
integrationId: '602aec4631d05a000c3536a4',
messageTemplate: {
category: 'MARKETING',
components: [{ type: 'BODY', text: 'This is my new template.' }],
name: 'new_template_test',
language: 'en_US',
allowCategoryChange: true
}
})
.then((response) => {
// async code
});
Response:
201 Created
{
"messageTemplate": {
"category": "UTILITY",
"name": "shipping_notification",
"language": "en_US",
"components": [{ "type": "BODY", "text": "Your order shipped!" }],
"status": "PENDING",
"id": "584875162392899"
}
}
POST v1.1/apps/{{appId}}/integrations/{{integrationId}}/messageTemplates
Create a message template.
| Arguments | |
|---|---|
| category required |
The category of message template. Please see the Message Templates section of Facebook’s Business Management API Documentation for the list supported categories. |
| name required |
The name of the message template with a maximum of 512 characters and only containing lowercase characters, numbers and underscores. |
| language required |
The language of the message template. Please see the Message Templates section of Facebook’s Business Management API Documentation for the list of supported languages. |
| components required |
An array of components that make up the message template. Please see Message Template Components for more information. |
| allowCategoryChange optional |
Set to true to allow Meta to automatically assign a category. If omitted, the template may be rejected due to miscategorization. Please see the Message Templates section of Facebook’s Business Management API Documentation for more information. |
List Message Templates
Request:
curl $SMOOCH_ROOT/v1.1/apps/5ee8d14978eb23ee8c7673f8/integrations/5f11bbcacf4320b66dc26c2a/messageTemplates \
-X GET \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations.messageTemplates
.list({
appId: '564f55ccc2aa7a2200db1e2a',
integrationId: '602aec4631d05a000c3536a4',
query: {
name: 'appointment',
before: 'NQZDZD',
limit: 5
}
})
.then((response) => {
// async code
});
Response:
200 OK
{
"messageTemplates": [
{
"name": "shipping_notification",
"components": [
{
"type": "BODY",
"text": "Your order shipped!"
}
],
"language": "en_US",
"status": "APPROVED",
"category": "UTILITY",
"id": "584875162392899"
}
],
"before": "MjUZD",
"after": "NDkZD"
}
GET v1.1/apps/{{appId}}/integrations/{{integrationId}}/messageTemplates
List all message templates.
| Parameter | Description |
|---|---|
name |
When specified, returns all the templates and translations which include it in their name. |
limit |
When specified, limits the number of message templates returned per page. |
before |
When specified, returns the message templates on the before page. (eg: MjUZD) |
after |
When specified, returns the message templates on the after page. (eg: NDkZD) |
previous |
Deprecated - use before instead |
next |
Deprecated - use after instead |
Delete Message Template
Request:
curl $SMOOCH_ROOT/v1.1/apps/5ee8d14978eb23ee8c7673f8/integrations/5f11bbcacf4320b66dc26c2a/messageTemplates/shipping_notification \
-X DELETE \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.integrations.messageTemplates
.delete({
appId: '564f55ccc2aa7a2200db1e2a',
integrationId: '602aec4631d05a000c3536a4',
messageTemplateName: 'blap'
})
.then((response) => {
// async code
});
Response:
200 OK
{}
DELETE v1.1/apps/{{appId}}/integrations/{{integrationId}}/messageTemplates/{{name}}
Delete a message template.
| Parameter | Description |
|---|---|
name |
The name of the message template to delete. |
Message Template Components
This section details the configuration for a message template component.
| Arguments | |
|---|---|
| type required |
The type of component. Must be one of the following values: BODY, HEADER, FOOTER, or BUTTONS. |
| format optional |
The format of the HEADER component. Must be one of the following: TEXT, IMAGE, DOCUMENT. Required only if the component’s type is HEADER. |
| text optional |
Text for the component. BODY text accepts a maximum of 1024 characters while HEADER and FOOTER text accepts a maximum of 60 characters. |
| buttons optional |
An array of buttons that make up the BUTTONS component. Please see Message Template Component Buttons for more information. |
Message Template Component Buttons
This section details the configuration for a message template component button.
| Arguments | |
|---|---|
| type required |
The type of component button. Must be one of the following values: QUICK_REPLY, PHONE_NUMBER, or URL. |
| phoneNumber optional |
The phoneNumber for a PHONE_NUMBER button. Required only if the buttons’s type is PHONE_NUMBER. |
| url optional |
The url for a URL button. Required only if the buttons’s type is URL. Add a {{1}} suffix to make the URL dynamic. |
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 Sunshine Conversations apps programmatically using Account Provisioning.
Authentication
Account Provisioning endpoints require account scope. See the authorization and authentication sections for information.
A user account API key (key id that starts with act_) can access all account provisioning routes. You can create an account key by going to your account page.
A service account API key (key id that starts with svc_) may be used to manage apps, but not service accounts or service account keys.
| Key Type | Authorized Methods |
|---|---|
| act | All Core and Account Provisioning methods. |
| svc | All Core methods, App Management methods, and App Keys methods. |
Service Accounts
Service Account schema and endpoints used for provisioning service accounts. A service account represents an API user, with its own set of credentials, that only has access to a certain subset of apps. For software makers that create apps on behalf of separate customers or businesses, service accounts can be used to generate and distribute credentials that only have access to a single business’ data.
Create Service Account
Request:
curl $SMOOCH_ROOT/v1.1/serviceaccounts \
-X POST \
-d '{"name": "My Service Account"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.serviceAccounts
.create({
name: 'My Service Account'
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"serviceAccount": {
"_id": "5a71d7419b3ad47012a5dde2",
"name": "My Service Account"
}
}
POST /v1.1/serviceaccounts
Creates a new service account. The response body will include the service account’s _id, which can be used to manage the service account’s API keys.
| Arguments | |
|---|---|
| name required |
A friendly name for the service account. Must be unique. |
List Service Accounts
Request:
curl $SMOOCH_ROOT/v1.1/serviceaccounts \
--user 'keyId:keySecret'
smooch.serviceAccounts.list().then((response) => {
// async code
});
Response:
200 OK
{
"serviceAccounts": [
{
"_id": "5a71d7419b3ad47012a5dde2",
"name": "My Service Account"
}
],
"hasMore": false,
"offset": 0
}
GET /v1.1/serviceaccounts
Lists all service accounts. This API is paginated. It returns a maximum of 25 service accounts by default, and accepts offset and limit query parameters. The maximum limit is 100.
| Parameter | Description |
|---|---|
limit |
Integer, the number of records to return (maximum 100, default 25). |
offset |
Integer, the number of initial records to skip before picking records to return. |
Get Service Account
Request:
curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2 \
--user 'keyId:keySecret'
smooch.serviceAccounts.get('5a71d7419b3ad47012a5dde2').then((response) => {
// async code
});
Response:
200 OK
{
"serviceAccount": {
"_id": "5a71d7419b3ad47012a5dde2",
"name": "My Service Account"
}
}
GET /v1.1/serviceaccounts/{serviceAccountId}
Fetches an individual service account.
Update Service Account
Request:
curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2 \
-X PUT \
-d '{"name": "My New Service Account"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.serviceAccounts
.update('5a71d7419b3ad47012a5dde2', {
name: 'My New Service Account'
})
.then((response) => {
// async code
});
Response:
200 OK
{
"serviceAccount": {
"_id": "5a71d7419b3ad47012a5dde2",
"name": "My New Service Account"
}
}
PUT /v1.1/serviceaccounts/{serviceAccountId}
Updates a service account.
| Arguments | |
|---|---|
| name required |
A friendly name for the service account. Must be unique. |
Delete Service Account
Request:
curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2 \
-X DELETE \
--user 'keyId:keySecret'
smooch.serviceAccounts.delete('5a71d7419b3ad47012a5dde2').then((response) => {
// async code
});
Response:
200 OK
{}
DELETE /v1.1/serviceaccounts/{serviceAccountId}
Removes the specified service account. A service account that still has access to one or more apps cannot be deleted - you must delete the apps first.
Schema
Service Account schema
The schema describes the fields you can expect to be associated with a service account.
| Field | Description |
|---|---|
| _id | A canonical ID that can be used to retrieve the service account. |
| name | The friendly name of the service account. |
Service Account Keys
This set of endpoints is used to provision and revoke API keys for a service account. A service account can have a maximum of 10 keys.
Create Service Account Key
Request:
curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys \
-X POST \
-d '{"name": "key1"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.serviceAccounts.keys.create('5a71d7419b3ad47012a5dde2', 'key1').then((response) => {
// async code
});
Response:
201 CREATED
{
"key": {
"secret": "Y4SINFtAUzEjayxgUjJZoTjG",
"name": "key1",
"_id": "svc_5735dcf248011972d621dc01"
}
}
POST /v1.1/serviceaccounts/{serviceAccountId}/keys
Creates an API key for the specified service account. The response body will include a secret as well it’s corresponding ID, which you can use to generate JSON Web Tokens to securely make API calls on behalf of the service account.
| Arguments | |
|---|---|
| name required |
A friendly identifier for the API key. |
List Service Account Keys
Request:
curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys \
--user 'keyId:keySecret'
smooch.serviceAccounts.keys.list('5a71d7419b3ad47012a5dde2').then((response) => {
// async code
});
Response:
200 OK
{
"keys": [
{
"secret": "TDCu5Y_ajUSHPfI-7nT3bzvZ",
"name": "key1",
"_id": "svc_5808ba5cedf3b5931970e054"
},
{
"secret": "Civ5oydK4UTwSPNsHbxJVYV2",
"name": "key2",
"_id": "svc_5a71d7639b3ad47012a5dde3"
}
]
}
GET /v1.1/serviceaccounts/{serviceAccountId}/keys
Lists all API keys for a given service account.
Get Service Account Key
Request:
curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys/svc_5808ba5cedf3b5931970e054 \
--user 'keyId:keySecret'
smooch.serviceAccounts.keys.get('5a71d7419b3ad47012a5dde2', 'svc_5808ba5cedf3b5931970e054').then((response) => {
// async code
});
Response:
200 OK
{
"key": {
"secret": "TDCu5Y_ajUSHPfI-7nT3bzvZ",
"name": "key1",
"_id": "svc_5808ba5cedf3b5931970e054"
}
}
GET /v1.1/serviceaccounts/{serviceAccountId}/keys/{keyId}
Returns an API key.
Delete Service Account Key
Request:
curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys/svc_5808ba5cedf3b5931970e054 \
-X DELETE \
--user 'keyId:keySecret'
smooch.serviceAccounts.keys.delete('5a71d7419b3ad47012a5dde2', 'svc_5808ba5cedf3b5931970e054').then((response) => {
// async code
});
Response:
200 OK
{}
DELETE /v1.1/serviceaccounts/{serviceAccountId}/keys/{keyId}
Removes an API key.
Get Service Account JWT
Request:
curl $SMOOCH_ROOT/v1.1/serviceaccounts/5a71d7419b3ad47012a5dde2/keys/svc_5808ba5cedf3b5931970e054/jwt \
--user 'keyId:keySecret'
smooch.serviceAccounts.keys.getJwt('5a71d7419b3ad47012a5dde2', 'svc_5808ba5cedf3b5931970e054').then((response) => {
// async code
});
Response:
200 OK
{
"jwt": "eyJraWQiOiJzdmNfNTgwOGJhNWNlZGYzYjU5MzE5NzBlMDU0IiwiYWxnIjoiSFMyNTYifQ.eyJzY29wZSI6ImFjY291bnQifQ.C_DaxSuIOc6smKbNHo0cIF0eAtRj_sCsNcR5bCLFji4"
}
GET /v1.1/serviceaccounts/{serviceAccountId}/keys/{keyId}/jwt
Returns an account-scoped JWT signed using the requested keyId/secret pair.
Apps
App schema and endpoints used for provisioning Sunshine Conversations apps.
Create App
Request:
curl $SMOOCH_ROOT/v1.1/apps \
-X POST \
-d '{"name": "My App", "settings": {"maskCreditCardNumbers": false, "useAnimalNames": true}}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.apps
.create({
name: 'My App',
settings: {
maskCreditCardNumbers: false,
echoPostback: false,
useAnimalNames: true
},
metadata: {
foo: 'bar'
}
})
.then((response) => {
// async code
});
Response:
201 CREATED
{
"app": {
"_id": "55c8d9758590aa1900b9b9f6",
"appToken": "3s58wwlgx8xqbidgyyvzunoyw",
"name": "My App",
"settings": {
"echoPostback": false,
"maskCreditCardNumbers": false,
"useAnimalNames": true
},
"metadata": {
"foo": "bar"
}
}
}
POST /v1.1/apps
Creates a new app. The response body will include the app’s _id, which can be used to initialize the Web, iOS and Android clients.
When using service account credentials, the service account is automatically granted access to the app.
| Arguments | |
|---|---|
| name required |
The User facing name of the app. |
| settings optional |
Customizable app settings (see app settings). |
| metadata optional |
Flat object containing any custom properties associated with the app. See metadata schema for more information. |
List Apps
Request:
curl $SMOOCH_ROOT/v1.1/apps \
--user 'keyId:keySecret'
smooch.apps.list().then((response) => {
// async code
});
Response:
200 OK
{
"apps": [
{
"_id": "55c8d9758590aa1900b9b9f6",
"appToken": "3s58wwlgx8xqbidgyyvzunoyw",
"name": "My App",
"settings": {
"maskCreditCardNumbers": true,
"echoPostback": false,
"useAnimalNames": false
}
}
],
"hasMore": false,
"offset": 0
}
GET /v1.1/apps
Lists all apps configured. This API is paginated. It returns a maximum of 25 apps by default, and accepts offset and limit query parameters. The maximum limit is 100.
When using service account credentials, only apps for which the service account has access are returned.
| Parameter | Description |
|---|---|
limit |
Integer, the number of records to return (maximum 100, default 25). |
offset |
Integer, the number of initial records to skip before picking records to return. |
serviceAccountId |
When specified, lists only the apps that the service account has access to. |
Get App
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6 \
--user 'keyId:keySecret'
smooch.apps.get('55c8d9758590aa1900b9b9f6').then((response) => {
// async code
});
Response:
200 OK
{
"app": {
"_id": "55c8d9758590aa1900b9b9f6",
"appToken": "3s58wwlgx8xqbidgyyvzunoyw",
"name": "My App",
"settings": {
"maskCreditCardNumbers": true,
"echoPostback": false,
"useAnimalNames": false
}
}
}
GET /v1.1/apps/{appId}
Fetches an individual app.
Update App
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6 \
-X PUT \
-d '{"name": "My New App", "settings": {"maskCreditCardNumbers": false, "useAnimalNames": true, "echoPostback": true}}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.apps
.update('55c8d9758590aa1900b9b9f6', {
name: 'My New App',
settings: {
maskCreditCardNumbers: false,
echoPostback: true,
useAnimalNames: true
},
metadata: {
foo: 'bar'
}
})
.then((response) => {
// async code
});
Response:
200 OK
{
"app": {
"_id": "55c8d9758590aa1900b9b9f6",
"appToken": "3s58wwlgx8xqbidgyyvzunoyw",
"name": "My New App",
"settings": {
"maskCreditCardNumbers": false,
"echoPostback": true,
"useAnimalNames": true
},
"metadata": {
"foo": "bar"
}
}
}
PUT /v1.1/apps/{appId}
Updates an app.
| Arguments | |
|---|---|
| name optional |
The User facing name of the app. |
| settings optional |
Customizable app settings (see app settings). |
| metadata optional |
Flat object containing any custom properties associated with the app. See metadata schema for more information. |
Delete App
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6 \
-X DELETE \
--user 'keyId:keySecret'
smooch.apps.delete('55c8d9758590aa1900b9b9f6').then((response) => {
// async code
});
Response:
200 OK
{}
DELETE /v1.1/apps/{appId}
Removes the specified app, including all its enabled integrations.
Get SDK IDs
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/sdks \
--user 'keyId:keySecret'
smooch.apps.getSdkIds('55c8d9758590aa1900b9b9f6').then((response) => {
// async code
});
Response:
200 OK
{
"androidIntegrationId": "5e13514150635a186b690113",
"iosIntegrationId": "5d65808b07bb28d9c6aa122c",
"webIntegrationId": "5e567af0643cd101468a5805"
}
GET /v1.1/apps/{appId}/sdks
Retrieve the IDs of the three SDK integrations (android, ios, and web) for the specified app, to be used when initializing the SDKs.
If any of the integrations do not exist already, they will be automatically provisioned with default settings as a result of this call.
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 Sunshine Conversations app. Also used to initialize Sunshine Conversations’ Mobile and Web SDKs. |
| appToken (deprecated) | A public token used to initialize older versions of the Sunshine Conversations 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 metadata schema for more information. |
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 Sunshine Conversations app. Also used to initialize Sunshine Conversations’ 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 Sunshine Conversations. |
| 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. |
| ignoreAutoConversationStart optional | A boolean specifying whether a non message event coming from a channel will trigger a start conversation event and count as a monthly active user (MAU). Note: Calling startConversation() (or equivalent) from the Android, iOS or Web SDK will count as a MAU, regardless of the value of this setting. |
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
Conversations that are created before conversationRetentionSeconds is set will not be affected by this setting until a new activity is detected.
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, Telegram, LINE and all Sunshine Conversations SDKs). In some channels Sunshine Conversations offers partial support for postback buttons via text fallback. For these channels, the user needs to answer with a message matching the postback action text. In this case, the user’s message will always be added to the conversation history.
App Keys
This set of endpoints is used to provision and revoke API keys for a Sunshine Conversations app. An app can have a maximum of 10 keys.
Create App Key
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys \
-X POST \
-d '{"name": "key1"}' \
-H 'content-type: application/json' \
--user 'keyId:keySecret'
smooch.apps.keys.create('55c8d9758590aa1900b9b9f6', 'key1').then((response) => {
// async code
});
Response:
201 CREATED
{
"key": {
"secret": "Y4SINFtAUzEjayxgUjJZoTjG",
"name": "key1",
"_id": "app_5735dcf248011972d621dc01"
}
}
POST /v1.1/apps/{appId}/keys
Creates an API key for the specified app. The response body will include a secret as well it’s corresponding id, which you can use to generate JSON Web Tokens to securely make API calls on behalf of the app.
| Arguments | |
|---|---|
| name required |
A friendly identifier for the API key. |
List App Keys
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys \
--user 'keyId:keySecret'
smooch.apps.keys.list('55c8d9758590aa1900b9b9f6').then((response) => {
// async code
});
Response:
200 OK
{
"keys": [
{
"secret": "5XJ85yjUtRcaQu_pDINblPZb",
"name": "key1",
"_id": "app_5723a347f82ba0516cb4ea34"
},
{
"secret": "sTE74doRFsxtiwyT9JGCBQ6H",
"name": "key2",
"_id": "app_5723a347f82ba0516cb4ea35"
}
]
}
GET /v1.1/apps/{appId}/keys
Lists all API keys for a given app.
Get App Key
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34 \
--user 'keyId:keySecret'
smooch.apps.keys.get('55c8d9758590aa1900b9b9f6', 'app_5723a347f82ba0516cb4ea34').then((response) => {
// async code
});
Response:
200 OK
{
"key": {
"secret": "5XJ85yjUtRcaQu_pDINblPZb",
"name": "key1",
"_id": "app_5723a347f82ba0516cb4ea34"
}
}
GET /v1.1/apps/{appId}/keys/{keyId}
Returns an API key.
Delete App Key
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34 \
-X DELETE \
--user 'keyId:keySecret'
smooch.apps.keys.delete('55c8d9758590aa1900b9b9f6', 'app_5723a347f82ba0516cb4ea34').then((response) => {
// async code
});
Response:
200 OK
{}
DELETE /v1.1/apps/{appId}/keys/{keyId}
Removes an API key.
Get App JWT
Request:
curl $SMOOCH_ROOT/v1.1/apps/55c8d9758590aa1900b9b9f6/keys/app_5723a347f82ba0516cb4ea34/jwt \
--user 'keyId:keySecret'
smooch.apps.keys.getJwt('55c8d9758590aa1900b9b9f6', 'app_5723a347f82ba0516cb4ea34').then((response) => {
// async code
});
Response:
200 OK
{
"jwt": "eyJraWQiOiJhcHBfNTczNDE0NjQwN2E2OWI2MTAwNzQiLCJhbGciOiJIUzI1NiJ9.eyJzY29wZSI6ImFwcCJ9.aDkuZKRXzI3I3XRDtnqbrxIsQQuA7kMrV4r7KcwmeHc"
}
GET /v1.1/apps/{appId}/keys/{keyId}/jwt
Returns an app-scoped JWT signed using the requested keyId/secret pair.
Sunshine Conversations Connect
Introduction
Sunshine Conversations 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 Sunshine Conversations using our partner application and we’ll provision you with everything you’ll need to build your end of the OAuth flow using Sunshine Conversations Connect. In the meantime the OAuth endpoints detailed below can be tested by impersonating Shoplifter, a partnership we built for testing purposes.
Add to Sunshine Conversations Button
<a href="https://app.smooch.io/oauth/authorize?client_id=shoplifter&response_type=code"><img alt="Add to Sunshine Conversations" height="40" width="278" src="https://cdn.smooch.io/images/add_to_sunshine_conversations.png" srcset="https://cdn.smooch.io/images/add_to_sunshine_conversations.png 1x, https://cdn.smooch.io/images/add_to_sunshine_conversations@2x.png 2x"/></a>
This HTML template can be used to place an “Add to Sunshine Conversations” button on your website.
Sample Application
An open source sample application implementing Sunshine Conversations 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 Sunshine Conversations 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 the literal string: 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 Sunshine Conversations 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 Sunshine Conversations app on behalf of an integration, identified by the integration’s clientId. The access token grants permission to get and create app users and conversations associated with the app. The token also grants permission to create webhooks, however only webhooks created for the integration will be visible. An access token with integration scope cannot see or modify webhooks that were created by other integrations, for example.
| API Root | Access |
|---|---|
| /v1.1/appusers/* | Yes |
| /v1.1/webhooks/* | Yes |
| /v1.1/apps/* | No |
| /v1.1/integrations/* | No |
| /v1.1/menu/* | No |
Revoke Access
Request:
curl -X DELETE https://api.smooch.io/oauth/authorization \
-H 'authorization: Bearer your-access-token'
// This endpoint is not currently wrapped in a JavaScript lib
Response:
200 OK
DELETE https://app.smooch.io/oauth/authorization
This endpoint is used to revoke your integration’s access to the user’s Sunshine Conversations 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 Sunshine Conversations 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
versionproperty - Removed support for
messagetrigger. Usemessage:appUserandmessage:appMakerinstead -
triggersis now a required property when creating a webhook -
message:appUserevents supportfilemessages. Previous versions sent them astextmessages -
postback,conversation:start,message:appUserandmessage:appMakerevents now include truncated appUser schema - New message delivery webhooks have been introduced, described below. See the Delivery Events guide for more details:
- Removed
delivery:successanddelivery:failurewebhook triggers which are replaced bymessage:delivery:channelandmessage:delivery:failurerespectively -
message:delivery:channeltriggers when messages are delivered to SDKs. -
message:delivery:failurecan be triggered after amessage:delivery:channelevent if a message cannot be delivered to the user. -
message:delivery:useris 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 onemessageand only contain an_idproperty. - New properties
isFinalEventandexternalMessagesare included in these new webhook payloads.
- Removed
AppUsers
- API responses no longer include a
devicesarray and acredentialRequiredproperty.deviceshas been renamed toclientslong ago and it was kept in API responses for backward compatibility - Link App User To Channel
-
confirmationis now a required property -
skipConfirmationproperty is no longer supported
-
- Pre-Create App User
-
credentialRequiredis no longer supported
-
Conversation
-
typeis now a required property when posting a message