Messages

Dynamic and bulk messages

Whispir allows you send messages with dynamic content. This is useful when you’re sending SMS messages or emails in bulk and want to replace the placeholders or variables with values from a spreadsheet, data file or database table.

This can be achieved easily by uploading a file with the message content and the message recipient information. Whispir’s messaging engine takes the information and processes it in the bulk sendout.

This process allows you to easily specify recipient information in the file and have it processed within the message content.

The file can be saved and uploaded to Whispir’s bulk messaging engine. As a result, Whispir proposes the following variables to be available for use in the message:

  • @@first_name@@
  • @@last_name@@
  • @@mobile@@
  • @@amount_owed@@
  • @@date_due@@

You then have the option to construct a message using this information, and Whispir will dynamically replace the variables at send time. For example, your message content could be as follows:

Hi @@first_name@@. Your account is currently outstanding, with the amount of @@amount_due@@ being due on @@due_date@@. Please make every effort to pay your account on time. If you would like more information, please contact us on 1800 000 000, regards.

After processing, the recipient would receive a message that could look as follows (substituting the @@tags@@ with sample data):

Hi Jono. Your account is currently outstanding, with the amount of $1000.00 being due on 21/08/2019. Please make every effort to pay your account on time. If you would like more information, please contact us on 1800 000 000, regards.

Sending dynamic messages

Sending bulk message is an easy two-step process:

  1. Upload the resource file via the API (CSV, JSON or XML).
  2. Create a new message using the resource file as the source data.


Step 1: Upload the resource file via the API

To upload a file to Whispir’s API, you make an API call to the /resources endpoint.

Applications can use this endpoint to store the source files for dynamic messages. This endpoint can also be used to store any file-based data (for example, images, PDF documents and spreadsheets) for an unlimited amount of time.

Note: The types of files allowed are: CSV, JSON, XML, images (JPEG, PNG0 and WAV.

For information about the /resources endpoint see Resources.

Step 2: Invoke the bulk message with reference to the resource ID and the desired content

Once the resource file has been uploaded and the location of the resource has been returned, applications can use this to populate a dynamic message using the /messages endpoint.

Dynamic messaging

Method definition and descriptions

Name

Value

Service URL

https://api..whispir.com/messages

https://api..whispir.com/workspaces/[id]/messages

Methods supported

GET, POST

Request MIME type

application/vnd.whispir.bulkmessage-v1+xml

application/vnd.whispir.bulkmessage-v1+json

/messages:

GET

Provides a list of all the currently sent messages within the company or workspace (URIs).

POST

Creates and sends a new message/bulk message.

/messages/{id}:

GET

Retrieves the representation of the requested message.

POST

NOT SUPPORTED

Note: The endpoint doesn't support PUT and DELETE in bulk messages. Similarly there is no POST for the /messages/{id}.

Request components

The structure of the bulk message is used to define the resource that should be used in the sendout. It also gives you the ability to override the message content in the event that a message template is not desired.

Main section:

messageTemplateId

The resource identifier of the message template that should be used for this request.

Sample value: 4FBBC384BCE3DAABFE3

callbackId

The ID of the callback to be used for responses to this message.

Sample value: SampleCallback

Note: Callback IDs are configured by Company Administrators within the Whispir platform.

Resource section:

resourceId

The resource identifier returned from the POST to /resources.

The resource referred to must be a valid CSV file.

Sample value: 384BCE34FBBCDAABFE3

smsMappingField

The column name from within the CSV file that refers to the field on each row that should be used for SMS messages.

Sample value: Mobile

Note: This field will default to ‘mobile’ if it’s present in the file and but is not populated.

emailMappingField

The column name from within the CSV file that refers to the field on each row that should be used for email messages.

Sample value: Email

Note: This field will default to ‘email’ if it’s present in the file but is not populated.

voiceMappingField

The column name from within the CSV file that refers to the field on each row that should be used for voice messages.

Sample value: Mobile

Note: This field will default to ‘mobile’ if it’s present in the file but is not populated.

options

This specifies other options that are available within the bulk message.

  • resolveRecipients (true/false): Whether recipients should be resolved to contacts in the Whispir workspace. Default: True for less than 5000 recipients.

Message content section (required when no template is used):

Subject

Defines the subject of the message. The subject also acts as the first line of the SMS message.

Sample value: Mary had a little lamb.

Body

The body of the SMS message being delivered.

Sample value: And its fleece was white as snow. Everywhere that Mary went, the lamb was sure to check her out in Foursquare. Soon, Mary was the president of the town.

Email section (required for email messages):

Body

The body of the email message being delivered.

Sample value: Jack and Jill went up the hill.

Footer

The footer of the email message being delivered. Usually used as an area for a signature.

Sample value: Regards, the well.

Type

The type of the email content.

Sample value: text/plain (default) / text/html.

Voice section (required for voice messages):

Header

The header of the voice content.

Sample value: The text-to-speech content of the introduction message for the voice call.

Body

The content of the voice message.

Sample value: The text-to-speech content of the body message for the voice call.

Type

The type parameter defines the other optional elements of the voice call.

Sample value: ConfCall:ConfAccountNo:ConfPinNo:ConfModPinNo:Pin:

Web section (required for web/rich push messages):

Body

The body of the web message

Sample value: The body content of the web message to be delivered.

Type

The type of the web message.

Sample value: text/plain (default) / text/html.

  • JSON
  • XML

Dynamic messages

Whispir’s API allows users to upload structured data, and process this line by line into outbound communications via SMS, email, voice, web or social media.

{{codeStart}}

|------------|------------|-------------|-------------|------------|

| First Name | Last Name | Mobile | Amount Owed | Date Due |

|------------|------------|-------------|-------------|------------|

| Jono | Johnson | +6590091234 | S$1000 | 21/08/2019 |

| Steve | Smith | +6590091235 | S$1100 | 22/08/2019 |

|------------|------------|-------------|-------------|------------|

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

"Accept": "application/vnd.whispir.bulkmessage-v1+json"

{

"resource" : {

"resourceId" : "resource_id", # From the resource you created

"smsMappingField" : "mobile",

"emailMappingField" : "",

"voiceMappingField" : "",

"options" : {

"resolveRecipients" : ""

}

},

"subject" : "Bulk Send Example",

"body" : "Hi @@first_name@@. Your account is currently outstanding, with the amount @@amount_due@@ being due on @@due_date@@. Please make every effort to pay your account on time. If you would like more information, please contact us on 1800 000 000, regards."

}

{{codeEnd}}

After processing, the first recipient would receive a message that looks like this:

{{codeStart}}

Hi Jono. Your account is currently outstanding, with the amount S$1000.00 being due on 21/08/2019. Please make every effort to pay your account on time. If you would like more information, please contact us on 1800 000 000, regards.

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

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

Accept: application/vnd.whispir.resource-v1+json

{

"name" : "sample.json",

"scope" : "private",

"mimeType" : "application/json",

"derefUri" : "//base64 encoded JSON content"

}

{{codeEnd}}

This will return a Resource ID that applications can use in the next step:

{{codeStart}}

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

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

{

"resource" : {

"resourceId" : "",

"smsMappingField" : "",

"emailMappingField" : "",

"voiceMappingField" : "",

"options" : {

"resolveRecipients" : ""

}

},

"messageTemplateId" : "",

"subject" : "",

"body" : "",

"email" : {

"body" : "",

"footer" : "",

"type" : ""

},

"voice" : {

"header" : "",

"body" : "",

"footer" : "",

"other" : "",

"type" : ""

},

"web" : {

"body" : "",

"type" : ""

},

"callbackId" : ""

}

{{codeEnd}}