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.

The Identity ID is derived from the User ID using:

var identityId = 'layer:///identities/' + encodeURIComponent(userId);


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 to create a queryable `layer.Identity` object that receives updates via Server API

// Unfollow a user to stop receiving identity updates

Note that the following shorthand of using a User ID instead of an Identity ID is currently accepted:



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.

var identityQuery = client.createQuery({
    model: layer.Query.Identity

identityQuery.on('change', function(evt) {

Full Identities vs Basic Identities

Typically, only a Basic Identity is loaded. A Basic Identity loads only the following properties:

  • id
  • userId
  • url
  • displayName
  • avatarUrl

A Basic Identity is loaded when Identities are loaded for Converation pariticipants and Message senders.

A Full Identity is only loaded when using a layer.Query to load them. A full identity adds the following properties:

  • firstName
  • lastName
  • phoneNumber
  • emailAddress
  • metadata
  • publicKey


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 is tracked as part of the Identity object, adding the following properties:

  • status: A string reporting on the user’s current status
  • lastSeenAt: A Date instance indicating when the user was last known to be online

Viewing Presence

The status property can have one of the following values:

  • layer.Identity.STATUS.AVAILABLE: The user’s status has been set to “available”
  • layer.Identity.STATUS.AWAY: The user’s status has been set to “away”
  • layer.Identity.STATUS.BUSY: The user’s status has been set to “busy”
  • layer.Identity.STATUS.OFFLINE: The user is currently offline
  • layer.Identity.STATUS.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

Given an Identity object, you should be able to access status with just:

var status = identity.status;

Given an Identity object, you should be able to detect changes to its status with just:

identity.on('identities:change', function(evt) {
  if (evt.hasProperty('status')) {
    var newStatus = identity.status;

Editing Presence

The layer.Identity object contains a setStatus method. This method may only be called on the Authenticated User’s Identity, and not on Identities of other users.

Authentication Conversations