Message Responses

Understanding Message Responses

This section describes the different ways that you can retrieve the responses or replies to a message after it has been sent.  If you have not already covered off sending messages, you can read about this in the Messaging Overview.

  1. Message Responses Overview
  2. How to retrieve a previously sent message
  3. How to retrieve a summary view of the responses to the message
  4. How to retrieve a detailed view of the responses to the message
  5. How to filter a summary view of responses by a Response Rule
  6. How to filter a detailed view of the responses by a Response Rule
  7. How to search through responses to a message

Message Responses Overview

Recipients of a message have the ability to respond directly to the message via the channels that they received the message on.  E.g. if they received the message via SMS, they can respond directly to the SMS message, and this will be visible through the Whispir API.

Retrieve a 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 example request below returns the Message that the API user requested.  

HTTP 1.1 GET http://api.whispir.com/messages/069BF68E5E0FE99B&apikey=<yourkey>
Authorization: Basic 498nadsasdff09fewdsafjaa90f
 
<?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>61423556682</to>
 <subject>test subject</subject>
 <body>test body</body>
 <voice/>
 <from></from>
 <direction>OUTGOING</direction>
 <responseCount>2</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 URLs 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.

Note: For more information about message status reporting, please view Understanding Message Status.

How to retrieve a summary of the responses to a message

Using the links provided in the message response, the user can simply make a new API request to retrieve the summaryResponses URL. 

In the example above, the summaryResponses URL is:

<ns3:link method="GET" 
   rel="summaryResponses" 
   uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=<yourkey>"/>

So the request would look as follows:

HTTP 1.1 GET http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=<yourkey>
Authorization: Basic 498nadsasdff09fewdsafjaa90f

This request is asking for a couple of things:

  1. The URL is specifically asking for all of the messageresponses to the message with ID 069BF68E5E0FE99B
  2. The View parameter is specifying that the message responses should be shown in a summary view
  3. The Filter parameter is specifying that the filter should not use a response rule, it should show the default filter

As this is a GET request we don't have to provide any message body.

The response to this request could look as follows:

<?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">
    <ns2:link method="GET" 
              rel="self" 
              uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=default&apikey=<yourkey>"/>
    <ns2:messageresponses>
        <ns2:response type="noresponse">
            <percentageTotal>50%</percentageTotal>
            <responseCount>1</responseCount>
        </ns2:response>
        <ns2:response type="notmatched">
            <percentageTotal>50%</percentageTotal>
            <responseCount>1</responseCount>
        </ns2:response>
    </ns2:messageresponses>
</ns2:return>

This shows the application client that there were two intended recipients of this message.  1 of the recipients is in the noresponse category, meaning they have not provided a response.  1 of the recipients is in the notmatched category, meaning the response did not match the search criteria.

Note: Searching responses will be described further on in this documentation.

How to retrieve a detailed view of the responses to a message

Using the links provided in the message response, the user can simply make a new API request to retrieve the detailedResponses URL. 

In the example above, the  detailedResponses URL is:

<ns3:link method="GET" 
   rel="detailedResponses" 
   uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&apikey=<yourkey>"/>

So the request would look as follows:

HTTP 1.1 GET http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&apikey=<yourkey>
Authorization: Basic 498nadsasdff09fewdsafjaa90f

This request is asking for a couple of things:

  1. The URL is specifically asking for all of the messageresponses to the message with ID 069BF68E5E0FE99B
  2. The View parameter is specifying that the message responses should be shown in a detailed view
  3. The Filter parameter is specifying that the filter should not use a response rule, it should show the default filter

As this is a GET request we don't have to provide any message body.

The response to this request could look as follows:

<?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 2 of 2</status>
    <ns2:messageresponses>
        <ns2:response>
            <from>
                <email>jsmith@test.com</email>                
                <mobile>61000000000</mobile> 
                <mri>John_Smith.484215.Critical_Incident_Management@Contact.whispir.com</mri>
                <name>John Smith</name>
                <voice>61000000000</voice> 
            </from>
            <responseCategory>noresponse</responseCategory>
            <responseMessage channel="N/A">
                <acknowledged>N/A</acknowledged>
                <content>N/A</content>
            </responseMessage>
        </ns2:response>
        <ns2:response>
            <from>
                <email>fsmith@test.com</email>
                <mobile>61000000001</mobile>  
                <mri>Fred_Smith.341550.Critical_Incident_Management@Contact.whispir.com</mri>
                <name>Fred Smith</name>
                <voice>61000000001</voice> 
            </from>
            <responseCategory>notmatched</responseCategory>
            <responseMessage channel="SMS">
                <acknowledged>28/09/12 08:48</acknowledged>
                <content>OK, got it. Thanks.</content>
            </responseMessage>
        </ns2:response>
    </ns2:messageresponses>
</ns2:return>

This shows the application client that there were two intended recipients of this message.  1 of the recipients is in the noresponse category, meaning they have not provided a response.  1 of the recipients is in the notmatched category, meaning the response did not match any search criteria.

