Sending Dynamic Messages

Whispir's Dynamic Messages

Whispir's API allows you to dynamically populate the content of your messages from source data contained within your existing systems.  

From an SMS reminder about when a package is ready to be collected, or an E-mail notification about a payment being due, through to a Voice Call waking an employee up for a shift; Whispir's Dynamic Messages make it easy for application developers to trigger rich message content from existing information sources.

What is a Dynamic Message?

Whispir's Dynamic Messages allow application developers to use existing data sources as the driver to populate message content.  

Developers can submit content in JSON, XML or CSV formats, and Whispir can dynamically create messages using any piece of content provided.

Let's take an example where a payment reminder needs to be sent:

The existing back end system will have a database with the list of people, and payments that are due, e.g.

Name Mobile Number Amount Due
Fred Smith 61412345678 25.00
Steve Cleave 61498765432 72.00
Susan Summers 61401234567 100.52

The aim of Dynamic Messaging is to take each of these rows, and send each a message within a single Whispir process.  Application Developers could easily iterate through these recipients, and specify a single message to each using Whispir's existing messaging capabilities, however, Whispir's Dynamic Messaging will allow you to do this in a single process, resulting in a much faster delivery, and less code within your application.

To deliver this message using Whispir's Dynamic Messaging, 5 steps are required:

  1. Convert the source data to either JSON, CSV, or XML
  2. Create a Message Template in Whispir that uses this data
  3. Encode the JSON, CSV or XML in Base64
  4. Upload the encoded file to Whispir using the API
  5. Instruct Whispir to send a message using the uploaded file and an appropriate message template

Convert the source data to either JSON, CSV or XML

Developers need to convert their source information into a common language that Whispir can parse.  This information can be exported to either JSON, CSV or an XML file.

The samples below show how the database table above could be converted to one of these three formats.

JSON Sample

The above database information converted into a JSON file would look as follows:

[{
   "name" : "Fred Smith",
   "mobile" : "61412345678",
   "amount" : "25.00"
},{
   "name" : "Steve Cleave",
   "mobile" : "61498765432",
   "amount" : "72.00"
},{
   "name" : "Susan Summers",
   "mobile" : "61401234567",
   "amount" : "100.52"
}]

CSV Sample

The above database information converted into a CSV file would look as follows:

name,mobile,amount
Fred Smith,61412345678,25.00
Steve Cleave,61498765432,72.00
Susan Summers,61401234567,100.52   

XML Sample

The above database information converted into a valid Whispir XML file requires a little bit more processing.  The sample would look as follows:

<?xml version="1.0" encoding="UTF-8" ?>
<recipients>
    <recipient>
      <name>Fred Smith</name>
      <mobile>61412345678</mobile>
      <amount>25.00</amount>
    </recipient>
    <recipient>
      <name>Steve Cleave</name>
      <mobile>61498765432</mobile>
      <amount>72.00</amount>
    </recipient>
    <recipient>
      <name>Susan Summers</name>
      <mobile>61401234567</mobile>
      <amount>100.52</amount>
    </recipient>
</recipients>

Once you have your data in one of the above 3 formats, you need to convert it into Base64, but before we do that, let's create our Message Template to determine what we actually want to send to these recipients.

Create a Message Template in Whispir that uses this data

In this section we'll create our message template that will actually use the data that we've outlined above.  

Essentially, the simplest SMS that we would deliver to each recipients could be:

Hi Fred Smith, your payment amount of $25.00 is due tomorrow. Any questions, please call 1300 WHISPIR.

From a message template, we would simply replace the variables with placeholders as follows:

Hi @@name@@, your payment amount of $@@amount@@ is due tomorrow. Any questions, please call 1300 WHISPIR.

Any of the data elements that you specify in your JSON, CSV or XML payload can be used by simply surrounding them with @@ tags.  Nested elements can be accessed using the . (dot) operator.  E.g.

{
  "address" : {
    "line1" : "123 Auburn Road",
    "line2" : "",
    "suburb" : "Hawthorn",
    "postcode" : "3013"
  }
}

To access the address data in the message would look like:

@@address.line1@@
@@address.line2@@
@@address.suburb@@
@@address.postcode@@

In XML, the data needs to be in a specific customData block.  For further information about this, please contact apisupport@whispir.com.

