Conversations endpoints

Method HTTP request Description
Get a conversation GET /apps/:app_uuid/conversations/:conversation_uuid Get conversation details
Create conversation POST /apps/:app_uuid/conversations Create a new conversation
Update participants PATCH /apps/:app_uuid/conversations/:conversation_uuid Add or remove participants
Update metadata PATCH /apps/:app_uuid/conversations/:conversation_uuid Change metadata values
Delete a conversation DELETE /apps/:app_uuid/conversations/:conversation_uuid Delete a conversation for all participants
Mark a Conversation Read POST /apps/:app_uuid /users/:user_uuid/conversations/:conversation_uuid/mark_all_read Set all messages in a conversation read for the user.

Get a conversation

This endpoint retrieves a single conversation. This means you can access any conversation within your app.

Parameters:

This method takes no parameters.

HTTP request:

GET/apps/:app_uuid/conversations/:conversation_uuid

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/conversations/<conversation_uuid>

Possible responses:

Got conversation | Status: 200 (OK)

Conversation

Conversation doesn’t exist
Status: 404 (Not Found)
(Empty body)

Conversation deleted
Status: 410 (Gone)
(Empty body)

Create conversation

This endpoint creates a conversation with a set of participants and syncs the conversation to each participant’s client.

Parameters:

Name Type Description
app_uuid string Your Layer App ID
participants string[] Identity IDs identifying participants who should be in the conversation
distinct boolean Whether the conversation should be distinct (see below)
metadata object Initial state of metadata on the conversation
significance object See Significance for details

HTTP request:

POST/apps/:app_uuid/conversations

Example:

{
    "participants": [
        "layer:///identities/1234",
        "layer:///identities/5678"
    ],
    "distinct": false,
    "metadata": {
        "background_color": "#3c3c3c"
    },
    "significance": {
        "default": "low",
        "recipients": {
            "layer:///identities/1234": "normal"
        }
    }
}
curl -X POST \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/conversations\
 -d '{"participants":["layer:///identities/1234","layer:///identities/5678"],"distinct":false,"metadata":{"background_color":"#3c3c3c"},"significance":{"default":"low","recipients":{"layer:///identities/1234":"normal"}}}'

Possible responses:

Conversation created successfully | Status: 201 (Created)

Conversation

Matching Distinct Conversation Found | Status: 200 (OK)

Conversation

Conflicting Distinct Conversation Found | Status: 409 (Conflict)

{
    "id": "conflict",
    "code": 108,
    "message": "The requested Distinct Conversation was found but had metadata that did not match your request.",
    "url": "https://developer.layer.com/api.md#creating-a-conversation",
    "data": Conversation
}

Discussion

When creating a Non-Distinct Conversation, Conversation Found (200) and Conflict 409 should not occur.

In a Distinct Conversation, it is guaranteed that among the given set of participants there will exist one (and only one) Conversation. As such, special handling is needed when creating a Distinct Conversation. There are three possible results:

Conversation Created Successfully

If there is no existing Distinct Conversation that matches the request, then a new conversation is created and returned. The result is the same as above.

Conversation Found

If there is a matching Distinct Conversation, and one of these is true, then the existing Conversation is returned:

  • The metadata property was not included in the new request
  • The metadata in the new request was set to null
  • The metadata property is identical to the metadata of the matching Conversation

If the details match, the response will include the existing conversation, along with a Location header containing the URL to that Conversation:

Location: /apps/24f43c32-4d95-11e4-b3a2-0fd00000020d/conversations/f3cc7b32-3c92-11e4-baad-164230d1df67

Conflict

If there is a matching Conversation, but the matadata is different, an error will be returned containing the existing Conversation so you can determine how to handle the difference in metadata.

Update participants

Parameters:

Name Type Description
apps_uuid string Your Layer App ID
operation string The type of operation, one of add or remove
property string The property to change. Should be participants to change participants.
id string Identity ID to add or remove