Note: Searching responses will be described further on in this documentation.

  • The responseMessage channel describes the messaging channel that the response has come in to the Whispir Platform via.
  • The responseMessage content describes the actual content of the inbound message.
  • The responseMessage acknowledged shows the date of when the response was received by the Whispir Platform

How to filter a summary view of responses by a response rule

Note on Response Rules

Response Rules are a mechanism provided by Whispir that allow users to automatically filter and categorise message responses based on the expected content.

For example; lets say I send a message to notify a group of people that they need to return to the office for a briefing.  I need to know how long they are going to take to get to the office, so I might add some preferred responses.

  • Please respond with 1 if you are going to be here in less than 30 minutes
  • Please respond with 2 if you are going to be here in more than 30 minutes
  • Please respond with 3 if you are not coming to the office.

Now that I know what my expected responses are, I can set up my response rule to expect and categorise responses of 1, 2 or 3.

More information on Message Response Rules can be found in the documentation.

Filtering responses based on Response Rules

Using the links provided in the message response, users can make a new API request to retrieve the summaryResponsesWithResponseRule URL. 

In the example above, the summaryResponsesWithResponseRule URL is:

<ns3:link method="GET" 
   rel="summaryResponsesWithResponseRule" 
   uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=responserule&apikey=<yourkey>"/>

So the request would look as follows:

HTTP 1.1 GET http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=summary&filter=responserule&apikey=<yourkey>
Authorization: Basic 498nadsasdff09fewdsafjaa90f

This request is asking for a couple of things:

  1. The URL is specifically asking for all of the messageresponses to the message with ID 069BF68E5E0FE99B
  2. The View parameter is specifying that the message responses should be shown in a summary view
  3. The Filter parameter is specifying that the filter should use the response rule that was associated with the message (if any)

As this is a GET request we don't have to provide any message body.

The response to this request could look as follows:

<?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">
    <ns2:link method="GET" rel="self" uri="http://api.whispir.com/workspaces/668A8F83C3D12E85/messages/11D510307A4B57DF/messageresponses?apikey=4fcn8xkeherbdm5y5fpnat8g&amp;view=summary&amp;filter=responserule"/>
    <ns2:messageresponses>
        <ns2:response type="LessThan30">
            <percentageTotal>33%</percentageTotal>
            <responseCount>1</responseCount>
        </ns2:response>
        <ns2:response type="MoreThan30">
            <percentageTotal>33%</percentageTotal>
            <responseCount>1</responseCount>
        </ns2:response>
        <ns2:response type="NotComing">
            <percentageTotal>33%</percentageTotal>
            <responseCount>1</responseCount>
        </ns2:response> 
    </ns2:messageresponses>
</ns2:return>

This shows the application client that there were three recipients of this message. 

  • 1 of the recipients is in the LessThan30 category, meaning they have responded with a 1 and will return to the office in less than 30 minutes
  • 1 of the recipients is in the MoreThan30 category, meaning they have responded with a 2 and will return to the office in more than 30 minutes
  • 1 of the recipients is in the NotComing category, meaning they have responded with a 3 and will not be returning to the office.

Note the difference between using the filter=default and filter=responserule parameter.  The response rule will automatically filter the responses into the categories, whereas with the default the application client must perform all the required searching and categorisations.

How to filter a detailed view of responses by a response rule

Using the links provided in the message response, users can make a new API request to retrieve the detailedResponsesWithResponseRule URL. 

In the example above, the detailedResponsesWithResponseRule URL is:

<ns3:link method="GET" 
   rel="detailedResponsesWithResponseRule" 
   uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=responserule&apikey=<yourkey>"/>

So the request would look as follows:

HTTP 1.1 GET http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=responserule&apikey=<yourkey>
Authorization: Basic 498nadsasdff09fewdsafjaa90f

This request is asking for a couple of things:

  1. The URL is specifically asking for all of the messageresponses to the message with ID 069BF68E5E0FE99B
  2. The View parameter is specifying that the message responses should be shown in a detailed view
  3. The Filter parameter is specifying that the filter should use the response rule that was associated with the message (if any)

As this is a GET request we don't have to provide any message body.

The response to this request could look as follows:

