Messages endpoints

Method HTTP request Description
Send message POST /apps/:app_uuid/conversations/:conversation_uuid/messages Send a message into a conversation
Get messages GET /apps/:app_uuid/conversations/:conversation_uuid/messages Get all messages in a conversation
Get a message GET /apps/:app_uuid /conversations/:conversation_uuid/messages/:message_uuid Retrieve a single Message
Delete a message DELETE /apps/:app_uuid /conversations/:conversation_uuid/messages/:message_uuid Delete a message for all recipients
Get a message part GET /apps/:app_uuid /conversations/:conversation_uuid/messages/:message_uuid/parts/:message_part_uuid Get a message part from a specific message.
Get all message parts of a message GET /apps/:app_uuid /conversations/:conversation_uuid/messages/:message_uuid/parts Get all message parts for a specific message.
Add a message part POST /apps/:app_uuid /conversations/:conversation_uuid/messages/:message_uuid/parts Add a message part to a message.
Remove a message part DELETE /apps/:app_uuid /conversations/:conversation_uuid/messages/:message_uuid/parts/:message_part_uuid Remove a message part from a message.
Update a message part PUT /apps/:app_uuid /conversations/:conversation_uuid/messages/:message_uuid/parts/:message_part_uuid Update a message part of a message.
Replace all message parts PUT /apps/:app_uuid /conversations/:conversation_uuid/messages/:message_uuid/parts Replace all message parts of a message.

Send message

Every Conversation you receive from the Server API will include this endpoint in the messages_url property. Using messages_url will help future-proof your application.

Parameters:

Name Type Description
sender_id string Identity ID of the user to be set as sender of the message
parts MessagePart[] Array of MessagePart objects that comprise this message
parts.id string (optional) Message part id of the form layer:///messages/:message_uuid/parts/:message_part_uuid
parts.body string Text or base64-encoded data for this message part
parts.mime_type string “text/plain”, “image/png” or other MIME type describing the body of this MessagePart
parts.encoding string (optional) Specify ‘base64’ if the body is base64-encoded
parts.content.id string (optional) ID of the content upload (see Requesting upload below)
parts.content.size number (optional) Size of the content upload (see Requesting upload below)
notification object See Notifications for details
schedule object See Delayed Messaging for details
significance object See Significance for details

HTTP request:

POST/apps/:app_uuid/conversations/:conversation_uuid/messages

Example:

