Dynamic and Bulk Messages

Whispir’s API allows users to upload structured data, and dynamically process the content of SMS, email, voice, web or social media messages. This is useful when you’re sending outbound communications in bulk and want to replace the placeholders with different values per contact, as taken from a spreadsheet, data file or database table

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 the specific values for that contact):

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 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

IMPORTANT: when you will retrieve a previously sent message the at-at variables will be left unresolved because the same message ID might correspond to a message sent to thousands of recipients and Whispir won't list all its instances. If you are interested in getting the values that were received by customers when the message is replied or undeliverable you can use Callbacks to get them back within their Custom Parameters

Sending dynamic messages

Step 1: Upload the resource file via the API

Applications will use the /resources endpoint to store the source files for dynamic messages. For further information about please visit the Resources section

IMPORTANT: when uploading resource files please ensure that their name will be different from the ones already available in your /resources endpoint. This will prevent any wrong reference and/or unexpected behaviour. Whispir recommends to append a timestamp to the file name as a good practice

NOTE: Whispir has a hard limit on the size of uploaded files of 10MB after Base 64 conversion. Base 64 conversion increases the size of files up to 30%, so it is strongly recommended to keep the batch size below 7MB

  • JSON
  • XML

File structure

Given the example above our file to upload would basically have the following structure. You can then represent it in CSV, JSON or XML

{{codeStart}}

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

| first_name | last_name | mobile | amount_due | due_date |

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

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

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

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

{{codeEnd}}

Uploading the resource

{{codeStart}}

POST https://api.<region>.whispir.com/resources

 

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_file_08-06-2020_18.07.34.json",

"scope" : "private",

"mimeType" : "application/json",

"derefUri" : "base64 encoded representation of the JSON file"

}

{{codeEnd}}

 

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

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, Whispir’s messaging engine takes the information and processes it in the bulk sendout using the /messages endpoint

IMPORTANT: in order to successfully send the message please check that the Resource to be used belongs to the same Workspace from which the Bulk Message will be sent

IMPORTANT: despite targeting the /messages endpoint, please notice that when it comes to sending Bulk Messaging has different Content-Type and Accept headers

There are actually two ways to use the resource:

  • one-off message
  • with a Template
  • JSON
  • XML

Sending a one-off bulk message using the resource

{{codeStart}}

POST https://api.<region>.whispir.com/messages

 

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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}}

Sending the bulk message with a Template using the resource

{{codeStart}}

POST https://api.<region>.whispir.com/messages

 

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

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

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

 

{

"resource" : {

"resourceId" : "resource_id",

"smsMappingField" : "mobile",

"emailMappingField" : "",

"voiceMappingField" : "",

"options" : {

"resolveRecipients" : ""

}

},

"messageTemplateId" : "2314CF95157C5F77",

"subject" : "",

"body" : "",

"email" : {

"body" : "",

"footer" : "",

"type" : ""

},

"voice" : {

"header" : "",

"body" : "",

"footer" : "",

"other" : "",

"type" : ""

},

"web" : {

"body" : "",

"type" : ""

},

"callbackId" : ""

}

{{codeEnd}}

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.