Processing Message Responses

So far, we have looked at how to send messages to be delivered to recipients. The discussions did not cover how to process the response received after submission of the message request. This section looks at how to process the message response to know which destinations were accepted for message submission and which were not.

It must be emphasised that the destination status from responses received after submitting a message do not indicate delivery status. The destination status that are returned after submitting a message only indicate whether message is accepted to be delivered to the destination or not. Delivery reporting is discussed under the section on Reporting.

Message Response

A MessageResponse object is returned after submitting a message request. The submit() function has a return type of APIResponse which is the base class of all response classes. The return value after submitting a message must therefore be cast to an object of MessageResponse for inspection.

// submit message and store the response
MessageResponse response = request.submit() as MessageResponse;

' submit message and store the response
Dim response As MessageResponse
Set response = request.submit

' submit message and store the response
Dim response As MessageResponse = request.submit()

// submit message and store the response
MessageResponse response = (MessageResponse)request.submit();

// submit message and store the response
$response = $request->submit();

# submit message and store the response
response = request.submit()

Message Report

MessageReport is a data container that stores information about submitted message batch. It is also used to store information about delivery status of destinations added to the message. It is declared in the Zenoph.Notify.Report namespace. To use it, applications may need to import the Report namespace.

// MessageReport is found in the Report namespace
using Zenoph.Notify.Report;

' not applicable

' MessageReport is found in the Report namespace
Imports Zenoph.Notify.Report

// MessageReport is found in the Report namespace
import Zenoph.Notify.Report.MessageReport;

// MessageReport is found in the Report namespace
use Zenoph\Notify\Report\MessageReport;

# MessageReport is found in the Store namespace
from Zenoph.Notify.Report.MessageReport import MessageReport

To retrieve the MessageReport object in order to get information about submitted message batch, we need to call getReport() on the MessageResponse object returned from the submit() method call.

// submit message and store the response
MessageResponse response = request.submit() as MessageResponse;

// get the message report
MessageReport report = response.getReport();

' submit message and store the response
Dim response As MessageResponse
Set response = request.submit

' get the message report
Dim report As MessageReport
Set report = response.getReport

' submit message and store the response
Dim response As MessageResponse = request.submit()

' get the message report
Dim report As MessageReport = response.getReport()

// submit message and store the response
MessageResponse response = (MessageResponse)request.submit();

// get the message report
MessageReport report = response.getReport();

// submit message and store the response
$response = $request->submit();

// get the message report
$report = $response->getReport();

# submit message and store the response
response = request.submit()

# get the message report
report = response.getReport()

The MessageReport object contains information such as the batch Identifier, message category, message destinations, and whether the report received is a submit report or delivery report. We take a look at these below.

Batch Identifier

When you call submit() method on a message object, the request is considered as a single batch of tasks which needs to be completed. The message request is therefore assigned a unique identifier which can be used to get information about the request later.

Each separate call to submit() on a message object has its own unique identifier that can be used to reference to task in a later request. For example, the batch identifier can be used to request for delivery status of the destinations that were added.

To get the unique batch identifier for a message request, a call on getBatchId() has to be made.

// get the message report
MessageReport report = response.getReport();

// get the Id assigned to the message submission request
string batchId = report.getBatchId();

' get the message report
Dim report As MessageReport 
Set report = response.getReport 

' get the Id assigned to the message submission request
Dim batchId As String
Set batchId = report.getBatchId

' get the message report
Dim report As MessageReport = response.getReport()

' get the Id assigned to the message submission request
Dim batchId As String = report.getBatchId()

// get the message report
MessageReport report = response.getReport();

// get the Id assigned to the message submission request
String batchId = report.getBatchId();

// get the message report
$report = $response->getReport();

// get the Id assigned to the message submission request
$batchId = $report->getBatchId();

# get the message report
report = response.getReport()

# get the Id assigned to the message submission request
batchId = report.getBatchId()

When the message batch identifier has been obtained, it can be used later to get information about the submitted message. This can include requesting for delivery status or loading a scheduled message.

Message Category

Message Category the category of a particular message. For example, it can be SMS or Voice message.

To know the category of the message for which the message report references, we will need to call getCategory() method on the Message Report object.

Message Category is an enumeration in the Enums namespace and may need to be imported when needed.

// get the message report
MessageReport report = response.getReport();

// get the message category
MessageCategory category = report.getCategory();

' get the message report
Dim report As MessageReport 
Set report = response.getReport 

' get the message category
Dim category As MessageCategory
Set category = report.getCategory

' get the message report
Dim report As MessageReport = response.getReport()

' get the message category
Dim category As MessageCategory = report.getCategory()

// get the message report
MessageReport report = response.getReport();

// get the message category
MessageCategory category = report.getCategory();

// get the message report
$report = $response->getReport();

