.. module:: restcomm.rest.resources.sms_messages

============
Messages
============

For more information, see the
`Message REST Resource <http://docs.telestax.com/restcomm-pages/>`_
documentation.


Sending a Text Message
----------------------

Send a text message in only a few lines of code.

.. code-block:: ruby

    require 'restcomm-ruby'

    # To find these visit http://docs.telestax.com/restcomm-pages/
    account_sid = "ACXXXXXXXXXXXXXXXXX"
    auth_token = "YYYYYYYYYYYYYYYYYY"
    host = "XXX.XXX.XXX.XXX"

    @client = Restcomm::REST::Client.new account_sid, auth_token, host

    @message = @client.messages.create(
      to: "+13216851234",
      from: "+15555555555",
      body: "Hello!"
    )

If you want to send a message from a `short code
<http://www.restcomm.com/api/sms/short-codes>`_ on Restcomm, 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 'restcomm-ruby'

    # To find these visit http://docs.telestax.com/restcomm-pages/
    account_sid = "ACXXXXXXXXXXXXXXXXX"
    auth_token = "YYYYYYYYYYYYYYYYYY"
    host = "XXX.XXX.XXX.XXX"

    @client = Restcomm::REST::Client.new account_sid, auth_token, host

    @message = @client.messages.create(
      to: "+15558676309",
      from: "+15555555555",
      body: "Jenny I need you!",
      media_url: "http://restcomm.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://restcomm.com/heart.jpg",
        "http://restcomm.com/rose.jpg"
      ]
    )

Retrieving Sent Messages
-------------------------

.. code-block:: ruby

    require 'restcomm-ruby'

    # To find these visit http://docs.telestax.com/restcomm-pages/
    account_sid = "ACXXXXXXXXXXXXXXXXX"
    auth_token = "YYYYYYYYYYYYYYYYYY"
    host = "XXX.XXX.XXX.XXX"

    @client = Restcomm::REST::Client.new account_sid, auth_token, host

    @client.messages.list.each do |message|
      puts message.body
    end

Redacting or Deleting Messages
------------------------------

.. code-block:: ruby

    require 'restcomm-ruby'

    # To find these visit http://docs.telestax.com/restcomm-pages/
    account_sid = "ACXXXXXXXXXXXXXXXXX"
    auth_token = "YYYYYYYYYYYYYYYYYY"
    host = "XXX.XXX.XXX.XXX"

    @client = Restcomm::REST::Client.new account_sid, auth_token, host
    @msg_sid = 'MM123'
    @msg = @client.messages.get('MM123')
    # Deletes the Body field contents
    @msg.redact

    # Removes the entire Message record
    @msg.delete

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 'restcomm-ruby'

    # To find these visit http://docs.telestax.com/restcomm-pages/
    account_sid = "ACXXXXXXXXXXXXXXXXX"
    auth_token = "YYYYYYYYYYYYYYYYYY"
    host = "XXX.XXX.XXX.XXX"

    @client = Restcomm::REST::Client.new account_sid, auth_token, host

    @messages = @client.messages.list(
      to: "+5466758723",
      date_sent: "2011-01-01"
    )

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