Send SMS

To send a message you will need to make a HTTP POST request to the following url:
The server expects:
Parameter Location Description Required
API key Header API key generated from your account settings Yes
Accept Header This is the format you would like your data formatted. It may be application/xml or application/json. The default is application/xml. The gateway classes provided uses application/json. No
username Body This is your username Yes
to Body The recipients Yes
message Body This is the message to be sent Yes
from Body Shortcode or alphanumeric that is registered with your Africa's Talking account. If missing, the default value (20414) will be populated on the message No
bulkSMSMode Body This parameter will be 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(The 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 No
enqueue Body This parameter is used for Bulk SMS clients that would like deliver as many messages to the API before waiting for an Ack from the Telcos. If enabled, the API will store the messages in its databases and send them out asynchronously after responding to the request No
keyword Body This parameter is used for premium services. It is essential for subscription premium services. No (Essential for subscription premium services)
linkId Body This parameter is used for premium services to send OnDemand messages. We forward the linkId to your application when the user send a message to your service. No (Essential for onDemand services.)
retryDurationInHours Body This parameter is used for premium messages. It specifies the number of hours your subscription message should be retried in case it's not delivered to the subscriber. No

The body of the response will be a JSON or XML object named SMSMessageData with an array of objects named Recipient: This object has the following format

Parameter Description
number The number that received the message.
cost The cost of sending the message.
statusCode 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
messageId The messageId received when the message was sent
<?xml version="1.0"?>
        <Message>Sent to 1/1 Total Cost: KES YY</Message>
                <cost>KES YY</cost>

  "SMSMessageData": {
      "Message": "Sent to 1/1 Total Cost: KES YY",
      "Recipients": [
              "statusCode": 101,
              "number": "+254711XXXYYY",
              "cost": "KES YY",
              "status": "Success",
              "messageId": "ATXid_1"
Example using CURL client
curl -v -H "Accept: application/xml" -d "username=myusername&message=hello test&to=+254711XXXYYY,+254733YYYZZZ" -H "Apikey:fb752d3417021812f0961y6c9464832dd1adb1
e555c73f1e7c32bcc006488674" -X POST --insecure

You need your AfricasTalking username and APIKey for any request to our API. If you don't have an APIKey, you can generate one from your applications settings page.

Send messages via url call

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 love code

# send to many users: comma-separate numbers as shown,+254733YYYZZZ&message=We love code

Sending messages: Use short code/Sender id

# for sender id love code

# for short code love code

Sending messages: Queue messages to be sent later

# from parameter is optional love code

Sending premium rated (subscription) messages

# set bulkSMSMode flag to 0 daily quote