Advanced Messages

Advanced Messaging Features

This section covers off some more advanced features that are available when sending messages.  Please make sure you've read the Messaging section prior to proceeding.

  1. Using recipient information in messages
  2. Using auto-populated system variables in messages
  3. Composing e-mail messages with rich content (HTML)
  4. Including attachments to e-mail messages
  5. Using custom WAV files as the content for Voice Calls
  6. Scheduling messages to be delivered later
  7. Scheduling messages for repeated delivery
  8. Using Message Attributes in your Messages

Using recipient information in messages

When sending messages using the Whispir API, users have the ability to automatically include recipient information as part of the message.  This is facilitated using tags.

The following tags can be included in any message:

Tag Name Description
@@first_name@@ Recipients first name
@@last_name@@ Recipients last name
@@recipient_email@@ Recipients Email channel
@@recipient_sms@@ Recipients Mobile channel
@@recipient_voice@@ Recipients Voice Channel
@@sender_email@@ Senders Email address
@@sender_full_name@@ Senders Full name
@@pin@@ Whispir message retrieval service call back PIN (only populated when voice is used)
@@recipient_role@@ Resolves to the recipient's 'Role' field
@@recipient_additionalrole@@ Resolves to the recipient's 'Additional Role' field
@@team_name1@@ Resolves to the recipient's 'Team Name' field
@@teleconf_number@@ Teleconference phone number
@@teleconf_account@@ Teleconference account number
@@teleconf_pin@@ Teleconference guest pin
@@teleconf_mod_pin@@ Teleconference moderator pin
@@messagelabel@@ Resolves to label used in the message
@@messagecategories@@

Resolves to the list of categories used in the message, separated with commas.

Each of these tags will resolve on send of the message to the individual recipient's information.  As Whispir needs to know about this information prior to sending the message, the tags will only work when sending messages to Contacts or Distribution Lists.

For more information about sending messages to Contacts or Distribution Lists, please consult the documentation under Messaging.

Using auto-populated system variables in messages

When sending messages using the Whispir API, users have the ability to automatically include system generated information as part of the message.  This is facilitated using system tags.

The following system tags can be included in any message:

Tag Name Description Example
@@dd@@ Current day with leading zero (ie; 08) 25
@@mm@@ Current month with leading zero (ie; 06) 10
@@yy@@ Current year, short form (ie; 10) 12
@@yyyy@@ Current year, long form (ie; 2010) 2012
@@day@@ Day in spoken form, (ie; Wednesday) Thursday
@@month@@ Month in spoken form, (ie; June) October
@@hrs@@ Current hour with leading zero in 24hrs (ie; 18) 12
@@min@@ Current minute with leading zero (ie; 07) 37
@@date@@ Current date i.e. yyyy/mm/dd 2012-10-25
@@time@@ Current time in 24hr format 12:37

Each of these system tags will resolve on send of the message to the system information.  The system tags will only work when sending messages to any recipient.

For more information about sending messages, please consult the documentation under Messaging.

Composing an e-mail message with rich content (HTML)

The Whispir API provides users with the ability to compose e-mail messages using plain text or HTML. 

This example demonstrates how to send an email using HTML content in both XML and JSON.

Composing HTML e-mails in XML

When composing HTML inside the email body, clients need to perform two actions:

  1. All HTML content must be wrapped in a CDATA block.  More information about CDATA can be found on Wikipedia.
  2. The type element must be set to text/html

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>john.smith@test.com</to>
    <subject>Test HTML e-mail message</subject>    
    <email>
        <body>
            <![CDATA[
                <div id="content">
                    <p>This is my content</p>
                </div>
            ]]>
        </body>
        <type>text/html</type>
    </email>
</ns2:message>

Composing HTML e-mails in JSON

When composing HTML inside the email body, clients need to perform a two actions:

  1. All HTML content must be in a single line.  JSON does not support line breaks in the content.
  2. The type element must be set to text/html

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

{
    "to" : "john.smith@test.com",
    "subject" : "Test HTML e-mail message",
    "email" : {
        "body" : "<div id='content'><p>This is my content</p></div>",
        "type" : "text/html"
    }
}

