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

The code uses our Ruby SDK.

Sending a Message

require 'AfricasTalking'

# Set your app credentials
username = "MyAppUsername"
apikey   = "MyAppAPIKey"

# Initialize the SDK
AT=AfricasTalking::Initialize.new username, apikey

# Get the SMS service
sms = AT.sms

# Set the numbers you want to send to in international format
to = "+254711XXXYYY, +254733YYYZZZ"

# Set your message
message = "I'm a lumberjack and it's ok, I sleep all night and I work all day"
options = {
  "to" => to,
  "message" => message
}
begin
  # That’s it, hit send and we’ll take care of the rest
  reports = sms.send options
  reports.each {|report|
    puts  report.to_yaml
  }
rescue AfricasTalking::AfricasTalkingException => ex
  puts 'Encountered an error: ' + ex.message
end

# DONE!

Sending messages: Use short code/Sender id

require 'AfricasTalking'

# Set your app credentials
username = "MyAppUsername"
apikey   = "MyAppAPIKey"

# Initialize the SDK
AT=AfricasTalking::Initialize.new username, apikey

# Get the SMS service
sms = AT.sms

# Set the numbers you want to send to in international format
to = "+254711XXXYYY,+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
from = "shortCode or senderId"

options = {
  'to' => to,
  "message" => message,
  "from" => from
}
begin
    # Thats it, hit send and we'll take care of the rest.
    reports = sms.send options
    reports.each {|report|
      puts report.to_yaml
    }
  rescue AfricasTalking::AfricasTalkingException => ex
    puts 'Encountered an error: ' + ex.message
  end
  
  # DONE!

Sending messages: Queue messages to be sent later

require 'AfricasTalking'

# Set your app credentials
username = "MyAppUsername"
apikey   = "MyAppAPIKey"

# Initialize the SDK
AT=AfricasTalking::Initialize.new username, apikey

# Get the SMS service
sms = AT.sms

# Set the numbers you want to send to in international format
to = "+254711XXXYYY,+254733YYYZZZ"

# Set your message
message = "I'm a lumberjack and it's ok, I sleep all night and I work all day"

# Set the enqueue flag to true, useful when you are sending high volumes
enqueue = true

options = {
  'to' => "+254711XXXYYY,+254733YYYZZZ",
  "message" => "I'm a lumberjack and it's ok, I sleep all night and I work all day",
  "enqueue" => enqueue
}
begin
    # Thats it, hit send and we'll take care of the rest.
    reports = sms.send options
    reports.each {|report|
      puts report.to_yaml
    }
  rescue AfricasTalking::AfricasTalkingException => ex
    puts 'Encountered an error: ' + ex.message
  end
  
  # DONE!

Sending premium rated (subscription) messages

require 'AfricasTalking'

# Set your app credentials
username = "MyAppUsername"
apikey   = "MyAppAPIKey"

# Initialize the SDK
AT=AfricasTalking::Initialize.new username, apikey

# Get the SMS service
sms = AT.sms

# Specify the numbers you want to send to in international format
to = "+254711XXXYYY"

# Set your message
message = "Get your daily message and thats how we roll."

# Set your premium product shortCode and keyword
shortCode = "myPremiumShortCode"
keyword = "premiumKeyword"

# Set the number of hours we should retry to send the message before giving a failure status in case it doesn't go through
retryDurationInHours = "2"

options = {
  'to' => to,
  "message" => message,
  "from" => shortCode,
  "keyword" => keyword,
  "retryDurationInHours" => retryDurationInHours
}
begin
    # Thats it, hit send and we'll take care of the rest.
    reports = sms.sendPremium options
    reports.each {|report|
      puts report.to_yaml
    }
  rescue AfricasTalking::AfricasTalkingException => ex
    puts 'Encountered an error: ' + ex.message
  end
  
  # DONE!

Sending premium rated (onDemand) messages

require 'AfricasTalking'

# Set your app credentials
username = "MyAppUsername"
apikey   = "MyAppAPIKey"

# Initialize the SDK
AT=AfricasTalking::Initialize.new username, apikey

# Get the SMS service
sms = AT.sms

# Specify the numbers you want to send to in international format
to = "+254711XXXYYY"

# Set your message
message = "Get your daily message and thats how we roll."

# Set your premium product shortCode and keyword
shortCode = "myPremiumShortCode"
keyword = "premiumKeyword"

# Set the number of hours we should retry to send the message before giving a failure status in case it doesn't go through
retryDurationInHours = "2"

# Set the linkId received from the message sent by a subscriber to your onDemand service
linkId = "messageLinkId"

options = {
  'to' => to,
  "message" => message,
  "from" => shortCode,
  "keyword" => keyword,
  "retryDurationInHours" => retryDurationInHours,
  "linkId" => linkId
}
begin
    # Thats it, hit send and we'll take care of the rest.
    reports = sms.sendPremium options
    reports.each {|report|
      puts report.to_yaml
    }
  rescue AfricasTalking::AfricasTalkingException => ex
    puts 'Encountered an error: ' + ex.message
  end
  
  # DONE!