In the Sunshine Conversations lexicon, user refers to an end-user on your platform, or a customer (or prospective customer) of your business. The following are all examples of what Sunshine Conversations refers to as a user:
When using the Sunshine Conversations REST API, a user can be referenced by either their Sunshine Conversations-assigned user ID (represented as id in the user record), or their business-assigned externalId. For example, using the Node.js API lib to retrieve a user record:
const apiInstance = new SunshineConversationsApi.UsersApi();
apiInstance.getUser(appId, userId)
.then(response => /* success */)
.catch(error => /* failure */);
When a user is referred to as “anonymous” in Sunshine Conversations, it simply means that the user has not been assigned an external ID. When a new user comes in from a Sunshine Conversations customer channel, they are anonymous by default. This includes users on email, SMS, Sunshine Conversations SDKs, and all supported messaging channels. An anonymous user can still be assigned profile information (name, email address, custom properties, etc.), and has most of the same capabilities as an identified user.
An identified user, in contrast with an anonymous user, is a user that your business has identified with an external ID. An externalId is a string that can have any value you like, but must be unique within a given Sunshine Conversations app. Examples of externalIds include email addresses, GUIDs, or any existing ID from your own user directory. By assigning a externalId to a Sunshine Conversations user, you are able to reference that user by their externalId when using the Sunshine Conversations REST API, and you will also receive the externalId in any relevant webhook events associated to that user. This allows your system to easily map a Sunshine Conversations user to a user record in your own system.
The key difference between an anonymous user and an identified user is how the Sunshine Conversations SDKs gain access to the user’s profile and conversation history. An identified user can only be accessed with a signed JWT credential with scope appUser or higher. An anonymous user can not be accessed using an appUser-scoped JWT; instead, the SDKs authenticate using a sessionToken mechanism, explained below.
Session tokens are managed automatically by the Sunshine Conversations SDKs, and cannot be used with the public API. In general, it is not necessary to know how session token-based authentication works, but the concept of a session is important to understand how a user can gain access to their conversation history on a different browser or mobile device. For more information on how users can be moved between different channels and devices, see the channel transfer guide.
By leveraging your business’ existing authentication mechanism in your application or website (for example, if your website has an area that requires the user to log in), the user can seamlessly transfer to another authenticated device. By identifying a user, and using your application’s own user directory and authentication mechanism to verify their identity, you are allowing them to switch between different domains, browsers, and devices, while still maintaining their conversation history.
There are currently two conversation types:
personal is the default conversation type created for a user who starts messaging a business using an SDK powered messaging experience or a social messsaging / sms channel. Personal conversations only have a single participant, and additional users cannot be added.sdkGroup type can have multiple users added to them as participants by calling the the join conversation endpoint. These group conversations aren’t compatible with all channels. They only work with the Android, iOS and Web messaging SDKs. See multi-party conversations for more information.