Files

Upload files so that you can use them in other endpoints. For example, you may upload an audio file so you can use it in a Voice Campaign.

A file is uploaded in two steps - the initialisation and the upload. Once you have initialised a "bucket" to upload the file into, you can either upload the file using a POST or PUT request.

• For a POST upload, you need to create a FormData object and use it as the request body.

• For a PUT upload, you just need to include two extra properties in the initialisation step, and then you can upload without the FormData object.

Restricted File Types

.ade, .adp, .app, .asp, .bas, .bat, .cer, .chm, .cmd, .com, .cpl, .crt, .csh, .der, .exe, .fxp, .gadget, .hlp, .hta, .inf, .ins, .isp, .its, .js, .jse, .ksh, .lib, .lnk, .mad, .maf, .mag, .mam, .maq, .mar, .mas, .mat, .mau, .mav, .maw, .mda, .mdb, .mde, .mdt, .mdw, .mdz, .msc, .msh, .msh1, .msh2, .mshxml, .msh1xml, .msh2xml, .msi, .msp, .mst, .ops, .pcd, .pif, .plg, .prf, .prg, .reg, .scf, .scr, .sct, .shb, .shs, .sys, .ps1, .ps1xml, .ps2, .ps2xml, .psc1, .psc2, .tmp, .url, .vb, .vbe, .vbs, .vps, .vsmacros, .vss, .vst, .vsw, .vxd, .ws, .wsc, .wsf, .wsh, .xnk

POST Upload File (Part 1 - Initialise)

https://api.app.message2give.com/2019-01-23/organisations/{workspace_id}/files/{file_type}

Authentication Required: Yes

Description

Initialises a bucket for your file to be uploaded to.

• To upload a file with the POST method, you need to add the received API response to a FormData object. This process is show below.

• To upload a file with the PUT method, you need to include some extra properties in the request body of this step.

Path Parameters

• workspace_id: the ID of your workspace.

• file_type: the type of file you are uploading. The supported values are:

  • oa - outbound attachments. Used for MMS and Email. Allows: .jpg, .jpeg, .png, .gif, .wav, .mp3, .3gp, .mp4, .mpg, .mpeg, .avi, .pdf, .vcf, .vcard, .cal

  • aud - audio files. Used for Voice Campaigns and Surveys. Allows: .wav

  • tgts - target files. Used for Campaign contact-list files. Allows: .csv

Body Properties

• name: the file's display name - eg emails.csv

• duration: (audio files only) duration of the audio in seconds

• processors: (outbound attachments only) only accepts the value of ['optimise.mms']. Including this property will automatically optimise the file's size for MMS.

PUT-Required Body Properties

• uploadMethod*: only accepts "put"

• contentType*: only accepts "text/csv"

For File Uploads with POST

Your JSON response will look something like this:

{
    "fields": {
        "Policy": "xxxx",
        "X-Amz-Algorithm": "xxxx",
        "X-Amz-Credential": "xxxx",
        "X-Amz-Date": "xxxx",
        "X-Amz-Security-Token": "xxxx",
        "X-Amz-Signature": "xxxx",
        "bucket": "xxxx",
        "key": "xxxx"
    },
    "id": "xxxx",
    "url": "xxxx",
    "status": "OK"
}

With this request complete, you will need to take each of the properties in the "fields" object and add them to a FormData object along with your csv file. Below is how to do this using javascript.

let formData = new FormData();
for (let k in response.data.fields) {
  formData.append(k, response.fields[k]);
}
formData.append('file', file);

Ensure you also save the "id" and "url" property for later.

In the second step, you will make a POST request to the "url" with the FormData object as the body.

Code Snippet

POST Upload File - (Part 2 - POST Upload)

{file_url}

Authentication Required: No

Description

Upload your file to the bucket.

Path Parameters

• file_url: the "url" value from the initialisation step.

Body Properties

The request body should be the FormData object you created in the initialisation step.

Code Snippet

PUT Upload File (Part 2 - PUT Upload)

{file_url}

Authentication Required: Yes

Description

Upload your file to the bucket.

Path Parameters

• file_url: the "url" value from the initialisation step.

Body Properties

• file*: the file you are uploading.

Code Snippet

GET File

https://api.app.message2give.com/2019-01-23/organisations/{workspace_id}/files/{file_id}

Authentication Required: Yes

Description

Retrieve information about a file.

Path Parameters

• workspace_id: the ID of your workspace.

• file_id: the ID of the file you are retrieving. This ID can be found in the API response to the initialisation step of a file upload.

{
    "file": {
        "records": 3,
        "parsed": 3,
        "phoneColumns": [
            "0"
        ],
        "samples": [
            [
                "phone",
                "name"
            ],
            [
                "61000000000",
                "John"
            ],
            [
                "61000000001",
                "Sarah"
            ]
        ],
        "type": "tgts",
        "created": "2023-09-29T00:28:57.215Z",
        "size": 264,
        "smsColumns": [
            "0"
        ],
        "columnStatistics": {
            "0": {
                "mobile": 2,
                "phone": 2,
                "email": 0
            },
            "1": {
                "mobile": 0,
                "phone": 0,
                "email": 0
            }
        },
        "updated": "2023-09-29T00:28:58.525Z",
        "filename": "emails.csv",
        "id": "123456",
        "complete": true,
        "emailColumns": [],
        "url": "xxxx",
        "urlExpires": "2023-09-29T00:49:43.000Z"
    },
    "status": "OK"
}

Code Snippet