Sending Messages

Sending Messages with Whispir's API

Using this information, application developers are able to create and send new messages through the Whispir API. 

This section contains the following information:

  1. Overview of sending messages
  2. Sending SMS messages
  3. Sending E-mail messages
  4. Sending Voice calls
  5. Sending Messages using Message Templates
  6. Publishing to Web, RSS or Social Media
  7. Message Recipient Information
  8. How to retrieve a list of messages you've sent
  9. How to retrieve all messages from all users in a workspace
  10. How to retrieve a single sent message

After reading through this section, users should have a basic knowledge of how to send messages using the Whispir API.

    Overview of sending messages

    This section describes how to send messages using the API.

    As message resources can exist in the Company workspace or any other workspace, messages have two access URLs:

    • http://api.whispir.com/messages - for Company Workspace messages 
    • http://api.whispir.com/workspaces/:id/messages - for other Workspace messages

    If your application does not require separate workspaces, you can simply send all messages from the default Company workspace.

    Name

    Value

    API URLs

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

    Method

    POST

    Request Headers

    Authorization

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

    Accept

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

    Content-Type

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

    Query String

    apikey=

    The Mashery API key to authenticate the request.

    Response

    202 Accepted

    The request has been accepted for processing

    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.

    Request Example

    The message XML shows the all of the different elements of a message being used.  

    Each section is described in further detail below.

    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>61400000000</to>
        <subject>Test Message</subject>    
        <body>This is the body of my test SMS message</body>
        <email>
            <body>This is the body of my test Email message</body>
            <footer>This is footer of test email</footer>
            <type>text/plain</type>
        </email>
        <voice>
            <header>test header</header>        
            <body>This is test voice body</body>
            <footer>test footer</footer>
            <type>ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:</type>
        </voice>
        <web> 
            <body>This is web body of my test message</body> 
            <type>text/plain</type> 
        </web> 
        <social> 
            <social id="social"> 
                <body>This is the content of social message for Twitter</body>
             </social> 
            <social id="social_long"> 
                <body>This is the content of social message for Facebook</body>
                <type>text/plain</type> 
            </social> 
        </social>
    </ns2:message>
    

    Response Example

    The following code is an example response from a successful message sendout.

    HTTP 1.1 202 Accepted
    Location: http://api.whispir.com/messages/ABD435DBFCD663DEDEFF?apikey=<yourkey>
    
    Your message has been accepted for processing.
    

    Sending SMS Messages

    The following provides a description of how to send SMS messages from the API

    Using XML - application/vnd.whispir.message-v1+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">
        <to>61400000000</to>
        <subject>Test SMS Message</subject>    
        <body>This is the body of my test SMS message</body>
    </ns2:message> 
    

    Using JSON - application/vnd.whispir.message-v1+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" : "61400000000"
       "subject" : "Test SMS Message"
       "body" : "This is the body of my test SMS message"
    }
    

    Notes:

    Each SMS message can contain up to 1600 characters. 

    • The Subject field is Mandatory.
    • The Body field is Mandatory.

    Sending E-Mail Messages

    The following provides a description of how to send Email messages from the API.

    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 Email Message</subject>    
        <email>
            <body>This is the body of my test Email message</body>
            <footer>This is footer of my test Email</footer>
            <type>text/plain</type>
        </email>
    </ns2:message> 
    

    Notes:

    • The Subject field is Mandatory.
    • The Body field is Mandatory.
    • The Type field is Mandatory and must specify a value of 'text/plain' or 'text/html' to describe the content of the message.

    Sending Voice Calls

    The following provides a description of how to send voice calls from the API.

    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>61400000000</to>
        <subject>Test Voice Call</subject>    
        <voice>
            <header>This is the introduction of the voice call</header>        
            <body>This is body of the message</body>
            <type>ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:</type>
        </voice>
    </ns2:message> 
    

    Notes:

    • The Subject field is Mandatory.
    • The Body field is Mandatory.
    • The Type field is Mandatory and at a minimum must specify the following string:
    <type>ConfCall:,ConfAccountNo:,ConfPinNo:,ConfModPinNo:,Pin:</type>

    Your account must be enabled to use the Voice capability within Whispir for this to function.  If you are unsure whether you can use Voice please contact apisupport@whispir.com.

    Sending Messages using Message Templates

    Using the Whispir API, message content and optional message features can be stored within a Message Template object that can be referenced within your API calls.

    The purpose of using a Message Template rather than including your content directly into your messages API call is to ensure a separation of message content/design and application code.

    To start using Message Templates within your application:

    First, Create a new Message Template (JSON example)

    HTTP 1.1 POST http://api.whispir.com/templates?apikey=<yourkey>
    Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
    Content-Type: application/vnd.whispir.template-v1+json
    
    { 
       "messageTemplateName": "Sample SMS Template", 
       "messageTemplateDescription": "Template to provide an example on developer.whispir.com",
       "subject": "Test SMS Message",    
       "body": "This is the body of my test SMS message"
    }
    

    The sample code above will create a simple SMS only message template within the default My Company workspace.

    The expected response to this call is an HTTP 201 - Created.

    HTTP 201 Created
    Content-Type: application/vnd.whispir.template-v1+json
    Location:&nbsp;https://api.whispir.com/templates/BACEB8D46BEF5315?apikey=<yourkey>
    
    {&nbsp;
      "id" : "BACEB8D46BEF5315",   
      "messageTemplateName" : "Sample SMS Template",   
      "messageTemplateDescription" : "Template to provide an example on developer.whispir.com",   
      "link" : [ {     
        "uri" : "http://api.whispir.com/templates/BACEB8D46BEF5315?apikey=<yourkey>",     
        "rel" : "self",   
        "method" : "GET"   
      }, {    
        "uri" : "http://api.whispir.com/templates/BACEB8D46BEF5315?apikey=<yourkey>",     
        "rel" : "updateTemplate",     
        "method" : "PUT"   
      }, {     
        "uri" : "http://api.whispir.com/templates/BACEB8D46BEF5315?apikey=<yourkey>",     
        "rel" : "deleteTemplate",     
        "method" : "DELETE"   
      } ]
    } 

    This response also includes handy URLs to assist with the retrieval, update or delete of this template if necessary in the future.

    Notes:

    • The Subject field is Mandatory.
    • At least one of the Body fields is Mandatory as per the SMS, Email or Voice sections above.

    You can now use this Message Template in place of your message content.

    API messages can now simply specify the Message Template ID in the messages request, instead of specifying the entire content payload.

    HTTP 1.1 POST http://api.whispir.com/messages?apikey=<yourkey>
    Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
    Content-Type: application/vnd.whispir.message-v1+json
    
    { 
       "to" : "6140000000000",
       "messageTemplateId" : "BACEB8D46BEF5315"
    }
    

     

    Alternatively, you can enter the Message Template Name in place of the ID:

    HTTP 1.1 POST http://api.whispir.com/messages?apikey=<yourkey>
    Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk
    Content-Type: application/vnd.whispir.message-v1+json
    
    { 
       "to" : "6140000000000",
       "messageTemplateName" : "Sample SMS Template"
    }
    

    The message template can then easily be changed (using either the API or the Whispir Platform) and the part of the application sending the messages does not need to be altered.

    For further information about message templates and using them in your messages, please feel free to post to the forum, or contact us at apisupport@whispir.com.

    Publishing to Web, RSS or Social Media

    The Whispir API supports publishing to Web, RSS and Social Media through existing configurations set up in the Whispir Platform.

    If your existing Whispir setup already allows you to publish to these destinations, you can simply specify the information in the message, and it will automatically be published as per your existing setup.

    Request/Response Example

    The message XML shows the all of the different elements of a message being used.  Each section is described in further detail below.

    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>61400000000</to>
        <subject>Test Message</subject>    
        <web> 
            <body>This is web body of my test message</body> 
            <type>text/plain</type> 
        </web> 
        <social> 
            <social id="social"> 
                <body>This is the content of social message for Twitter</body>
             </social> 
            <social id="social_long"> 
                <body>This is the content of social message for Facebook</body>
                <type>text/plain</type> 
            </social> 
        </social>
    </ns2:message>
    

    Web Publishing

    The Web section is primarily used for Rich Messaging, however, this can also be used to publish information to Whispir's Contact Portal, or to a pre-defined web destination e.g. your company intranet.  Whispir can automatically export this content as plain text or HTML and export it to a location for you to either iFrame into your webpage, or include via AJAX.

    For more information on web publishing, please contact apisupport@whispir.com or post a message in the forum.

    Social Publishing

    The Social section is used to publish information to Twitter or Facebook as per your Whispir implementation.  Whispir can automatically publish content to your pre-configured Twitter and Facebook pages based on the information you have provided us.

    For more information about configuring Social Publishing, please contact apisupport@whispir.com or post a message in the forum.

    Message Recipient Information

    Using the Whispir API, users can send message to either ad-hoc or predefined recipients. 

    The details below describe how these can be used in the <to> field for any type of message.

    For ad-hoc recipients

    • Any valid E-mail address

    <to>jsmtih@test.com</to> 
    • Any valid Mobile number for SMS or Voice calls (countrycode prefixed)

    <to>61423589146,6596624876</to> 
    • Any valid Landline number for Voice calls only (countrycode prefixed)

    <to>6197468794</to> 

    For pre-entered Whispir recipients:

    • Contacts can be used as a message recipient simply by specifying any valid Whispir Contact MRI

    <to>John_Smith.782749@Contact.whispir.com</to> 
    • Users can be used as a message recipient simply by specifying any valid Whispir User MRI

    <to>John_Smith@User.whispir.com</to> 
    • Distribution Lists can be used as a message recipient simply by specifying any valid Whispir Distribution List MRI

    <to>Crisis_Management.Critical_Incident_Management@list.project.whispir.com</to> 

    Each of these can be found by using the Whispir API to search for the resource type and locate the MRI field in the response.

    How to retrieve a list messages you've sent (my view)

    Name

    Value

    Service URL

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

    Method

    GET

    Request Headers

    Authorization

    The Base 64 representation of the Whispir Username and Password.

    Accept

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

    Query String

    apikey=

    The Mashery API key to authenticate the request.

    limit=

    The number of rows to return in this request.
    Default: 20
    Max: 20 

    offset=

    The offset (from zero) to start returning results from. E.g. if offset is 5, and limit is 20, you will be returned rows 5 to 25.

    Response

    200 OK

    The request was processed successfully

    401 Unauthorized

    The authorization details were incorrect

    415 Unsupported Media Type

    The MIME type requested is not supported for the requested resource

    Request/Response Example

    The Messages XML returns URIs to each of the Messages that the authenticated API user has access to. 

    This allows the application client to traverse the available Messages easily:

    HTTP 1.1 GET https://api.whispir.com/messages/?apikey=<yourkey>
    Authorization: Basic DNF023KF890FNR4U90NKL34
    Accept: application/vnd.whispir.message-v1+xml
    
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
        <status>1 to 20 of 40</status>
        <ns2:link method="GET" rel="next" uri="http://api.whispir.com/messages?limit=20&offset=20&apikey=<yourkey>"/>
        <ns2:messages>
            <ns2:message>
                <subject>ESR: escalation test 2.</subject>
                <from>Jordan Walsh</from>
                <direction>OUTGOING</direction>
                <responseCount>0</responseCount>
                <createdTime>2012-06-13T15:08:08+10:00</createdTime>
                <ns2:link method="GET" rel="self" uri="http://api.whispir.com/messages/0E42D5FCC1DAA066?apikey=<yourkey>"/>
            </ns2:message>
            . . .
        </ns2:messages>
    </ns2:return> 
    

    How to retrieve all messages from all users in a workspace (shared view)

    Name

    Value

    Service URL

    https://api.whispir.com/messages?viewType=shared&apikey=
    https://api.whispir.com/workspaces/:id/messages?viewType=shared&apikey= 

    Method

    GET

    Request Headers

    Authorization

    The Base 64 representation of the Whispir Username and Password.

    Accept

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

    Query String

    apikey=

    The Mashery API key to authenticate the request.

    viewType=

    Shared

    This will return all messages from the workspace, not just the messages you've sent.

    limit=

    The number of rows to return in this request.
    Default: 20
    Max: 20 

    offset=

    The offset (from zero) to start returning results from. E.g. if offset is 5, and limit is 20, you will be returned rows 5 to 25.

    Response

    200 OK

    The request was processed successfully

    401 Unauthorized

    The authorization details were incorrect

    415 Unsupported Media Type

    The MIME type requested is not supported for the requested resource

    Request/Response Example

    Similar to the example above, the Messages XML returns URIs to each of the Messages that the authenticated API user has access to.  However, when using the viewType=shared parameter, the user will now retrieve messages from all authors in this workspace, not just the messages that the current user has sent.

    HTTP 1.1 GET https://api.whispir.com/messages?viewType=shared&apikey=<yourkey>
    Authorization: Basic DNF023KF890FNR4U90NKL34
    Accept: application/vnd.whispir.message-v1+xml
    
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <ns2:return xmlns:ns2="http://schemas.api.whispir.com/dap" xmlns:ns3="http://schemas.api.whispir.com">
        <status>1 to 20 of 40</status>
        <ns2:link method="GET" rel="next" uri="http://api.whispir.com/messages?viewType=shared&apikey=<yourkey>"/>
        <ns2:messages>
            <ns2:message>
                <subject>ESR: escalation test 2.</subject>
                <from>Jordan Walsh</from>
                <direction>OUTGOING</direction>
                <responseCount>0</responseCount>
                <createdTime>2012-06-13T15:08:08+10:00</createdTime>
                <ns2:link method="GET" rel="self" uri="http://api.whispir.com/messages/0E42D5FCC1DAA066?viewType=shared&apikey=<yourkey>"/>
            </ns2:message>
            . . .
        </ns2:messages>
    </ns2:return>   

    Restricting the number of message results using date filters

    When retrieving a list of messages from the /messages endpoint, users may notice that requests can sometimes take a while to come back (as it could be a large amount of data).  Because of this, it is appropriate to limit the date range on your request using the following parameters:

    • criteriaFromDate
    • criteriaToDate
    • criteriaFromTime
    • criteriaToTime

    A sample request would be as follows:

    HTTP 1.1 GET https://api.whispir.com/messages?viewType=shared&criteriaFromDate=12/12/2014&criteriaFromTime=00:00&criteriaToDate=12/12/2014&criteriaFromTime=23:59apikey=<yourkey>
    Authorization: Basic DNF023KF890FNR4U90NKL34
    Accept: application/vnd.whispir.message-v1+xml

    Notes:

    • All four parameters are required for the criteria to work.
    • Dates are in the format: DD/MM/YYYY
    • Times are in the format 00:00

     

    How to retrieve a single previously sent message

    Name

    Value

    Service URL

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

    Method

    GET

    Request Headers

    Authorization

    The Base 64 representation of the Whispir Username and Password.

    Accept

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

    Query String

    apikey=

    The Mashery API key to authenticate the request.

    Response

    200 OK

    The request was processed successfully

    401 Unauthorized

    The authorization details were incorrect

    404 Not Found The id specified in the URI does not exist or has been deleted.

    415 Unsupported Media Type

    The MIME type requested is not supported for the requested resource

    Request/Response Example

    The Message XML returns the specific details of the Message that the authenticated API user requested.  

    <?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>61400000000</to>
     <subject>test subject</subject>
     <body>test body</body>
     <voice/>
     <from></from>
     <direction>OUTGOING</direction>
     <responseCount>0</responseCount>
     <social/>
     <createdTime>2012-09-24T15:36:16+10:00</createdTime>
     <ns3:link method="GET" 
       rel="self" 
       uri="http://api.whispir.com/messages/069BF68E5E0FE99B?apikey="/>
     <ns3:link method="GET" 
       rel="summaryStatus" 
       uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=<yourkey>"/>
     <ns3:link method="GET" 
       rel="detailedStatus" 
       uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=detailed&apikey=<yourkey>"/>
     <ns3:link method="GET" 
       rel="summaryResponses" 
       uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=<yourkey>"/>
     <ns3:link method="GET" 
       rel="detailedResponses" 
       uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&apikey=<yourkey>/>
     <ns3:link method="GET" 
       rel="summaryResponsesWithResponseRule" 
       uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=responserule&apikey=<yourkey>"/>
     <ns3:link method="GET" 
       rel="detailedResponsesWithResponseRule" 
       uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=responserule&apikey=<yourkey>"/>
    </ns2:message> 

    Each of the URIs specified in the response can be accessed using the REL and appropriate METHOD to perform the specified functionality.

    REL name

    Description

    self

    Retrieves the current message.

    summaryStatus

    Returns the status information of the message as a messagestatus object, in a summary view.

    detailedStatus

    Returns the status information of the message as a messagestatus object, in a detailed view.

    summaryResponses

    Returns the response information of the message as a messageresponse object, in a summary view.

    detailedResponses

    Returns the response information of the message as a messageresponse object, in a detailed view.

    summaryResponsesWithResponseRule

    Returns the response information of the message as a messageresponse object, filtered by the Response Rule (if one was used) in a summary view.

    detailedResponsesWithResponseRule

    Returns the response information of the message as a messageresponse object, filtered by the Response Rule (if one was used) in a detailed view.