twilio-ruby 3.10.1 → 3.11.0

data/docs/usage/applications.rst

@@ -0,0 +1,108 @@
+.. module:: twilio.rest.resources
+
+=================
+Applications
+=================
+
+An application inside of Twilio is just a set of URLs and other configuration
+data that tells Twilio how to behave when one of your Twilio numbers receives
+a call or message.
+
+For more information, see the `Application REST Resource
+<http://www.twilio.com/docs/api/rest/applications>`_ documentation.
+
+
+Listing Your Applications
+--------------------------
+
+The following code will print out the :attr:`friendly_name` for each :class:`Application`.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @client.applications.each do |app|
+        puts app.friendly_name
+    end
+
+
+Filtering Applications
+---------------------------
+
+You can filter applications by FriendlyName
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @client.applications.list({:friendly_name => 'FOO'})}.each do |app|
+        puts app.sid
+    end
+
+
+Creating an Application
+-------------------------
+
+When creating an application, no fields are required. We create an application
+with only a :attr:`friendly_name`. The :meth:`Applications.create()` method
+accepts many other arguments for url configuration.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @application = @client.applications.create({:friendly_name => "My New App"})
+
+
+Updating an Application
+------------------------
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+
+    url = "http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient"
+    app_sid = 'AP123' # the app you'd like to update
+
+    @application = @client.applications.get(app_sid)
+    @application.update({:voice_url => url})
+
+
+Deleting an Application
+-------------------------
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+
+    app_sid = 'AP123' # the app you'd like to delete
+    @client.applications.get(app_sid)
+    @application.delete()
+

data/docs/usage/basics.rst

@@ -0,0 +1,81 @@
+.. module:: twilio.rest
+
+=========================
+Accessing REST Resources
+=========================
+
+To access Twilio REST resources, you'll first need to instantiate a
+:class:`TwilioRestClient`.
+
+Authentication
+--------------------------
+
+The :class:`TwilioRestClient` needs your Twilio credentials. To get
+your credentials, visit `your Twilio account portal
+<https://www.twilio.com/user/account>`_. If you don't have a Twilio account
+yet, go `here <https://www.twilio.com/try-twilio>`_ to get started.
+
+Once you have your credentials, you can create create a new :class:`Client` and get started.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+
+
+Listing Resources
+-------------------
+
+The :class:`Client` gives you access to various list resources.
+:meth:`ListResource.list`, by default, returns the most recent 50 instance resources.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @calls = client.calls.list()
+
+:meth:`ListResource.list` accepts paging arguments.
+The following will return page 3 with page size of 25.
+
+.. code-block:: python
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @calls = client.calls.list(page=3, page_size=25)
+
+
+Get an Individual Resource
+-----------------------------
+
+To get an individual instance resource, use :meth:`ListResource.get`.
+Provide the :attr:`sid` of the resource you'd like to get.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+
+    @call = @client.calls.get("CA123")
+    puts @call.to
+

data/docs/usage/caller-ids.rst

@@ -0,0 +1,45 @@
+.. module:: twilio.rest.resources
+
+=================
+Caller Ids
+=================
+
+
+Validate a Phone Number
+-----------------------
+
+Validating a phone number is quick and easy.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @response = @client.caller_ids.create("+44 9876543212")
+    puts @response.validation_code
+
+Twilio will call the provided number and wait for the validation code to be
+entered.
+
+Delete a Phone Number
+---------------------
+
+Deleting a phone number is quick and easy.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+
+    @response = @client.caller_ids.list(phone_number="+15555555555")
+    @callerid = response[0]
+    @callerid.delete()

data/docs/usage/conferences.rst

