In addition to the information automatically collected and stored for each of a user’s clients, a user itself can have other specific information attached to it to allow better context and history understanding.
Information can be added to a user in two ways:
This information can be structured or unstructured.
These are properties that Sunshine Conversations has identified as common across many use cases, and has exposed as common properties across all users, when present. They are composed of signedUpAt as well as the user profile information.
Stored in an object under user, the profile contains information which can identify the user. All personal identifiable information about a user can be deleted with one call to the delete user personal information API.
The currently supported structured fields are:
signedUpAt, which is the date when the user first started using your service, or when they first became a customer. If not customized on user creation, this field is automatically populated to be the date the user was created in Sunshine Conversations, which is most likely the moment when the user messaged you for the first time.The profile fields:
givenName, also referred to as firstName in some contexts, which represents the user’s given namesurname, also referred to as lastName in some contexts, which represents the user’s surnameemail, which represents the user’s email address. Note that this field is only used for display purposes, and does not affect how delivers messages in any way. For information on how to link an email address to a user to be able to send them messages over email, see the outbound messaging guide.avatarUrl, which represents the user’s avatarlocale, which represents the user’s locale information in BCP 47 format. If not customized, this field may be automatically populated based on information collected from the user’s source channel, messages, or the account settings. This field is supported starting with the v2 API.By default, Sunshine Conversations will use the locale to translate any fallback messages from English into the user’s locale. If no locale is available, fallback messages will be sent in English. To turn off the translation feature, see the app settings.
A user’s locale may be automatically populated by the platform through one of the following:
Otherwise, if the business sets or updates a user’s locale, Sunshine Conversations will not overwrite the value set by the business.
Example
{
"user": {
"id": "deb920657bbc3adc3fec7963",
"externalId": "user-id-231",
"signedUpAt": "2015-10-08T23:52:11.677Z",
"profile": {
"givenName": "Steve",
"surname": "Brule",
"email": "steveb@channel5.com",
"avatarUrl": "https://s3.amazonaws.com/avatar.jpg",
"locale": "fr-CA"
}
}
}
Unstructured information, stored under a metadata object under user, is a set of key/value pairs that are specific to your application domain or use case. The metadata can contain fields with values of type Number, String, or Boolean and is limited to 4KB in size.
Example
{
"user": {
"id": "deb920657bbc3adc3fec7963",
"externalId": "user-id-231",
"metadata": {
"premiumUser": true,
"numberOfPurchases": 20,
"itemsInCart": 3,
"couponCode": "PREM_USR"
}
}
}
To add properties via the REST API, call the Update User endpoint:
const apiInstance = new SunshineConversationsClient.UsersApi();
const appId = '5d8cff3cd55b040010928b5b'; // Identifies the app.
const userIdOrExternalId = '42589ad070d43be9b00ff7e5'; // The user's id or externalId.
const data = new SunshineConversationsClient.UserUpdateBody();
data.metadata = {
premiumUser: true,
numberOfPurchases: 20,
itemsInCart: 3,
couponCode: 'PREM_USR'
};
data.profile = {
givenName: 'Steve'
};
apiInstance.updateUser(appId, userIdOrExternalId, data).then(
function(data) {
console.log('API called successfully. Returned data: ' + data);
},
function(error) {
console.error(error);
}
);
Each of Sunshine Conversations’ web and mobile SDKs (iOS, Android, and Web) support attaching properties to a user at runtime. The details of when and how these properties are uploaded to the server is handled automatically by the SDKs, so in general you should not need to worry about this detail. However, the process is documented here for completeness.
On Android and iOS, when a user property is set using one of the SDK methods, the properties are immediately serialized to disk until they can be uploaded to the server. Changes to user properties are uploaded in batches at regular intervals while the app is in the foreground, as well as just before the app is sent to the background, or immediately before a message is sent by the user. If the application exits unexpectedly, or the user has intermittent internet connection or no internet connection, the properties will remain on disk until the upload eventually succeeds (even across app launches). If the user does not yet exist (i.e. the user has not yet sent their first message, and the createConversation method has not been called), the properties are still tracked and stored on disk until the user is eventually created, and they will be uploaded as part of the user creation flow.
On Web, the user properties are stored in memory, and uploaded in batches at regular intervals, or immediately before a message is sent by the user. If the user does not yet exist (i.e. the user has not yet sent their first message, and the createConversation method has not been called), the properties are still tracked and stored in memory until the user is eventually created, and they will be uploaded as part of the user creation flow. In contrast to the Android and iOS SDKs, the Web Messenger does not store any user property information on disk - if the browser window is closed before the user is created, then the properties will be discarded.
Objective-C
#import <Smooch/Smooch.h>
[SKTUser currentUser].firstName = @"Steve";
[SKTUser currentUser].lastName = @"Brule";
[SKTUser currentUser].email = @"steveb@channel5.com";
[SKTUser currentUser].signedUpAt = [NSDate date];
[[SKTUser currentUser] addProperties:@{
@"premiumUser": @YES,
@"numberOfPurchases": @20,
@"itemsInCart": @3,
@"couponCode": @"PREM_USR"
}];
Swift
SKTUser.current()?.firstName = "Steve"
SKTUser.current()?.lastName = "Brule"
SKTUser.current()?.email = "steveb@channel5.com"
SKTUser.current()?.signedUpAt = NSDate() as Date
SKTUser.current()?.addProperties([
"premiumUser": true,
"numberOfPurchases": 20,
"itemsInCart": 3,
"couponCode": "PREM_USR"
])
Java
import io.smooch.core.User;
User.getCurrentUser().setFirstName("Steve");
User.getCurrentUser().setLastName("Brule");
User.getCurrentUser().setEmail("steveb@channel5.com");
User.getCurrentUser().setSignedUpAt(new Date(1420070400000l));
final Map<String, Object> customProperties = new HashMap<>();
customProperties.put("premiumUser", true);
customProperties.put("numberOfPurchases", 20);
customProperties.put("itemsInCart", 3);
customProperties.put("couponCode", "PREM_USR");
User.getCurrentUser().addProperties(customProperties);
JavaScript
Smooch.updateUser({
givenName: 'Steve',
surname: 'Brule',
email: 'steveb@channel5.com',
signedUpAt: Date.now(),
properties: {
premiumUser: true,
numberOfPurchases: 20,
itemsInCart: 3,
couponCode: 'PREM_USR'
}
});