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 Java code snippet below shows how to make a call using our API.

The code uses our Java gateway class: AfricasTalkingGateway.java [ Download]

To help decode JSON responses, you will need to add one of the available JAVA libraries as a dependency. For this tutorial we chose to use json-20090211.jar which you can download from this repository.

Note On SSL Certificate Validation Issues

Some of our users have experienced SSL Certificate validation issues when connecting to our website due to our use of https. The error you see may look something like this:

Unable to find valid certification path to requested target

Please do not panic! Our certificate is perfectly valid (as evidenced by these verification tests), and the error you are seeing is quite common amongst Java clients connecting to secure websites. Here is how to fix the issue:

  • Download and compile InstallCert.java (you can find the code here).
  • On the CMD prompt(Windows) or Terminal(*nix), run: java InstallCert api.africastalking.com
    This will download a copy of our Certificate and create a file named jssecacerts in the current directory.
  • You can now add our Certificate to your trusted store by copying the created jssecacerts file to the Java security directory under $JAVA_HOME/jre/lib/security
// Make sure the downloaded jar file is in the classpath
import org.json.*;

public class TestCalling
{
    public static void main(String[] args_)
    {
		// Specify your login credentials
		String username = "MyAfricasTalking_Username";
		String apiKey   = "MyAfricasTalking_APIKey";

		// Specify your Africa's Talking phone number in international format
		String from = "+254711082XXX";

		// Specify the numbers that you want to call to in a comma-separated list
		// Please ensure you include the country code (+254 for Kenya in this case)
		String to   = "+254711XXXYYY,+254733YYYZZZ";

		// Create a new instance of our awesome gateway class
		AfricasTalkingGateway gateway  = new AfricasTalkingGateway(username, apiKey);

		/*************************************************************************************
			NOTE: If connecting to the sandbox:

			1. Use "sandbox" as the username
			2. Use the apiKey generated from your sandbox application
				https://account.africastalking.com/apps/sandbox/settings/key
			3. Add the "sandbox" flag to the constructor

			AfricasTalkingGateway gateway = 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 {
			JSONArray results = gateway.call(from, to);
			int len = results.length();
			for(int i = 0; i < len; i++) {
				JSONObject result = results.getJSONObject(i);
				//Only status "Queued" means the call was successfully placed
				System.out.print(result.getString("status") + ",");
				System.out.print(result.getString("phoneNumber") + "\n");
			}
			// Our API will now contact your callback URL once the recipient answers the call!
		} catch (Exception e) {
			System.out.println("Encountered an error" + e.getMessage());
		}
	}
}
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