Metadata-Version: 1.1
Name: africastalking
Version: 1.0.4
Summary: Official Africa's Talking Python SDK
Home-page: https://github.com/AfricasTalkingLtd/africastalking-python
Author: Africa's Talking
Author-email: info@africastalking.com
License: MIT
Download-URL: https://codeload.github.com/AfricasTalkingLtd/africastalking-python/tar.gz/1.0.4
Description: africastalking-python
        =====================
        
        |image0| |image1|
        
            The SDK provides convenient access to the Africa’s Talking APIs from
            python apps.
        
        Documentation
        -------------
        
        Take a look at the `API docs here <http://docs.africastalking.com>`__.
        
        Install
        -------
        
        .. code:: bash
        
            $ pip  install africastalking # python 2.x
        
            OR
        
            $ python -m pip install africastalking # python 2.x
        
            OR
        
            $ pip3 install africastalking # python 3.x
        
            OR
        
            $ python3 -m pip install africastalking # python 3.x
        
        Usage
        -----
        
        .. code:: python
        
            # 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"])
        
            # 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 <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:
        
        -  `Account <#accountservice>`__: ``africastalking.Account``
        -  `Airtime <#airtimeservice>`__: ``africastalking.Airtime``
        -  `SMS <#smsservice>`__: ``africastalking.SMS``
        -  `Payments <#paymentservice>`__: ``africastalking.Payments``
        -  `Voice <#voiceservice>`__: ``africastalking.Voice``
        -  `Token <#tokenservice>`__: ``africastalking.Token``
        -  `USSD <#ussdservice>`__: ``africastalking.USSD``
        
        Services
        --------
        
        All methods are synchronous (i.e. will block current thread) but provide
        asynchronous variants that take a callback
        ``function (error: AfricasTalkingException, data: dict)``.
        
        The synchronous variant always return and instance a ``dict`` while the
        async one returns a ``Thread``.
        
        All phone numbers use the international format. e.g. ``+234xxxxxxxx``.
        
        All amount strings contain th currency code as well. e.g.
        ``UGX 443.88``.
        
        ``AccountService``
        ~~~~~~~~~~~~~~~~~~
        
        -  ``fetch_account()``: Get app balance info.
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            account = africastalking.Account
            res = account.fetch_account()
        
        ``AirtimeService``
        ~~~~~~~~~~~~~~~~~~
        
        -  ``send(phone_number: str, amount: str)``: Send airtime to a phone
           number. An example amount would be ``KES 150``.
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            airtime = africastalking.Airtime
            res = airtime.send(phone_number='+254718769882', amount='KES 908')
        
        -  ``send(recipients: [dict])``: Send airtime to a bunch of phone
           numbers. The keys in the ``recipients`` dictionary are phone numbers
           while the values are airtime amounts. The amounts need to have
           currency info e.g. ``UXG 4265``.
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            airtime = africastalking.Airtime
            res = airtime.send(recipients=[
                        {'phoneNumber': '+2348160663047', 'amount': 'NGN 1535' },
                        {'phoneNumber': '+254718769881', 'amount': 'KES 733'},
            ])
        
        For more information about status notification, please read
        http://docs.africastalking.com/airtime/callback
        
        ``SmsService``
        ~~~~~~~~~~~~~~
        
        -  ``send(message: str, recipients: [str], sender_id: str = None, enqueue: bool = False)``:
           Send a bulk message to recipients, optionally from sender_id (Short
           Code or Alphanumeric).
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            sms = africastalking.SMS
            res = sms.send(message='hello', recipients=['+254718769882'])
        
        -  ``send_premium(message: str, keyword: str, link_id: str, recipients: [str])``:
           Send a premium SMS
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            sms = africastalking.SMS
            res = sms.send_premium(message='hello', keyword='music', link_id='233dddd', recipients=['+254718769882'])
        
        -  ``fetch_messages(last_received_id: int = 0)``: Fetch your messages
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            sms = africastalking.SMS
            res = sms.fetch_messages()
        
        -  ``fetch_subscriptions(short_code: str, keyword: str, last_received_id: int = 0)``:
           Fetch your premium subscription data
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            sms = africastalking.SMS
            res = sms.fetch_subscriptions(short_code='6673', keyword='music')
        
        -  ``create_subscription(short_code: str, keyword: str, phone_number: str, checkout_token: str)``:
           Create a premium subscription
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            sms = africastalking.SMS
            token = africastalking.Token
            res = token.create_checkout_token(phone_number='+254718767882')
            checkout_token = res['token']
            res = sms.create_subscription(short_code='6673', keyword='music', phone_number='+254718767882', checkout_token=checkout_token)
        
        For more information on:
        
        -  How to receive SMS: http://docs.africastalking.com/sms/callback
        -  How to get notified of delivery reports:
           http://docs.africastalking.com/sms/deliveryreports
        -  How to listen for subscription notifications:
           http://docs.africastalking.com/subscriptions/callback
        
        ``PaymentService``
        ~~~~~~~~~~~~~~~~~~
        
        -  ``card_checkout(product_name: str, amount: str, payment_card: dict, narration: str)``:
           Initiate card checkout.
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            payment = africastalking.Payment
            card = {
                'number': '3234324235452345',
                'countryCode': 'NG',
                'cvvNumber': 3343,
                'expiryMonth': 3, # 1-12
                'expiryYear': 2022, # > 2018
                'authToken': '3322' # card pin
            }
            res = payment.card_checkout(product_name='TestProduct', amount='NGN 7822', payment_card=card, narration='Small Chops Checkout')
        
        -  ``validate_card_checkout(transaction_id: str, otp: str)``: Validate a
           card checkout
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            payment = africastalking.Payment
            res = payment.validate_card_checkout(transaction_id='ATId_3829u49283u423u', otp='233333')
        
        -  ``bank_checkout(product_name: str, amount: str, bank_account: dict, narration: str)``:
           Initiate bank checkout.
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            payment = africastalking.Payment
            account = {
                'accountNumber': '3234324235452345',
                'bankCode': payment.BANK['FCMB_NG'],
                'accountName': 'Fake Bob Naija',
                # Optional YYYY-MM-DD // required only for Zenith Nigeria
                #'dateOfBirth': '2000-01-01'
            }
            res = payment.bank_checkout(product_name='TestProduct', amount='NGN 7822', bank_account=account, narration='Small Chops Checkout')
        
        -  ``validate_bank_checkout(transaction_id: str, otp: str)``: Validate a
           bank checkout
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            payment = africastalking.Payment
            res = payment.validate_bank_checkout(transaction_id='ATId_3829u492SQSW383u423u', otp='AA22w33')
        
        -  ``bank_transfer(product_name: str, recipients: [dict])``: Move money
           form payment wallet to bank account.
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            payment = africastalking.Payment
            recipients = [
                {
                  "bankAccount": {
                    "accountNumber": "3234324235452345",
                    "bankCode": payment.BANK['FCMB_NG'],
                    "accountName": "Fake Bob Naija"
                  },
                  "currencyCode": "NGN",
                  "amount": 332434,
                  "narration": "Some description",
                  "metadata": {}
                }
            ]
            res = payment.bank_transfer(product_name='TestProduct', recipients=recipients)
        
        -  ``mobile_checkout(product_name: str, phone_number: str, amount: str, metadata: dict = {})``:
           Initiate mobile checkout. An example amount would be ``KES 323``
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            payment = africastalking.Payment
            res = payment.mobile_checkout(product_name='TestProduct', amount="KES 565")
        
        -  ``mobile_b2c(product_name: str, consumers: [dict])``: Send mobile
           money to consumer. Each consumer is a ``dict`` of this format:
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            payment = africastalking.Payment
            consumers = [
                {
                
                  "name": "Bob Mwangi",
                  "phoneNumber": "+254718769882",
                  "currencyCode": "KES",
                  "amount": 6766.88,
                  "providerChannel": "1212",
                  "reason": payment.REASON['SalaryPayment'],
                  "metadata": {}
                }
            ]
            res = payment.mobile_b2c(product_name='TestProduct', consumers=consumers)
        
        -  ``mobile_b2b(product_name: str, business: dict)``: Send mobile money
           to business.
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            payment = africastalking.Payment
            business = {
              "currencyCode": "KES",
              "amount": 6766.88,
              "destinationChannel": "1212",
              "destinationAccount": "ABC",
              "provider": payment.PROVIDER['Mpesa'],
              "transferType": payment.TRANSFER_TYPE[''],
              "metadata": {}
            }
            res = payment.mobile_b2b(product_name='TestProduct', business=business)
        
        For more information, please read
        http://docs.africastalking.com/payments
        
        ``VoiceService``
        ~~~~~~~~~~~~~~~~
        
        -  ``call(source: str, destination: str)``: Initiate a phone call
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            voice = africastalking.Voice
            res = voice.call(source="+254718769881", destination="+254718769880")
        
        -  ``fetch_queued_calls(phone_number: str)``: Get queued calls
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            voice = africastalking.Voice
            res = voice.fetch_queued_calls(phone_number="+2548933373")
        
        -  ``upload_media_file(phone_number: str, url: str)``: Upload voice
           media file
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            voice = africastalking.Voice
            res = voice.upload_media_file(phone_number="+2548933373", url="https://www.my-site.zr/my_fil.mp3")
        
        For more information, please read http://docs.africastalking.com/voice
        
        ``TokenService``
        ~~~~~~~~~~~~~~~~
        
        -  ``create_checkout_token(phone_number: str)``: Create a new checkout
           token for ``phone_number``.
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            token = africastalking.Token
            res = token.create_checkout_token("+254787633677")
        
        -  ``generate_auth_token()``: Generate an auth token to use for
           authentication instead of an API key.
        
        .. code:: python
        
            import africastalking
            africastalking.initialize(username='sandbox', api_key='someKey')
            token = africastalking.Token
            res = token.generate_auth_token()
        
        ``UssdService``
        ~~~~~~~~~~~~~~~
        
        For more information, please read http://docs.africastalking.com/ussd
        
        Development
        -----------
        
        .. code:: shell
        
            $ git clone https://github.com/aksalj/africastalking-python.git
            $ cd africastalking-python
            $ touch .env
        
        Make sure your ``.env`` file has the following content then run
        ``python -m unittest discover -v``
        
        .. code:: ini
        
            # AT API
            USERNAME=sandbox
            API_KEY=some_key
        
        Issues
        ------
        
        If you find a bug, please file an issue on `our issue tracker on
        GitHub <https://github.com/AfricasTalkingLtd/africastalking-python/issues>`__.
        
        .. |image0| image:: https://img.shields.io/pypi/v/africastalking.svg
        .. |image1| image:: https://img.shields.io/pypi/pyversions/africastalking.svg
        
        
Keywords: ussd voice sms mpesa card bank b2b b2c sender_id payments airtime africastalking
Platform: UNKNOWN
