Message Requests

In the previous section on Request Basics, we looked at basics of sending requests and processing responses. This section extends our earlier discussions with much emphasis on messaging.

Request Initialisation

To send SMS, for example, SMSRequest object has be created and the same object can be used to set message properties, add message destinations, and also submit the message properties. The following code initialises a message request object.

  SMSRequest request = new SMSRequest();

Internally, the request object creates an instance of SMScomposer. In this case, an object of SMSComposer is implicitly initialised as a result of the instantiation of the SMSRequest object. Message properties can be set using the request object.

Request Host

During our discussion on Request Authentication, it was emphasised that the domain on which the messaging account was created, preceded by api., must be set as the request host. This is done with a call to setHost() method.

  // initialise request object
  request = new SMSRequest();
  
  // set host
  request.setHost("api.smsonlinegh.com");

Request Authentication

All requests to the server require user authentication. In addition to setting the request host, authentication model needs to be specified. For example, performing authentication with API Key requires setting the authentication model as API_KEY and then setting your account API key for authentication.

  // set authentication details
  request.setAuthModel(AuthModel.API_KEY);
  request.setAuthApiKey("d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128");

Message Properties

Message request objects can be used to set properties of message composer objects to be submitted.

  // set message properties
  request.setMessage("A new test message!");
  request.setSender("TEST");
  request.setSMSType(SMSType.GSM_DEFAULT);
Note

The value set as sender must exist in the list of user message sender names. If the name has not been added in user message sender names, then the message will not be submitted. The sender name must be requested from the user account under SMS Messaging menu option.

Message Destinations

Phone numbers can also be added to a message using the message request object. This is done by calling addDestination() or addDestinationEx() methods using the initialised message request object.

  // add message destinations
  request.addDestination("0241111111");
  request.addDestination("233201111111");

To add destinations from a collection or array, a call to addDestinationsFromCollection() can be made. VB/VBA applications must rather call addDestinationsFromCollectionEx() to add message destinations from an array.

In the sample code below, we create an array or collection directly in the code for demonstration purposes only. When integrating in your applications, the source of the collection may be from file, database, or from other source. When you have received your array data, you will need to call addDestinationsFromCollection() and specify the array or list data as argument to the method call.

  // a list of destinations
  List<string> destsList = new List<string>();
  destsList.Add("0242053072");
  destsList.Add("0246314915");
	
  // add list of destinations
  request.addDestinationsFromCollection(destsList);
	
  // an array of destinations
  string[] destsArr = new string[] {"0242053072", "0246314915"};
	
  // add array of destinations
  request.addDestinationsFromCollection(destsArr);

Actually, there are more that can be done with message destinations than as seen in the sample code. The next section on Message Destinations delves deeper into adding message destinations. It is very important to read the discussions in that section for much control and simplicity in dealing with message destinations.

Submitting Message

Once the message properties have been set with destinations added, the message can but submitted for delivery. This is done by calling submit() on the message request object.

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

Message Response

After submitting a message, an object of type MessageResponse is returned. It should be emphasised that all requests return an object of type APIResponse when submitted. APIResponse is the base class for other response objects. This means that MessageResponse is a sub-class of APIResponse. Hence, the response object, after submitting a message request, may need to be cast to MessageResponse in order to process the response. The section on Message Response extensively covers the internals of the MessageResponse object and how to effectively process message responses.

Summary

In this section, we have looked at basic messaging procedures using an object of SMSRequest to set message properties and also submit the message. In the subsequent discussions, we will go by the approach discussed in this section.

We also considered the most basic way of adding message destinations. The next section is entirely devoted to adding message destinations. As indicated earlier, it is highly recommended to read this section in order to have much control and simplicity in messaging with our programming SDKs, especially when adding message destinations.

SMS Test

The following sample code can be used to send a test SMS using the messaging SDK.

using System;

using Zenoph.Notify.Enums;
using Zenoph.Notify.Request;
using Zenoph.Notify.Response;

public class TestMessage {
    public static void Main(){
        try {
            // initialise request object 
            SMSRequest request = new SMSRequest();
			
            // set request host
            request.setHost("api.smsonlinegh.com");
			
            // By default requests will be sent using SSL/TLS with https connection.
            // If you encounter SSL/TLS warning or error, your machine may be using unsupported
            // SSL/TLS version. In that case uncomment the following line to set it to false
            // request.useSecureConnection(false);

            // set authentication details.
            request.setAuthModel(AuthModel.API_KEY);
            request.setAuthApiKey("d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128");
			
            // message properties
            request.setMessage("This is a test message!");
            request.setSMSType(SMSType.GSM_DEFAULT);
            request.setSender("TEST");		// should be registered
			
            // add message destination
            request.addDestination("0242053072");
			
            // send message.
            request.submit();
        }
		
        catch (Exception ex){
            // output error message
            Console.WriteLine(String.Format("Error: {0}.", ex.Message));
        }
    }
}

As emphasised earlier, the SMS sender name used in the call to setSender() function must exist in the list of user message sender names. If the name has not been added in user message sender names, then it must be requested from the user account under SMS Messaging menu option.