In the Sunshine Conversations lexicon, user (usually referred to as an app user or appUser) refers to an end-user of your platform or a customer of your business. The following are all examples of what Sunshine Conversations refers to as an appUser:
When consuming the Sunshine Conversations REST API, a user can be referred to by either their Sunshine Conversations-assigned ID (represented as _id in appUser payloads), or their business-assigned userId. Assigning a userId is optional. A user that has been assigned a userId is referred to as an identified user, and all other users are referred to as anonymous users.
When a user is referred to as “anonymous” in Sunshine Conversations, it simply means that the user has not been assigned a userId. 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.
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.
For users created on SDKs, the mobile device (or browser) from which the user was created can gain access to profile information and conversation history via a sessionToken that is generated when the user is created, and returned to the calling SDK client. 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 anonymous users can be moved between different channels and devices, see the channel transfer guide.
An identified user, in contrast with an anonymous user, is a user that your business has identified with a userId. A userId is a string that can have any value you like, but must be unique within a given Sunshine Conversations app. Examples of userIds include email addresses, GUIDs, or any existing ID from your own user directory. By assigning a userId to a Sunshine Conversations user, you are able to reference that user by their userId when using the Sunshine Conversations REST API, and you will also receive the userId 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.
In addition to mapping Sunshine Conversations users to your own user record, identifying users is also a tool to enable cross-device use cases. 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 without having to go through any channel transfer flows. By identifying a user, and using your application’s own user directory and authentication mechanism to verify their identity, you are allowing them to easily switch between different browsers and devices, while still maintaining their conversation history.
A user can only be assigned a userId by using one of Sunshine Conversations’ messaging SDKs (iOS, Android, and Web) and calling the login method. When a user is assigned a userId, they can no longer be accessed via session token-based authentication (described above). Instead, an identified user’s profile information and conversation history can only be accessed using a JWT credential. For more information on assigning userIds, and how to sign and distribute JWTs to your users, see the authenticating users guide.
A named user is a user that has been assigned a givenName or a surname by either yourself or from information received from a third party channel. A user can be named regardless of whether they are anonymous or identified.
When a user is named, messages coming from that user will be tagged with that user’s name. In the absence of a user’s name, we’ll use this message naming logic to determine the message name.