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

The code uses our Python SDK.

Sending a Message

# works with both python 2 and 3
from __future__ import print_function

import africastalking

class SMS:
    def __init__(self):
		# Set your app credentials
	    self.username = "YOUR_USERNAME"
        self.api_key = "YOUR_API_KEY"
		# Initialize the SDK
        africastalking.initialize(self.username, self.api_key)
		# Get the SMS service
        self.sms = africastalking.SMS

    def send_sms_sync(self):
        # Set the numbers you want to send to in international format
        recipients = ["+254713YYYZZZ", "+254733YYYZZZ"]
        # Set your message
        message = "I'm a lumberjack and it's ok, I sleep all night and I work all day";
        # And send the SMS
        try:
			# That’s it, hit send and we’ll take care of the rest
            response = self.sms.send(message, recipients)
            print (response)
        except Exception as e:
            print ('Encountered an error while sending: %s' % str(e))


if __name__ == '__main__':
    SMS().send_sms_sync()

Sending messages: Use short code/Sender id

# works with both python 2 and 3
from __future__ import print_function

import africastalking

class SMS:
    def __init__(self):
		# Set your app credentials
	    self.username = "YOUR_USERNAME"
        self.api_key = "YOUR_API_KEY"
		# Initialize the SDK
        africastalking.initialize(self.username, self.api_key)
		# Get the SMS service
        self.sms = africastalking.SMS

    def send_sms_sender_id(self):
            # Set the numbers you want to send to in international format
            recipients = ["+254713YYYZZZ", "+254733YYYZZZ"]
            # Set your message
            message = "I'm a lumberjack and it's ok, I sleep all night and I work all day";
            # Set your shortCode or senderId
            sender = "shortCode or senderId"
            try:
				# Thats it, hit send and we'll take care of the rest.
                response = self.sms.send(message, recipients, sender)
                print (response)
            except Exception as e:
                print ('Encountered an error while sending: %s' % str(e))

if __name__ == '__main__':
    SMS().send_sms_sender_id()

Sending messages: Queue messages to be sent later

# works with both python 2 and 3
from __future__ import print_function

import africastalking

class SMS:
    def __init__(self):
		# Set your app credentials
	    self.username = "YOUR_USERNAME"
        self.api_key = "YOUR_API_KEY"
		# Initialize the SDK
        africastalking.initialize(self.username, self.api_key)
		# Get the SMS service
        self.sms = africastalking.SMS

    def enqueue_send_sms(self):
            # Set the numbers you want to send to in international format
            recipients = ["+254713YYYZZZ", "+254733YYYZZZ"]
            # Set your message
            message = "I'm a lumberjack and it's ok, I sleep all night and I work all day";
            # Specify your AfricasTalking shortCode or sender id
            sender = None
            # Set the enqueue flag to true, useful when you are sending high volumes
            enqueue = True
            try:
				# Thats it, hit send and we'll take care of the rest.
                response = self.sms.send(message, recipients, sender, enqueue)
                print (response)
            except Exception as e:
                print ('Encountered an error while sending: %s' % str(e))

if __name__ == '__main__':
    SMS().enqueue_send_sms()

Sending premium rated (subscription) messages

# works with both python 2 and 3
from __future__ import print_function

import africastalking

class SMS:
    def __init__(self):
		# Set your app credentials
	    self.username = "YOUR_USERNAME"
        self.api_key = "YOUR_API_KEY"
		# Initialize the SDK
        africastalking.initialize(self.username, self.api_key)
		# Get the SMS service
        self.sms = africastalking.SMS

    def premium_rated_subscription_sms(self):
			# Set the numbers you want to send to in international format
			recipients = ["+254711XXXYYY", "+254702XXXYYY"]
			# Set your message
			message = "Get your daily message and thats how we roll."
			# Set your premium product shortCode and keyword
			sender_id = ""
			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
			retry_duration_in_hours = 1
            try:
				# Thats it, hit send and we'll take care of the rest.
                response = self.sms.send_premium(message, keyword, recipients, sender_id, retry_duration_in_hours)
                print (response)
            except Exception as e:
                print ('Encountered an error while sending: %s' % str(e))

if __name__ == '__main__':
    SMS().premium_rated_subscription_sms()

Sending premium rated (onDemand) messages

# works with both python 2 and 3
from __future__ import print_function

import africastalking

class SMS:
    def __init__(self):
		# Set your app credentials
	    self.username = "YOUR_USERNAME"
        self.api_key = "YOUR_API_KEY"
		# Initialize the SDK
        africastalking.initialize(self.username, self.api_key)
		# Get the SMS service
        self.sms = africastalking.SMS

    def premium_rated_ondemand_sms(self):
			# Specify the numbers you want to send to in international format
			recipients = ["+254711XXXYYY", "+254702XXXYYY"]
			# Set your message
			message = "We are lumberjacks. We sleep all day and code all night"
			# Set your premium product shortCode and keyword
			sender_id = ""
			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
			retry_duration_in_hours = 1
			# Set the linkId received from the message sent by a subscriber to your onDemand service
			link_id = "sampleLinkId"
            try:
				# Thats it, hit send and we'll take care of the rest.
                response = self.sms.send_premium(message, keyword, link_id, recipients, sender_id, retry_duration_in_hours)
                print (response)
            except Exception as e:
                print ('Encountered an error while sending: %s' % str(e))

if __name__ == '__main__':
    SMS().premium_rated_ondemand_sms()