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

The code uses our Node SDK.

Sending a Message

// Set your app credentials
const credentials = {
    apiKey: 'MyAppAPIkey',
    username: 'MyAppUsername'
}

// Initialize the SDK
const AfricasTalking = require('africastalking')(credentials);

// Get the SMS service
const sms = AfricasTalking.SMS;

function sendMessage(){
    const options = {
        // Set the numbers you want to send to in international format
        to: ['+254711XXXYYY', '+254733YYYZZZ'],
        // Set your message
        message: "I'm a lumberjack and its ok, I sleep all night and I work all day"
    }

    // That’s it, hit send and we’ll take care of the rest
    sms.send(options).then( response => {
        console.log(response);
    }).catch( error => {
        console.log(error);
    });

}

sendMessage();

Sending messages: Use short code/Sender id

// Set your app credentials
const credentials = {
    apiKey: 'MyAppAPIkey',
    username: 'MyAppUsername',
}

// Initialize the SDK
const AfricasTalking = require('africastalking')(credentials);

// Get the SMS service
const sms = AfricasTalking.SMS;

function sendMessage() {
    const options = {
        // Set the numbers you want to send to in international format
        to: ['+254711XXXYYY', '+254733YYYZZZ'],
        // Set your message
        message: "I'm a lumberjack and its ok, I sleep all night and I work all day",
        // Set your shortCode or senderId
        from: 'XXYYZZ'
    }

    // That’s it, hit send and we’ll take care of the rest
    sms.send(options).then(response => {
        console.log(response);
    }).catch(error => {
        console.log(error);
    });

}

sendMessage();

Sending messages: Queue messages to be sent later

// Set your app credentials
const credentials = {
    apiKey: 'MyAppAPIkey',
    username: 'MyAppUsername'
}

// Initialize the SDK
const AfricasTalking = require('africastalking')(credentials);

// Get the SMS service
const sms = AfricasTalking.SMS;

function sendMessage() {
    const options = {
        from: 'XXYYZZ',
        // Set the numbers you want to send to in international format
        to: ['+254711XXXYYY', '+254733YYYZZZ'],
        // Set your message
        message: "I'm a lumberjack and its ok, I sleep all night and I work all day",
        // Set the enqueue flag to true, useful when you are sending high volumes
        enque: true
    }

    // That’s it, hit send and we’ll take care of the rest
    sms.send(options).then(response => {
        console.log(response);
    }).catch(error => {
        console.log(error);
    });

}

sendMessage();

Sending premium rated (subscription) messages

// Set your app credentials
const credentials = {
    apiKey: 'MyAppAPIkey',
    username: 'MyAppUsername'
}

// Initialize the SDK
const AfricasTalking = require('africastalking')(credentials);

// Get the SMS service
const sms = AfricasTalking.SMS;

function sendMessage() {

    const options = {
        // Set the numbers you want to send to in international format
        to: ['+254711XXXYYY', '+254733YYYZZZ'],
        // Set your message
        message: "Get your daily message and thats how we roll.",
        // Set your premium product shortCode and keyword
        shortCode: 'XXYYZZ',
        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: 'No of hours to retry'
    }

    // That’s it, hit send and we’ll take care of the rest
    sms.sendPremium(options).then( response => {
        console.log(response.SMSMessageData.Message);

        response.SMSMessageData.Recipients.forEach(recipient => {
            let result = `
            Number: ${recipient.number}
                Status: ${recipient.status}
                StatusCode: ${recipient.statusCode}
                MessageId: ${recipient.messageId}`;

            console.log(result);
        });
    }).catch( error => {
        console.log(error);
    });
}

sendMessage();

Sending premium rated (onDemand) messages

// Set your app credentials
const credentials = {
    apiKey: 'MyAppAPIkey',
    username: 'MyAppUsername'
}

// Initialize the SDK
const AfricasTalking = require('africastalking')(credentials);

// Get the SMS service
const sms = AfricasTalking.SMS;

function sendMessage() {

    const options = {
        // Specify the numbers you want to send to in international format
        to: ['+254711XXXYYY', '+254733YYYZZZ'],
        // Set your message
        message: "Get your daily message and thats how we roll.",
        // Set your premium product shortCode and keyword
        shortCode: 'XXYYZZ',
        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: 'No of hours to retry',
        // Set the linkId received from the message sent by a subscriber to your onDemand service
        linkId: 'messageLinkId'
    }

    // That’s it, hit send and we’ll take care of the rest
    sms.sendPremium(options).then( response => {
        console.log(response.SMSMessageData.Message);

        response.SMSMessageData.Recipients.forEach(recipient => {
            let result = `
            Number: ${recipient.number}
                Status: ${recipient.status}
                StatusCode: ${recipient.statusCode}
                MessageId: ${recipient.messageId}`;

            console.log(result);
        });
    }).catch( error => {
        console.log(error);
    });
}

sendMessage();