Africa's Talking PHP SDK

This SDK provides convenient access to the Africa's Talking API for applications written in PHP.

Documentation

Take a look at the API docs here.

Install

You can install the PHP SDK via composer or by downloading the source

Via Composer

The recommended way to install the SDK is with Composer.

composer require africastalking/africastalking

Usage

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.

Instantiation

Instantiating the class will give you an object with available methods

• $AT = new AfricasTalking($username, $apiKey): Instantiate the class
• Get available service
  • SMS Service: $sms = $AT->sms()
  • Content Service: $content = $AT->content()
  • Airtime Service: $airtime = $AT->airtime()
  • Payments Service: $payments = $AT->payments()
  • Voice Service: $voice = $AT->voice()
  • Token Service: $token = $AT->token()
  • Application Service: $application = $AT->application()

Application

• fetchApplicationData(): Get app information. e.g balance

Airtime

• send($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 requests
    • maxNumRetry: Maximum number of retries in case of failed airtime deliveries due to telco unavailability or any other reason.

SMS

• 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)

Content

• 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 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

  • 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

Payments

• mobileCheckout($parameters, $options): Charge a customers mobile money account

  • $parameters: associative array with the following keys:

    • productName: Payment product on Africa's Talking. REQUIRED
    • providerChannel: Provider channel to consider when charging.
    • phoneNumber: Customer phone number (in international format). REQUIRED
    • currencyCode: 3-digit ISO format currency code (e.g KES, USD, UGX etc). REQUIRED
    • amount: Amount to charge. REQUIRED
    • metadata: Additional data to associate with the transaction. REQUIRED

  • $options: optional associative array with the following keys:

    • idempotencyKey: Key to use when making idempotent requests

• mobileB2C($parameters, $options): Send mobile money to customers

  • $parameters: associative array with the following keys:

    • productName: Payment product on Africa's Talking. REQUIRED

    • recipients: A list of up to 10 recipients. Each recipient has:

      • phoneNumber: Customer phone number (in international format). REQUIRED
      • currencyCode: 3-digit ISO format currency code (e.g KES, USD, UGX etc). REQUIRED
      • amount: Amount to pay. REQUIRED
      • reason: The purpose of the payment. See payments::REASON* for supported reasons. 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 requests

• mobileB2B($parameters, $options): Send mobile money to businesses e.g banks

  • $parameters: associative array with the following keys:

    • productName: Payment product on Africa's Talking. REQUIRED
    • provider: Payment provider that is facilitating this transaction. See payments::PROVIDER* for supported providers. REQUIRED
    • transferType: Describes the type of payment being made. See payments::TRANSFER_TYPE* for supported transfer types. REQUIRED
    • destinationChannel: Name or number of the channel that will receive payment by the provider. REQUIRED
    • destinationAccount: Name used by the business to receive money on the provided destinationChannel. REQUIRED
    • currencyCode: 3-digit ISO format currency code (e.g KES, USD, UGX etc). REQUIRED
    • amount: Amount to pay. REQUIRED
    • requester: PhoneNumber through which KPLC will send tokens when using B2B to buy electricity tokens.
    • metadata: Additional data to associate with the transaction. REQUIRED

  • $options: optional associative array with the following keys:

    • idempotencyKey: Key to use when making idempotent requests