// get the message category
$category = $report->getCategory();

# get the message report
report = response.getReport()

# get the message category
category = report.getCategory()

When the category has been obtained, we can check which of the message categories is the message report that was returned.

Message Destinations

The list of destinations that were added to the message for submission can be obtained for inspection by calling getDestinations() on the MessageReport object. The function returns a collection of type MessageDestinationsList which contains the list of destinations. MessageDestinationsList class is defined in the Zenoph.Notify.Collections namespace.

// get the message destinations list
MessageDestinationsList destsList = report.getDestinations();

' get the message destinations list
Dim destsList As MessageDestinationsList
Set destsList = report.getDestinations

' get the message destinations list
Dim destsList As MessageDestinationsList = report.getDestinations()

// get the message destinations list
MessageDestinationsList destsList = report.getDestinations();

// get the message destinations list
$destsList = $report->getDestinations();

# get the message destinations list
destsList = report.getDestinations()

After obtaining the message destinations list, we need to iterate through the collection to get information about each destination. Information about each destination is stored in an object of MessageDestination class which exists in the Zenoph.Notify.Store namespace.

// get the message destinations list
MessageDestinationsList destsList = report.getDestinations();

// iterate throug the list for each destination information
foreach (MessageDestination destInfo in destsList){
    // get the phone number
    string phoneNumber = destInfo.getPhoneNumber();
  
    // get the unique identifier assigned to the destination
    string messageId = destInfo.getMessageId();
  
    // get the status which will indicate if message
    // will be submitted to the destination or not
    DestinationStatus status = destInfo.getSatus();
}

' get the message destinations list
Dim destsList As MessageDestinationsList
Set destsList = report.getDestinations

' iterate through the list for each destination information
For Each destInfo in destsList
    ' get the phone number
    Dim phoneNumber As String
    phoneNumber = destInfo.getPhoneNumber
  
    ' get the unique identifier assigned to the destination
    Dim messageId As String
    messageId = destInfo.getMessageId
  
    ' get the status which will indicate if message
    ' will be submitted to the destination or not
    Dim destStatus As DestinationStatus
    status = destInfo.getStatus
Next

' get the message destinations list
Dim destsList As MessageDestinationsList = report.getDestinations()

' iterate through the list for each destination information
For Each destInfo As MessageDestination In destsList
    ' get the phone number
    Dim phoneNumber As String = destInfo.getPhoneNumber()
  
    ' get the unique identifier assigned to the destination
    Dim messageId As String = destInfo.getMessageId();
  
    ' get the status which will indicate if message
    ' will be submitted to the destination or not
    Dim status As DestinationStatus = destInfo.getStatus()
Next

// get the message destinations list
MessageDestinationsList destsList = report.getDestinations();

// iterate through the list for each destination information
for (MessageDestination destInfo : destsList){
    // get the phone number
    String phoneNumber = destInfo.getPhoneNumber();
	
    // get the unique identifier assigned to the destination
    String messageId = destInfo.getMessageId();
	
    // get the status which will indicate if message
    // will be submitted to the destination or not
    DestinationStatus status = destInfo.getStatus();
}

// get the message destinations list
$destsList = $report->getDestinations();

// iterate through the list for each destination information
foreach ($destsList as $destInfo){
    // get the phone number
    $phoneNumber = $destInfo->getPhoneNumber();
  
    // get the unique identifier assigned to the destination
    $messageId = $destInfo->getMessageId();
  
    // get the status which will indicate if message
    // will be submitted to the destination or not
    $status = $destInfo->getStatus();
}

# get the message destinations list
destsList = report.getDestinations()

# iterate through the list for each destination information
for destInfo in destsList:
    # get the phone number
    phoneNumber = destInfo.getPhoneNumber()
	
    # get the unique identifier assigned to the destination
    messageId = destInfo.getMessageId()
	
    # get the status which will indicate if message
    # will be submitted to the destination or not
    status = destInfo.getStatus()

As seen from the sample code, we obtain the status of each destination with a call to getStatus() to know whether message will be or is being submitted to that destination or not. The status value is of the type DestinationStatus which exists in the Zenoph.Notify.Store namespace.

For non-scheduled messages, the status value will be DS_SUBMIT_ENROUTE if the message is being submitted to the destination. For scheduled messages, the status value will be DS_SUBMIT_SCHEDULED if the destination was accepted for message to be scheduled for delivery at the specified schedule date and time.

If the status is any other member of DestinationStatus enumeration constants apart from DS_PENDING_ENROUTE and DS_PENDING_SCHEDULED, then message will not be submitted to the destination. The reason will depend on the value of the destination status identifier returned.

// get the phone number
string phoneNumber = destInfo.getPhoneNumber();
  
// get the status which will indicate if message
// will be submitted to the destination or not
DestinationStatus status = destInfo.getSatus();

