Official PHP SDK
This SDK provides convenient access to the Africa's Talking API for applications written in PHP.
Take a look at the API docs here.
You can install the PHP SDK via composer or by downloading the source
The recommended way to install the SDK is with Composer.
composer require africastalking/africastalking
The SDK needs to be instantiated using your username and API key, which you can get from the dashboard.
You can use this SDK for either production or sandbox apps. For sandbox, the app username is ALWAYS
sandbox
use AfricasTalking\SDK\AfricasTalking;
$username = 'YOUR_USERNAME'; // use 'sandbox' for development in the test environment
$apiKey = 'YOUR_API_KEY'; // use your sandbox app API key for development in the test environment
$AT = new AfricasTalking($username, $apiKey);
// Get one of the services
$sms = $AT->sms();
// Use the service
$result = $sms->send([
'to' => '+2XXYYYOOO',
'message' => 'Hello World!'
]);
print_r($result);
See example for more usage examples.
Instantiating the class will give you an object with available methods
$AT = new AfricasTalking($username, $apiKey)
: Instantiate the class$sms = $AT->sms()
$content = $AT->content()
$airtime = $AT->airtime()
$mobileData = $AT->mobileData()
$voice = $AT->voice()
$token = $AT->token()
$application = $AT->application()
fetchApplicationData()
: Get app information. e.g balancesend($parameters, $options)
: Send airtime
$parameters: associative array with the following keys:
recipients
: An array of arrays containing the following keys
phoneNumber
: Recipient of airtime. REQUIRED
currencyCode
: 3-digit ISO format currency code (e.g KES
, USD
, UGX
etc). REQUIRED
amount
: Amount to send. REQUIRED
$options: optional associative array with the following keys:
idempotencyKey
: Key to use when making idempotent requestsmaxNumRetry
: Maximum number of retries in case of failed airtime deliveries due to telco unavailability or any other reason.send($options)
: Send a message
message
: SMS content. REQUIRED
to
: An array of phone numbers. REQUIRED
from
: Shortcode or alphanumeric ID that is registered with your Africa's Talking account.enqueue
: Set to true
if you would like to deliver as many messages to the API without waiting for an acknowledgement from telcos.fetchMessages($options)
: Fetch your messages
lastReceivedId
: This is the id of the message you last processed. Defaults to 0
The followoing methods have been moved to the content service, but, have been maintained on SMS for backwards compatibility:
sendPremium($options)
: Send a premium SMS. Calls $content->send($options)
createSubscription($options)
: Create a premium subscription. Calls $content->createSubscription($options)
fetchSubscriptions($options)
: Fetch your premium subscription data. Calls $content->fetchSubscriptions($options)
deleteSubscription($options)
: Delete a phone number from a premium subscription. Calls $content->$deleteSubscription($options)
send($options)
: Send a premium SMS
message
: SMS content. REQUIRED
to
: An array of phone numbers. REQUIRED
from
: Shortcode that is registered with your Africa's Talking account. REQUIRED
keyword
: Your premium product keywordlinkId
: "[...] We forward the linkId
to your application when a user sends a message to your onDemand service"retryDurationInHours
: "This specifies the number of hours your subscription message should be retried in case it's not delivered to the subscriber"createSubscription($options)
: Create a premium subscription
shortCode
: Premium short code mapped to your account. REQUIRED
keyword
: Premium keyword under the above short code and is also mapped to your account. REQUIRED
phoneNumber
: PhoneNumber to be subscribed REQUIRED
fetchSubscriptions($options)
: Fetch your premium subscription data
shortCode
: Premium short code mapped to your account. REQUIRED
keyword
: Premium keyword under the above short code and mapped to your account. REQUIRED
lastReceivedId
: ID of the subscription you believe to be your last. Defaults to 0
deleteSubscription($options)
: Delete a phone number from a premium subscription
shortCode
: Premium short code mapped to your account. REQUIRED
keyword
: Premium keyword under the above short code and is also mapped to your account. REQUIRED
phoneNumber
: PhoneNumber to be subscribed REQUIRED
send($parameters, $options)
: Send mobile data to customers
$parameters: associative array with the following keys:
productName
: Payment product on Africa's Talking. REQUIRED
recipients
: A list of recipients. Each recipient has:
phoneNumber
: Customer phone number (in international format). REQUIRED
quantity
: Mobile data amount. REQUIRED
unit
: Mobile data unit. Can either be MB
or GB
. REQUIRED
validity
: How long the mobile data is valid for. Must be one of Day
, Week
and Month
. REQUIRED
metadata
: Additional data to associate with the tranasction. REQUIRED
$options: optional associative array with the following keys:
idempotencyKey
: Key to use when making idempotent requestsfindTransaction($parameters)
: Find a particular transaction
transactionId
: ID of trancation to find. REQUIRED
fetchWalletBalance()
: Fetch your payment wallet balance
call($options)
: Initiate a phone call
to
: Phone number that you wish to dial (in international format). REQUIRED
from
: Phone number on Africa's Talking (in international format). REQUIRED
clientRequestId
: Variable sent to your Events Callback URL that can be used to tag the call. OPTIONAL
fetchQueuedCalls($options)
: Fetch queued calls on a phone number
phoneNumber
: Phone number mapped to your Africa's Talking account (in international format). REQUIRED
name
: Fetch calls for a specific queue.uploadMediaFile($options)
: Upload a voice media file
phoneNumber
: phone number mapped to your Africa's Talking account (in international format). REQUIRED
url
: The url of the file to upload. Should start with http(s)://
. REQUIRED
Build voice xml when callback URL receives a POST from the voice API. Actions can be chained to create an XML string.
$voiceActions = $voice->messageBuilder();
$xmlresponse = $voiceActions
->getDigits($options)
->say($text)
->record()
->build();
say($text)
: Add a Say
action
text
: Text (in English) that will be read out to the user.
play($url)
: Add a Play
action
url
: Public url to an audio file. This file will be played back to user.getDigits($options)
: Add a GetDigits
action
numDigits
: Number of digits should be gotten from the usertimeout
: Timeout (in seconds) for getting digits from a user.finishOnKey
: key which will terminate the action of getting digits.callbackUrl
: URL to forward the results of the GetDigits action.dial($options)
: Add a Dial
action
phoneNumbers
: An array of phone numbers (in international format) to call. REQUIRED
record
: Boolean - Whether to record the conversation.sequenntial
: Boolean - If many numbers provided for phoneNumbers
, determines whether the phone numbers will be dialed one after the other or at the same time.callerId
: Africa's Talking number you want to dial out with.ringBackTone
: URL location of a media playback you would want the user to listen to when the call has been placed before its picked up.maxDuration
: maximum amount of time in seconds a call should take.conference()
: Add a Conference
action
record($options)
: Add a Record
action
finishOnKey
: Key which will terminate the action of recording.maxLength
: Maximum amount of time in seconds a recording should take.timeout
: Timeout (in seconds) for getting a recording from a user.trimSilence
: Boolean - Specifies whether you want to remove the initial and final parts of a recording where user was silent.playBeep
: Boolean - Specifies whether the API should play a beep when recording starts.callbackUrl
: URL to forward the results of the Recording action.enqueue($options)
: Add an Enqueue
action
holdMusic
: URL to the file to be played while the user is on hold.name
: Name of queue to put call on.deqeue($options)
: Add a Dequeue
acton
phoneNumber
: Phone number mapped to your Africa's Talking account which a user called to join the queue. REQUIRED
name
: Name of queue you want to dequeue from.reject()
: Add a Reject
action
redirect($url)
: Add a Redirect
action
url
: URL to transfer control of the call tobuild()
: Build the xml after chaining some of the above actions
generateAuthToken()
: Generate an auth token to use for authenticating API requests instead of your API key.The SDK uses PHPUnit as the test runner.
To run available tests, from the root of the project run:
# Configure needed fixtures, e.g sandbox api key, Africa's Talking products
cp tests/Fixtures.php.tpl tests/Fixtures.php
# Run tests
phpunit --testdox
If you find a bug, please file an issue on our issue tracker on GitHub.