Send SMS

To send a message you will need to make a HTTP POST request to the following url:
POST URL: http://api.africastalking.com/version1/messaging
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 appliaction/json. No
username Body This is your username Yes
to Body The recipients Yes
message Body This is the message to b 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 AfricasTalking 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

Upon successful processing, the server shall respond in the following format:
XML
                        
<?xml version="1.0"?>
  <AfricastalkingResponse>
   <SMSMessageData>
     <Recipients>
       <Recipient>
         <number>+254711XXXYYY</number>
         <cost>KES YY</cost>
         <status>Success</status>
         <messageId>ATSid_1</messageId>
       </Recipient>
       .
       .
       .
       .
       <Recipient>
         <number>+254733YYYZZZ</number>
         <cost>KES XX</cost>
         <messageId>ATSid_2</messageId>
       </Recipient>
       
      </Recipients>
    </SMSMessageData>
  </AfricastalkingResponse>
 
JSON

{"SMSMessageData":
  {"Recipients":
    [
      {
       "number"    : "+254711XXXYYY",
       "cost"      : "KES YY",
       "status"    : "Success",
       "messageId" : "ATSid_1"
      },
      .
      .
      .
      .
      {
        "number"    : "+254733YYYZZZ",
        "cost"      : "KES XX",
        "status"    : "Success",
        "messageId" : "ATSid_n"
      }
    ]
  }
}
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 http://api.africastalking.com/version1/messaging --insecure

You need your AfricasTalking username and APIKey for any request to our API. If you don't have an APIKey, please click here to get one

Send messages using VB.NET

The VB.NET code snippet below shows how to airtime using our API.

The code uses VB gateway class: AfricasTalkingGateway.vb [ Download]

The code encodes and decodes data using Javascript serializer so you will need to add System.Web.Extensions to your referenced libraries

Sending a Message

Imports System
Imports System.Collections.Generic
Imports System.Data
Imports System.Data.SqlClient
Imports System.Linq
Imports System.Text
Imports System.Threading.Tasks

Namespace ClassLibraryAT
    Public Class Class1
        Public Shared Sub Main()

            Dim username As String = "myAfricasTalkingUsername"
            Dim apiKey As String = "myAPIKey"

            ' Specify the numbers that you want to send to in a comma-separated list
            ' Please ensure you include the country code (+254 for Kenya in this case)
            Dim recipients As String = ""

            ' And of course we want our recipients to know what we really do
            Dim message As String = "I'm a lumberjack and it's ok, I sleep all night and I work all day!"

            'Create a new instance of our awesome gateway class
            Dim gateway As New AfricasTalkingGateway(username, apiKey)


            ''NOTE If connecting Then To the sandbox, please add the sandbox flag To the constructor:
            ''*************************************************************************************
            ''                   ****SANDBOX****
            ''Dim gateway As New AfricasTalkingGateway(username, apiKey, "sandbox")
            ''*************************************************************************************
            ' Any gateway errors will be captured by our custom Exception class below,
            ' so wrap the call in a try-catch block   
            Try

                ' Thats it, hit send and we'll take care of the rest

                Dim results As Object = gateway.sendMessage(recipients, message)

                For Each result As Object In results
                    Console.Write(CStr(result("number")) & ",")
                    Console.Write(CStr(result("status")) & ",") ' status is either "Success" or "error message"
                    Console.Write(CStr(result("messageId")) & ",")
                    Console.WriteLine(CStr(result("cost")))
                Next result
            Catch e As AfricasTalkingGatewayException

                Console.WriteLine("Encountered an error: " & e.Message)

            End Try
        End Sub
    End Class
End Namespace

Sending messages: Use short code/Sender id

' Sending Messages using sender id/short code

Imports System.IO
Imports System.Collections
Imports System.Collections.Generic

Public Class Application
	Public Shared Sub Main()
			
			Dim username As String = "myAfricasTalkingUsername"
			Dim apikey As String   = "myAPIKey"
			
			Dim recipients As String = "+254711XXXYYY,+254733YYYZZZ"
			
			Dim message As String = "I'm a lumberjack and its ok, I sleep all night and I work all day"
			
			' Specify your AfricasTalking shortCode or sender id
			Dim sender As String = "shortCode or senderId";
			
			Dim gateway As New AfricasTalkingGateway(username, apikey)
			
			Try
			 ' Hit send and we will handle the rest
				Dim response as object() = gateway.sendMessage(recipients, message, sender)
				
				Dim result as object
				for each result in response
					System.Console.WriteLine("Status: " + result("status"))
					System.Console.WriteLine("MessageID: " + result("messageId"))
					System.Console.WriteLine("phoneNumber: " + result("number"))
					System.Console.WriteLine("Cost: " + result("cost"))
				next
		catch ex As AfricasTalkingGatewayException
			System.Console.WriteLine(ex.Message())
		End Try 
	End Sub
End Class

Sending messages: Queue messages to be sent later

' Message queueing