// we assume non-scheduled message request so we check for DS_PENDING_ENROUTE
if (status == DestinationStatus.DS_PENDING_ENROUTE){
    // message is being submitted to the destination
    Console.WriteLine("Message is being submitted to {0}", phoneNumber);
}
else {
    // destination not accepted. we can use a switch to determine the cause
    Console.WriteLine("Not submitted to {0}", phoneNumber);
}

' get the phone number
Dim phoneNumber As String
phoneNumber = destInfo.getPhoneNumber
  
' get the status which will indicate if message
' will be submitted to the destination or not
Dim destStatus As DestinationStatus
status = destInfo.getStatus

If status = DestinationStatus_DS_PENDING_ENROUTE Then
    ' message is being submitted to the destination
    Debug.Print "Message is being submitted to " & phoneNumber
Else
    ' destination not accepted. we can use a switch to determine the cause
    Debug.Print "Not submitted to " & phoneNumber
End If

' get the phone number
Dim phoneNumber As String = destInfo.getPhoneNumber()
  
' get the status which will indicate if message
' will be submitted to the destination or not
Dim status As DestinationStatus = destInfo.getStatus()

If status = DestinationStatus.DS_PENDING_ENROUTE Then
    ' message is being submitted to the destination
    Console.WriteLine("Message is being submitted to {0}", phoneNumber)
Else
    ' destination not accepted. we can use a switch to determine the cause
    Console.WriteLine("Not submitted to {0}", phoneNumber)
End If

// get the phone number
String phoneNumber = destInfo.getPhoneNumber();
	
// get the status which will indicate if message
// will be submitted to the destination or not
DestinationStatus status = destInfo.getStatus();

if (status == DestinationStatus.DS_PENDING_ENROUTE){
    // message is being submitted to the destination
    System.out.println("Message is being submitted to %s", phoneNumber);
}
else {
    // destination not accepted. we can use a switch to determine the cause
    System.out.println("Not submitted to %s", phoneNumber);
}

// get the phone number
$phoneNumber = $destInfo->getPhoneNumber();
  
// get the status which will indicate if message
// will be submitted to the destination or not
$status = $destInfo->getStatus();

if ($status == DestinationStatus::DS_PENDING_ENROUTE){
    // message is being submitted to the destination
    printf("Message is being submitted %s", $phoneNumber);
}
else {
    // destination not accepted. we can use a switch to determine the cause
    printf("Not submitted to %s", $phoneNumber);
}

# get the phone number
phoneNumber = destInfo.getPhoneNumber()
	
# get the status which will indicate if message
# will be submitted to the destination or not
status = destInfo.getStatus()

if status == DestinationStatus.DS_PENDING_ENROUTE:
    # message is being submitted to the destination
    print("Message is being submitted to %s" % phoneNumber)
else:
    # destination not accepted. we can use a switch to determine the cause
    print("Not submitted to %s" % phoneNumber)

Report Type

When the submit() method is called, the request is sent to the messaging server for processing. The messaging server reads the request data and immediately returns a report before continuing with processing of the message for delivery.

The report that is returned and stored in MessageResponse after a call to submit() is not a report that contains message delivery information. We refer to this as the Submit Report.

A Delivery Report on the other hand is a message report that contains message delivery information. Such report is returned when a delivery request is made.

To know if a report has delivery information, we need to call isDeliveryReport(). If the report contains message delivery information, the method returns true otherwise false will be returned.

// get the message report
MessageReport report = response.getReport();

// see if it is delivery report or not
if (report.isDeliveryReport()){
    Console.WriteLine("This is delivery report data.");
}
else {
    Console.WriteLine("This is submit report data.");
}

' get the message report
Dim report As MessageReport 
Set report = response.getReport 

' see if it is a delivery report or not
If report.isDeliveryReport = True Then
    Debug.Print "This is delivery report data."
Else
    Debug.Print "This is submit report data."
End If

' get the message report
Dim report As MessageReport = response.getReport()

' see if it is delivery report or not
If report.isDeliveryReport = True Then
    Console.WriteLine("This is delivery report data.")
Else
    Console.WriteLine("This is submit report data.")
End If

// get the message report
MessageReport report = response.getReport();

// see if it is delivery report or not 
if (report.isDeliveryReport()){
    System.out.println("This is delivery report data.");
}
else {
    System.out.println("This is submit report data.");
}

// get the message report
$report = $response->getReport();

// see if it is delivery report or not
if ($report->isDeliveryReport()) {
    echo "This is delivery report data.");
}
else {
    echo "This is submit report data.");
}

# get the message report
report = response.getReport()

# see if it is delivery report or not 
if report.isDeliveryReport() == True:
    print("This is delivery report data.")
else:
    print("This is submit report data.")