The wrapper provides convenient access to the Africa's Talking API from 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
<?php
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);
You can now make API calls using the $AT
object we have just created. See example for more usage examples.
Send airtime to phone numbers
$airtime = $AT->airtime();
$airtime->send($options);
The options array $options
must contain the following keys:
recipients
: Contains an array of arrays containing the following keysphoneNumber
: Recipient of airtimeamount
: Amount sent>= 10 && <= 10K
with currency e.gKES 100
$SMS = $AT->sms();
$SMS->send($options);
The options array $options
has the following keys:
message
: SMS content.REQUIRED
to
: A single recipient or an array of recipients.REQUIRED
- array of recipients contains
from
: Shortcode or alphanumeric ID that is registered with Africa's Talking account.enqueue
: Set totrue
if you would like to deliver as many messages to the API without waiting for an acknowledgement from telcos.
$SMS->sendPremium($options);
The options array $options
has the following keys:
message
: SMS content.REQUIRED
to
: A single recipient or an array of recipients.REQUIRED
- array of recipients contains
from
: Shortcode or alphanumeric ID that is registered with Africa's Talking account.keyword
: Value is a premium keywordREQUIRED
linkId
: "This is used for premium services to send OnDemand messages. We forward the linkId to your application when the user sends a message to your service.REQUIRED
retryDurationInHours
: "It specifies the number of hours your subscription message should be retried in case it's not delivered to the subscriber"
$SMS->fetchMessage()
Create a premium subscription
$SMS->createSubscription($options);
The options array $options
has the following keys
shortCode
: This is a premium short code mapped to your account.REQUIRED
keyword
: Value is a premium keyword under the above short code and mapped to your account.REQUIRED
phoneNumber
: The phoneNumber to be subscribedREQUIRED
checkoutToken
: This is a token used to validate the subscription requestREQUIRED
$SMS->fetchSubscription($options);
The options array $options
has the following keys
shortCode
: This is a premium short code mapped to your account.REQUIRED
keyword
: Value is a 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 to0
$payments = $AT->payments();
Initiate a card checkout
$payments->cardCheckout($options);
The options array $options
has the following keys
-
productName
: Payment Product as setup on your account.REQUIRED
-
checkoutToken
: Token that has been generated by our APIs as as result of charging a user's Payment Card in a previous transaction. When using a token, thepaymentCard
data should NOT be populated. -
paymentCard
: Payment Card to be charged:number
: The payment card number.REQUIRED
cvvNumber
: The 3 or 4 digit Card Verification Value.REQUIRED
expiryMonth
: The expiration month on the card (e.g8
)REQUIRED
authToken
: The card's ATM PIN.REQUIRED
countryCode
: The 2-Digit countryCode where the card was issued (onlyNG
is supported).REQUIRED
-
currencyCode
: 3-digit ISO format currency code (onlyNGN
is supported).REQUIRED
-
amount
: Payment amount.REQUIRED
-
narration
: A short description of the transactionREQUIRED
-
metadata
: Some optional data to associate with transaction.
$payments->validateCardCheckout($options);
The options array $options
has the following keys
transactionId
: The transaction that your application wants to validate.REQUIRED
otp
: One Time Password that the card issuer sent to the client.REQUIRED
$payments->bankCheckout($options);
The options array $options
has the following keys
-
productName
: Payment Product as setup on your account.REQUIRED
-
bankAccount
: Bank account to be charged:accountName
: The name of the bank account.REQUIRED
accountNumber
: The account number.REQUIRED
bankCode
: A 6-Digit Integer Code for the bank that we allocate. Seepayments.BANK.*
for supported banks.REQUIRED
dateOfBirth
: Date of birth of the account owner (YYYY-MM-DD
). Required for Zenith Bank Nigeria.
-
currencyCode
: 3-digit ISO format currency code (onlyNGN
is supported).REQUIRED
-
amount
: Payment amount.REQUIRED
-
narration
: A short description of the transactionREQUIRED
-
metadata
: Some optional data to associate with transaction.
$payments->validateBankCheckout($options);
The options array $options
has the following keys:
transactionId
: The transaction that your application wants to validate.REQUIRED
otp
: One Time Password that the bank sent to the client.REQUIRED
Initiate a bank transfer
$payments->bankTransfer($options);
The options array $options
has the following keys:
productName
: Payment Product as setup on your account.REQUIRED
recipients
: A list of recipients. Each recipient has:bankAccount
: Bank account to be charged:accountName
: The name of the bank account.accountNumber
: The account numberREQUIRED
bankCode
: A 6-Digit Integer Code for the bank that we allocate; Seepayments.BANK.*
for supported banks.REQUIRED
currencyCode
: 3-digit ISO format currency code (onlyNGN
is supported).REQUIRED
amount
: Payment amount.REQUIRED
narration
: A short description of the transactionREQUIRED
metadata
: Some optional data to associate with transaction.
Request payment from customer on mobile money
$payments->mobileCheckout($options);
The options array $options
has the following keys:
productName
: Your Payment Product.REQUIRED
phoneNumber
: The customer phone number (in international format; e.g.25471xxxxxxx
).REQUIRED
currencyCode
: 3-digit ISO format currency code (e.gKES
,USD
,UGX
etc.)REQUIRED
amount
: This is the amount.REQUIRED
metadata
: Some optional data to associate with transaction.
Send mobile money to customers
$payments->mobileB2C($options);
The options array $options
has the following keys:
-
productName
: Your Payment Product.REQUIRED
-
recipients
: A list of up to 10 recipients. Each recipient has:-
phoneNumber
: The payee phone number (in international format; e.g.25471xxxxxxx
).REQUIRED
-
currencyCode
: 3-digit ISO format currency code (e.gKES
,USD
,UGX
etc.)REQUIRED
-
amount
: Payment amount.REQUIRED
-
reason
: This field contains a string showing the purpose for the payment. If set, it should be one of the followingpayments.REASON.SALARY payments.REASON.SALARY_WITH_CHARGE payments.REASON.BUSINESS payments.REASON.BUSINESS_WITH_CHARGE payments.REASON.PROMOTION
-
metadata
: Some optional data to associate with transaction.
-
Send mobile money payments TO businesses eg banks FROM your payment wallet
$payments->mobileB2B($options);
The options array $options
has the following keys:
-
productName
: Your Payment Product as setup on your account.REQUIRED
-
provider
: This contains the payment provider that is facilitating this transaction. Supported providers at the moment are:payments.PROVIDER.ATHENA payments.PROVIDER.MPESA
-
transferType
: This contains the payment provider that is facilitating this transaction. Supported providers at the moment are:payments.TRANSFER_TYPE.BUY_GOODS payments.TRANSFER_TYPE.PAYBILL payments.TRANSFER_TYPE.DISBURSE_FUNDS payments.TRANSFER_TYPE.B2B_TRANSFER
-
currencyCode
: 3-digit ISO format currency code (e.gKES
,USD
,UGX
etc.)REQUIRED
-
destinationChannel
: This value contains the name or number of the channel that will receive payment by the provider.REQUIRED
-
destinationAccount
: This value contains the account name used by the business to receive money on the provided destinationChannel.REQUIRED
-
amount
: Payment amount.REQUIRED
-
metadata
: Some optional data to associate with transaction.
$voice = $AT->voice();
$voice->call($options)
The options array $options
has the following keys:
to
: The phone number that you wish to dial (in international format)REQUIRED
from
: Your Africa's Talking phone number (in international format).REQUIRED
$voice->fetchQueuedCalls($phoneNumber);
The $phoneNumber
is phone number mapped to your AfricasTalking account
$voice->uploadMediaFile($options);
The options array $options
has the following keys:
phoneNumber
: phone number mapped to your AfricasTalking accounturl
: The url of the file to upload. Don't forget to start with http://
Build voice xml when callback URL receives a POST from the voice API
$voiceActions = $voice->messageBuilder();
Actions can be chained to create an XML string e.g.
You finally build the XML by running the build()
method
$voiceActions->getDigits($options)->say($text)->record()->build();
$voiceActions->say($text);
$text
: You can send us some text (in English) and we will read it out to the user.
$voiceActions->play($url);
$url
: This element lets you play back an audio file that is located anywhere on the web.
$voiceActions->getDigits($options);
The options array $options
has the following keys:
numDigits
: This number of digits you would like to get from the usertimeout
: Timeout (in seconds) for getting the digits, after which the system moves on to the next element. If there is no other element to execute, the system will hang upfinishOnKey
: The key which will terminate the action of getting digits. If it is not specified, the API will send back the first digit that the user presses.callbackUrl
: The parameter instructs us to forward the results of the GetDigits action to the URL value passed in. If absent, our API will forward the request to the default URL for this phone number (or to the redirected URL if a redirect has been issues). This redirection is permanent.
You can use this element to connect the user who called your phone number to an external phone number.
$voiceActions->dial($options);
The options array $options
has the following keys:
phoneNumbers
: An array of phone numbers (in international format) to call.REQUIRED
record
: Boolean value of whether to record the conversation.sequenntial
: Boolean If many numbers provided forphoneNumbers
, this determines whether the phone numbers will be dialed one after the other, or whether they will all ring at the same time.callerId
: This contains your AfricasTalking number you want to dial out with. It is mainly important when the caller used a sip number. If not specified in this case, the default number will be used.ringBackTone
: This contains a 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
: This contains the maximum amount of time in seconds a call should take.
This element lets you add all the users that dial into the phone number to a conference call. This is a terminal action. ie. No action will be executed after this.
$voiceActions->conference();
This action lets you record a call session into an mp3 file that you can then retrieve and play later.
For final recording, the recording starts when the record action is called until the mobile user hangs up.
$voiceActions->record();
Partial recording may be useful where a particular user response is required like while prompting for a name.
$voiceActions->record($options);
The options array $options
has the following keys:
finishOnKey
: The key which will terminate the action of getting digits. If it is not specified, the API will send back the first digit that the user presses.maxLength
: Specifies the maximum amount of time in seconds a recording should take.timeout
: Timeout (in seconds) for getting the digits, after which the system moves on to the next element. If there is no other element to execute, the system will hang uptrimSilence
: Boolean - Specifies whether you want to remove the initial and final parts of a recording where the user was silent.playBeep
: Boolean - Specifies whether the API should play a beep when recording starts.callbackUrl
: The parameter instructs us to forward the results of the GetDigits action to the URL value passed in. If absent, our API will forward the request to the default URL for this phone number (or to the redirected URL if a redirect has been issues). This redirection is permanent.
Our gateway allows you to add incoming calls to a queue (with music being played in the background). You can then call a separate number to dequeue the calls one at a time.
$voiceActions->enqueue($options);
The options array $options
has the following keys:
holdMusic
: A valid URL that contains a link to the file to be played while the user is on hold.name
: You can put a call in a particular queue. eg. support, general, technical. This would help you dequeue it or know to the correct person.
After enqueueing you can then call a separate number to dequeue the calls one at a time.
$voiceActions->dequeue($options);
The options array $options
has the following keys:
phoneNumber
: This the phone number which a user called to join the queue.REQUIRED
name
: This is the name of the queue you want to dequeue from.
This action lets you reject an incoming call without incurring any usage charges from our APIs. Note that this should be the only element in your response. This is a terminal action. ie. No action will be executed after this.
$voiceActions->reject();
This action will transfer control of the call to the script whose URL is passsed in. This can help you better organize your call handling logic by spreading the logic across multiple scripts
$voiceActions->redirect($url);
This finally builds the XML after chaining some of the actions above actions
$voiceActions->build();
$token = $AT->token();
Create a checkout token.
$token->createCheckoutToken($phoneNumber);
$phoneNumber
: Phone number to create an account for
Generate an auth token to us for authentication instead of the API key.
$token->generateAuthToken();
$account = $AT->account();
Use this method to fetch account information such as the account balance
$account->fetchAccount();
The SDK uses PHPUnit as the test runner.
To run available tests, from the root of the project run:
$ phpunit
If you find a bug, please file an issue on our issue tracker on GitHub.