Messages

The following JSON represents a typical Message; referred to throughout this document as Message:

{
  "id": "layer:///messages/940de862-3c96-11e4-baad-164230d1df67",
  "url": "https://api.layer.com/messages/940de862-3c96-11e4-baad-164230d1df67",
  "receipts_url": "https://api.layer.com/messages/940de862-3c96-11e4-baad-164230d1df67/receipts",
  "position": 15032697020,
  "conversation": {
    "id": "layer:///conversations/e67b5da2-95ca-40c4-bfc5-a2a8baaeb50f",
    "url": "https://api.layer.com/conversations/e67b5da2-95ca-40c4-bfc5-a2a8baaeb50f"
  },
  "parts": [
    {
      "id": "layer:///messages/940de862-3c96-11e4-baad-164230d1df67/parts/0",
      "mime_type": "text/plain",
      "body": "This is the message."
    },
    {
      "id": "layer:///messages/940de862-3c96-11e4-baad-164230d1df67/parts/1",
      "mime_type": "image/png",
      "content": {
        "id": "layer:///content/7a0aefb8-3c97-11e4-baad-164230d1df67",
        "download_url": "http://google-testbucket.storage.googleapis.com/some/download/path",
        "expiration": "2014-09-09T04:44:47+00:00",
        "refresh_url": "https://api.layer.com/content/7a0aefb8-3c97-11e4-baad-164230d1df67",
        "size": 172114124
      }
    }
  ],
  "sent_at": "2014-09-09T04:44:47+00:00",
  "sender": {
    "id": "layer:///identities/1234",
    "url": "https://api.layer.com/identities/1234",
    "user_id": "1234",
    "display_name": "One Two Three Four"
  },
  "is_unread": true,
  "recipient_status": {
    "layer:///identities/777": "sent",
    "layer:///identities/999": "read",
    "layer:///identities/111": "delivered",
    "layer:///identities/1234": "read"
  }
}

The Message object represents a message sent by a user (or by a server) to the participants within a Conversation. A Message has the following properties:

Name Type Description
id string Layer ID to identify the Message
url string URL for accessing the Message via the REST API
sender BasicIdentity Identifies the message sender
sent_at string Date/time that the message was sent, eg 2014-09-09T04:44:47+00:00
position integer A per-client ordering of the message in the conversation
conversation object Conversation that the Message is a part of
is_unread boolean Indicates if the current user has read the message
recipient_status object Hash of Identity IDs indicating which users have received/read the message
parts MessagePart[] Each MessagePart in the parts array contains a part of the contents of the message
updated_at string Date/time of the last change of the message parts

The id property

An ID consists of a prefix of layer:///messages/ followed by a UUID. This ID format is common across all of the Layer Platform.

This ID is a required parameter for many requests. It could also be used for indexing an in-app cache. Within Layer APIs, the full ID is used as a parameter; however, only the UUID is used if the ID is being used within a URL.

The url property

The url property specifies how to retrieve, update or delete the Message via the REST API.

The sender property

The sender object is an BasicIdentity that identifies and contains rendering information for the sender of this Message.

The sent_at property

An ISO-8601 formatted date/time string indicating when the Message was received by the server. For example, 2014-09-09T04:44:47+00:00.

The position property

Conversations contain an array of messages, ordered by their position properties. The position is specific to each individual user and their view of the Conversation, which means that sorting by position could lead to a different order for different users.

The conversation property

Each Message object identifies the Conversation it is a part of, providing both an id and a url for accessing it. Under normal conditions, it should be obvious what Conversation a Message belongs to. However, when receiving a Message via a websocket, the conversation property is the only way to know which Conversation it belongs with.

The is_unread property

A Message is known to be read if any client that is authenticated as this user has sent a read receipt. Until that is received, is_unread is equal to true, and can be taken as a hint to your UI on how to highlight this Message.

The sender of a Message is always assumed to have read the Message even if no read receipt was sent.

The recipient_status property

Every Message has a Recipient Status object. The status object looks roughly like:

{
  "layer:///identities/1234": "read",
  "layer:///identities/777": "delivered",
  "layer:///identities/999": "sent"
}
Value Description
“sent” The user is on the recipient list but no Delivery Receipt has been received
“delivered” A Delivery Receipt has been received for this user
“read” A Read Receipt has been received for this user, or this user is the sender

The recipient status object is driven by receipts. A Receipt is a request sent by a browser/device to the server when a message is received (delivery receipt) or displayed (read receipt).

The parts property

The parts represents an array of MessagePart objects that make up this Message.

The updated_at property

Property describing the last server time when the message part has been altered in conjunction with the message