Click or drag to resize
Processing Submit Responses

Sometimes when a message is submitted, the submit status of the destinations may not be returned but rather a token that can be used to query the submit status of the destinations. The conditions under which either a token or submit status of the destinations are returned are provided in the discussion of submit method and non-personalised messaging.

This section looks at how to process token responses when there is the need. In other words, it looks at how to query the submit status of submitted destinations when a token is returned. A token will always be returned when any of the following three conditions is true:

The status of submitted destinations can be obtained by calling getSubmitStatus(String, STATUSQUERY) with the returned token and one or more of STATUSQUERY enumeration. The method returns a Dictionary of the specified states and the corresponding destinations. For a full understanding, suppose we send a message and a token is returned and that we are interested in the submit status of the destinations,

Usually, when there are lot of phone numbers to add to the destinations list, they will be added in an iteration before submission as shown below:

List<string> phonenums = sms.extractPhoneNumbers("string containing phone numbers");

// add phone numbers in an iteration.
foreach (string number in phonenums)
    sms.addRecipient(number, true);

// phone numbers have been added. submit the message
List<string[]> resp = sms.submit();

When the total number of destinations added is greater than the maximum value for batch submit for which submit status of the destinations will be immediately return, the SMS server will return a token and continue with the submission of the message. If there is the need to get the submit status of all the destinations immediately, then the iteration must be changed to the processing as shown next:

List<string> phonenums = sms.extractPhoneNumbers("string containing phone numbers");

// add phone numbers in an iteration.
foreach (string number in phonenums)
{
    sms.addRecipient(number, true);

    // check the destinations added. If total is equal to the maximum value of batch submission, 
    // then submit the message to added destinations and add the rest.

    if (sms.getRecipientsCount() == ZenophSMS.getBatchSubmitMax())
    {
        // get and process response. A method can be defined to do this
        List<string[]> resp = sms.submit();
        sms.clearRecipients();    // very important to ensure that previous list is emptied.

        // process the status. (here let's print them)
        foreach (string[] s in resp)
            Console.WriteLine("Phone Number: {0},   Status: {1},    Identifier: {2}", s[1], s[0], s[2]);
    }
}

// If there are other phone numbers, submit them.
if (sms.getRecipientsCount() > 0)
    List<string[]> resp = sms.submit();

Submitting messages this way ensures that the SMS server immediately submits the message to the added destinations and return with the submit status of the destinations before adding the rest for submission.

Processing Token Responses

A token is always returned for personalised messages as well as when a message is submitted with total number of destinations exceeding the maximum value for batch submission. When the token is obtained, it can be used to request for the status of the submitted destinations if there is the need.

When a token is returned, applications can request for the submit status of the destinations by calling the getSubmitStatus(String, STATUSQUERY) method. The second argument to the method is a parameter list of STATUSQUERY which specifies the states that are being requested. By default, the method does not return the destinations but only the total number of either submitted, pending, or rejected destinations depending on the states that were requested. The overloaded method getSubmitStatus(String, Boolean, STATUSQUERY) takes an argument to tell whether the destinations should be returned as well or not.

When there is the need to obtain the submit status of the destinations from a token, it is highly recommended to call getSubmitStatus(String, STATUSQUERY) since it does not load the destinations. Then from the returned statistics, if the number of destinations pending is zero, then it means that the message has been submitted to all destinations. Then if there is the need to load the destinations and their submit status, getSubmitStatus(String, Boolean, STATUSQUERY) can be called while passing true as the second argument to the method call.

The following code is a demonstration of how to get the status of submitted destinations.

using System;
using System.Threading;
using System.Collections.Generic;
using Zenoph.SMSLib;
using Zenoph.SMSLib.Enums;

class SMSTest
{
    public static void Main(string[] args)
    {
        try
        {
            // initialise SMS object
            ZenophSMS sms = new ZenophSMS();
            sms.setUser("account_login");
            sms.setPassword("account_password");
            sms.authenticate();

            // set message parameters.
            sms.setMessage("Hello there!");
            sms.setSenderId("SMSTEST");
            sms.setMessageType(MSGTYPE.TEXT);

            // suppose we have a lot of destinations to add from string
            foreach (string phonenum in sms.extractPhoneNumbers("string containing phone numbers"))
                sms.addRecipient(phonenum, true);

            // submit the message.
            List<string[]> resp = sms.submit();

            // if the total destinations exceeds the maximum value for batch submit,
            // then a token was returned from the call.
            if (sms.getRecipientsCount() > ZenophSMS.getBatchSubmitMax() || sms.isPersonalised())    // then a token was returned.
            {
                processTokenResponse(resp[0][0], sms);
            }

            else    // the submit status of the destinations were returned
            {
                // process them as done earlier.
            }
        }

        catch (SMSException sex)
        {
            Console.WriteLine("Error: {0}", sex.Message);
        }

        catch (Exception ex)
        {
              Console.WriteLine("Error: {0}", ex.Message);
        }
    }

    static void processTokenResponse(string token, ZenophSMS sms)
    {
        if (string.IsNullOrEmpty(token))
            throw new Exception("Invalid token for requesting submit status.");

        Dictionary<STATUSQUERY, List<string>> st = null;

        do
        {
            Thread.Sleep(5000);
            st = sms.getSubmitStatus(token, STATUSQUERY.PENDING);   // only want to know if some are pending.
        } while (Convert.ToInt32(st[STATUSQUERY.PENDING][0]) > 0);

        // at this point all message has been submitted to all destinations.
        // If we are interested in the destinations and their states, we can do that below

        st = sms.getSubmitStatus(token, true, STATUSQUERY.SUBMITTED, STATUSQUERY.REJECTED);

        // we can obtain them separately.
        List<string> submitted = st[STATUSQUERY.SUBMITTED];
        List<string> rejected  = st[STATUSQUERY.REJECTED];

        // we can do what we want to do with the returned data.
    }
}