Note: Creating Message Templates is described in detail here, so this section will simply show how to execute the request and ensure the Template is created.

Posting the following data to Whispir will create a message template.  The response to this request will contain the ID of the Message Template

HTTP 1.1 POST http://api.whispir.com/templates?apikey=<yourkey>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
Content-Type: application/vnd.whispir.template-v1+json 

{ 
  "messageTemplateName" : "Payment Reminder", 
  "subject" : "Reminder:", 
  "body" : "Hi @@name@@, your payment amount of $@@amount@@ is due tomorrow. Any questions, please call 1300 WHISPIR."
}

Response Example

The following is the expected result for when a Template has been created via the API:

HTTP 1.1 201 Created
Location: http://api.whispir.com/templates/BCD384BC3847CD3484CD?apikey=<yourkey>  

Now that you have created your message template, you can encode the source data into the format for transfer to Whispir via the API.

Encode the JSON, CSV or XML into Base64

In order to prepare the file to be uploaded to Whispir, it needs to be endcoded from it's textual representation into a Base64 encoded version.  Base64 is a common method of encoding binary data in ASCII format. Whispir uses it as a common method of exchange of file data.  It is also used when uploading attachments to messages in Whispir, or specifing custom WAV files for outbound voice calls.  More information about Base64 can be found here

Most programming languages will provide a facility to convert text into Base64.  A simple internet search for 'base 64 encode java', or 'base 64 encode PHP' will yeild results on how to accomplish this task.

JSON file encoded to Base64

The output after encoding the JSON Sample File into Base64 will look as follows:

W3sNCiAgICJuYW1lIiA6ICJGcmVkIFNtaXRoIiwNCiAgICJtb2JpbGUiIDogIjYxNDEyMzQ1Njc4
IiwNCiAgICJhbW91bnQiIDogIjI1LjAwIg0KfSx7DQogICAibmFtZSIgOiAiU3RldmUgQ2xlYXZl
IiwNCiAgICJtb2JpbGUiIDogIjYxNDk4NzY1NDMyIiwNCiAgICJhbW91bnQiIDogIjcyLjAwIg0K
fSx7DQogICAibmFtZSIgOiAiU3VzYW4gU3VtbWVycyIsDQogICAibW9iaWxlIiA6ICI2MTQwMTIz
NDU2NyIsDQogICAiYW1vdW50IiA6ICIxMDAuNTIiDQp9XQ==

This is now ready to be uploaded to Whispir.

Upload the encoded file to Whispir using the API

Using Whispir’s API, users will now be able to submit data payloads to be stored by Whispir and used in various API calls.  These files are uploaded through the Resources RESTful endpoint.

Using the  Resources endpoint, application developers can retrieve, submit, update and delete resources that are then used as part of either Whispir Bulk (Dynamic) Messages, or to be used for importing Contacts.  

The following details describe how application developers can use the  Resources endpoint through the Whispir API.

Name

Value

API URLs

https://api.whispir.com/resources?apikey=
https://api.whispir.com/workspaces/:id/resources?apikey=

Method

GET, POST

Request Headers

Authorization

The Base 64 representation of your Whispir Username and Password to authenticate the request.

Accept

application/vnd.whispir.resource-v1+xml
application/vnd.whispir.resource-v1+json

Content-Type

application/vnd.whispir.resource-v1+xml
application/vnd.whispir.resource-v1+json

Query String

apikey=

The Mashery API key to authenticate the request.

Response

200 OK

The request was successful

201 Created The resource has been created

401 Unauthorized

The authorization details provided in the Authorization header were incorrect.

415 Unsupported Media Type

The MIME type requested is not supported for the requested resource.

Method Descriptions

This section defines the methods that are available to the  resources endpoint URI’s.

URI

GET

POST

PUT

DELETE

/resources

Provides a list of all the currently saved resources in the Whispir Instance (URIs)

Creates a new resource for use in the API

METHOD not supported

METHOD not supported

/workspaces/[ID]/resources

Provides a list of all the currently saved resources in the Whispir Instance (URIs)

Creates a new resource for use in the API

METHOD not supported

METHOD not supported

Request Example

Application developers can use the request structure below to query the Whispir API to submit files for storage, or to manage the files that are currently stored within Whispir.

The request message for a resource consists of the following structure in XML and JSON:

XML Request to Upload the JSON Sample File

