8000 add usage api docs · RekindleInc/twilio-python@ad5ec46 · GitHub
[go: up one dir, main page]
Skip to content

Commit ad5ec46

Browse files
author
Doug Black
committed
add usage api docs
1 parent a1878e8 commit ad5ec46

File tree

3 files changed

+87
-2
lines changed

3 files changed

+87
-2
lines changed

‎docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ Query the Twilio REST API to create phone calls, send messages and more!
6969
usage/notifications
7070
usage/recordings
7171
usage/transcriptions
72+
usage/usage
7273
usage/caller-ids
7374
usage/queues
7475
usage/sip

‎docs/usage/usage.rst

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
Usage API
2+
=========
3+
4+
Usage Records
5+
-------------
6+
You can query your :class:`UsageRecords` to see the activity
7+
of your Twilio account. Here we'll make a query for the activity
8+
over the last day.
9+
10+
.. code-block:: python
11+
12+
from twilio.rest import TwilioRestClient
13+
14+
# To find these visit https://www.twilio.com/user/account
15+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
16+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
17+
18+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
19+
20+
todays_usage = client.usage.records.today
21+
for category in todays_usage:
22+
print '{}: {}'.format(category.description, category.price)
23+
24+
This will print out the amount spent for each usage category over the
25+
last day. To see all of the possible usage categories, as well as all of the
26+
possible time ranges to query over, check out the [REST API UsageRecord docs](https://www.twilio.com/docs/api/rest/usage-records#usage-all-categories).
27+
28+
29+
Usage Triggers
30+
--------------
31+
You can also set up a :class:`UsageTrigger`. :class:`UsageTriggers` notify
32+
you once your usage reaches a certain level. Here we'll set up a :class:`UsageTrigger`
33+
to tell us when we've sent 1000 total messages.
34+
35+
.. code-block:: python
36+
37+
from twilio.rest import TwilioRestClient
38+
39+
# To find these visit https://www.twilio.com/user/account
40+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
41+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
42+
43+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
44+
45+
trigger = client.usage.triggers.create(
46+
friendly_name="1000 messages",
47+
usage_category="sms",
48+
trigger_value="1000",
49+
callback_url="http://example.com/thousand-sms",
50+
trigger_by="count"
51+
)
52+
53+
Once this trigger is created, Twilio will make a POST to "http://example.com/thousand-sms"
54+
once your account has sent 1000 messages.
55+
56+
Relative Triggers
57+
-----------------
58+
59+
The previous example is helpful, but it is an example of an *absolute* trigger value.
60+
What if your account has already sent 1000 messages, and you want to be notified once
61+
it sends the next 1000, regardless of how many you've previously sent? To do this,
62+
you must add a '+' in front of the :attr:`trigger_value`, so Twilio knows this is a
63+
relative count. Here's an example that shows how to set a relative trigger.
64+
65+
.. code-block:: python
66+
67+
from twilio.rest import TwilioRestClient
68+
69+
# To find these visit https://www.twilio.com/user/account
70+
ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXX"
71+
AUTH_TOKEN = "YYYYYYYYYYYYYYYYYY"
72+
73+
client = TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN)
74+
75+
trigger = client.usage.triggers.create(
76+
friendly_name="1000 messages",
77+
usage_category="sms",
78+
trigger_value="+1000",
79+
callback_url="http://example.com/thousand-sms",
80+
trigger_by="count"
81+
)
82+
83+
Once this trigger is created, Twilio will make a POST to "http://example.com/thousand-sms"
84+
once your account has sent 1000 more messages.

‎twilio/rest/resources/usage.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,9 +43,9 @@ def list(self, **kwargs):
4343

4444
def create(self, **kwargs):
4545
"""
46-
Create an :class:`Application` with any of these optional parameters.
46+
Create an :class:`UsageTrigger` with any of these optional parameters.
4747
48-
:param friendly_name: A human readable description of the application,
48+
:param friendly_name: A human readable description of the UsageTrigger,
4949
with maximum length 64 characters.
5050
:param usage_category: The trigger will watch this usage category.
5151
:param trigger_value: The trigger will fire when usage reaches this

0 commit comments

Comments
 (0)
0