The SDK provides convenient access to the Africa's Talking APIs to python apps.
Take a look at the API docs here.
$ pip install africastalking # python 2.7.x
OR
$ python -m pip install africastalking # python 2.7.x
OR
$ pip3 install africastalking # python 3.6.x
OR
$ python3 -m pip install africastalking # python 3.6.x
The package needs to be configured with your app 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
# import package
import africastalking
# Initialize SDK
username = "YOUR_USERNAME" # use 'sandbox' for development in the test environment
api_key = "YOUR_API_KEY" # use your sandbox app API key for development in the test environment
africastalking.initialize(username, api_key)
# Initialize a service e.g. SMS
sms = africastalking.SMS
# Use the service synchronously
response = sms.send("Hello Message!", ["+2547xxxxxx"])
print(response)
# Or use it asynchronously
def on_finish(error, response):
if error is not None:
raise error
print(response)
sms.send("Hello Message!", ["+2547xxxxxx"], callback=on_finish)
See example for more usage examples.
Initialize the SDK by calling africastalking.initialize(username, api_key)
. After initialization, you can get instances of offered services as follows:
- SMS:
africastalking.SMS
- Airtime:
africastalking.Airtime
- Voice:
africastalking.Voice
- Token:
africastalking.Token
- Application:
africastalking.Application
- Mobile Data:
africastalking.MobileData
- Insights:
africastalking.Insights
fetch_application_data()
: Get app information. e.g balance.
-
send(recipients: [dict])
: Send airtime-
recipients
: Contains an array of arrays containing the following keysphone_number
: Recipient of airtimeamount
: Amount to send with currency e.g100
currency_code
: 3-digit ISO format currency code (e.gKES
,USD
,UGX
etc).
-
-
max_num_retry
: This allows you to specify the maximum number of retries in case of failed airtime deliveries due to various reasons such as telco unavailability. The default retry period is 8 hours and retries occur every 60 seconds. For example, settingmax_num_retry=4
means the transaction will be retried every 60 seconds for the next 4 hours.OPTIONAL
.
-
send(message: str, recipients: [str], sender_id: str = None, enqueue: bool = False)
: Send a message.message
: SMS content.REQUIRED
recipients
: An array of phone numbers.REQUIRED
sender_id
: Shortcode or alphanumeric ID that is registered with your 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.
-
send_premium(message: str, short_code: str, recipients: [str], link_id: [str] = None, retry_duration_in_hours [int] = None)
: Send a premium SMSmessage
: SMS content.REQUIRED
short_code
: Your premium product shortCode.REQUIRED
recipients
: An array of phone numbers.REQUIRED
keyword
: Your premium product keyword.link_id
: We forward thelinkId
to your application when a user sends a message to your onDemand serviceretry_duration_in_hours
: This specifies the number of hours your subscription message should be retried in case it's not delivered to the subscriber
-
fetch_messages(last_received_id: int = 0)
: Fetch your messageslast_received_id
: This is the id of the message you last processed. Defaults to0
-
create_subscription(short_code: str, keyword: str, phone_number: str)
: Create a premium subscriptionshort_code
: Premium short code mapped to your account.REQUIRED
keyword
: Premium keyword under the above short code and is also mapped to your account.REQUIRED
phone_number
: PhoneNumber to be subscribedREQUIRED
-
fetch_subscriptions(short_code: str, keyword: str, last_received_id: int = 0)
: Fetch your premium subscription datashort_code
: Premium short code mapped to your account.REQUIRED
keyword
: Premium keyword under the above short code and mapped to your account.REQUIRED
last_received_id
: ID of the subscription you believe to be your last. Defaults to0
-
delete_subscription(short_code: str, keyword: str, phone_number: str)
: Delete a phone number from a premium subscriptionshort_code
: Premium short code mapped to your account.REQUIRED
keyword
: Premium keyword under the above short code and is also mapped to your account.REQUIRED
phone_number
: PhoneNumber to be subscribedREQUIRED
-
send_hashed(message: str, masked_number: str, sender_id: str, telco: str = Safaricom)
: Send a message to a hashed number.message
: SMS content.REQUIRED
masked_number
: The hashed number being sent to.REQUIRED
sender_id
: Shortcode or alphanumeric ID that is registered with your Africa's Talking account.REQUIRED
telco
: The telco being used.
-
call(callFrom: str, callTo: [str])
: Initiate a phone callcallFrom
: Phone number on Africa's Talking (in international format).REQUIRED
callTo
: An array of phone numbers that you wish to dial (in international format).REQUIRED
-
fetch_queued_calls(phone_number: str)
: Get queued callsphone_number
: Phone number mapped to your Africa's Talking account (in international format).REQUIRED
-
upload_media_file(phone_number: str, url: str)
: Upload voice media filephone_number
: phone number mapped to your Africa's Talking account (in international format).REQUIRED
url
: The url of the file to upload. Should start withhttp(s)://
.REQUIRED
-
send(product_name: str, recipients: dict)
: Send mobile data to customers.product_name
: 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 beMB
orGB
.REQUIRED
validity
: How long the mobile data is valid for. Must be one ofDay
,Week
andMonth
.REQUIRED
metadata
: Additional data to associate with the transaction.OPTIONAL
-
find_transaction(transaction_id: str)
: Find a mobile data transaction. -
fetch_wallet_balance()
: Fetch a mobile data product balance.
generate_auth_token()
: Generate an auth token to use for authentication instead of an API key.
check_sim_swap_state(phone_numbers: [str])
: Check the sim swap state of a given [array of ] phone number(s).
For more information, please read https://developers.africastalking.com/docs/ussd
$ git clone https://github.com/AfricasTalkingLtd/africastalking-python.git
$ cd africastalking-python
$ touch .env
Make sure your .env
file has the following content then run python -m unittest discover -v
# AT API
AT_USERNAME=sandbox
AT_API_KEY=some_key
If you find a bug, please file an issue on our issue tracker on GitHub.