|
| 1 | +# twilio-python |
| 2 | + |
| 3 | +[](http://travis-ci.org/twilio/twilio-python) |
| 4 | +[](https://pypi.python.org/pypi/twilio) |
| 5 | +[](https://pypi.python.org/pypi/twilio) |
| 6 | + |
| 7 | +A module for using the Twilio REST API and generating valid |
| 8 | +[TwiML](http://www.twilio.com/docs/api/twiml/ "TwiML - |
| 9 | +Twilio Markup Language"). [Click here to read the full |
| 10 | +documentation.][documentation] |
| 11 | + |
| 12 | +## Installation |
| 13 | + |
| 14 | +Install from PyPi using [pip](http://www.pip-installer.org/en/latest/), a |
| 15 | +package manager for Python. |
| 16 | + |
| 17 | + pip install twilio==6.0.0rc12 |
| 18 | + |
| 19 | +Don't have pip installed? Try installing it, by running this from the command |
| 20 | +line: |
| 21 | + |
| 22 | + $ curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python |
| 23 | + |
| 24 | +Or, you can [download the source code |
| 25 | +(ZIP)](https://github.com/twilio/twilio-python/zipball/master "twilio-python |
| 26 | +source code") for `twilio-python`, and then run: |
| 27 | + |
| 28 | + python setup.py install |
| 29 | + |
| 30 | +You may need to run the above commands with `sudo`. |
| 31 | + |
| 32 | +### Migrate from 5.x |
| 33 | +[Upgrade Guide][upgrade] |
| 34 | + |
| 35 | +## Feedback |
| 36 | +Report any feedback or problems with this Release Candidate to the [Github Issues](https://github.com/twilio/twilio-python/issues) for twilio-python. |
| 37 | + |
| 38 | +## Documentation |
| 39 | +[Here][documentation] |
| 40 | + |
| 41 | +## Getting Started |
| 42 | + |
| 43 | +Getting started with the Twilio API couldn't be easier. Create a |
| 44 | +`Client` and you're ready to go. |
| 45 | + |
| 46 | +### API Credentials |
| 47 | + |
| 48 | +The `Twilio` needs your Twilio credentials. You can either pass these |
| 49 | +directly to the constructor (see the code below) or via environment variables. |
| 50 | + |
| 51 | +```python |
| 52 | +from twilio.rest import Client |
| 53 | + |
| 54 | +account = "ACXXXXXXXXXXXXXXXXX" |
| 55 | +token = "YYYYYYYYYYYYYYYYYY" |
| 56 | +client = Client(account, token) |
| 57 | +``` |
| 58 | + |
| 59 | +Alternately, a `Client` constructor without these parameters will |
| 60 | +look for `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` variables inside the |
| 61 | +current environment. |
| 62 | + |
| 63 | +We suggest storing your credentials as environment variables. Why? You'll never |
| 64 | +have to worry about committing your credentials and accidentally posting them |
| 65 | +somewhere public. |
| 66 | + |
| 67 | + |
| 68 | +```python |
| 69 | +from twilio.rest import Client |
| 70 | +client = Client() |
| 71 | +``` |
| 72 | + |
| 73 | +### Make a Call |
| 74 | + |
| 75 | +```python |
| 76 | +from twilio.rest import Client |
| 77 | + |
| 78 | +account = "ACXXXXXXXXXXXXXXXXX" |
| 79 | +token = "YYYYYYYYYYYYYYYYYY" |
| 80 | +client = Client(account, token) |
| 81 | + |
| 82 | +call = client.calls.create(to="9991231234", |
| 83 | + from_="9991231234", |
| 84 | + url="http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient") |
| 85 | +print(call.sid) |
| 86 | +``` |
| 87 | + |
| 88 | +### Send an SMS |
| 89 | + |
| 90 | +```python |
| 91 | +from twilio.rest import Client |
| 92 | + |
| 93 | +account = "ACXXXXXXXXXXXXXXXXX" |
| 94 | +token = "YYYYYYYYYYYYYYYYYY" |
| 95 | +client = Client(account, token) |
| 96 | + |
| 97 | +message = client.messages.create(to="+12316851234", from_="+15555555555", |
| 98 | + body="Hello there!") |
| 99 | +``` |
| 100 | + |
| 101 | +### Handling a call using TwiML |
| 102 | + |
| 103 | +To control phone calls, your application needs to output |
| 104 | +[TwiML](http://www.twilio.com/docs/api/twiml/ "TwiML - Twilio Markup |
| 105 | +Language"). Use `twilio.twiml.Response` to easily create such responses. |
| 106 | + |
| 107 | +```python |
| 108 | +from twilio import twiml |
| 109 | + |
| 110 | +r = twiml.Response() |
| 111 | +r.say("Welcome to twilio!") |
| 112 | +print(str(r)) |
| 113 | +``` |
| 114 | + |
| 115 | +```xml |
| 116 | +<?xml version="1.0" encoding="utf-8"?> |
| 117 | +<Response><Say>Welcome to twilio!</Say></Response> |
| 118 | +``` |
| 119 | + |
| 120 | +### Digging Deeper |
| 121 | + |
| 122 | +The full power of the Twilio API is at your fingertips. The [full |
| 123 | +documentation][documentation] explains all the awesome features available to |
| 124 | +use. |
| 125 | + |
| 126 | +* [Retrieve Call Records][calls] |
| 127 | +* [Retrieve Message Records][messages] |
| 128 | +* [Search for a Phone Number][number] |
| 129 | +* [Buy a Number][number] |
| 130 | +* [Validate a Phone Number][validate] |
| 131 | +* [List Recordings][recordings] |
| 132 | + |
| 133 | +[number]: http://twilio-python.readthedocs.org/en/latest/usage/phone-numbers.html#searching-and-buying-a-number |
| 134 | +[validate]: http://twilio-python.readthedocs.org/en/latest/usage/caller-ids.html |
| 135 | +[recordings]: http://twilio-python.readthedocs.org/en/latest/usage/recordings.html#listing-your-recordings |
| 136 | +[messages]: http://twilio-python.readthedocs.org/en/latest/usage/messages.html#retrieving-sent-messages |
| 137 | +[calls]: http://twilio-python.readthedocs.org/en/latest/usage/phone-calls.html#retrieve-a-call-record |
| 138 | +[issues]: https://github.com/twilio/twilio-python/issues |
| 139 | +[documentation]: http://twilio-python.readthedocs.org/en/release-6x/ |
| 140 | +[upgrade]: https://github.com/twilio/twilio-python/wiki/Python-Version-6.x-Upgrade-Guide |
0 commit comments