Africa's Talking PHP SDK
, (*1)
This SDK provides convenient access to the Africa's Talking API for applications written in PHP., (*2)
Documentation
Take a look at the API docs here., (*3)
Install
You can install the PHP SDK via composer or by downloading the source, (*4)
Via Composer
The recommended way to install the SDK is with Composer., (*5)
composer require africastalking/africastalking
Usage
The SDK needs to be instantiated using your username and API key, which you can get from the dashboard., (*6)
You can use this SDK for either production or sandbox apps. For sandbox, the app username is ALWAYS sandbox, (*7)
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., (*8)
Instantiation
Instantiating the class will give you an object with available methods, (*9)
-
$AT = new AfricasTalking($username, $apiKey): Instantiate the class
- Get available service
Application
-
fetchApplicationData(): Get app information. e.g balance
Airtime
SMS
-
send($options): Send a message, (*15)
-
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, (*16)
-
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:, (*17)
-
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)
Content
-
send($options): Send a premium SMS, (*18)
-
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 keyword
-
linkId: "[...] 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, (*19)
-
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, (*20)
-
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, (*21)
-
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
Mobile Data
-
send($parameters, $options): Send mobile data to customers, (*22)
-
$parameters: associative array with the following keys:, (*23)
-
productName: Payment product on Africa's Talking. REQUIRED, (*24)
-
recipients: A list of recipients. Each recipient has:, (*25)
-
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:, (*26)
-
idempotencyKey: Key to use when making idempotent requests, (*27)
-
findTransaction($parameters): Find a particular transaction, (*28)
-
transactionId: ID of trancation to find. REQUIRED
-
fetchWalletBalance(): Fetch your payment wallet balance, (*29)
Voice
-
call($options): Initiate a phone call, (*30)
-
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, (*31)
-
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, (*32)
-
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
MessageBuilder
Build voice xml when callback URL receives a POST from the voice API. Actions can be chained to create an XML string., (*33)
$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, (*34)
-
url: Public url to an audio file. This file will be played back to user.
-
getDigits($options): Add a GetDigits action, (*35)
-
numDigits: Number of digits should be gotten from the user
-
timeout: 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, (*36)
-
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, (*37)
-
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, (*38)
-
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, (*39)
-
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, (*40)
-
url: URL to transfer control of the call to
-
build(): Build the xml after chaining some of the above actions
Token
-
generateAuthToken(): Generate an auth token to use for authenticating API requests instead of your API key.
Testing the SDK
The SDK uses PHPUnit as the test runner., (*41)
To run available tests, from the root of the project run:, (*42)
# Configure needed fixtures, e.g sandbox api key, Africa's Talking products
cp tests/Fixtures.php.tpl tests/Fixtures.php
# Run tests
phpunit --testdox
Issues
If you find a bug, please file an issue on our issue tracker on GitHub., (*43)
Wallogit.com
