Africa's Talking Python SDK

After calling africastalking.initialize(), you can access the following service instances:

• africastalking.SMS
• africastalking.Airtime
• africastalking.Voice
• africastalking.Token
• africastalking.Application
• africastalking.MobileData
• africastalking.Insights
• africastalking.Whatsapp
• africastalking.Ussd (Refer to official docs for USSD implementation)

Before using any services, you must initialize the SDK with your credentials.

For production apps, use your actual username and API key from the Africa's Talking dashboard. For sandbox (development) apps, the username must ALWAYS be sandbox.

import africastalking

# For sandbox/development
username = "sandbox"
api_key = "YOUR_SANDBOX_API_KEY"

# For production
# username = "YOUR_USERNAME"
# api_key = "YOUR_API_KEY"

africastalking.initialize(username, api_key)

Once initialized, you can access services via africastalking.<ServiceName>.

• Synchronous usage: Call the method directly and wait for the response.
• Asynchronous usage: Provide a callback function. The callback accepts two arguments: error and response.

import africastalking

africastalking.initialize("sandbox", "YOUR_API_KEY")
sms = africastalking.SMS

# Synchronous
response = sms.send("Hello Message!", ["+2547xxxxxx"])
print(response)

# Asynchronous
def on_finish(error, response):
    if error is not None:
        raise error
    print(response)

sms.send("Hello Message!", ["+2547xxxxxx"], callback=on_finish, timeout=(3, 6))

Install the SDK using pip3 to access Africa's Talking APIs in your Python applications. This requires Python 3.8.x or higher.

$ pip3 install africastalking

# OR

$ python3 -m pip install africastalking

The Token service allows for alternative authentication.

Method: generate_auth_token()

• Generates an auth token to be used for authentication instead of a standard API key.

The Insights service provides SIM state information.

Method: check_sim_swap_state(phone_numbers: [str])

• Checks the SIM swap state for an array of provided phone numbers.

The Airtime service allows you to send airtime to recipients.

Method: send(recipients: [dict])

recipients is an array of objects, where each object contains:

• phone_number: Recipient's phone number.
• amount: Amount to send (e.g., 100).
• currency_code: 3-digit ISO format currency code (e.g., KES, USD, UGX).

Optional Parameter:

• max_num_retry: Specifies the maximum number of retries for failed deliveries. The default retry period is 8 hours with retries every 60 seconds. Setting max_num_retry=4 means the transaction will be retried every 60 seconds for the next 4 hours.

# Example structure for recipients
recipients = [
    {
        "phone_number": "+2547xxxxxx",
        "amount": "100",
        "currency_code": "KES"
    }
]
airtime = africastalking.Airtime
airtime.send(recipients, max_num_retry=4)

The Voice service allows for initiating calls and managing media.

Method: call(callFrom: str, callTo: [str])

• callFrom: Your Africa's Talking phone number (international format). (Required)
• callTo: Array of destination phone numbers (international format). (Required)

Method: fetch_queued_calls(phone_number: str)

• phone_number: Your Africa's Talking phone number (international format). (Required)

Method: upload_media_file(phone_number: str, url: str)

• phone_number: Your Africa's Talking phone number (international format). (Required)
• url: The http(s):// URL of the file to upload. (Required)

The Application service provides access to application-level data.

Method: fetch_application_data()

• Retrieves application information, such as account balance.

The MobileData service manages mobile data transactions.

Method: send(product_name: str, recipients: dict)

• product_name: Africa's Talking payment product name. (Required)
• recipients: A list of recipient objects, each containing:
  • phoneNumber: Customer phone number (international format). (Required)
  • quantity: Data amount. (Required)
  • unit: MB or GB. (Required)
  • validity: Day, Week, or Month. (Required)
  • metadata: Additional transaction data. (Optional)

Method: find_transaction(transaction_id: str)

• Finds a specific mobile data transaction.

Method: fetch_wallet_balance()

• Fetches the balance for a mobile data product.