{
    "sender_id": "layer:///identities/1234",
    "parts": [
        {
            "body": "Hello, World!",
            "mime_type": "text/plain"
        },
        {
            "body": "YW55IGNhcm5hbCBwbGVhc3VyZQ==",
            "mime_type": "image/jpeg",
            "encoding": "base64"
        },
        {
            "mime_type": "image/png",
            "content": {
                "id": "layer:///content/7a0aefb8-3c97-11e4-baad-164230d1df67",
                "size": 10001
            }
        }
    ],
    "notification": {
        "title": "New Alert",
        "text": "This is the alert text to include with the Push Notification.",
        "sound": "chime.aiff"
    },
    "significance": {
        "default": "low",
        "recipients": {
            "layer:///identities/5678": "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/<conversation_uuid>/messages\
 -d '{"sender_id":"layer:///identities/1234","parts":[{"body":"Hello, World!","mime_type":"text/plain"},{"body":"YW55IGNhcm5hbCBwbGVhc3VyZQ==","mime_type":"image/jpeg","encoding":"base64"},{"mime_type":"image/png","content":{"id":"layer:///content/7a0aefb8-3c97-11e4-baad-164230d1df67","size":10001}}],"notification":{"title":"New Alert","text":"This is the alert text to include with the Push Notification.","sound":"chime.aiff"},"significance":{"default":"low","recipients":{"layer:///identities/5678":"normal"}}}'

Possible responses:

Message sent successfully | Status: 201 (Created)

Message

Discussion

Note

For developers who have used SAPI 1.0 where sending a Message as a bot is done using just “sender.name”: “Moderator”, make special note of this section:

All users within the Layer Platform are represented by Identities. Even a bot must have an Identity defined if it is to send a Message. This is a change from previous behaviors where a bot was simply an arbitrary string sent as part of the sender.name property. These APIs no longer accept sender.user_id nor sender.name, but instead require a single sender_id that identifies the Identity this message is being sent from, regardless of whether it is a Human or Bot.

Get messages

This endpoint will retrieve all messages in a conversation

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/apps/:app_uuid/conversations/:conversation_uuid/messages

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>/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/apps/:app_uuid/conversations/:conversation_uuid/messages/:message_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>/messages/<message_uuid>

Possible responses:

Got message successfully | Status: 200 (OK)

Message

Delete a message

Parameters:

This method takes no parameters.

HTTP request:

DELETE/apps/:app_uuid/conversations/:conversation_uuid/messages/:message_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>/messages/<message_uuid>

Possible responses:

Deleted message successfully
Status: 204 (No Content)
(Empty body)

Get a message part

Parameters:

This method takes no parameters.

HTTP request:

GET/apps/:app_uuid/conversations/:conversation_uuid/messages/:message_uuid/parts/:message_part_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>/messages/<message_uuid>/parts/<message_part_uuid>

Possible responses:

Message part successfully read | Status: 200 (OK)

{
    "id": "layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
    "url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
    "message_url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f",
    "mime_type": "text/plain",
    "body": "This is the message.",
    "updated_at": "2017-05-15T18:05:09Z"
}

Not allowed to add amessage part | Status: 403 (Forbidden)

{
    "id": "permission_denied",
    "code": 999,
    "message": "The request could not be completed because you do not have sufficient permissions to perform the requested action.",
    "url": "http://docs.layer.com/reference/client_api#create-a-conversation"
}

A message or message part with the specified id could not be found.
Status: 404 (Not Found)
(Empty body)

Get all message parts of a message

Parameters:

This method takes no parameters.

HTTP request:

GET/apps/:app_uuid/conversations/:conversation_uuid/messages/:message_uuid/parts

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>/messages/<message_uuid>/parts

Possible responses:

Message parts successfully read | Status: 200 (OK)

[
    {
        "id": "layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
        "url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
        "message_url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f",
        "mime_type": "text/plain",
        "body": "This is the message.",
        "updated_at": "2017-05-15T18:05:09Z"
    },
    {
        "id": "layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/7d47c33a-8105-11e7-aa2d-1bcd3841c5f8",
        "url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/7d47c33a-8105-11e7-aa2d-1bcd3841c5f8",
        "message_url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f",
        "mime_type": "text/html",
        "body": "<html><body><p>Hello!</p></body></html>"
    }
]

Not allowed to add amessage part | Status: 403 (Forbidden)

{
    "id": "permission_denied",
    "code": 999,
    "message": "The request could not be completed because you do not have sufficient permissions to perform the requested action.",
    "url": "http://docs.layer.com/reference/client_api#create-a-conversation"
}

A message or message part with the specified id could not be found.
Status: 404 (Not Found)
(Empty body)

Add a message part

Parameters:

Name Type Description
id string (optional) Optional generated message part id URI for the new message type, if omitted the platform will generate one. The URI consists of the message id UUID and a message part UUID that is unique within the message.
mime_type string A mime type identifier for the body or content of the message.
body string (optional) A string representation of the in-stream message payload. Could be base64 encoded in which case encoding would be present.
encoding string (optional) String representing the encoding type of the body. Can be "base64" or null
content Content (optional) External content

HTTP request:

POST/apps/:app_uuid/conversations/:conversation_uuid/messages/:message_uuid/parts

Example:

{
    "id": "layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
    "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": "2017-09-09T04:44:47+00:00",
        "refresh_url": "https://api.layer.com/content/7a0aefb8-3c97-11e4-baad-164230d1df67",
        "size": 172114124
    }
}
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/<conversation_uuid>/messages/<message_uuid>/parts\
 -d '{"id":"layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7","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":"2017-09-09T04:44:47+00:00","refresh_url":"https://api.layer.com/content/7a0aefb8-3c97-11e4-baad-164230d1df67","size":172114124}}'

Possible responses:

Message part added successfully | Status: 201 (Created)

{
    "id": "layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
    "url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
    "message_url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f",
    "mime_type": "text/plain",
    "body": "This is the message.",
    "updated_at": "2017-05-15T18:05:09Z"
}

Not allowed to add amessage part | Status: 403 (Forbidden)

{
    "id": "permission_denied",
    "code": 999,
    "message": "The request could not be completed because you do not have sufficient permissions to perform the requested action.",
    "url": "http://docs.layer.com/reference/client_api#create-a-conversation"
}

A message with the specified id could not be found.
Status: 404 (Not Found)
(Empty body)

Remove a message part

Parameters:

This method takes no parameters.

HTTP request:

DELETE/apps/:app_uuid/conversations/:conversation_uuid/messages/:message_uuid/parts/:message_part_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>/messages/<message_uuid>/parts/<message_part_uuid>

Possible responses:

Message part removed successfully
Status: 204 (No Content)
(Empty body)

Not allowed to remove the message part | Status: 403 (Forbidden)

{
    "id": "permission_denied",
    "code": 999,
    "message": "The request could not be completed because you do not have sufficient permissions to perform the requested action.",
    "url": "http://docs.layer.com/reference/client_api#create-a-conversation"
}

A message or message part with the specified id could not be found.
Status: 404 (Not Found)
(Empty body)

Update a message part

Parameters:

Name Type Description
id string (optional) Optional generated message part id URI for the new message type, if omitted the platform will generate one. The URI consists of the message id UUID and a message part UUID that is unique within the message.
mime_type string A mime type identifier for the body or content of the message.
body string (optional) A string representation of the in-stream message payload. Could be base64 encoded in which case encoding would be present.
encoding string (optional) String representing the encoding type of the body. Can be "base64" or null
content Content (optional) External content

HTTP request:

PUT/apps/:app_uuid/conversations/:conversation_uuid/messages/:message_uuid/parts/:message_part_uuid

Example:

{
    "id": "layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
    "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": "2017-09-09T04:44:47+00:00",
        "refresh_url": "https://api.layer.com/content/7a0aefb8-3c97-11e4-baad-164230d1df67",
        "size": 172114124
    }
}
curl -X PUT \
     -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>/messages/<message_uuid>/parts/<message_part_uuid>\
 -d '{"id":"layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7","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":"2017-09-09T04:44:47+00:00","refresh_url":"https://api.layer.com/content/7a0aefb8-3c97-11e4-baad-164230d1df67","size":172114124}}'

Possible responses:

Message part updated successfully | Status: 200 (OK)

{
    "id": "layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
    "url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
    "message_url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f",
    "mime_type": "text/plain",
    "body": "This is the message.",
    "updated_at": "2017-05-15T18:05:09Z"
}

Not allowed to update a message part | Status: 403 (Forbidden)

{
    "id": "permission_denied",
    "code": 999,
    "message": "The request could not be completed because you do not have sufficient permissions to perform the requested action.",
    "url": "http://docs.layer.com/reference/client_api#create-a-conversation"
}

A message or message part with the specified id could not be found.
Status: 404 (Not Found)
(Empty body)

Replace all message parts

Parameters:

Name Type Description
id string (optional) Optional generated message part id URI for the new message type, if omitted the platform will generate one. The URI consists of the message id UUID and a message part UUID that is unique within the message.
mime_type string A mime type identifier for the body or content of the message.
body string (optional) A string representation of the in-stream message payload. Could be base64 encoded in which case encoding would be present.
encoding string (optional) String representing the encoding type of the body. Can be "base64" or null
content Content (optional) External content

HTTP request:

PUT/apps/:app_uuid/conversations/:conversation_uuid/messages/:message_uuid/parts

Example:

[
    {
        "id": "layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/9f598fba-b55a-4727-948d-d15197f6b405",
        "mime_type": "text/plain",
        "body": "This is the message."
    },
    {
        "id": "layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
        "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/content/7a0aefb8-3c97-11e4-baad-164230d1df67",
            "size": 172114124
        }
    }
]
curl -X PUT \
     -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>/messages/<message_uuid>/parts\
 -d '[{"id":"layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/9f598fba-b55a-4727-948d-d15197f6b405","mime_type":"text/plain","body":"This is the message."},{"id":"layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7","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/content/7a0aefb8-3c97-11e4-baad-164230d1df67","size":172114124}}]'

