Message Status

Understanding Message Status

This section describes the different ways that you can retrieve the status of 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.

Message Status Overview

Whispir will automatically monitor the status of each message after it has been sent to each recipient.  Using the message status information, you are able to determine who received the message, what exact time they received it, on what message channel (SMS, Email, Voice), whether they replied to the message, what time they replied, and on what messaging channel.

Each message progresses through various states, from Pending to Acknowledged.

Message Status Types

Status

Description

Pending The message has not yet been processed by Whispir.  It is in a queue and will be processed shortly.
Sent The message has been sent from Whispir to the recipient, however, there has been no acknowledgement from the recipient via read receipt that the message has arrived.
Received

Email: Whispir has received acknowledgement via a read receipt that the message has arrived in the inbox.

SMS: Received status can mean one of two things for SMS.

  1. The message has been received by the network and is being processed for delivery to the handset.  How long the message stays in this state is up to the telco.
  2. The message has been received by the handset and confirmed by the telco.
Acknowledged Whispir has received an intended response from the recipient, either by reply SMS, Email or Voice prompt
Undeliverable Whispir was not able to deliver the message to the intended recipient on the specified channel.  This may be due to incorrect information e.g. wrong phone number or email address, or due to poor network coverage.

Using the API, developers are able to access this status information at either a Summary or Detailed level.  This is described in more detail in the documentation below.

The first thing a developer must do in order to retrieve the status of a sent message is retrieve the message using the API.

How to 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>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 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.

How to retrieve the summary status of a message

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

In the example above, the summaryStatus URL is:

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

So the request would look as follows:

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

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:messageStatuses>
  <ns2:messageStatus>
    <ns2:link method="GET" 
             rel="self" 
             uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messagestatus?view=summary&apikey=<yourkey>"/>
    <categories>
      <status name="Sent">
        <percentageTotal>0.0%</percentageTotal>
        <recipientCount>0</recipientCount>
      </status>
      <status name="Pending">
        <percentageTotal>0.0%</percentageTotal>
        <recipientCount>0</recipientCount>
      </status>
      <status name="Received">
        <percentageTotal>0.0%</percentageTotal>
        <recipientCount>0</recipientCount>
      </status>
      <status name="Acknowledged">
        <percentageTotal>100.0%</percentageTotal>
        <recipientCount>2</recipientCount>
      </status>
      <status name="Undeliverable">
        <percentageTotal>0.0%</percentageTotal>
        <recipientCount>0</recipientCount>
      </status>
    </categories>
  </ns2:messageStatus>
 </ns2:messageStatuses>
</ns2:return>

This response states that of the 2 people that were sent the message, both of them Acknowledged it by sending a response.  Your application can use this information to easily determine the numbers of recipients in each state and show a small graph.

You can use the Detailed Status request to show more detailed information, e.g. who acknowledged the message, and at what time.

How to retrieve the detailed status of a message

Similar to the summaryStatus, using the links provided in the message response, the user can simply make a new API request to retrieve the detailedStatus URL. 

In the example above, the detailedStatus URL is:

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

So the request would look as follows:

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

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:messageStatuses>
    <ns2:messageStatus>
      <ns2:link method="GET" 
	        rel="self" 
                uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messagestatus?apikey=dmdjqc3wx93aqyzcwwyk5dqz&view=detailed"/>
      <status type="email">
        <destination></destination>
        <status></status>
      </status>
      <status type="sms">
        <acknowlegedTimestamp>2012-09-28T08:47:50+10:00</acknowlegedTimestamp>
        <destination>61456191351</destination>
        <receivedTimestamp>2012-09-28T08:47:20+10:00</receivedTimestamp>
        <sentTimestamp>2012-09-28T08:47:17+10:00</sentTimestamp>
        <status>READ</status>
      </status>
      <status type="voice">
        <destination></destination>
        <status></status>
      </status>
      <info> Out bound SMS text message sent OK. </info>
      <name>John Smith</name>
    </ns2:messageStatus>
    <ns2:messageStatus>
      <ns2:link method="GET" 
	        rel="self" 
                uri="http://api.whispir.com/messages/069BF68E5E0FE99B/messagestatus?apikey=dmdjqc3wx93aqyzcwwyk5dqz&view=detailed"/>
      <status type="email">
        <destination></destination>
        <status></status>
      </status>
      <status type="sms">
        <acknowlegedTimestamp>2012-09-28T08:47:49+10:00</acknowlegedTimestamp>
        <destination>61456191368</destination>
        <receivedTimestamp>2012-09-28T08:47:20+10:00</receivedTimestamp>
        <sentTimestamp>2012-09-28T08:47:17+10:00</sentTimestamp>
        <status>READ</status>
      </status>
      <status type="voice">
        <destination></destination>
        <status></status>
      </status>
      <info> Out bound SMS text message sent OK. </info>
      <name>Fred Smith</name>
    </ns2:messageStatus>
  </ns2:messageStatuses>
</ns2:return>

The user can easily use this information to receive a far more detailed status breakdown of (for each recipient):

  • The name of the recipient
  • The channel type (SMS, Email, Voice, Web)
  • The sent timestamp for each channel
  • The received timestamp for each channel
  • The acknowledged timestamp for each channel
  • The undeliverable timestamp (only present when the channel is undeliverable)
  • The overall status for this recipient (PEND, SENT, READ, ACKL, UNDVBL)
  • The information text describing how this message has progressed.

Once you have processed the status information, the next likely piece of information you will be looking to find is the content of the responses (if any).  This is further described in the next section Understanding Message Responses.