Introduction to Users

In the Smooch 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 Smooch refers to as an appUser:

  • A visitor to your Website
  • The holder of an SMS number
  • A user of your mobile app
  • A member of the public on Facebook Messenger

When consuming the Smooch REST API, a user can be referred to by either their Smooch-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.

Anonymous Users

When a user is referred to as “anonymous” in Smooch, it simply means that the user has not been assigned a userId. When a new user comes in from a Smooch customer channel, they are anonymous by default. This includes users on email, SMS, Smooch 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 Smooch 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 Smooch 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.

Identified Users

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 Smooch app. Examples of userIds include email addresses, GUIDs, or any existing ID from your own user directory. By assigning a userId to a Smooch user, you are able to reference that user by their userId when using the Smooch 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 Smooch user to a user record in your own system.

In addition to mapping Smooch 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 Smooch’s 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.

Named Users

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.