Notes on Whispir's support of HTML e-mails

  • HTML, HEAD and BODY HTML elements are not supported.  HTML content assumes that it is starting from within the BODY tag.
  • HTML form and input elements are not supported in most email clients.  These can be included in the HTML content but should be thoroughly tested prior to use.
  • STYLE elements are supported.  It is recommended that a single STYLE element at the top of the HTML that defines the styles for the entire email.  However, inline styles are also supported.
  • Javascript is not supported and should not be used in e-mail messages.
  • Images must be referenced through absolute web urls, any other mechanism will not work on most email clients. Note: Whispir does not host images for clients, you must use another hosting service and reference the URL in your Whispir request payload.

Including attachments in e-mail messages

The Whispir API provides users with the ability to compose e-mail messages that also contain attachments.

Attachments can be of any type, and can be up to 10MB in size (maximum for all attachments).

This example demonstrates how to send an e-mail with attachments in both XML and JSON.

Composing e-mails with attachments in XML

This example shows how to send a plain text e-mail with a small icon attached.

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>john.smith@test.com</to>
    <subject>Test e-mail message with attachment</subject>    
    <email>
        <body>Test Message Content</body>
        <type>text/plain</type>
	<resources>
            <attachment>
                <attachmentName>TestIcon.png</attachmentName>
                <attachmentDesc>TestIcon.png</attachmentDesc>
                <derefUri>iVBORw0KGgoAAAANSUhEUgAAABQAAAASCAIAAADUsmlHAAAAAXNSR0IArs4c6QAAAARnQU1BAACx
jwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAMvSURBVDhPTVT5S1RhFD3fezOOOePTXHKriWgj
sogWC1TSMuuHIFqoX0KsIIgSWwiq/6FFU8MKK6KyXYSKpkUKR4QMSSpCLQpyxHHUZpztzdu63xub
5vKWj/fu+c6599z3mMfjSU9P13UdZoiCaLfZYQWiUGKq1WrBLEBDOBpWNTWeQyEIwvT0NAsEAgRO
PKXFxceNbQOtv4ShkKCkaZZ5kYU1Sw6dqT0NMTkLBIbf7zf+xaOuJzgG4RmyPyP/Kwq/oWAYeT+R
6gYOofnmlUQmLQjI6JQkifasu368KdCQWwFEwBiYQOIgiDBETDFIORh/iZ0De55cehgXQJIphce9
d/ebJhuyV0P3QY9Cj/HDUKhseIPomP/CW2QYB42nSx+db76YUM9IusPhYHVM2g5Bpo5xNuIkZibC
F8On0oGVjhWabmR8EBx5GDuHaItsy0zhzA6bo/H5ZSyDMQ1d4YQa0Sqc1hdAe3E7IYkqp9tiUcHG
kXIQZ8+fm+k5uXK3/46YAV3mMMLEt/BHUJ1Vua9oH+WV9ayLyLpVhRYFkT8d4mUzRuI0DAcHmQng
SLrGoBJ/GC/L31JSy/cm91ifXTcboYDJGLX+1kI6WS3AQFSRCUDvwhGEwubiD1yVLkLKWuxoT50k
zGwab6Ru6HIsahpiwTybkwTLU9iUU1Ezf394CmuyV20p2kLg8mcbRHLLxGimLlWFFMpMc6TRFlx2
9aJqePBgx4M3u7tubb1dMXfjw6rHhOwb+/jhV3+qNtMFKspQEZnA+oxSPr9UdjgUllV59pHZhSUF
I/We5AnMv5o7bvhsFu5f3DlmR7ATr/a+rtq2mVulqEqmlFlbUuv5MbqudW0C7PrhGpvwidRhIoyX
qiHoRam/tGrT5n9Wmfcb9TfmBOf0DXy80H0h/uKU6yQRcqlmk+mji0RhbbN2XOpAygzF/9nmfp4o
c4+4y6vLqRnuUTdsfNqYFRop/4JFw4t723qz52YlZpvPd/K30vm+03nAie1ADXAYOADsgHOXs/la
ix7RkzMJyJJ/BjQ09lQ7me8f9/cP9nsnvemzpOIFy3PzclkK0wyNgvDEHP8Z/AXQ58rAz69IBAAA
AABJRU5ErkJggg==</derefUri>
            </attachment>
        </resources>
    </email>
