# africastalking-python

![](https://img.shields.io/pypi/v/africastalking.svg)

> 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

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

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

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

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

```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](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).


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


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

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


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

```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](http://docs.africastalking.com/sms/callback)
- How to get notified of delivery reports: [http://docs.africastalking.com/sms/deliveryreports](http://docs.africastalking.com/sms/deliveryreports)
- How to listen for subscription notifications: [http://docs.africastalking.com/subscriptions/callback](http://docs.africastalking.com/subscriptions/callback)

### `PaymentService`

- `card_checkout(product_name: str, amount: str, payment_card: dict, narration: str)`: Initiate card checkout.

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

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

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


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

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

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


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

```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](http://docs.africastalking.com/payments)

### `VoiceService`

- `call(source: str, destination: str)`: Initiate a phone call

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

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

```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](http://docs.africastalking.com/voice)


### `TokenService`

- `create_checkout_token(phone_number: str)`: Create a new checkout token for `phone_number`.

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

```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](http://docs.africastalking.com/ussd)


## Development
```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`

```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).