Imports System.IO
Imports System.Collections
Imports System.Collections.Generic

Public Class Application
	Public Shared Sub Main()
			
			Dim username As String = "myAfricasTalkingUsername"
			Dim apikey As String   = "myAPIKey"
			
			Dim recipients As String = "+254711XXXYYY,+254733YYYZZZ"
			
			Dim message As String = "I'm a lumberjack and its ok, I sleep all night and I work all day"
			
			Dim sender As String = Nothing 'Dim sender As String = "shortCode or senderId";
			
			Dim bulkSMSMode As Integer = 1 ' This should always be 1 for bulk messages
			
			' enqueue flag is used to queue messages incase you are sending a high volume.
			' The default value is 0.
			Dim options As New Hashtable()
			options("enqueue") = 1;
			
			Dim gateway As New AfricasTalkingGateway(username, apikey)
			
			Try
			
				 Dim response as object() = gateway.sendMessage(recipients, message, sender, bulkSMSMode, options)
				
				Dim result as object
				for each result in response
					System.Console.WriteLine("Status: " + result("status"))
					System.Console.WriteLine("MessageID: " + result("messageId"))
					System.Console.WriteLine("phoneNumber: " + result("number"))
					System.Console.WriteLine("Cost: " + result("cost"))
				next
		catch ex As AfricasTalkingGatewayException
			System.Console.WriteLine(ex.Message())
		End Try 
	End Sub
End Class

Sending premium rated (subscription) messages

' Sending premium rated messages

Imports System.IO
Imports System.Collections
Imports System.Collections.Generic

Public Class Application
	Public Shared Sub Main()
	 
	 	Dim username As String = "myAfricasTalkingUsername"
	 	Dim apikey As String   = "myAPIKey"
	 
	 	Dim recipient As String = "+254711XXXYYY"
	 
	 	' Specify your premium shortCode and keyword
	 	Dim shortCode As String = "XXXXX"
	 	Dim keyword As String   = "premiumKeyword"
	 
	 	' Set the bulkSMSMode to 0 so that the subscriber gets charged
	 	Dim bulkSMSMode As Integer = 0
	 	
	 	' Create a hashtable which would hold the following parameters:
	 	' keyword: Your premium keyword,
	 	' retryDurationInHours: The numbers of hours our API should retry to send the 
	 	' incase it doesn't go through. It is optional
	 	
	 	Dim options As New Hashtable();
	 	options("keyword")              = keyword
	 	options("retryDurationInHours") = "No of hrs to retry eg. 6"
	 	
	 	' And of course we want our recipients to get our daily quote
	 	Dim message As String = "Get your daily message and thats how we roll."
	 	
	 	Dim gateway As New AfricasTalkingGateway(username, apikey)
			
			
			Try
			
				Dim response as object()= gateway.sendMessage(recipient, message, shortCode, bulkSMSMode, options)
				
				Dim result as object
				for each result in response
					System.Console.WriteLine("Status: " + result("status"))
					System.Console.WriteLine("MessageID: " + result("messageId"))
					System.Console.WriteLine("phoneNumber: " + result("number"))
				next
				
		catch ex As AfricasTalkingGatewayException
			System.Console.WriteLine(ex.Message())
			
		End Try 
		
	End Sub
End Class

Sending premium rated (onDemand) messages

' Sending onDemand premium messages

Imports System.IO
Imports System.Collections
Imports System.Collections.Generic

Public Class Application
	Public Shared Sub Main()
	 
	 	Dim username As String = "myAfricasTalkingUsername"
	 	Dim apikey As String   = "myAPIKey"
	 
	 	Dim recipient As String = "+254711XXXYYY"
	 
	 	Dim shortCode As String = "XXXXX"
	 	Dim keyword As String   = "premiumKeyword" ' Dim keyword As String = Nothing
	 
	 	Dim bulkSMSMode As Integer = 0
	 	
	 	' Create a hashtable which would hold parameters keyword, retryDurationInHours and linkId
	 	' linkId is received from the message sent by subscriber to your onDemand service
	   Dim linkId As String = "messageLinkId"
	 	
	 	Dim options As New Hashtable();
	 	options("keyword")              = keyword
	 	options("linkId")               = linkId
	 	options("retryDurationInHours") = "No of hrs to retry eg. 6"
	 	
	 	Dim message As String = "Get your daily message and thats how we roll."
	 	
	 	Dim gateway As New AfricasTalkingGateway(username, apikey)
			
			
			Try
			
				Dim response as object()= gateway.sendMessage(recipient, message, shortCode, bulkSMSMode, options)
				
				Dim result as object
				for each result in response
					System.Console.WriteLine("Status: " + result("status"))
					System.Console.WriteLine("MessageID: " + result("messageId"))
					System.Console.WriteLine("phoneNumber: " + result("number"))
				next
				
		catch ex As AfricasTalkingGatewayException
			System.Console.WriteLine(ex.Message())
			
		End Try 
		
	End Sub
End Class