</ns2:message>

Notes:

  • attachmentName - The name of the file being attached (mandatory)
  • attachmentDesc - An optional description of the file being attached
  • derefUri - The base64 representation of the file being uploaded

Composing e-mails with attachments in JSON

This example shows how to send a plain text e-mail with a small icon attached.

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

{
    "to" : "jsmith@test.com",
    "subject" : "Test e-mail message with attachment",
    "email" : {
        "body" : "This is my content",
        "type" : "text/plain",
        "resources" : {
            "attachment" : [{
                "attachmentName" : "TestIcon.png",
                "attachmentDesc" : "TestIcon.png",
                "derefUri" : "iVBORw0KGgoAAAANSUhEUgAAABQAAAASCAIAAADUsmlHAAAAAXNSR0IArs4c6QAAAARnQU1BAACx
jwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAMvSURBVDhPTVT5S1RhFD3fezOOOePTXHKriWgj
sogWC1TSMuuHIFqoX0KsIIgSWwiq/6FFU8MKK6KyXYSKpkUKR4QMSSpCLQpyxHHUZpztzdu63xub
5vKWj/fu+c6599z3mMfjSU9P13UdZoiCaLfZYQWiUGKq1WrBLEBDOBpWNTWeQyEIwvT0NAsEAgRO
PKXFxceNbQOtv4ShkKCkaZZ5kYU1Sw6dqT0NMTkLBIbf7zf+xaOuJzgG4RmyPyP/Kwq/oWAYeT+R
6gYOofnmlUQmLQjI6JQkifasu368KdCQWwFEwBiYQOIgiDBETDFIORh/iZ0De55cehgXQJIphce9
d/ebJhuyV0P3QY9Cj/HDUKhseIPomP/CW2QYB42nSx+db76YUM9IusPhYHVM2g5Bpo5xNuIkZibC
F8On0oGVjhWabmR8EBx5GDuHaItsy0zhzA6bo/H5ZSyDMQ1d4YQa0Sqc1hdAe3E7IYkqp9tiUcHG
kXIQZ8+fm+k5uXK3/46YAV3mMMLEt/BHUJ1Vua9oH+WV9ayLyLpVhRYFkT8d4mUzRuI0DAcHmQng
SLrGoBJ/GC/L31JSy/cm91ifXTcboYDJGLX+1kI6WS3AQFSRCUDvwhGEwubiD1yVLkLKWuxoT50k
zGwab6Ru6HIsahpiwTybkwTLU9iUU1Ezf394CmuyV20p2kLg8mcbRHLLxGimLlWFFMpMc6TRFlx2
9aJqePBgx4M3u7tubb1dMXfjw6rHhOwb+/jhV3+qNtMFKspQEZnA+oxSPr9UdjgUllV59pHZhSUF
I/We5AnMv5o7bvhsFu5f3DlmR7ATr/a+rtq2mVulqEqmlFlbUuv5MbqudW0C7PrhGpvwidRhIoyX
qiHoRam/tGrT5n9Wmfcb9TfmBOf0DXy80H0h/uKU6yQRcqlmk+mji0RhbbN2XOpAygzF/9nmfp4o
c4+4y6vLqRnuUTdsfNqYFRop/4JFw4t723qz52YlZpvPd/K30vm+03nAie1ADXAYOADsgHOXs/la
ix7RkzMJyJJ/BjQ09lQ7me8f9/cP9nsnvemzpOIFy3PzclkK0wyNgvDEHP8Z/AXQ58rAz69IBAAA
AABJRU5ErkJggg=="
            }]
        }
    }
}

Notes:

  • attachmentName - The name of the file being attached (mandatory)
  • attachmentDesc - An optional description of the file being attached
  • derefUri - The base64 representation of the file being uploaded
  • The attachment element is also an array, so be sure to add the square bracket in there!

Using custom WAV files as the content for Voice Calls

The Whispir API provides users with the ability to compose voice calls using Text-To-Speech (TTS) as well as allowing users to provide custom WAV files to be played over the phone.