<?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 2 of 2    </status>
    <ns2:messageresponses>
        <ns2:response>
            <from>
                 <email>jsmith@test.com</email>
                 <mobile>61000000000</mobile>
                 <mri>John_Smith.484215.Critical_Incident_Management@Contact.whispir.com</mri>
                 <name>John Smith</name>
                 <voice>61000000000</voice> 
            </from>
            <responseCategory>LessThan30</responseCategory>
            <responseMessage channel="SMS">
                <acknowledged>25/10/12 10:16</acknowledged>
                <content>1</content>
            </responseMessage>
        </ns2:response>
        <ns2:response>
            <from>
                <email>fsmith@test.com</email>
                <mobile>61000000001</mobile>
                <mri>Fred_Smith.341550.Critical_Incident_Management@Contact.whispir.com</mri>
                <name>Fred Smith</name>
                <voice>61000000001</voice> 
            </from>
            <responseCategory>MoreThan30</responseCategory>
            <responseMessage channel="SMS">
                <acknowledged>25/10/12 10:16</acknowledged>
                <content>2</content>
            </responseMessage>
        </ns2:response>
        <ns2:response>
            <from>
                <mri>Jack_Smith.408789.Sandbox@Contact.whispir.com</mri>
                <name>Jack Smith</name>
            </from>
            <responseCategory>NotComing</responseCategory>
            <responseMessage channel="SMS">
                <acknowledged>25/10/12 10:17</acknowledged>
                <content>3</content>
            </responseMessage>
        </ns2:response>
    </ns2:messageresponses>
</ns2:return> 

This shows the application client that there were three recipients of this message. 

  • 1 of the recipients is in the LessThan30 category, meaning they have responded with a 1 and will return to the office in less than 30 minutes
  • 1 of the recipients is in the MoreThan30 category, meaning they have responded with a 2 and will return to the office in more than 30 minutes
  • 1 of the recipients is in the NotComing category, meaning they have responded with a 3 and will not be returning to the office.

The detailed view also shows the application client information about the sender of the response, including Name and MRI, the date and time the response was issued, and the content of the response.

How to search through responses to a message

In any of the cases above, search parameters can be added to the URL to further filter the responses to a message based on a search query.

The following parameters are supported:

Parameter

Description

limit

Integer - The number of responses that will be returned in the query.
Default: 20

offset

Integer - The offset from 0 to start returning results from.
Default: 0

view

String - Whether to display a summary or a detailed view of responses
Default: summary
Supported values: summary. detailed

filter

String - Whether to filter responses by a response rule
Default: default
Supported values: default. responserule

searchCriteria

String - Allows the user to define the category of search criteria being looked up
Default: startsWith
Supported values: startsWith,contains,notcontains,exactMatch

searchValue

String - Allows the user to specify search content to search the responses for
Default: empty 

channel

String - Allows the user to specify which channels to search for the content
Default: sms
Supported values: all,sms,email,web, voice

Note: searchCriteria, searchValue and channel parameters only work when the filter parameter is set to default.  This is because when filter is set to responserule the searching and categorisation has already been performed.  Applications need to modify this before performing any search queries.

If we go back to our detailedResponses example, we can now demonstrate the use of searching to query the responses for some text we would like to find.

Using the links provided in the message response, the user can simply make a new API request to retrieve the detailedResponses URL. 

In the example above, the  detailedResponses URL is:

<ns3:link method="GET" 
   rel="detailedResponses" 
   uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&apikey=<yourkey>"/>

Lets assume we want to search the responses to this message for the string 'OK'.

So with the searching added, the request would look as follows:

HTTP 1.1 GET http://api.whispir.com/messages/069BF68E5E0FE99B/messageresponses?view=detailed&filter=default&searchCriteria=startsWith&searchValue=OK&channel=all&apikey=<yourkey>
Authorization: Basic 498nadsasdff09fewdsafjaa90f

This request is asking for a couple of things:

  1. The URL is specifically asking for all of the messageresponses to the message with ID 069BF68E5E0FE99B
  2. The View parameter is specifying that the message responses should be shown in a detailed view
  3. The Filter parameter is specifying that the filter should not use a response rule, it should show the default filter
  4. The SearchCriteria parameter is specifing the search should be looking for responses that startWith the searchValue
  5. The SearchValue parameter is specifying that the content to look for is the text OK
  6. The Channel parameter is specifying the search should cover all channels (SMS, Email, Voice)

As this is a GET request we don't have to provide any message body.

The response to this request could look as follows:

<?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 2 of 2</status>
    <ns2:messageresponses>
        <ns2:response>
            <from>
                <mri>John_Smith.484215.Critical_Incident_Management@Contact.whispir.com</mri>
                <name>John Smith</name>
            </from>
            <responseCategory>notmatched</responseCategory>
            <responseMessage channel="SMS">
                <acknowledged>28/09/12 08:48</acknowledged>
                <content>Thanks.</content>
            </responseMessage>
        </ns2:response>
        <ns2:response>
            <from>
                <mri>Fred_Smith.341550.Critical_Incident_Management@Contact.whispir.com</mri>
                <name>Fred Smith</name>
            </from>
            <responseCategory>matched</responseCategory>
            <responseMessage channel="SMS">
                <acknowledged>28/09/12 08:48</acknowledged>
                <content>OK, got it. Thanks.</content>
            </responseMessage>
        </ns2:response>
    </ns2:messageresponses>
</ns2:return>

We can see from the responseCategory in each of the responses above whether the search criteria has matched or notmatched for each of the responses.  The response that contained the content OK has been categorised as matched whereas the response that did not contain the content OK has been categorised as notmatched.

For more information about message responses, please contact apisupport@whispir.com or browse the forum.