Make a call

You can make an outbound call through our Voice API by sending a HTTP POST request to our RESTFul call resource.

That's right, it is now actually possible to curl someone... See what we did there :)


How To Make an Outgoing Call

Here is how it all comes together...

1. Your application invokes our REST resource for making calls. You can use the call() function in our helper gateway classes to do this (see below)

2. Our API calls the user(s) specified in the request

3. The user answers the call

4. Our API sends a POST request to the URL that you have set for that phone number in your Voice Dashboard. The parameters passed in with this request are outlined in the section on handling calls

5. Your application responds with XML that tells our API how to handle the call. This XML will typically contain a list of actions that our API will execute in sequence.

6. Our API translates those actions into events or messages relayed back to the caller

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.

The Node.js code snippet below shows how to make a call using our API.

//Import the required libraries
querystring = require('querystring');
https       = require('https');

var username = "myAfricasTalkingUsername";
var apiKey   = "myAfricasTalkingAPIkey";

//create the call function
function call(from_, to_) {
	//Build post string from object
	
 var post_data = querystring.stringify({
       'username'  : username,
       'from'     : from_,
       'to'        : to_
 });
 
 //create the request paramater object
 
 var request_parameters = {
           host    : 'voice.africastalking.com',
           port    : 443,
           path    : '/call',
           
           method  : 'POST',
           
           rejectUnauthorized : false,
           requestCert        : true,
           agent              : false,
           
           headers : {  
                 'Content-Type'     : 'application/x-www-form-urlencoded',
                 'Content-Length'   : post_data.length,
                 'apikey'           : apiKey,
                 'Accept'           : 'application/json'
               }
        }
                         
  request = https.request(request_parameters, function (response) {
     response.setEncoding('utf8');
     response.on('data', function (data_chunk) {
     	 try {
     	 	
         	var jsObject = JSON.parse(data_chunk);
		if(jsObject.errorMessage != "None")
			throw jsObject.errorMessage;
			 	 
		var entries = jsObject.entries;
		var logStr = "";
		
		//This will loop thru all the numbers you wanted called	 	 
		for(result in entries) {
			// Only status "Queued" means the call was successfully placed
			logStr  += '\nStatus : ' + entries.status;
			logStr  += ';phoneNumber : ' + entries.phoneNumber;
		}
		console.log(logStr);
            
		console.log('Call initiated. Time for song and dance');

		// Our API will now contact your callback URL once recipient answers the call!
        }
        catch (error) {
         console.log("Error: " + error);
        }
     });
  });
  
  request.write(post_data);
  request.end();
}

var from = "myAfricasTalkingPhoneNumber"; //eg +254711082XXXvar to   = "+254711XXXYYY,+254733YYYZZZ";

//call the function
call(from, to);

Our REST resource for making calls is located at: https://voice.africastalking.com/call. In order to make a call, you will need to pass in the following parameters within a POST request:
Variable Name Location Description
apikey Header Your API Key, which you can generate from your dashboard
username Body Your Africa's Talking account username
from Body Your Africa's Talking phone number (in international format)
to Body The phone number that you wish to dial (in international format)

You can check the HTTP Response Code to determine whether the request was successful. Any response code other than 201 (Created) indicates that the call was not initiated

Example using CURL client
curl -H "Accept: application/xml" -H "Apikey:fb752d3417021812f0961y6c9464832dd1adb1e555c73f1e7c32bcc006488674" -d "username=myUsername&to=+254711XXXYYY&from=+254711082XXX" https://voice.africastalking.com/call