<commit_before># Bandwidth Python API

[![Build Status](https://travis-ci.org/bandwidthcom/python-bandwidth.svg?branch=master)](https://travis-ci.org/bandwidthcom/python-bandwidth)

[![Can I Use Python 3?](https://caniusepython3.com/project/bandwidth-sdk.svg)](https://caniusepython3.com/project/bandwidth-sdk)

Bandwidth SDK is Python library for working with [Bandwidth](https://catapult.inetwork.com/pages/home.jsf) platform API.
It should be integrated in your python web application easily.

Complete original documentation of API [here](https://catapult.inetwork.com/docs/)

## Getting started
You need to have

    - Git
    - Python (2.7, 3.3, 3.4)
    - Bandwidth Application Platform account
    - pip

## Installation
Simply use the following command to install the latest released version:
```console
pip install bandwidth_sdk
```

If you want the cutting edge version (that may be broken), use this:
```console
pip install -e git+https://github.com/bandwidthcom/python-bandwidth.git#egg=bandwidth_sdk
```
## Usage

The SDK setup

Default setup from environment variables in UNIX shell:

```console
export BANDWIDTH_USER_ID=u-your-user-id
export BANDWIDTH_TOKEN=t-your-token
export BANDWIDTH_SECRET=s-your-secret
```
Or explicitly set up in code:

```python
from bandwidth_sdk import Client
Client('u-user', 't-token', 's-secret')
```

###Calls basic usage

Import Call from sdk
```python
from bandwidth_sdk import Call
```

Creating a new call:
```python
call = Call.create("+1919000001", "+1919000002")
>>> Call(c-xxxxx, state=started)
```
Speaking a sentence in a phone call:
```python
call.speak_sentence("Hello", gender="female")
```
Transferring a call and saying something before bridging the calls:
```python
call.transfer('+1919000008', whisper_audio={"sentence": "Hello {number}, thanks for calling"})
>>> Call(c-yyyyy, state=started)
```
Retrieving list of calls:
```python
Call.list()<commit_msg>add available numbers part of usage to readme<commit_after># Bandwidth Python API

[![Build Status](https://travis-ci.org/bandwidthcom/python-bandwidth.svg?branch=master)](https://travis-ci.org/bandwidthcom/python-bandwidth)

[![Can I Use Python 3?](https://caniusepython3.com/project/bandwidth-sdk.svg)](https://caniusepython3.com/project/bandwidth-sdk)

Bandwidth SDK is Python library for working with [Bandwidth](https://catapult.inetwork.com/pages/home.jsf) platform API.
It should be integrated in your python web application easily.

Complete original documentation of API [here](https://catapult.inetwork.com/docs/)

## Getting started
You need to have

    - Git
    - Python (2.7, 3.3, 3.4)
    - Bandwidth Application Platform account
    - pip

## Installation
Simply use the following command to install the latest released version:
```console
pip install bandwidth_sdk
```

If you want the cutting edge version (that may be broken), use this:
```console
pip install -e git+https://github.com/bandwidthcom/python-bandwidth.git#egg=bandwidth_sdk
```
## Usage

The SDK setup

Default setup from environment variables in UNIX shell:

```console
export BANDWIDTH_USER_ID=u-your-user-id
export BANDWIDTH_TOKEN=t-your-token
export BANDWIDTH_SECRET=s-your-secret
```
Or explicitly set up in code:

```python
from bandwidth_sdk import Client
Client('u-user', 't-token', 's-secret')
```

###Allocate phone number basic

Import AvailableNumber from sdk
```python
from bandwidth_sdk import AvailableNumber
```
Get available number for yours search criteria:

```python
available_numbers = AvailableNumber.list_local(city='San Francisco', state='CA')
available_numbers[0].allocate()
>>> PhoneNumber(number=+14158000000)
```

You can also create Application before (or update current), to use your endpoint to handle events related to this Phonenumber.

```python
from bandwidth_sdk import Application
application = Application.create(name='new-application',
                                 incoming_call_url='http://test.callback.info')
# getting number that we allocated before
number = PhoneNumber.get_number_info(number=+14158000000)
number.patch(application=application)
```

Now this number is attached to your application, and all events will deliver to `incoming_call_url` that your point in Application.

###Calls basic usage

Import Call from sdk
```python
from bandwidth_sdk import Call
```

Creating a new call:
```python
call = Call.create("+1919000001", "+1919000002")
>>> Call(c-xxxxx, state=started)
```
Speaking a sentence in a phone call:
```python
call.speak_sentence("Hello", gender="female")
```
Transferring a call and saying something before bridging the calls:
```python
call.transfer('+1919000008', whisper_audio={"sentence": "Hello {number}, thanks for calling"})
>>> Call(c-yyyyy, state=started)
```
Retrieving list of calls:
```python
Call.list()
{'fraction_non_alphanumeric': 0.12367049009384776, 'fraction_numerical': 0.021063607924921793, 'mean_word_length': 5.369189907038512, 'pattern_counts': {'":': 2, '<': 3, '<?xml version=': 0, '>': 18, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3762313', 'n_tokens_mistral': 1555, 'n_tokens_neox': 1414, 'n_words': 448}