Messages endpoints

Method HTTP request Description
Get all messages GET /conversations/:conversation_uuid/messages Get the most recent messages in a conversation
Get a message GET /messages/:message_uuid Get details of a single message
Send a message POST /conversations/:conversation_uuid/messages Send a message into the given conversation
Delete a message DELETE /messages/:message_uuid Delete a message

Get all messages

Parameters:

Name Type Description
page_size integer (optional) Number of messages to return; max and default of 100
from_id string (optional) Get the Messages logically sorted after this ID (by default, this corresponds to Messages chronologically before this ID). Can be passed as a Layer URI layer:///messages/uuid or simply a UUID

HTTP request:

GET/conversations/:conversation_uuid/messages

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Layer session-token="<TOKEN>"'' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/conversations/<conversation_uuid>/messages

Possible responses:

Got messages successfully | Status: 200 (OK)

[
    Message,
    Message
]

Discussion

The response will include a header indicating the total number of results available to page through:

Layer-Count: 4023

Get a message

Parameters:

This method takes no parameters.

HTTP request:

GET/messages/:message_uuid

Example:

curl -X GET \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Layer session-token="<TOKEN>"'' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/messages/<message_uuid>

Possible responses:

Got message successfully | Status: 200 (OK)

Message

Send a message

Parameters:

Name Type Description
parts MessagePart[] Array of message parts
parts.id string (optional) Optional message part id URI for the new message type, if omitted the platform will generate one. ID is of the form layer:///messages/:message_uuid/parts/:part_uuid where the part UUID is unique within the message.
parts.body string Text or base64-encoded data, up to 2KB in size
parts.mime_type string “text/plain”, “image/png”, or other MIME type describing the message part
parts.encoding string (optional) If sending base64-encoded data, specify “base64”. Otherwise, omit this field
parts.content Content (optional) If sending Rich Content, use the Content object
notification object (optional) See Push Notifications for details
id string (optional) UUID or Layer ID, used for deduplication

HTTP request:

POST/conversations/:conversation_uuid/messages

Example:

{
    "parts": [
        {
            "body": "Hello, World!",
            "mime_type": "text/plain"
        },
        {
            "body": "YW55IGNhcm5hbCBwbGVhc3VyZQ==",
            "mime_type": "image/jpeg",
            "encoding": "base64"
        }
    ],
    "notification": {
        "title": "New Message from The Beyond",
        "text": "This is the alert text to include with the Push Notification.",
        "sound": "chime.aiff"
    }
}
curl -X POST \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Layer session-token="<TOKEN>"'' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/conversations/<conversation_uuid>/messages\
 -d '{"parts":[{"body":"Hello, World!","mime_type":"text/plain"},{"body":"YW55IGNhcm5hbCBwbGVhc3VyZQ==","mime_type":"image/jpeg","encoding":"base64"}],"notification":{"title":"New Message from The Beyond","text":"This is the alert text to include with the Push Notification.","sound":"chime.aiff"}}'

Possible responses:

Message sent successfully | Status: 201 (Created)

Message

Message conflict | Status: 409 (Conflict)

{
    "id": "id_in_use",
    "code": 111,
    "message": "The requested Message already exists",
    "url": "http://docs.layer.com/reference/client_api#send-a-message",
    "data": Message
}

Websocket request:

{
    "type": "request",
    "body": {
        "method": "Message.create",
        "request_id": "fred.flinstone.3",
        "object_id": "layer:///conversations/e67b5da2-95ca-40c4-bfc5-a2a8baaeb50f",
        "data": {
            "parts": [
                {
                    "mime_type": "text/plain",
                    "body": "This is the message."
                },
                {
                    "mime_type": "image/png",
                    "content": {
                        "id": "layer:///content/7a0aefb8-3c97-11e4-baad-164230d1df67",
                        "size": 172114124
                    }
                }
            ],
            "notification": {
                "title": "The Uprising",
                "text": "All rise, its a Message!",
                "sound": "salute.aiff"
            }
        }
    }
}

Success

{
    "name": "Success",
    "body": {
        "type": "response",
        "counter": 16,
        "timestamp": "2015-01-19T09:15:43+00:00",
        "body": {
            "request_id": "fred.flinstone.3",
            "method": "Message.create",
            "success": true,
            "data": Message
        }
    }
}

Error

{
    "name": "Error",
    "body": {
        "type": "response",
        "counter": 18,
        "timestamp": "2015-01-19T09:15:43+00:00",
        "body": {
            "request_id": "fred.flinstone.3",
            "method": "Message.create",
            "success": false,
            "data": {
                "code": 102,
                "id": "not_found",
                "message": "The Conversation could not be found.",
                "url": "https://developer.layer.com/"
            }
        }
    }
}

Deduplication error

{
    "name": "Deduplication error",
    "body": {
        "type": "response",
        "counter": 18,
        "timestamp": "2015-01-19T09:15:43+00:00",
        "body": {
            "request_id": "fred.flinstone.3",
            "method": "Message.create",
            "success": false,
            "data": {
                "id": "id_in_use",
                "code": 111,
                "message": "The requested Message already exists",
                "url": "http://docs.layer.com/reference/client_api#send-a-message",
                "data": Message
            }
        }
    }
}

Discussion

Note

  1. MessagePart objects whose bodies cannot be encoded as a JSON string need to be encoded as Base64, and the part’s encoding property should be “base64”.
  2. The total length of a MessagePart body cannot exceed 2KB.

Push notifications

Layer provides extensive support for Push Notifications on both iOS (APNS) and Android (GCM). Pushes are delivered to devices when Messages are sent using the notification parameter. The possible values for the notification object are described below:

Name Type Description
text string The text to be displayed on the notification alert. On iOS, displayed on the lock screen or banner. On GCM, delivered in the push intent as advisory information
sound string The name of a sound to be played. On iOS, must exist in the main application bundle. On GCM, delivered in the push intent as advisory information
title string Text to be displayed on the lock screen or notification banner

Note that values for iOS badge counts cannot be provided because we compute the correct badge count on a per-recipient basis.

Push Notifications are an optional feature and the notification parameter can be omitted entirely, in which case notifications will not be sent.

Delete a message

Parameters:

Name Type Description
mode string Possible values are “all_participants” or “my_devices”

HTTP request:

DELETE/messages/:message_uuid

Example:

curl -X DELETE \
     -H 'Accept: application/vnd.layer+json; version=3.0' \
     -H 'Authorization: Layer session-token="<TOKEN>"'' \
     -H 'Content-Type: application/json' \
     https://api.layer.com/messages/<message_uuid>?mode=all_participants

Possible responses:

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

Discussion

There are two possible values for mode:

  • mode=all_participants: The Message will be deleted for all participants in the conversation
  • mode=my_devices: The Message will be hidden for the current user on all their devices

There is no undelete, automatic or otherwise, regardless of the deletion mode.