Identities represent users within your application; they are used

  1. To identify a user to Layer’s APIs
  2. To provide your application with information to help render each user

Each Identity should contain:

  • A User ID: Allows you to map the Identity to a user in your own User Management system
  • An Identity ID: Allows you to identify the user to Layer APIs
  • A Display Name: Helps you render the user, for example, putting their name next to a Message they sent
  • An Avatar URL: Helps you render the user, for example, putting their image next to a Message they sent

Identity properties can be setup while generating Identity Tokens within the authentication handshake or via Server API.

Using identities

Identities are modeled by the Identity class and are returned by APIs that involve identity information (such as the sender of a message, or the currently authenticated user). Instances of Identity contain a number of properties reflecting the profile information for that user. Currently, the SDK instantiates Identity objects as needed; there is no need for developers to create their own instances.

Setting identity fields

You can include some identity fields in your identity token upon authentication.

Currently it is not possible to update identity fields from the Layer SDK.

To update identity fields, please use the Server API.


Users can be followed in order to receive updates when changes are made to their Identity. Any participant in a Conversation with your user is already implicitly followed and cannot be explicitly unfollowed. Other users can be explicitly followed or unfollowed via this API. This is useful for presenting a searchable list of identities a user can begin a new conversation with, without relying on an external user management system.

// Follow a user ID to create a queryable `Identity` object that receives updates via the Platform API

// This can also be used with `Identity` objects
Identity identity = ...;

// Unfollows a user to stop receiving identity mutation updates


Identities can be accessed by Querying, providing a simple way to load and page through Identities. Only Identities of users followed by your user will be loaded. Note that un-followed users will be loaded if they were followed at any point after the initial authentication. In this case the Identity will have its followed flag set to false.

// Queries for all identities with display name `randomName`
Query<Identity> query = Query.builder(Identity.class)
        .predicate(new Predicate(Identity.Property.DISPLAY_NAME, Predicate.Operator.EQUAL_TO, "randomName"))

// Queries for all identities with display name beginning with `rando`
Query<Identity> query = Query.builder(Identity.class)
        .predicate(new Predicate(Identity.Property.DISPLAY_NAME, Predicate.Operator.LIKE, "rando%"))

// Queries for all identities that start with `random`, any character, and end with `ame`
Query<Identity> query = Query.builder(Identity.class)
        .predicate(new Predicate(Identity.Property.DISPLAY_NAME, Predicate.Operator.LIKE, "random_ame"))


Presence allows a user to see that other users are online, and either available, busy, away or offline. To see presence, one must Follow a user, the SDK will expose their presence information and presence updates to you.

Presence has the following 2 concepts.

  • Presence.PresenceStatus: An enum reporting on the user’s current status.
  • last_seen_at: A Date instance indicating when the user was last known to be online.

Viewing PresenceStatus

The PresenceStatus property can have one of the following values:

  • PresenceStatus.ONLINE: The user is currently online
  • PresenceStatus.AWAY: The user’s status has been set to “away”
  • PresenceStatus.BUSY: The user’s status has been set to “busy”
  • PresenceStatus.OFFLINE: The user is currently offline. For the currently authenticated user, this indicates that the user has never set their presence status.
  • PresenceStatus.INVISIBLE: The currently authenticated user has set their status to “invisible”; all other users will see this user as “offline”, but “invisible” is what this user sees so we know it was explicitly set for/by this user.
  • null: The user’s PresenceStatus is not available. Applications should explictly handle this.

Given an Identity object, PresenceStatus is accessible with just:

Presence.PresenceStatus status =  Identity.getPresenceStatus();

Viewing Last Seen At

Given an Identity object, last_seen_at is accessible with just:

Date lastSeenAt =  Identity.getLastSeenAt();

Editing PresenceStatus

The LayerClient object contains a setPresenceStatus method. This allows the current user to set their PresenceStatus.


Editing Last Seen At

last_seen_at is automatically determined by Layer server. So, it cannot be set from the client sdk.

Authentication Conversations