HTTP 1.1 POST http://api.whispir.com/resources?apikey=<yourkey>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
Content-Type: application/vnd.whispir.resource-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ns2:resource xmlns:ns2="http://schemas.api.whispir.com"> <name>test.json</name> <mimeType>application/json</mimeType> <scope>private</scope> <derefUri> W3sNCiAgICJuYW1lIiA6ICJGcmVkIFNtaXRoIiwNCiA gICJtb2JpbGUiIDogIjYxNDEyMzQ1Njc4IiwNCiAgICJhbW91bnQi IDogIjI1LjAwIg0KfSx7DQogICAibmFtZSIgOiAiU3RldmUgQ2xlY XZlIiwNCiAgICJtb2JpbGUiIDogIjYxNDk4NzY1NDMyIiwNCiAgIC JhbW91bnQiIDogIjcyLjAwIg0KfSx7DQogICAibmFtZSIgOiAiU3V zYW4gU3VtbWVycyIsDQogICAibW9iaWxlIiA6ICI2MTQwMTIzNDU2 NyIsDQogICAiYW1vdW50IiA6ICIxMDAuNTIiDQp9XQ== </derefUri> </ns2:resource>

JSON Request to Upload the JSON Sample File

HTTP 1.1 POST http://api.whispir.com/resources?apikey=<yourkey>
Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
Content-Type: application/vnd.whispir.resource-v1+json

{
  "name" : "test.json",
  "mimeType" : "application/json",
  "scope" : "private",
  "derefUri" : "W3sNCiAgICJuYW1lIiA6ICJGcmVkIFNtaXRoIiwNCiA
    gICJtb2JpbGUiIDogIjYxNDEyMzQ1Njc4IiwNCiAgICJhbW91bnQi
    IDogIjI1LjAwIg0KfSx7DQogICAibmFtZSIgOiAiU3RldmUgQ2xlY
    XZlIiwNCiAgICJtb2JpbGUiIDogIjYxNDk4NzY1NDMyIiwNCiAgIC
    JhbW91bnQiIDogIjcyLjAwIg0KfSx7DQogICAibmFtZSIgOiAiU3V
    zYW4gU3VtbWVycyIsDQogICAibW9iaWxlIiA6ICI2MTQwMTIzNDU2
    NyIsDQogICAiYW1vdW50IiA6ICIxMDAuNTIiDQp9XQ=="
}

Response Example

The following is the expected result for when a Resource has been uploaded via the API:

HTTP 1.1 201 Created
Location: http://api.whispir.com/resources/ABD435DBFCD663DEDEFF?apikey=<yourkey>  

Once your resource is updated, you can instruct Whispir to send a message to each of the recipients using the data within the resource.

Instruct Whispir to send a message using the uploaded file and an appropriate message template

If you have completed the steps above, you will have a Template ID that needs to be delivered, and a Resource ID that can be used as the recipients of the message.

Using these two key pieces of information, developers can submit an API request to kick off the Dynamic Messaging process.

POST https://api.whispir.com/messages?apikey=<yourkey>
Authentication: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
Content-Type: application/vnd.whispir.bulkmessage-v1+xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
   <resource>
      <resourceId>ABD435DBFCD663DEDEFF</resourceId>
   </resource>
   <messageTemplateId>BCD384BC3847CD3484CD</messageTemplateId>
</ns2:message>

The response to this request will be a  202 Accepted as follows:

Response Example

The following is the expected result for when a Resource has been uploaded via the API:

HTTP 1.1 202 Accepted
Location: http://api.whispir.com/messages/CDB938478CD6DBC3784C?apikey=<yourkey>  

Each of the recipients specified in the original file will now receive an SMS message with the content particulars that are relevant to them.  E.g.

Fred Smith will receive an SMS:

Hi Fred Smith, your payment amount of $25.00 is due tomorrow. Any questions, please call 1300 WHISPIR.

Steve Cleave will receive an SMS:

Hi Steve Cleave, your payment amount of $72.00 is due tomorrow. Any questions, please call 1300 WHISPIR.

and Susan Summers will receive an SMS:

Hi Susan Summers, your payment amount of $100.52 is due tomorrow. Any questions, please call 1300 WHISPIR.

Further Information

For further information about any of the content in this article, please contact  apisupport@whispir.com, or post a message in the Forum.