Uploading content for notifications

To send a visual notification using banners or videos, you need to first create a reference to that content inside our system.

You do this by creating "Content Items", which can either be stored in our S3 storage and distributed via our Cloudfront CDN, or on your own hosting.

Content items have a type associated with them which determines additional options and how they can be used. Video, for example, can have the fullscreen option, an array of buttons, whereas banners don't have any options. These options are set on a per-notification basis, rather than being stored alongside the content item to make it easier to reuse assets in different ways.

If you're going to use our hosting and CDN, you'll first need to upload the content to S3.

The process requires two steps:

1. Creating a content item, and getting a secure S3 upload URL.
2. Uploading the content to Amazon S3 using the credentials from the previous call.

Getting upload URL

We will be making an HTTP call that will get us content upload URL to which we will make a POST call. Handily, by making this call a new Content Item will also be created for us:

POST /v1/content-item/get-upload-data

{
  "name": "<A unique name for your content>",
  "filename": "your-video-file.mp4",
  "mediaType": "VIDEO",
  "presentation": ["DEFAULT"]
}

mediaType attribute can either be VIDEO, IMAGE or OTHER.

presentation is an array where each item is enum value of ["DEFAULT", "BANNER", "BUTTON", "CAROUSEL"].

As noted before, we use Amazon S3 to securely store your content and to make it easier to distribute. The response to the get-upload-data call will include the S3 signed POST URL with the POST data fields you'll need to supply, along with newly created Content Item details.

Uploading to S3

In the postData.url and postData.fields values from the get-upload-data call you have everything you need to make a direct request to upload the content into the right place in S3. A example to do this in Javascript using the axios library and FormData can be

const formData = new FormData();

Object.keys(postData.fields).forEach((key) => {
  formData.append(key, postData.fields[key]);
});
formData.append('file', file);

await axios.post(postData.url, formData);

Make sure the file is the last field you append to the form as AWS will disregard all other fields after processing the file.

You can read in more detail the process of uploading to S3 even in different languages on the AWS website.

One small gotcha - you won't get a 200 response back from the S3 URL, you'll get a 204. This is OK, and is confirming the content was uploaded, so when writing your code, you'll need to handle that slightly odd case.

The secure S3 URL is only valid for 24 hours. If content did not get uploaded to S3 within 24 hours we will auto-remove the Content Item, you'll also need to get a new URL and try the upload again.

Congratulations! Now you have a Content Item created, the content in S3 ready for attaching and sending. If you've followed the previous step and have a segment already, or are only sending to a few subscribers, it's time to create a notification!

If you're doing a notification with banners, or image buttons (or both!) you will need to do several uploads to get everything you need for a single notification uploaded.