@@ -0,0 +1,108 @@
+.. module:: twilio.rest.resources
+
+==============================
+Conferences and Participants
+==============================
+
+For more information, see the `Conference REST Resource <http://www.twilio.com/docs/api/rest/conference>`_
+and `Participant REST Resource <http://www.twilio.com/docs/api/rest/participant>`_ documentation.
+
+
+Listing Conferences
+-----------------------
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @conferences = @client.conferences.list()
+
+    @conferences.each do |conference|
+        puts conference.sid
+    end
+
+
+Filtering Conferences
+-----------------------
+
+The :meth:`Twilio::REST::Conferences.list` method supports filtering on :attr:`status`,
+:attr:`date_updated`, :attr:`date_created` and :attr:`friendly_name`. The following code
+will return a list of all in-progress conferences and print their friendly name.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @conferences = @client.conferences.list({:status => "in-progress"})
+    
+    @conference.each do |conference|
+        puts conference.friendly_name
+    end
+
+
+Listing Participants
+----------------------
+
+Each :class:`Conference` has a :attr:`participants` instance which represents all current users in the conference
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @conference = @client.conferences.get("CF123")
+
+    @conference.participants.list.each.do |paricipant|
+        puts participant.sid
+    end
+
+:class:`Conferences` and :class:`Participants` are subclasses of :class:`ListResource`.
+Therefore, their instances have the inherited methods such as :meth:`count`.
+
+
+Managing Participants
+----------------------
+
+Each :class:`Conference` has a :attr:`participants` function that returns a
+:class:`Participants` instance. This behavior differs from other list resources
+because :class:`Participants` needs a participant sid AND a conference sid to
+access the participants resource.
+
+Participants can be either muted or kicked out of the conference. The following
+code kicks out the first participant and mutes the rest.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+    @participants = @client.conferences.get("CF123").participants.list()
+
+    if @participants.empty?
+        return
+
+    # Kick the first person out
+    @participants.pop().kick()
+
+    # And mute the rest
+    @participants.each do |participant|
+        participant.mute()
+

data/docs/usage/messages.rst

@@ -0,0 +1,110 @@
+.. module:: twilio.rest.resources.sms_messages
+
+============
+Messages
+============
+
+For more information, see the
+`Message REST Resource <http://www.twilio.com/docs/api/rest/message>`_
+documentation.
+
+
+Sending a Text Message
+----------------------
+
+Send a text message in only a few lines of code.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+
+    @message = client.messages.create({:to => "+13216851234",
+                                       :from => "+15555555555",
+                                       :body => "Hello!"})
+
+If you want to send a message from a `short code
+<http://www.twilio.com/api/sms/short-codes>`_ on Twilio, just set :attr:`from`
+to your short code's number.
+
+
+Sending a Picture Message
+-------------------------
+
+To send a picture, set :attr:`media_url` to the url of the picture you wish to send.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+
+    @message = client.messages.create({:to => "+15558676309",
+                                       :from => "+15555555555",
+                                       :body => "Jenny I need you!",
+                                       :media_url => "http://twilio.com/heart.jpg"})
+
+You can send multiple pictures in the same message by setting :attr:`media_url` to
+an array of urls.
+
+.. code-block:: ruby
+
+    @message = client.messages.create({:to => "+15558676309",
+                                       :from => "+15555555555",
+                                       :body => "Jenny I need you!",
+                                       :media_url => [
+                                            "http://twilio.com/heart.jpg",
+                                            "http://twilio.com/rose.jpg"
+                                        ]})
+
+
+Retrieving Sent Messages
+-------------------------
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+
+    @client.messages.each do |message|
+        puts message.body
+
+
+Filtering Your Messages
+-------------------------
+
+The :meth:`list` methods supports filtering on :attr:`to`, :attr:`from`,
+and :attr:`date_sent`.
+The following will only show messages to "+5466758723" on January 1st, 2011.
+
+.. code-block:: ruby
+
+    require 'twilio-ruby'
+
+    # To find these visit https://www.twilio.com/user/account
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+
+    @client = Twilio::REST::Client.new account_sid, auth_token
+
+    @messages = client.messages.list({:to => "+5466758723",
+                                      :date_sent => date(2011,1,1)})
+
+    @messages.each do |message|
+        puts message.body
+    
+