.. 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.account.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.account.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.account.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.account.messages.list.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.account.messages.list({:to => "+5466758723", :date_sent => "2011-01-01"})

    @messages.each do |message|
        puts message.body