Send SMS

Send an SMS through your application by making a HTTP POST request to the following endpoints:

Endpoints

Live: https://api.africastalking.com/version1/messaging
Sandbox: https://api.sandbox.africastalking.com/version1/messaging

Request Parameters

In addition to the standard request headers, the body of the request should contain the following fields:

Parameter Description
username
String
Required
Your Africa's Talking application username.
to
String
Required
A comma separated string of recipients' phone numbers.
message
String
Required
The message to be sent.
from
String
Optional
Your registered short code or alphanumeric, defaults to AFRICASTKNG.
bulkSMSMode
String
Optional
This is used by the Mobile Service Provider to determine who gets billed for a message sent using a Mobile-Terminated ShortCode. The default value is 1 (which means that the sender - Africa's Talking account being used - gets charged). This parameter will be ignored for messages sent using alphanumerics or Mobile-Originated shortcodes. The value must be set to 1 for bulk messages.
enqueue
String
Optional
This is used for Bulk SMS clients that would like to deliver as many messages to the API before waiting for an acknowledgement from the Telcos. If enabled, the API will store the messages in a queue and send them out asynchronously after responding to the request.
keyword
String
Optional
The keyword to be used for a premium service.
linkId
String
Optional
This is used for premium services to send OnDemand messages. We forward the linkId to your application when the user sends a message to your service.
retryDurationInHours
String
Optional
This specifies the number of hours your subscription message should be retried in case it's not delivered to the subscriber.

API Response

The body of the response will be a JSON object containing the following fields:

Parameter Description
SMSMessageData
Map
A Map detailing the eventual result of the sms request. It contains the following fields:
  • Message: String A summary of the total number of recipients that the sms was sent to and the total cost incurred.
  • Recipients List A list of recipients included in the original request. Each recipient is a Map with the following fields:
    • statusCode: Integer This corresponds to the status of the request. Possible values are:
      • 100: Processed
      • 101: Sent
      • 102: Queued
      • 401: RiskHold
      • 402: InvalidSenderId
      • 403: InvalidPhoneNumber
      • 404: UnsupportedNumberType
      • 405: InsufficientBalance
      • 406: UserInBlackList
      • 407: CouldNotRoute
      • 500: InternalServerError
      • 501: GatewayError
      • 502: RejectedByGateway
    • number: String The recipient's phone number
    • cost: String Amount incurred to send this sms. The format of this string is: (3-digit Currency Code)(space)(Decimal Value) e.g KES 1.00
    • Status: String A string indicating whether the sms was sent to this recipient or not. This does not indicate the delivery status of the sms to this recipient.
    • messageId: String The messageId received when the sms was sent.

Below is a sample send sms response for a successful request:

{
    "SMSMessageData": {
        "Message": "Sent to 1/1 Total Cost: KES YY",
        "Recipients": [{
            "statusCode": 101,
            "number": "+254711XXXYYY",
            "cost": "KES YY",
            "status": "Success",
            "messageId": "ATXid_1"
        }]
    }
}

Sending messages sample code

The C# code snippet below shows how to send SMS Messages using our API.

The code uses our C# gateway class: AfricasTalkingGateway.cs [ Download]

To help decode JSON responses, you will need to add a reference to System.Web.Extensions and System.Microsoft.CSharp

Sending a Message

using System;

class MainClass
{
	static public void Main (){
		
		// Specify your login credentials
		string username = "MyAppUsername";
		string apiKey   = "MyAppAPIKey"; 
		
		// Specify the numbers that you want to send to in a comma-separated list
		// Please ensure you include the country code (+254 for Kenya in this case)
		string recipients = "+254711XXXYYY,+254733YYYZZZ";

		// And of course we want our recipients to know what we really do
		string message = "I'm a lumberjack and its ok, I sleep all night and I work all day";
		
		// Create a new instance of our awesome gateway class
		AfricasTalkingGateway gateway = new AfricasTalkingGateway (username, apiKey);

		// Any gateway errors will be captured by our custom Exception class below,
		// so wrap the call in a try-catch block   
		try {

			// Thats it, hit send and we'll take care of the rest
			
			dynamic results = gateway.sendMessage (recipients, message);
			
			foreach( dynamic result  in results){
				Console.Write((string)result["number"] + ",");
				Console.Write((string)result["status"] + ","); // status is either "Success" or "error message"
				Console.Write((string)result["statusCode"] + ",");
				Console.Write((string)result["messageId"] + ",");
				Console.WriteLine((string)result["cost"]);
			}
		} catch (AfricasTalkingGatewayException e) {

			Console.WriteLine ("Encountered an error: " + e.Message);		

		}
	}
}

Sending messages: Use short code/Sender id

// Sending Messages using sender id/short code
using System;

class MainClass
{
	static public void Main (){
		
		string username = "MyAppUsername";
		string apiKey   = "MyAppAPIKey"; 
		
		string recipients = "+254711XXXYYY,+254733YYYZZZ";
		
		string message = "I'm a lumberjack and its ok, I sleep all night and I work all day";
		
		// Specify your AfricasTalking shortCode or sender id
		string from = "shortCode or senderId";
		
		AfricasTalkingGateway gateway = new AfricasTalkingGateway (username, apiKey);
		
		try {
			
			dynamic results = gateway.sendMessage (recipients, message, from);
			
			foreach( dynamic result  in results){
				Console.Write((string)result["number"] + ",");
				Console.Write((string)result["status"] + ",");
				Console.Write((string)result["statusCode"] + ",");
				Console.Write((string)result["messageId"] + ",");
				Console.WriteLine((string)result["cost"]);
			}
		} catch (AfricasTalkingGatewayException e) {

			Console.WriteLine ("Encountered an error: " + e.Message);		

		}
	}
}

Sending messages: Queue messages to be sent later

//Message queueing 
using System;

class MainClass
{
	static public void Main (){
		
		string username = "MyAppUsername";
		string apiKey   = "MyAppAPIKey"; 
		
		string recipients = "+254711XXXYYY,+254733YYYZZZ";
		
		string message = "I'm a lumberjack and its ok, I sleep all night and I work all day";
		
		string from = null; //$from = "shortCode or senderId";
		
		int bulkSMSMode = 1; // This should always be 1 for bulk messages
		
		// enqueue flag is used to queue messages incase you are sending a high volume.
		// The default value is 0.
		Hashtable options = new Hashtable();
		options["enqueue"] = 1;
		
		AfricasTalkingGateway gateway = new AfricasTalkingGateway (username, apiKey);
		
		try {
			
			dynamic results = gateway.sendMessage (recipients, message, from, bulkSMSMode, options);
			
			foreach( dynamic result  in results){
				Console.Write((string)result["number"] + ",");
				Console.Write((string)result["status"] + ",");
				Console.Write((string)result["statusCode"] + ",");
				Console.Write((string)result["messageId"] + ",");
				Console.WriteLine((string)result["cost"]);
			}
		} catch (AfricasTalkingGatewayException e) {

			Console.WriteLine ("Encountered an error: " + e.Message);		

		}
	}
}

Sending premium rated (subscription) messages

// Sending premium rated messages
using System;

class MainClass
{
	static public void Main (){
		
		string username = "MyAppUsername";
		string apiKey   = "MyAppAPIKey"; 
		
		string recipients = "+254711XXXYYY,+254733YYYZZZ";
		
		string message = "Get your daily message and thats how we roll.";
		
		// Specify your premium shortCode and keyword
		string shortCode = "XXXXX";
		string keyword   = "premiumKeyword";
		
		// Set the bulkSMSMode flag to 0 so that the subscriber get charged
		int bulkSMSMode = 0;
		
		// Create an array which would hold the following parameters:
		// keyword: Your premium keyword,
		// retryDurationInHours: The numbers of hours our API should retry to send the message 
		// incase it doesn't go through. It is optional
		
		Hashtable options = new Hashtable();
		options["keyword"] = keyword;
		options["retryDurationInHours"] = No. of hours to retry sending message;
		
		AfricasTalkingGateway gateway = new AfricasTalkingGateway (username, apiKey);
		
		try {
			
			dynamic results = gateway.sendMessage (recipients, message, shortCode, bulkSMSMode, options);
			
			foreach( dynamic result  in results){
				Console.Write((string)result["number"] + ",");
				Console.Write((string)result["status"] + ",");
				Console.Write((string)result["statusCode"] + ",");
				Console.WriteLine((string)result["messageId"]);
			}
		} catch (AfricasTalkingGatewayException e) {

			Console.WriteLine ("Encountered an error: " + e.Message);		

		}
	}
}

Sending premium rated (onDemand) messages

// Sending onDemand premium messages
using System;

class MainClass
{
	static public void Main (){
		
		string username = "MyAppUsername";
		string apiKey   = "MyAppAPIKey"; 
		
		string recipients = "+254711XXXYYY,+254733YYYZZZ";
		
		string message = "Get your daily message and thats how we roll.";
		
		string shortCode = "XXXXX";
		string keyword   = "premiumKeyword"; // string keyword = null;
		
		int bulkSMSMode = 0;
		
		// Create a hashtable which would hold the parameters keyword, retryDurationInHours and linkId
		// linkId is received from the message sent by subscriber to your onDemand service
		string linkId = "messageLinkId";
		
		Hashtable options = new Hashtable();
		options["keyword"] = keyword;
		options["linkId"] = linkId;
		options["retryDurationInHours"] = No. of hours to retry sending message;
		
		AfricasTalkingGateway gateway = new AfricasTalkingGateway (username, apiKey);
		
		try {
			
			dynamic results = gateway.sendMessage (recipients, message, shortCode, bulkSMSMode, options);
			
			foreach( dynamic result  in results){
				Console.Write((string)result["number"] + ",");
				Console.Write((string)result["status"] + ",");
				Console.Write((string)result["statusCode"] + ",");
				Console.Write((string)result["messageId"] + ",");
			}
		} catch (AfricasTalkingGatewayException e) {

			Console.WriteLine ("Encountered an error: " + e.Message);		

		}
	}
}