Conversations

The following JSON represents a typical Conversation. It is referred to throughout this document as Conversation:

{
  "id": "layer:///conversations/f3cc7b32-3c92-11e4-baad-164230d1df67",
  "url": "https://api.layer.com/conversations/f3cc7b32-3c92-11e4-baad-164230d1df67",
  "messages_url": "https://api.layer.com/conversations/f3cc7b32-3c92-11e4-baad-164230d1df67/messages",
  "created_at": "2014-09-15T04:44:47+00:00",
  "last_message": null,
  "participants": [
    {
      "id": "layer:///identities/1234",
      "url": "https://api.layer.com/identities/1234",
      "user_id": "1234",
      "display_name": "One Two Three Four",
      "avatar_url": "https://mycompany.co/images/1234.png"
    },
    {
      "id": "layer:///identities/777",
      "url": "https://api.layer.com/identities/777",
      "user_id": "777",
      "display_name": "Number Sevens",
      "avatar_url": "https://mycompany.co/images/777.png"
    },
    {
      "id": "layer:///identities/999",
      "url": "https://api.layer.com/identities/999",
      "user_id": "999",
      "display_name": "Nein!",
      "avatar_url": "https://mycompany.co/images/999.png"
    },
    {
      "id": "layer:///identities/111",
      "url": "https://api.layer.com/identities/111",
      "user_id": "111",
      "display_name": "I One!",
      "avatar_url": "https://mycompany.co/images/111.png"
    }
  ],
  "distinct": true,
  "unread_message_count": 3,
  "metadata": {
    "title": "Who likes this conversation?",
    "favorite": "true",
    "background_color": "#3c3c3c",
    "likes": "5",
    "likers": {
      "layer:///identities/777": "3",
      "layer:///identities/1234": "2"
    }
  }
}
Name Type Description
id string Layer ID to identify the Conversation
url string URL for accessing the Conversation via the REST API
participants BasicIdentity[] Array of User IDs indicating who is currently participating in a Conversation
created_at string Date that the Conversation was created, eg 2014-09-09T04:44:47+00:00
last_message Message A Message object representing the last message sent within this Conversation
distinct boolean true if this is the only distinct Conversation with these participants
unread_message_count integer Number of unread messages for this Conversation
metadata object Custom data associated with the Conversation that is viewable/editable by all participants

Note

Note, The values of the fields above may vary amongst participants of the Conversation. Different users will have different values for unread_message_count for example. And a user who has deleted a message in a Conversation may have a different last_message than a participant who did NOT delete that message.

The id property

An ID consists of a prefix of layer:///conversations/ 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 Conversation via the REST API.

The participants property

A Participant is a user who can send and receive messages within this Conversation, and is represented in the participants property as an BasicIdentity. The participants property is an array of up to 25 BasicIdentity objects for users who are a part of this Conversation.

The metadata property

Metadata allows custom data to be associated with a Conversation. For example, there is no title property in the Conversation Object. If your Conversations need a title to share between all participants and render as part of your view, you can add a title property to the metadata and share it that way.

All values in metadata must be strings or objects. The following metadata is valid:

{
  "metadata": {
    "title": "Fred's Conversation",
    "history": {
      "last_favorite": {
        "body": "Doh!",
        "time": "10-10-2010 10:05:00"
      },
      "least_favorite": {
        "body": "01110000101",
        "time": "10-10-2010 10:05:00"
      }
    }
  }
}

The created_at property

An ISO 8601 formatted date/time string indicating when the Conversation was created on the server, such as 2014-09-09T04:44:47+00:00

The last_message property

The last_message property is a convenience, used primarily for rendering a list of Conversations and indicating the state of the Conversation. It contains a full Message obect (see below) representing the last message in the conversation. If there are no messages in the Conversation, the last_message property will be null.

The distinct property

Whether the conversation is a Distinct Conversation