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 Java code snippet below shows how to send SMS Messages using our API.

The code uses our Java SDK.

Sending a message

/* Import SDK classes */
import com.africastalking.Callback;
import com.africastalking.SmsService;
import com.africastalking.sms.Message;
import com.africastalking.sms.Recipient;
import com.africastalking.AfricasTalking;

import java.util.List;
import java.io.IOException;

public class TestSending
{
    public static void main(String[] args)
    {
		/* Set your app credentials */
		String USERNAME = "sandbox";
		String API_KEY = "";

		/* Initialize SDK */
		AfricasTalking.initialize(USERNAME, API_KEY);

		/* Get the SMS service */
		SmsService sms = AfricasTalking.getService(AfricasTalking.SERVICE_SMS);

		/* Set the numbers you want to send to in international format */
		String[] recipients = new String[] {
			"+254711XXXYYY", "+254702XXXYYY"
		};

		/* Set your message */
		String message = "We are lumberjacks. We sleep all day and code all night";
		
		/* That’s it, hit send and we’ll take care of the rest */
		try {
            List<Recipient> response = sms.send(message, recipients, true);
			for (Recipient recipient : response) {
				System.out.print(recipient.number);
				System.out.print(" : ");
				System.out.println(recipient.status);
			}
		} catch(Exception ex) {
			ex.printStackTrace();
		}
   	}
}

Sending a message using a shortCode or senderId

/* Import SDK classes */
import com.africastalking.Callback;
import com.africastalking.SmsService;
import com.africastalking.sms.Message;
import com.africastalking.sms.Recipient;
import com.africastalking.AfricasTalking;

import java.util.List;
import java.io.IOException;

public class TestSendingWithSenderID
{
    public static void main(String[] args)
    {
		/* Set your app credentials */
		String USERNAME = "sandbox";
		String API_KEY = "";

		/* Initialize SDK */
		AfricasTalking.initialize(USERNAME, API_KEY);

		/* Get the SMS service */
		SmsService sms = AfricasTalking.getService(AfricasTalking.SERVICE_SMS);

		/* Set the numbers you want to send to in international format */
		String[] recipients = new String[] {
			"+254711XXXYYY", "+254702XXXYYY"
		};

		/* Set your message */
		String message = "We are lumberjacks. We sleep all day and code all night";

		/* Set your shortCode or senderId */
		String from = "XXXXX"; // or "ABCDE"
		
		/* That’s it, hit send and we’ll take care of the rest */
		try {
			List<Recipient> response = sms.send(message, from, recipients, true);
			for (Recipient recipient : response) {
				System.out.print(recipient.number);
				System.out.print(" : ");
				System.out.println(recipient.status);
			}
		} catch(Exception ex) {
			ex.printStackTrace();
		}
   	}
}

Enqueue messages

/* Import SDK classes */
import com.africastalking.Callback;
import com.africastalking.SmsService;
import com.africastalking.sms.Message;
import com.africastalking.sms.Recipient;
import com.africastalking.AfricasTalking;

import java.util.List;
import java.io.IOException;

public class TestSendingEnqueue
{
    public static void main(String[] args)
    {
		/* Set your app credentials */
		String USERNAME = "sandbox";
		String API_KEY = "";

		/* Initialize SDK */
		AfricasTalking.initialize(USERNAME, API_KEY);

		/* Get the SMS service */
		SmsService sms = AfricasTalking.getService(AfricasTalking.SERVICE_SMS);

		/* Set the numbers you want to send to in international format */
		String[] recipients = new String[] {
			"+254711XXXYYY", "+254702XXXYYY"
		};

        /* Set your message */
		String message = "We are lumberjacks. We sleep all day and code all night";

		/* Set the enqueue flag to true, useful when you are sending high volumes */
        boolean enqueue = true; 
		
		/* That’s it, hit send and we’ll take care of the rest */
		try {
			List<Recipient> response = sms.send(message, recipients, enqueue);
			for (Recipient recipient : response) {
				System.out.print(recipient.number);
				System.out.print(" : ");
				System.out.println(recipient.status);
			}
		} catch(Exception ex) {
			ex.printStackTrace();
		}
   	}
}

Sending a premium rated subscription message

/* Import SDK classes */
import com.africastalking.Callback;
import com.africastalking.SmsService;
import com.africastalking.sms.Message;
import com.africastalking.sms.Recipient;
import com.africastalking.AfricasTalking;

import java.util.List;
import java.io.IOException;

public class TestSendingPremium
{
    public static void main(String[] args)
    {
		/* Set your app credentials */
		String USERNAME = "sandbox";
		String API_KEY = "";

		/* Initialize SDK */
		AfricasTalking.initialize(USERNAME, API_KEY);

		/* Get the SMS service */
		SmsService sms = AfricasTalking.getService(AfricasTalking.SERVICE_SMS);

		/* Set the numbers you want to send to in international format */
		String[] recipients = new String[] {
			"+254711XXXYYY", "+254702XXXYYY"
		};

        /* Set your message */
		String message = "We are lumberjacks. We sleep all day and code all night";

		/* Set your premium product shortCode and keyword */
		String from = "8989";
		String keyword = "ABC";

		/* Set the number of hours we should retry to send the message before giving
		 	a failure status in case it doesn't go through */
		int retryDurationInHours = 1;

		/* That’s it, hit send and we’ll take care of the rest */
		try {
			List<Recipient> response = sms.sendPremium(
				message,
				from,
				keyword,
				null,
				retryDurationInHours,
				recipients
			);
			for (Recipient recipient : response) {
				System.out.print(recipient.number);
				System.out.print(" : ");
				System.out.println(recipient.status);
			}
		} catch(Exception ex) {
			ex.printStackTrace();
		}
   	}
}

Sending a premium rated onDemand message

/* Import SDK classes */
import com.africastalking.Callback;
import com.africastalking.SmsService;
import com.africastalking.sms.Message;
import com.africastalking.sms.Recipient;
import com.africastalking.AfricasTalking;

import java.util.List;
import java.io.IOException;

public class TestSendingPremium
{
    public static void main(String[] args)
    {
		/* Set your app credentials */
		String USERNAME = "sandbox";
		String API_KEY = "";

		/* Initialize SDK */
		AfricasTalking.initialize(USERNAME, API_KEY);

		/* Get the SMS service */
		SmsService sms = AfricasTalking.getService(AfricasTalking.SERVICE_SMS);

		/* Specify the numbers you want to send to in international format */
		String[] recipients = new String[] {
			"+254711XXXYYY", "+254702XXXYYY"
		};

		/* Set your message */
		String message = "We are lumberjacks. We sleep all day and code all night";

		/* Set your premium product shortCode and keyword */
		String from = "8989";
		String keyword = "ABC";

		/* Set the number of hours we should retry to send the message before giving
		 	a failure status in case it doesn't go through */
		int retryDurationInHours = 1;

		/* Set the linkId received from the message sent by a subscriber to your onDemand service */
		String linkId = "messageLinkId";
		
		/* And send the message (synchronously) */
		try {
			List<Recipient> response = sms.sendPremium(
				message,
				from,
				keyword,
				linkId,
				retryDurationInHours,
				recipients
			);
			for (Recipient recipient : response) {
				System.out.print(recipient.number);
				System.out.print(" : ");
				System.out.println(recipient.status);
			}
		} catch(Exception ex) {
			ex.printStackTrace();
		}
   	}
}