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

Our APIs allows a sender to send messages by opening a URL link. That's how easy it is to send a message.

The response is in XML format. See the xml response here.

Sending a Message

# send to a single user
https://api.africastalking.com/restless/send?username=myusername&Apikey=XXXX&to=+254711XXXYYY&message=We love code

# send to many users: comma-separate numbers as shown
https://api.africastalking.com/restless/send?username=myusername&Apikey=XXXX&to=+254711XXXYYY,+254733YYYZZZ&message=We love code

Sending messages: Use short code/Sender id

# for sender id
https://api.africastalking.com/restless/send?username=myusername&Apikey=XXXX&from=MYSENDERID&to=+254711XXXYYY&message=We love code

# for short codes
https://api.africastalking.com/restless/send?username=myusername&Apikey=XXXX&from=MYShortCode&to=+254711XXXYYY&message=We love code

Sending messages: Queue messages to be sent later

# from parameter is optional
https://api.africastalking.com/restless/send?username=myusername&Apikey=XXXX&from=MYSENDERID&to=+254711XXXYYY&enqueue=1&message=We love code

Sending premium rated (subscription) messages

# set bulkSMSMode flag to 0
https://api.africastalking.com/restless/send?username=myusername&Apikey=XXXX&from=MyShortCode&keyword=MyPremiumKeyword&bulkSMSMode=0&to=+254722XXXYYY&message=My daily quote