Layer Concepts Overview

Layer’s services provide the means of adding chat-style communications into your applications. This document begins by explaining what these services entail, and what the core concepts are that are needed to understand these services, prior to digging into details of the individual SDKs and APIs.

What are Layer’s services?

Layer is an asynchronous, person-to-person messaging platform delivered as a service. We provide native SDKs for mobile and JavaScript, REST and WebSocket APIs for other platforms, and UI toolkits for implementing a rich, engaging messaging experience within your own applications and services. The platform is fully managed, HIPAA-compliant and powers a wide range of products providing both person-to-person and business-to-consumer communication use cases.

On the client, these chat services can be added using our:

  • iOS SDK
  • Android SDK
  • WebSDK
  • Client API (REST + WebSocket API)

These services can also be integrated into your backend services using our server-side APIs:

  • Server API
  • Webhooks API

What form do these services take?

Typically, Messaging is done within Conversations. A Conversation consists of a set of participants, and a set of Messages sent within that Conversation. A Message can contain simple text, images, interactive content; a Message is a building block for providing whatever type of content your communications requires. That said, it is still a Message, with timestamps, fields for indicating if its been read by participants, as well as having a sequence/position within the Conversation.

Whether you’re building a UI that presents a list of Messages, distributes Messages across a UI rendering a city map, or creates other innovative user experiences is entirely within your control; Layer offers the Message structure, the Conversation to send it within, and the servers, infrastructure and SDKs to ensure it reaches its intended recipient, and can be rendered for that recipient.

Core concepts

There are a few high level concepts to understand before getting into the details of any of our APIs.

Users and Identity

Every user within Layer’s Services has an Identity. An Identity is an object used to identify users both within Layer and within your own User Management System; as well as to provide rendering information to a UI on how best to render that user’s name/avatar.

  • If you identify a user as “83”, then you can simply provide a User ID of “83” and that will be a key part of that user’s Identity.
  • If you identify a user as “”, that too can be used as the Identity’s User ID.

An Identity is created within Layer’s Services any time:

  • A new user authenticates with Layer’s Services
  • Your server uses our Server APIs to create an Identity
  • A user who does not yet exist is added as a participant to a Conversation

Note that newer/upcoming versions of our APIs use the Identity or Identity ID as a key input to many of its APIs for operating upon data. For example, creating a Conversation would be done with an array of Identity IDs. Some of Layer’s APIs will have no reference to Identity in them; that implies its not available for that version of that platform.


A Conversation is a container in which Messages are sent, and contains a set of Identities who are participants in that Conversation.

Messages sent within a Conversation can be accessed by participants, or via the Server API, but not by other users.

The Conversation enables users who are participants, as well as your server to:

  1. Access a history of Messages
  2. Send additional Messages
  3. Add and remove participants

Conversations come with associated and customizable metadata that lets your applications and services associate helpful data with these Conversations. Uses for this may include adding titles for the conversation’s UI; identifying an object or resources that the discussion is around, managing conversation state, etc…

Each Conversation can have between 2 and 25 participants.

Conversation types

There are different types of Conversations that come with slightly different behaviors:

  • Distinct Conversations: There can only be a single Distinct Conversation between a set of participants; any attempt to create a New Distinct Conversation between these participants will simply return any existing Distinct Conversation.
  • Non-Distinct Conversations: There can be many Conversations between a given set of participants, each with different messages and metadata.


A Message is the basic unit of communication within Layer’s Services. Any Message sent will be received by all participants of the Conversation in which it was sent. A Message consists of a sender (Identity of the user that sent the Message), timestamps, receipts (identifying which users have received and read the Message), and an array of Message Parts.


A MessagePart consists of a MIME Type and data. The interpretation, parsing and rendering of any given MIME Type is entirely up to your application. Such a MessagePart might have a MIME Type of ‘text/plain’ and contain a simple text message. It could be ‘text/calendar’ and contain text in the specified format, which you may render in various interesting ways enabling interactive scheduling. It could be a custom type used only by your product: ‘application/json+sink-a-battleship’.

The fact that a Message consists of one or more of these can allow for a rich dialog entailing multiple types of content that all work together to form a complete Message to be rendered for the recipients.

MessagePart objects can only contain up to 2KB of data, beyond which, the data is separately uploaded into cloud storage and is linked to but not directly loaded with your Message Parts. Note that most of Layer’s SDKs automatically detect when the size excedes 2KB and uploads the data for you.


Announcements are a special type of Message that is not sent as part of a Conversation, and which can be used to send:

  • System wide messages to some or all of your users
  • One-on-one messages from the system to individual users (“your quota is exceded”, “congratulations on being the number one poster”, “your subscription is about to expire”).

Developer Dashboard

The Developer Dashboard provides you with access to your applications, enabling you to configure authentication, set up webhooks, access application IDs and access keys, enable push notifications, view logs and more. Go to your Developer Dashboard to learn more.


Authentication provides a means of validating that a user that connects with Layer’s Services has been authorized to do so by you, and associates an Identity with that user.

Apps, App IDs and Staging Apps

Working with Layer, all of your activity typically takes place within a single Application. The Application is identified using an App ID, typically of the form layer:///apps/production/dcf02a2a-2222-1111-0000-cb816aafe979. There are two types of Applications:

  • Staging Applications layer:///apps/staging/12102a2a-2222-1111-0000-cb816aafe121: Use these apps for testing purposes.
  • Production Aplications layer:///apps/production/dcf02a2a-2222-1111-0000-cb816aafe979: Use these apps for production.

Common mistake

The staging or production portion of the app ID is for developer convenience and is ignored by our SDKs. Typically the ID portion of staging and production IDs only differ in a few characters and may look the same at first glance. Using the wrong ID is a common source of missing content, authentication issues, and incorrect push notification behavior.

Staging applications have the following characteristics:

  • Authentication will expire every 5 minutes (expiration is 30 days for production applications). This behavior allows you to readily test your reauthentication code; if done correctly, your staging apps can present a seamless, uninterrupted session as far as any user can perceive.
  • All data can be deleted via the Developer Dashboard so that you can resume testing with a clean environment.