Messaging Media Uploads

When replying to messages from Genesys Cloud, media can be used in the reply message. There are 3 steps associated with this workflow.

1. Generate the mediaId
2. Upload the media
3. Use the mediaId in #1, to send the media message

Note: There are content and size restrictions associated with the media that can be uploaded. See MMS messaging and Social Messaging

Use GET /api/v2/conversations to get the active conversations, to gather the required info needed.

Request: GET https://api.mypurecloud.com/api/v2/conversations

Response:

{
  "entities": [
    {
      "id": "31594bb4-9611-40ff-a4bd-ab0f27e65126" //This is the conversationId
      "participants": [
        {
          "purpose": "agent",
          "messages": [
            {
              "id": "acd98233-d3e2-4abd-ac82-9e19087df3f5" //This is the communicationId
              "messages": []
            }           
          ]
        }
      ]
    }
  ],
  "pageSize": 1
}

Now call POST /api/v2/conversations/messages/{conversationId}/communications/{communicationId}/messages/media. No Body is required here. Use the above example to find the conversationId and communicationId. The response will contain an id which will be referred to throughout as the mediaId, and an uploadUrl to upload the media to.

Request: POST https://api.mypurecloud.com/api/v2/conversations/messages/31594bb4-9611-40ff-a4bd-ab0f27e65126/communications/acd98233-d3e2-4abd-ac82-9e19087df3f5/messages/media

Response:

{
  "id": "84afaa85-bfaa-40bf-bc37-a534cfa0e0c9", //This is the mediaId
  "uploadUrl": "https://apps.mypurecloud.com/uploads/v4/services/messaging/4c5257d2-9943-4360-bc22-dd29cd0528dc",
  "status": "uploading"
}

Use the response from the above POST. The uploadUrl will be the resource that will be used to upload the media. Note: this is not a public api resource url that can be determined by the consumer. It is only obtained using the response to the previous POST messages/media mentioned above.

The upload method for attachments is a multi-part post. For more information, checkout multipart/form-data at http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4 (Form content types).

The request headers should include the Authorization header with the same bearer token that is used to make other API requests. The body of the POST should be a form encoded value with the following details:

This is a javascript example that will use file data from an input with type = file. The url in the example, was from the above uploadUrl response to the POST messages/media request.

function uploadAttachment(authToken, file) {
    var form = new FormData();
    form.append('file', file);
    
    $.ajax({
             url: 'https://apps.mypurecloud.com/uploads/v4/services/messaging/4c5257d2-9943-4360-bc22-dd29cd0528dc',
             method: 'POST',
             headers: {
               Authorization: 'bearer ' + authToken
             },
             processData: false,
             contentType: false,
             mimeType: 'multipart/form-data',
             data: form
           });
}

The status of the media can be checked with GET /api/v2/conversations/messages/{conversationId}/communications/{communicationId}/messages/media/{mediaId}. The response will contain a status field. If everything was performed correctly with uploading the media, the status would transition to "valid".

Request: GET https://api.mypurecloud.com/api/v2/conversations/messages/31594bb4-9611-40ff-a4bd-ab0f27e65126/communications/acd98233-d3e2-4abd-ac82-9e19087df3f5/messages/media/84afaa85-bfaa-40bf-bc37-a534cfa0e0c9

Response:

{
  "id": "84afaa85-bfaa-40bf-bc37-a534cfa0e0c9",
  "status": "valid"
}

Sending the media in the message can be done either after the status is "valid" or before. If done before the media status is valid, the message won't be sent until the media is valid.

Now the media can be sent in a message. To do that call POST /api/v2/conversations/messages/{conversationId}/communications/{communicationId}/messages and supply the mediaId from above in the mediaIds[] field.

Request: POST https://api.mypurecloud.com/api/v2/conversations/messages/31594bb4-9611-40ff-a4bd-ab0f27e65126/communications/acd98233-d3e2-4abd-ac82-9e19087df3f5/messages

Body

{
  "mediaIds": ["84afaa85-bfaa-40bf-bc37-a534cfa0e0c9"]
}