Attachments must be WAV files and can be up to 10MB in size (maximum for all attachments).

Each Voice Call is made up of four parts:

  1. Message Introduction - Either TTS or WAV file, mandatory for all messages
  2. Message Acceptance - Requests the recipient to press a button to accept the message
  3. Message Content - The concatenation of the Message Subject and Message Body (either TTS or WAV file)
  4. Message Response - Allows the recipient to provide an acknowledgement to the message, either default options or based off a response rule

WAV File Criteria

Before a WAV file will be played, it needs to conform to a certain criteria. 

All WAV files must be 8bit, 8000Hz, 1ch, 64kbps MAX.

If the WAV is supplied outside of these criteria, the TTS will be used instead.  It is vital that TTS is provided even when using WAV files.

Composing voice calls with custom WAV files in XML

This example demonstrates how to send a voice call with attachments for the message introduction and the message body in both XML and JSON.

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com">
    <to>61423568958</to>
    <subject>Test voice call with attachment</subject>    
    <voice>
        <body>Will be replaced by the voicebody.wav file</body>
        <header>Will be replaced by the voiceintro.wav file</header>
        <type>ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:</type>
        <resources>
            <attachment>
                <attachmentName>Introduction.wav</attachmentName>
                <attachmentDesc>voiceintro.wav</attachmentDesc>
                <derefUri>...</derefUri>
            </attachment>
            <attachment>
                <attachmentName>Body.wav</attachmentName>
                <attachmentDesc>voicebody.wav</attachmentDesc>
                <derefUri>...</derefUri>
            </attachment>
        </resources>
    </voice>
</ns2:message> 

Notes:

  • attachmentName - The name of the file being attached (mandatory)
  • attachmentDesc - For the WAV file to be played as the introduction, this must be voiceintro.wav
  • attachmentDesc - For the WAV file to be played as the body, this must be voicebody.wav
  • derefUri - The base64 representation of the WAV file being played

Composing voice calls with custom WAV files in JSON

Similar to the XML above, this is the same message but composed in JSON.

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


{
    "to" : "61423568958",
    "subject" : "Test voice call with attachments",
    "voice" : {
        "body" : "Will be replaced by the voicebody.wav file",
        "header" : "Will be replaced by the voiceintro.wav file",
        "type" : "ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:",
        "resources" : {
            "attachment" : [{
                "attachmentName" : "Introduction.wav",
                "attachmentDesc" : "voiceintro.wav",
                "derefUri" : "..."
            },{
                "attachmentName" : "Body.wav",
                "attachmentDesc" : "voicebody.wav",
                "derefUri" : "..."
            }]
        }
    }
}

Notes:

  • attachmentName - The name of the file being attached (mandatory)
  • attachmentDesc - For the WAV file to be played as the introduction, this must be voiceintro.wav
  • attachmentDesc - For the WAV file to be played as the body, this must be voicebody.wav
  • derefUri - The base64 representation of the file being uploaded
  • The attachment element is also an array, so be sure to add the square bracket in there!

Scheduling messages to be delivered later

Using the Whispir API, users can schedule messages to be sent later.

Users can configure the schedule of message delivery as part of the message sendout.

For example. the following code will schedule a single message to be delivered at 3:55pm on the 14th February 2013.

Scheduled Message in JSON

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

{
    "to" : "john.smith@test.com",
    "subject" : "Test scheduled e-mail message",
    "email" : {
        "body" : "This is my scheduled content",
        "type" : "text/plain"
    },
    "messageType" : "SCHEDULED",
    "scheduleType" : "ONCE",
    "scheduleDate" : "14/02/2013 15:55"
}

Scheduled Message in XML

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <to>john.smith@test.com</to>
    <subject>Test scheduled e-mail message</subject>
    <email>
        <body>This is my scheduled content</body>
        <type>text/plain</type>
    </email>
    <messageType>SCHEDULED</messageType>
    <scheduleType>ONCE</scheduleType>
    <scheduleDate>14/02/2013 15:55</scheduleDate>
</ns2:message>

Using this method, messages can be easily scheduled so that the message is delivered when the recipient requires it.

