africastalking 2.0.3

Official Africa's Talking Python SDK

africastalking-python

The SDK provides convenient access to the Africa's Talking APIs to python apps.

Documentation

Take a look at the API docs here.

Install

$ pip3 install africastalking # python 3.8.x

OR

$ python3 -m pip install africastalking # python 3.8.x

Usage

The package needs to be configured with your app username and API key, which you can get from the dashboard. Note that all functions accept an optional timeout argument, but have a set default.

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, timeout=(3, 6))    

See example for more usage examples.

Initialization

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
• Whatsapp: africastalking.Whatsapp

Application

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

Airtime

• send(recipients: [dict]): Send airtime

  • recipients: Contains an array of arrays containing the following keys

    • phone_number: Recipient of airtime
    • amount: Amount to send with currency e.g 100
    • currency_code: 3-digit ISO format currency code (e.g KES, 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, setting max_num_retry=4 means the transaction will be retried every 60 seconds for the next 4 hours. OPTIONAL.

Sms

• 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 to true 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 SMS

  • message: 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 the linkId to your application when a user sends a message to your onDemand service
  • retry_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 messages

  • last_received_id: This is the id of the message you last processed. Defaults to 0

• create_safaricom_subscription(short_code: str, keyword: str, phone_number: str, request_id: str, redirect_url: str, source_ip: str, user_agent: str): Create a premium Safaricom subscription

  • short_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
  • request_id: Request id associated with the request.
  • redirect_url: URL that the user will be redirected to after they have confirmed their subscription.
  • phone_number: PhoneNumber to be subscribed.
  • source_ip: IP address the subscribing party is originating from.
  • user_agent: String stating which browser was used to access the content.

Voice

• call(callFrom: str, callTo: [str]): Initiate a phone call

  • callFrom: 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 calls

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

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

Token

• generate_auth_token(): Generate an auth token to use for authentication instead of an API key.

MobileData

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

• find_transaction(transaction_id: str): Find a mobile data transaction.

• fetch_wallet_balance(): Fetch a mobile data product balance.

Insights

• check_sim_swap_state(phone_numbers: [str]): Check the sim swap state of a given [array of ] phone number(s).

Whatsapp

• send(body: dict, wa_number: str, phone_number: str): Send a whatsapp message to a given phone number.

  • wa_number: The number being used to send the message that is associated with the account. REQUIRED
  • phone_number: The number that is to receive the message. REQUIRED
  • body: The message to be sent. The message has a combination of the following:
    • message: The message to be sent to the client. OPTIONAL
    • mediaType: The type of message being sent Can be one of Image, Video, Audio, Voice, Sticker or Document OPTIONAL
    • url: The hosted URL of what is being sent. OPTIONAL
    • caption: The caption associated with an image or video that is being sent. OPTIONAL
    • action: A dictionary with a list of actions. OPTIONAL
    • body: A dictionary containing what is being sent with the interactive button or list. OPTIONAL
    • header: A dictionary containing what header is being sent with the interactive button or list.OPTIONAL
    • footer: A dictionary containing what footer is being sent with the interactive button or list.OPTIONAL

• send_template(component: dict, wa_number: str, name: str, language: str, category: str): Send a Whatsapp template for your future messages.

  • wa_number: The Whatsapp phone number that will be used to send the messages associated with the template. REQUIRED
  • name: The name of the template. This must be unique. REQUIRED
  • language: The language code associated with the template. REQUIRED
  • category: The category associated with the template. REQUIRED
  • component: A complex type containing the values that will be in the template. It can contain the following types:
    • header: The header of the template to be sent. OPTIONAL
    • body: The type of message being sent in the body of the template. OPTIONAL
    • footer: The footer of the template to be sent. OPTIONAL
    • buttons: A list of buttons to be sent in the template. OPTIONAL

Ussd

For more information, please read https://developers.africastalking.com/docs/ussd

Development

$ git clone https://github.com/AfricasTalkingLtd/africastalking-python.git
$ cd africastalking-python
$ python3 -m unittest

Issues

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