• mobileData($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 requests

• bankCheckoutCharge($parameters, $options): Charge a customers bank account

  • $parameters: associative array with the following keys:

    • productName: Payment product on Africa's Talking. REQUIRED

    • bankAccount: Bank account to be charged:

      • accountName: Name of the bank account. REQUIRED
      • accountNumber: Account number. REQUIRED
      • bankCode: A 6-Digit Integer Code for the bank that we allocate. See payments::BANK* for supported banks. REQUIRED
      • dateOfBirth: Date of birth of the account owner (in the format YYYY-MM-DD). Required for Zenith Bank Nigeria.

    • currencyCode: 3-digit ISO format currency code (only NGN is supported at present). REQUIRED

    • amount: Amount to charge. REQUIRED

    • narration: A short description of the transaction. REQUIRED

    • metadata: Additional data to associate with the transaction. REQUIRED

  • $options: optional associative array with the following keys:

    • idempotencyKey: Key to use when making idempotent requests

• bankCheckoutValidate($parameters): Validate a bank checkout charge

  • transactionId: Transaction id returned from a bank charge request. REQUIRED
  • otp: One Time Password provided by the customer you're charging. REQUIRED

• bankTransfer($parameters, $options): Send money to a bank account

  • $parameters: associative array with the following keys:

    • productName: Payment product on Africa's Talking. REQUIRED

    • recipients: A list of recipients. Each recipient has:

      • bankAccount: Bank account to receive money:

        • accountName: Name of the bank account. REQUIRED
        • accountNumber: Account number. REQUIRED
        • bankCode: A 6-Digit Integer Code for the bank that we allocate. See payments::BANK* for supported banks. REQUIRED
        • dateOfBirth: Date of birth of the account owner (in the format YYYY-MM-DD). Required for Zenith Bank Nigeria.

      • currencyCode: 3-digit ISO format currency code (only NGN is supported at present). REQUIRED

      • amount: Amount to pay. REQUIRED

      • narration: A short description of the transaction. REQUIRED

      • metadata: Additonal data to associate with the transaction. REQUIRED

  • $options: optional associative array with the following keys:

    • idempotencyKey: Key to use when making idempotent requests

• cardCheckoutCharge($parameters, $options): Charge a customers payment card

  • $parameters: associative array with the following keys:

    • productName: Payment product on Africa's Talking. REQUIRED

    • paymentCard: Payment card to be charged:

      • number: Payment card number. REQUIRED
      • cvvNumber: 3 or 4 digit card verification Value. REQUIRED
      • expiryMonth: Expiration month on the card (e.g 8). REQUIRED
      • authToken: Payment card's ATM PIN. REQUIRED
      • countryCode: 2-Digit countryCode where the card was issued (only NG is supported at present). REQUIRED

    • checkoutToken: A token that has been generated by our APIs as as result of charging a customers payment card in a previous transaction. When using a checkoutToken, the paymentCard data should NOT be populated.

    • currencyCode: 3-digit ISO format currency code (only NGN is supported at present). REQUIRED

    • amount: Amount to charge. REQUIRED

    • narration: A short description of the transaction. REQUIRED

    • metadata: Additonal data to associate with the transaction. REQUIRED

  • $options: optional associative array with the following keys:

    • idempotencyKey: Key to use when making idempotent requests

• cardCheckoutValidate($parameters): Validate a card checkout charge

  • transactionId: Transaction id returned from a card charge request. REQUIRED
  • otp: One Time Password provided by the customer you're charging. REQUIRED

• walletTransfer($parameters): Move money from one payment product to another

  • productName: Payment product on Africa's Talking. REQUIRED
  • targetProductCode: Unique code ode of payment product receiving funds on Africa's Talking. REQUIRED
  • currencyCode: 3-digit ISO format currency code. REQUIRED
  • amount: Amount to transfer. REQUIRED
  • metadata: Additional data to associate with the transation. REQUIRED

• topupStash($parameters): Move money from a payment product to an applications stash

  • productName: Payment product on Africa's Talking. REQUIRED
  • currencyCode: 3-digit ISO format currency code. REQUIRED
  • amount: Amount to transfer. REQUIRED
  • metadata: Additonal data to associate with the transaction. REQUIRED

• fetchProductTransactions($parameters): Fetch payment product transactions

  • productName: Payment product on Africa's Talking. REQUIRED

  • filters: Filters to use when fetching transactions:

    • pageNumber: Page number to fetch results from. Starts from 1. REQUIRED
    • count: Number of results to fetch. REQUIRED
    • startDate: Start Date to consider when fetching.
    • endDate: End Date to consider when fetching.
    • category: Category to consider when fetching.
    • provider: Provider to consider when fetching.
    • status: Status to consider when fetching.
    • source: Source to consider when fetching.
    • destination: Destination to consider when fetching.
    • providerChannel: Provider channel to consider when fetching.

• fetchWalletTransactions($parameters): Fetch payment wallet transactions

  • filters: Filters to use when fetching transactions:

    • pageNumber: Page number to fetch results from. Starts from 1. REQUIRED
    • count: Number of results to fetch. REQUIRED
    • startDate: Start Date to consider when fetching.
    • endDate: End Date to consider when fetching.
    • categories: Comma delimited list of categories to consider when fetching.

• findTransaction($parameters): Find a particular transaction

  • transactionId: ID of trancation to find. REQUIRED

• fetchWalletBalance(): Fetch your payment wallet balance

Voice

• 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

MessageBuilder

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 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

  • 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 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.

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

Issues

If you find a bug, please file an issue on our issue tracker on GitHub.