Scheduling messages for repeated delivery

A second method of scheduling messages, users can schedule messages to be sent multiple times (e.g. every hour, every day or every 7 days).

Users can configure the repeat rate of the message delivery as part of the message sendout.

For example. the following code will schedule a single message to be delivered at 3:55pm on the 14th February 2013, and repeated every hour for 10 times.

Scheduled Message in JSON

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

{
    "to" : "john.smith@test.com",
    "subject" : "Test scheduled e-mail message",
    "email" : {
        "body" : "This is my scheduled content",
        "type" : "text/plain"
    },
    "messageType" : "SCHEDULED",
    "scheduleType" : "REPEAT",
    "scheduleDate" : "14/02/2013 15:55",
    "repetitionCount" : "10",
    "repeatDays" : "0",
    "repeatHrs" : "1",
    "repeatMin" : "0" 
}

Scheduled Message in XML

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:message xmlns:ns2="http://schemas.api.whispir.com" xmlns:ns3="http://schemas.api.whispir.com/dap">
    <to>john.smith@test.com</to>
    <subject>Test scheduled e-mail message</subject>
    <email>
        <body>This is my scheduled content</body>
        <type>text/plain</type>
    </email>
    <messageType>SCHEDULED</messageType>
    <scheduleType>REPEAT</scheduleType>
    <scheduleDate>14/02/2013 15:55</scheduleDate>
    <repetitionCount>10</repetitionCount>
    <repeatDays>0</repeatDays>
    <repeatHrs>1</repeatHrs>
    <repeatMin>0</repeatMin> 
</ns2:message>

Using this example, users can easily schedule a message to be delivered multiple times starting from a date and continuing until desired.

Using Message Attributes in your Messages

Whispir's API customers who have Message Attributes configured within the Whispir Platform have the ability to simplify their API message requests by using the Message Attributes directly from the API.

Using Message Attributes allows developers to focus on the data behind a message, rather than focusing on the presentation or messaging channels within the message. 

This separation ensures that the marketing or communications teams within an organisation can focus on what they are best at, and the developers can ensure the system integrations are working as effectively as possible.

For example;

A message could contain some content, and a potential variable such as the expiry of the invitation:

Reminder: your invitation to the Acme Event will expire on 13/06/2014.

The API call to populate this without Message Attributes could look as follows:

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

{
   "to" : "john@api-example.com", 
   "subject" : "Reminder:", 
   "body" : "Your invitation to the Acme Event will expire on 13/06/2014.", 
   "email" : { 
      "type" : "text/plain", 
      "body" : "Your invitation to the Acme Event will expire on 13/06/2014." 
   }
}

This is combining both the channels being selected for the message, and the data driving the message.  

Using Message Attributes and Message Templates allows developers to cleanly separate these responsibilities.

For example; the same message could be saved into a Whispir 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" : "Event Reminder", 
   "subject" : "Reminder:", 
   "body" : "Your invitation to the Acme Event will expire on @@event_expiry@@.", 
   "email" : { 
      "type" : "text/plain", 
      "body" : "Your invitation to the Acme Event will expire on @@event_expiry@@." 
   }
}

This would provide a response of:

HTTP 1.1 201 Created
Location: http://api.whispir.com/templates/DACADB02209CC93C

{ 
   "id": "DACADB02209CC93C", 
   "messageTemplateName" : "Event Reminder", 
   "subject" : "Reminder:", 
   "body" : "Your invitation to the Acme Event will expire on @@event_expiry@@.", 
   "email" : { 
      "type" : "text/plain", 
      "body" : "Your invitation to the Acme Event will expire on @@event_expiry@@." 
   }
}

Using this Message Template ID and now using the Message Attribute @@event_expiry@@, the updated is far simpler to implement and is more efficient.

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

{ 
   "to" : "john@api-example.com", 
   "messageTemplateId" : "DACADB02209CC93C", 
   "messageattributes" : {
      "attribute" : [{     
         "name" : "event_expiry",     
         "value" : "13/06/2014"   
      }]
   } 
} 

Note: Message Attributes are not enabled by default for Whispir Customers.  These can be configured in your account by contacting your Whispir Representative or sales@whispir.com