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/apps/APP_ID/conversations/f3cc7b32-3c92-11e4-baad-164230d1df67",
  "messages_url": "https://api.layer.com/apps/APP_ID/conversations/f3cc7b32-3c92-11e4-baad-164230d1df67/messages",
  "created_at": "2014-09-15T04:44:47+00:00",
  "participants": [
    {
      "id": "layer:///identities/1234",
      "url": "https://api.layer.com/identities/1234",
      "user_id": "1234",
      "display_name": "One Two Three Four",
      "avatar_url": "https://mydomain.com/images/1234.gif"
    },
    {
      "id": "layer:///identities/777",
      "url": "https://api.layer.com/identities/777",
      "user_id": "777",
      "display_name": "Seven Seven Seven",
      "avatar_url": "https://mydomain.com/images/777.gif"
    },
    {
      "id": "layer:///identities/999",
      "url": "https://api.layer.com/identities/999",
      "user_id": "999",
      "display_name": "Nine Nine Nine",
      "avatar_url": "https://mydomain.com/images/999.gif"
    },
    {
      "id": "layer:///identities/111",
      "url": "https://api.layer.com/identities/111",
      "user_id": "111",
      "display_name": "One One One",
      "avatar_url": "https://mydomain.com/images/111.gif"
    }
  ],
  "distinct": true,
  "metadata": {
    "title": "Who likes this conversation?",
    "favorite": "true",
    "background_color": "#3c3c3c",
    "likes": "5",
    "likers": {
      "user1": "3",
      "user8": "2"
    }
  },
  "total_message_count": 258
}
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 Basic Identities 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
distinct boolean true if this is the only distinct Conversation with these participants
metadata object Custom data associated with the Conversation that is viewable/editable by all participants

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

Each participant in the Conversation is represented by a BasicIdentity, the full array of Identities specifies who is a part of the Conversation. There is a limit of at most 25 users per 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 distinct property

A boolean value specifies whether the conversation is a Distinct Conversation