Rich content endpoints

The process for sending rich content is:

  1. POST /content, receive an upload_url and Content ID
  2. Upload your data to the upload_url; see Google Cloud Storage Documentation for more detail
  3. Create a message (POST /conversations/:conversation_uuid/messages) with the Content ID within a MessagePart.
Method HTTP request Description
Request upload POST /apps/:app_uuid/conversations/:conversation_uuid/content Request an endpoint to upload content
Send upload POST /apps/:app_uuid/conversations/:conversation_uuid/messages Send a message with Rich Content
Refresh URL GET /apps/:app_id /conversations/:conversation_id/content/:content_id Get a new download_url for Rich Content

Request upload

Message parts can be up to 2KB in size. To send larger content, upload your content to a secure URL provided by requesting an upload.

Parameters:

Name Type Description
Upload-Content-Type string HTTP header containing the MIME type of the content to be uploaded
Upload-Content-Length integer HTTP header containing the size (in bytes) of the content to be uploaded
Upload-Origin string (optional) HTTP header containing the origin the upload is coming from (for CORS support in browsers)

HTTP request:

POST/apps/:app_uuid/conversations/:conversation_uuid/content

Example:

curl  -X POST \
      -H 'Accept: application/vnd.layer+json; version=3.0' \
      -H 'Authorization: BEARER <TOKEN>' \
      -H 'Content-Type: application/json' \
      -H 'Upload-Content-Type: image/jpeg' \
      -H 'Upload-Content-Length: 10000' \
      -H 'Upload-Origin: http://mydomain.com' \
      https://api.layer.com/apps/<app_uuid>/conversations/<conversation_uuid>/content

Possible responses:

Content requested successfully | Status: 201 (Created)

{
    "id": "layer:///content/3d0736d9-1a50-4e9a-a9b3-2400caa9e161",
    "download_url": null,
    "expiration": null,
    "upload_url": "https://www.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=resumable&upload_id=xa298sd_sdlkj2"
}

Discussion

You must upload your data to the upload_url in the response before sending a message itself.

Note

Your content must have completed uploading before you can send the Message

Send upload

After your data has finished uploading, you can send a message, in which one or more parts contain a Content object with the ID of your upload.

Parameters:

Name Type Description
part.content.id string Content ID (eg layer:///content/cbf5f150-2f45-11e5-82f7-0242ac1100e3)
part.content.size integer Size of the file that was uploaded; should match the Upload-Content-Length header
part.mime_type string text/plain, image/png, or other MIME type describing the message part

HTTP request:

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

Example:

{
    "parts": [
        {
            "mime_type": "text/plain",
            "body": "This is the message."
        },
        {
            "mime_type": "image/png",
            "content": {
                "id": "layer:///content/7a0aefb8-3c97-11e4-baad-164230d1df67",
                "size": 10001
            }
        }
    ]
}
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 '{"parts":[{"mime_type":"text/plain","body":"This is the message."},{"mime_type":"image/png","content":{"id":"layer:///content/7a0aefb8-3c97-11e4-baad-164230d1df67","size":10001}}]}'

Possible responses:

Message sent successfully | Status: 201 (Created)

Message

Refresh URL

The download_url on a Content object will expire; expiration time can be seen in the Content object’s expiration field. You can then request a new download_url.

Parameters:

Name Type Description
content_id string ID of the Content object to refresh

HTTP request:

GET/apps/:app_id/conversations/:conversation_id/content/:content_id

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_id>/conversations/<conversation_id>/content/<content_id>

Possible responses:

Got content details successfully | Status: 200 (OK)

{
    "id": "8a896e15-2908-4d7c-9f4e-d47e18ae2774",
    "download_url": "http://google-testbucket.storage.googleapis.com/some/download/path",
    "expiration": "2014-09-09T04:44:47+00:00",
    "upload_url": null
}

Discussion

The GET request will only work if data was actually uploaded to cloud storage. If you create a Content resource but never uploaded data, this request will fail.