diff --git a/README.md b/README.md index e8defae..1dfb92a 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,9 @@ Requirements * Flowroute [API credentials](https://manage.flowroute.com/accounts/preferences/api/) * [Python](https://www.python.org/downloads/) 2.x or higher -### Installation +* * * +Installation +------------ 1. First, start a shell session and clone the SDK: * via HTTPS: `git clone https://github.com/flowroute/flowroute-numbers-python.git` @@ -32,38 +34,40 @@ Requirements `pip install -r requirements.txt` -### Usage +* * * +Usage +------------ In Flowroute's approach to building Python API Wrapper v3, HTTP requests are handled by controllers named after the API resources they represent: **Numbers**, **Routes**, and **Messages**. These controllers contain the methods used to perform number management, route management, and messaging tasks with the Python SDK. -#### Controllers +### Controllers * NumbersController Contains all of the methods necessary to search through Flowroute's phone number inventory, purchase a phone number, and review details of your account phone numbers. - * [list\_available\_area\_codes()](#listareacodes) \- Returns a list of all Numbering Plan Area (NPA) codes containing purchasable phone numbers. - * [list\_available\_exchange\_codes()](#listexchanges) \- Returns a list of all Central Office (exchange) codes containing purchasable phone numbers. - * [search\_for\_purchasable\_phone\_numbers()](#search) \- Searches for purchasable phone numbers by state or rate center, or by your specified search value. - * [purchase\_a\_phone\_number(number\_id)](#purchase) \- Lets you purchase a phone number from available Flowroute inventory. - * [list\_account\_phone\_numbers()](#listaccountnumbers) \- Returns a list of all phone numbers currently on your Flowroute account. The response includes details such as the phone number's rate center, state, number type, and whether CNAM Lookup is enabled for that number. - * [list\_phone\_number\_details(numberid)](#numberdetails) \- Lists all of the information associated with any of the phone numbers in your account, including billing method, primary voice route, and failover voice route. + * [list\_available\_area\_codes()](#list_available_area_codes) \- Returns a list of all Numbering Plan Area (NPA) codes containing purchasable phone numbers. + * [list\_available\_exchange\_codes()](#list-available_exchange_codes) \- Returns a list of all Central Office (exchange) codes containing purchasable phone numbers. + * [search\_for\_purchasable\_phone\_numbers()](#search_for_purchasable_phone_numbers) \- Searches for purchasable phone numbers by state or rate center, or by your specified search value. + * [purchase\_a\_phone\_number(number\_id)](#purchase_a_phone_numbernumber_id) \- Lets you purchase a phone number from available Flowroute inventory. + * [list\_account\_phone\_numbers()](#list_account_phone_numbers) \- Returns a list of all phone numbers currently on your Flowroute account. The response includes details such as the phone number's rate center, state, number type, and whether CNAM Lookup is enabled for that number. + * [list\_phone\_number\_details(numberid)](#list_phone_number_detailsnumber_id) \- Lists all of the information associated with any of the phone numbers in your account, including billing method, primary voice route, and failover voice route. * RoutesController Contains the methods required to create new inbound routes, view all of your account routes, and update primary and failover voice routes for your phone numbers. - * [create\_an\_inbound\_route(route\_body)](#createnewroute) \- Create a new inbound route that can then be assigned as either a primary or failover voice route for a phone number. - * [list\_inbound\_routes()](#listroutes) \- Returns a list of your inbound routes. From the list, you can then select routes to use as the primary and failover voice routes for your phone number. - * [update\_primary\_voice\_route(number\_id, route\_body)](#updateprimaryvoiceroute) \- Updates the primary voice route for a phone number. You must create the route first via the `create_an_inbound_route(routebody)` method. - * [update\_failover\_voice\_route(number\_id, route\_body)](#updatefailovervoiceroute) \- Updates the failover voice route for a phone number. You must create the route first via the `create_an_inbound_route(routebody)` method. + * [create\_an\_inbound\_route(route\_body)](#create_an_inbound_routeroute_body) \- Create a new inbound route that can then be assigned as either a primary or failover voice route for a phone number. + * [list\_inbound\_routes()](#list_inbound_routes) \- Returns a list of your inbound routes. From the list, you can then select routes to use as the primary and failover voice routes for your phone number. + * [update\_primary\_voice\_route(number\_id, route\_body)](#update_primary_voice_route) \- Updates the primary voice route for a phone number. You must create the route first via the `create_an_inbound_route(routebody)` method. + * [update\_failover\_voice\_route(number\_id, route\_body)](#update_failover_voice_route) \- Updates the failover voice route for a phone number. You must create the route first via the `create_an_inbound_route(routebody)` method. * MessagesController Contains the methods required to send an MMS or SMS, and review a specific Message Detail Record (MDR) or a set of messages. - * [send\_a\_message(message\_body)](#sendmessage) \- Sends an SMS or MMS from a Flowroute long code or toll-free phone number to another valid phone number. - * [look\_up\_a\_message\_detail\_record()](#lookupmessage) \- Searches for a specific message record ID and returns a Message Detail Record (in MDR2 format). - * [look\_up\_a\_message\_detail\_record()](#lookupmessage) \- Searches for a specific message record ID and returns a Message Detail Record (in MDR2 format). + * [send\_a\_message(message\_body)](#send_a_messagemessage_body) \- Sends an SMS or MMS from a Flowroute long code or toll-free phone number to another valid phone number. + * [look\_up\_a\_message\_detail\_record()](#look_up_a_message_detail_record) \- Searches for a specific message record ID and returns a Message Detail Record (in MDR2 format). + * [look\_up\_a\_set\_of\_messages()](#look_up_a_set_of_messages) \- Retrieves a list of Message Detail Records (MDRs) within a specified date range. Date and time is based on Coordinated Universal Time (UTC). The following shows an example of a single Python file that imports the Flowroute API client and all the required modules. The Python SDK comes with a **demo.py** file that you can edit and run as an example. @@ -96,56 +100,24 @@ messages_controller = client.messages ### Number Management -#### List Area Codes -##### list\_available\_area\_codes() +Flowroute SDK version 3 for Python allows you to make HTTP requests to the `numbers` resource of Flowroute API v2: `https://api.flowroute.com/v2/numbers` + +#### list\_available\_area\_codes() The method accepts `limit`, `offset`, and `max_setup_cost` as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/list-available-area-codes/). -###### Example Request - +##### Example Request ```python -print("--List Available Exchange Codes") +print("--List Available Area Codes") +max_setup_cost = 3.25 limit = 3 offset = None -max_setup_cost = None -areacode = 347 -result = numbers_controller.list_available_exchange_codes(limit, offset, max_setup_cost, areacode) +result = numbers_controller.list_available_area_codes(limit, offset, max_setup_cost) pprint.pprint(result) ``` -###### Example Response - +##### Example Response ``` -{ - "data": [ - { - "type": "exchange", - "id": "347215", - "links": { - "related": "https://api.flowroute.com/v2/numbers/available?starts_with=1347215" - } - }, - { - "type": "exchange", - "id": "347325", - "links": { - "related": "https://api.flowroute.com/v2/numbers/available?starts_with=1347325" - } - }, - { - "type": "exchange", - "id": "347331", - "links": { - "related": "https://api.flowroute.com/v2/numbers/available?starts_with=1347331" - } - } - ], - "links": { - "self": "https://api.flowroute.com/v2/numbers/available/exchanges?areacode=347&limit=3&offset=0", - "next": "https://api.flowroute.com/v2/numbers/available/exchanges?areacode=347&limit=3&offset=3" - } -} -Marias-MacBook-Pro:~ mbermudez$ pbpaste | jq . { "data": [ { @@ -177,12 +149,11 @@ Marias-MacBook-Pro:~ mbermudez$ pbpaste | jq . } ``` -##### list\_available\_area\_codes() +#### list\_available\_exchange\_codes() The method accepts `limit`, `offset`, `max_setup_cost`, and `areacode` as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/list-available-exchanges/). -###### Example Request - +##### Example Request ```python print("--List Available Exchange Codes") limit = 3 @@ -192,8 +163,7 @@ areacode = 347 result = numbers_controller.list_available_exchange_codes(limit, offset, max_setup_cost, areacode) pprint.pprint(result) ``` -###### Example Response - +##### Example Response ``` { "data": [ @@ -223,16 +193,14 @@ pprint.pprint(result) "self": "https://api.flowroute.com/v2/numbers/available/exchanges?areacode=347&limit=3&offset=0", "next": "https://api.flowroute.com/v2/numbers/available/exchanges?areacode=347&limit=3&offset=3" } - } ``` -##### search\_for\_purchasable\_phone\_numbers - -The method accepts `starts_with`. `contains`, `ends_with`, `limit`, `offset`, `rate_center`, and `state` as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v1.0/search-for-purchasable-phone-numbers/). +#### search\_for\_purchasable\_phone\_numbers() -###### Example Request +The method accepts `starts_with`, `contains`, `ends_with`, `limit`, `offset`, `rate_center`, and `state` as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/search-for-purchasable-phone-numbers/). +##### Example Request ```python print("--Search for Purchasable Phone Numbers") starts_with = 646 @@ -243,10 +211,9 @@ offset = None rate_center = None state = None result = numbers_controller.search_for_purchasable_phone_numbers(starts_with, contains, ends_with, limit, offset, rate_center, state) - ``` -###### Example Response +##### Example Response ``` { "data": [ @@ -302,20 +269,22 @@ result = numbers_controller.search_for_purchasable_phone_numbers(starts_with, co } } ``` -##### purchase\_a\_phone\_number(number\_id) -The method is used to purchase a telephone number from Flowroute's inventory and accepts the phone number ID as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/purchase-a-phone-number/). +#### purchase\_a\_phone\_number(number\_id) -###### Example Request +The method is used to purchase a telephone number from Flowroute's inventory and accepts the phone number `id` as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/purchase-a-phone-number/). +##### Example Request ```python print("--Purchase a Phone Number") numberid = result['data'][0]['id']) result = numbers_controller.purchase_a_phone_number(numberid) ``` -In our example above, we have assigned the `id` of the first phone number in the resulting JSON array as the phone number to be purchased. -##### Example Response +In the example above, we have assigned the `id` of the first phone number in the resulting JSON array as the phone number to be purchased. + +#### Example Response +``` { "data": { "attributes": { @@ -367,14 +336,14 @@ In our example above, we have assigned the `id` of the first phone number in the "self": "https://api.flowroute.com/v2/numbers/16502390214" } } +``` -##### list\_account\_phone\_numbers() +#### list\_account\_phone\_numbers() The method accepts `starts_with`, `ends_with`, `contains`, `limit`, and `offset` as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/list-account-phone-numbers/). -###### Example Request - +##### Example Request ```python print("--List Account Phone Numbers") starts_with = 201 @@ -386,7 +355,7 @@ result = numbers_controller.list_account_phone_numbers(starts_with, ends_with, c pprint.pprint(result) ``` -###### Example Response +##### Example Response ``` { "data": [ @@ -426,19 +395,19 @@ pprint.pprint(result) } } ``` -##### list\_phone\_number\_details(number\_id) -The method accepts the `number_id` as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/list-phone-number-details/). In the following example, we request the details of our newly purchased phone number above. +#### list\_phone\_number\_details(number\_id) -###### Example Request +The method accepts the `number_id` as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/list-phone-number-details/). In the following example, we request the details of our newly purchased phone number above. +##### Example Request ```python print("--List Phone Number Details") -result = numbers\_controller.list\_phone\_number\_details(numberid) +result = numbers_controller.list_phone_number_details(numberid) pprint.pprint(result) ``` -###### Example Response +##### Example Response ``` { "included": [ @@ -492,13 +461,17 @@ pprint.pprint(result) } } ``` + ### Route Management + +Flowroute SDK version 3 for Python allows you to make HTTP requests to the `routes` resource of Flowroute API v2: `https://api.flowroute.com/v2/routes` -##### create\_an\_inbound\_route(route\_body) - WIP +#### create\_an\_inbound\_route(route\_body) +WIP The method accepts the route object in JSON format as a parameter which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/create-an-inbound-route/). -###### Example Request +##### Example Request ```python #print ("---Create an Inbound Route") #request_body = '{ @@ -517,20 +490,24 @@ The method accepts the route object in JSON format as a parameter which you can result = routes_controller.create_an_inbound_route(request_body) pprint.pprint(result) ``` + +##### Example Response +``` +``` Currently has some issues with POST and PATCH requests via the SDK methods provided. -##### list\_inbound\_routes() +#### list\_inbound\_routes() The method accepts `limit` and `offset` as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/list-inbound-routes/). -###### Example Response +##### Example Request ```python print ("---List Inbound Routes") result = routes_controller.list_inbound_routes() pprint.pprint(result) ``` -###### Example Response +##### Example Response ``` { "data": [ @@ -565,11 +542,108 @@ pprint.pprint(result) } } ``` + +#### update\_primary\_voice\_route(number\_id, route\_body) +WIP + +The method accepts a phone number `id` and a route record object in JSON format as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/update-number-primary-voice-route/). + +##### Example Request +```python +print ("---Update Primary Voice Route for a Phone Number") +``` + +##### Example Response +`204 NO CONTENT` + +On success, the HTTP status code in the response header is `204 NO CONTENT` which means that the server successfully processed the request and is not returning any content. + +#### update\_failover\_voice\_route(number\_id, route\_body) +WIP + +The method accepts a phone number `id` and a route record object in JSON format as parameters which you can learn more about in the [API reference](https://developer.flowroute.com/api/numbers/v2.0/update-number-failover-voice-route/). + +##### Example Request +```python +print ("---Update Failover Voice Route for a Phone Number") +``` + +##### Example Response +`204 NO CONTENT` + +On success, the HTTP status code in the response header is `204 NO CONTENT` which means that the server successfully processed the request and is not returning any content. + +### Messaging +Flowroute SDK version 3 for Python allows you to make HTTP requests to the `messages` resource of Flowroute API v2.1: `https://api.flowroute.com/v2.1/messages` + +#### send\_a\_message(message\_body) +WIP + +The method accepts a message object in JSON format as a parameter which you can learn more about in the API References for [MMS](https://developer.flowroute.com/api/messages/v2.1/send-an-mms/) and [SMS](https://developer.flowroute.com/api/messages/v2.1/send-an-sms/). + +##### Example Request +```python +print ("---Send a Message") +``` + +##### Example Response +`202 ACCEPTED` + +On success, the HTTP status code in the response header is `202 Accepted` and the response body contains the message record ID with `mdr2` prefix. + +#### look\_up\_a\_message\_detail\_record(message\_id) + +The method accepts a message `id` in MDR2 format as a parameter which you can learn more about in the [API Reference](https://developer.flowroute.com/api/messages/v2.1/look-up-a-message-detail-record/). + +##### Example Request +```python +print ("---Look Up a Message Detail Record") +message_id = "mdr2-ca82be46e6ba11e79d08862d092cf73d" +result = messages_controller.look_up_a_message_detail_record(message_id) +pprint.pprint(result) +``` + +##### Example Response +``` +{ + "data": { + "attributes": { + "body": "Hello are you there? ", + "status": "delivered", + "direction": "inbound", + "amount_nanodollars": 4000000, + "to": "12012673227", + "message_encoding": 0, + "timestamp": "2017-12-22T01:52:39.39Z", + "delivery_receipts": [], + "amount_display": "$0.0040", + "from": "12067392634", + "is_mms": false, + "message_type": "longcode" + }, + "type": "message", + "id": "mdr2-ca82be46e6ba11e79d08862d092cf73d" + } +} +``` + +#### look\_up\_a\_set\_of\_messages(start\_date) +WIP +The method accepts `start_date`, `end_date`, `limit`, and `offset` as a parameters which you can learn more about in the [API Reference](https://developer.flowroute.com/api/messages/v2.1/look-up-set-of-messages/). + +##### Example Request +```python +print ("---Look Up a Set of Messages") +``` + +##### Example Response +`202 ACCEPTED` +On success, the HTTP status code in the response header is `202 Accepted` and the response body contains the message record ID with `mdr2` prefix. #### Errors In cases of method errors, the API Controller returns an error object with the same fields as our [API's error response](https://developer.flowroute.com/api/errors). -###### Example Error +##### Example Error ``` { "errors": [