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/apps/YOUR_APP_ID/messages/940de862-3c96-11e4-baad-164230d1df67",
  "conversation": {
    "id": "layer:///conversations/e67b5da2-95ca-40c4-bfc5-a2a8baaeb50f",
    "url": "https://api.layer.com/apps/YOUR_APP_ID/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/apps/YOUR_APP_ID/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"
  },
  "recipient_status": {
    "layer:///identities/777": "sent",
    "layer:///identities/999": "read",
    "layer:///identities/111": "delivered",
    "layer:///identities/1234": "read"
  },
  "updated_at": "2014-09-09T04:44:47+00:00"
}

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
conversation object Conversation that the Message is a part of
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 (optional) Date/time of the last change to 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 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 conversation property

Each Message object identifies the Conversation it is a part of, providing both an id and a url for accessing it.

The recipient_status property

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

{
  "layer:///identities/777": "read",
  "layer:///identities/999": "delivered",
  "layer:///identities/111": "sent",
  "layer:///identities/1234": "read"
}
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, which can be sent from all of the Client SDKs. 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 any message part has been altered in conjunction with the message