Possible responses:

Message parts updated successfully | Status: 200 (OK)

{
    "note": "Look at the notes"
}

Not allowed to replace message parts | Status: 403 (Forbidden)

{
    "id": "permission_denied",
    "code": 999,
    "message": "The request could not be completed because you do not have sufficient permissions to perform the requested action.",
    "url": "http://docs.layer.com/reference/client_api#create-a-conversation"
}

A message with the specified id could not be found.
Status: 404 (Not Found)
(Empty body)

Discussion

Note

  1. The input data has to be a JSON array of objects with the fields specified in the properties section
  2. The example actually returns the following data:
[
  {
    "id": "layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/9f598fba-b55a-4727-948d-d15197f6b405",
    "url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/9f598fba-b55a-4727-948d-d15197f6b405",
    "message_url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f",
    "mime_type": "text/plain",
    "body": "This is the message.",
    "updated_at": "2017-05-15T18:05:09Z"
  },
  {
    "id": "layer:///messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
    "url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f/parts/aedf4b6b-a9d9-40f2-ac86-3e959a3f99a7",
    "message_url": "https://api.layer.com/messages/dd1894ab-d74d-42e7-8d77-fe134604502f",
    "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/content/7a0aefb8-3c97-11e4-baad-164230d1df67",
      "size": 172114124
    },
    "updated_at": "2017-05-15T18:05:09Z"
  }
]