HTTP request:

PATCH/apps/:app_uuid/conversations/:conversation_uuid

Example:

[
    {
        "operation": "add",
        "property": "participants",
        "id": "layer:///identities/user1"
    },
    {
        "operation": "remove",
        "property": "participants",
        "id": "layer:///identities/user2"
    }
]
curl -X PATCH \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/vnd.layer-patch+json' \
     https://api.layer.com/apps/<app_uuid>/conversations/<conversation_uuid>\
 -d '[{"operation":"add","property":"participants","id":"layer:///identities/user1"},{"operation":"remove","property":"participants","id":"layer:///identities/user2"}]'

Possible responses:

Participants updated successfully
Status: 204 (No Content)
(Empty body)

Discussion

If you are trying to add a user that is already a participant, or removing a user who is not a participant, that operation won’t do anything.

You can use an operation of “set” if you want to set the participant list to empty; the following request removes all participants and then adds in User 3:

[
  {"operation": "set", "property": "participants", "value": []},
  {"operation": "add", "property": "participants", "id": "layer:///identities/user3"]}
]

Update metadata

Parameters:

Name Type Description
apps_uuid string Your Layer App ID
operation string The type of operation, one of add, remove, set, or delete
property string The property to change; can use . to access nested properties
value string object

HTTP request:

PATCH/apps/:app_uuid/conversations/:conversation_uuid

Example:

[
    {
        "operation": "set",
        "property": "metadata.stats.counter",
        "value": "10"
    },
    {
        "operation": "set",
        "property": "metadata.admin",
        "value": {
            "user_id": "fred",
            "hours": {
                "start": "9",
                "end": "5"
            }
        }
    }
]
curl -X PATCH \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/vnd.layer-patch+json' \
     https://api.layer.com/apps/<app_uuid>/conversations/<conversation_uuid>\
 -d '[{"operation":"set","property":"metadata.stats.counter","value":"10"},{"operation":"set","property":"metadata.admin","value":{"user_id":"fred","hours":{"start":"9","end":"5"}}}]'

Possible responses:

Metadata updated successfully
Status: 204 (No Content)
(Empty body)

Discussion

Metadata values can only be strings or nested objects. Other data types can be passed as strings and parsed into the desired type by the receiver.

Delete a conversation

This endpoint will remove a conversation for all participants, from all their devices.

Parameters:

Name Type Description
apps_uuid string Your Layer App ID
conversation_uuid string ID of the conversation to delete

HTTP request:

DELETE/apps/:app_uuid/conversations/:conversation_uuid

Example:

curl -X DELETE \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/conversations/<conversation_uuid>

Possible responses:

Conversation deleted successfully
Status: 204 (No Content)
(Empty body)

Mark a Conversation Read

Parameters:

Name Type Description
position number or null (optional) The position of the latest message to be marked as read for the user. That message and all earlier ones will be affected. If omitted, this defaults to the most recent message

HTTP request:

POST/apps/:app_uuid/users/:user_uuid/conversations/:conversation_uuid/mark_all_read

Example:

{
    "position": 102837410234
}
curl -X POST \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Bearer <TOKEN>' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/apps/<app_uuid>/users/<user_uuid>/conversations/<conversation_uuid>/mark_all_read\
 -d '{"position":102837410234}'

Possible responses:

Conversation marked read successfully | Status: 202 (Accepted)

{
    "position": 102837410234
}

No Conversation with that ID | Status: 404 (Not Found)

{
    "id": "not_found",
    "code": 102,
    "message": "A Conversation with the specified identifier could not be found.",
    "url": "https://developer.layer.com/reference/api#conversations"
}

The specified Conversation may have already been deleted, or never existed.

Discussion

When position is omitted or null, all messages in the conversation are marked as read. This can create a race condition if there are new messages on the server that the client hasn’t seen yet, so use an explicit position if that case concerns you.