Resources

Creating a resource

To create a new resource you can use the /resources endpoint.

The following fields are mandatory:

  • name
  • scope
  • mimeType
  • derefUri
  • JSON
  • XML

{{codeStart}}

HTTP 1.1 POST https://api.<region>.whispir.com/resources?apikey=[your_api_key]

Authorization: Basic asdf98nf89asdvasd2r398h8sdf

x-api-key: your_api_key

Content-Type: application/vnd.whispir.resource-v1+json

{

"name" : "test.csv",

"scope" : "private",

"mimeType" : "text/csv",

"derefUri" : "...base64 representation..."

}

{{codeEnd}}

 

Response

HTTP 1.1 201 Created
...
Location: http://api.<region>.whispir.com/resources/4FBBC384BCE3DAABFE3
...


High-level response elements

name

String

Specifies the name of the file being uploaded. The file extension can be present in the name too. For example, ‘australia-contacts.csv’.

Note: Names should not contain spaces or special characters other than ‘-’ and ‘.’. This helps with searching and valid URL links.

For example, ‘australia-contacts.csv’ is better than ‘australia contacts.csv’ as the latter converts to ‘australia%20contacts.csv’.

scope

String

Specifies the permission scope of the file being uploaded.

The scope defines the access restriction of the resource. It can be only one of the following:

  • Public: Public files have an addressable URL and are available publicly.
  • Private: Private files have no URL and are only available for bulk messaging purposes and for importing contacts.

mimeType

String

The mime type of the file that is being uploaded. The type is dependent on the scope of the resource.

  • Public: Public files can be any mimetype. text/HTML; text/CSV
  • Private: Private files are restricted to CSV, JSON and XML.

derefUri

String

The base64 representation of the file being submitted.


Note: When you’re creating a resource, the following conditions apply:

  • Maximum of 10 MB per file being uploaded.
  • Transactions have an enforced timeout.
  • Resources are available in the Whispir platform for a limited time (90 days). After this time they are automatically cleaned. This is a configurable setting for Whispir Administrators.


Example resources

The following are all equivalent representations of the same data structure, across the three supported formats.

 

1. CSV format

As the CSV file format doesn't support structured objects, they have been omitted from the dataset. 

fullname,email,mobile,streetaddress,suburb,manifest.name,manifest.value.timestamp

Franco Himboli,fhimboli@gmail.com,0410509001,123 Auburn Rd,Hawthorn,Delivery Manifest,20-10-2014 10:24

Jordan Windsor,jwindsor@yahoo.com,0410509002,360 Walsh Rd,North Melbourne,Delivery Manifest,20-10-2014 10:24

 

2. JSON format

See the JSON example below.

 

3. XML

See the XML example below.

  • JSON
  • XML

{{codeStart}}

[{

"fullname": "Franco Himboli",

"email": "fhimboli@gmail.com",

"mobile": "0410509001",

"streetaddress": "123 Auburn Rd",

"suburb": "Hawthorn",

"Reference": "Xpress Mail",

"MsgData" : {

"POBDetail": {

"DateAndTime" : "09-Sep-2019 12:15 PM",

"Message" : "Please let us know if the time slot is acceptable. Respond with a 'No' to get alternative time slot"

}

}

},

{

"fullname": "Jordan Windsor",

"email": "jwindsor@yahoo.com",

"mobile": "0410509002",

"streetaddress": "360 Walsh Rd",

"suburb": "North Melbourne",

"Reference": "Xpress Mail",

"MsgData" : {

"POBDetail": {

"DateAndTime" : "09-Sep-2019 12:30 PM",

"Message" : "Please let us know if the time slot is acceptable. Respond with a 'No' to get alternative time slot"

}

}

}]

{{codeEnd}}

 

Once you have your data in one of these 3 formats, you need to convert it to Base64 format. But before you can do that, let’s create a message template to determine what we actually want to send to recipients.