TextMagic::API

new(username, password)

Creates new API instance with specified credentials. These will be used in all requests to the TextMagic SMS gateway done through this instance. Multiple instances with different credentials can be used at the same time.

Example usage:

  api = TextMagic::API.new('fred', 'secret')

Source: show | on GitHub

# File lib/api.rb, line 16
    def initialize(username, password)
      @username = username
      @password = password
    end

account()

Executes an account command by sending a request to the TextMagic’s SMS gateway.

This method returns an object with balance attribute. In case the request to the SMS gateway is not successful or the server returns an error response, an Error is raised.

Example usage:

 api.account.balance
 # => 314.15

Source: show | on GitHub

# File lib/api.rb, line 32
    def account
      hash = Executor.execute('account', @username, @password)
      TextMagic::API::Response.account(hash)
    end

check(*phones)

Alias for check_number

check_number(*phones)

Executes a check_number command by sending a request to the TextMagic’s SMS gateway.

If called with a single phone number, this method returns an OpenStruct instance with credit price and country code for the given phone number. If called with multiple phone numbers, the method returns a hash of such instances with phone numbers as keys. In case the request to the SMS gateway is not successful or the server returns an error response, an Error is raised.

Example usage:

 check = api.check_number('447624800500')
 check.price
 # => 0.8
 check.country
 # => 'GB'

Example with multiple phone numbers:

 check = api.check_number('447624800500', '61428102137')
 check['447624800500'].price
 # => 0.8
 check['61428102137'].country
 # => 'AU'

Multiple phone number can be supplied as an array or as a list of arguments:

 api.check_number(['447624800500', '61428102137'])
 api.check_number('447624800500', '61428102137')

If you want to check a single phone number but still want to get a hash response, put the number in an array:

 api.check_number(['447624800500'])

This method is also aliased as check

Source: show | on GitHub

# File lib/api.rb, line 238
    def check_number(*phones)
      single = phones.size == 1 && phones.first.is_a?(String)
      phones.flatten!
      raise TextMagic::API::Error.new(4, 'Insufficient parameters') if phones.empty?
      hash = Executor.execute('check_number', @username, @password, :phone => phones.join(','))
      TextMagic::API::Response.check_number(hash, single)
    end

delete(*ids)

Alias for delete_reply

delete_reply(*ids)

Executes a delete_reply command by sending a request to the TextMagic’s SMS gateway.

This method always returns true. In case the request to the SMS gateway is not successful or the server returns an error response, an Error is raised.

Example usage:

 api.delete_reply('141421')
 api.delete_reply('173205', '223606')
 api.delete_reply(['244948', '264575'])

This method is also aliased as delete

Source: show | on GitHub

# File lib/api.rb, line 194
    def delete_reply(*ids)
      single = ids.size == 1 && ids.first.is_a?(String)
      ids.flatten!
      raise TextMagic::API::Error.new(4, 'Insufficient parameters') if ids.empty?
      Executor.execute('delete_reply', @username, @password, :ids => ids.join(','))
      true
    end

message_status(*ids)

Executes a message_status command by sending a request to the TextMagic’s SMS gateway.

If called with a single id, this method returns a single string value denoting the message status. This string is extended with custom attributes text, status, created_time, completed_time, reply_number and credits_cost. If called with multiple ids, it returns a hash of such strings with message ids as keys. In case the request to the SMS gateway is not successful or the server returns an error response, an Error is raised.

Example usage:

 status = api.message_status('141421')
 # => 'd'
 status.completed_time
 # => Fri May 22 10:10:18 +0200 2009

Example with multiple ids:

 statuses = api.message_status('141421', '173205')
 # => { '141421' => 'r', '173205' => 'd' }
 statuses['141421'].text
 # => 'Hi Wilma'
 statuses['173205'].created_time
 # => Thu May 28 16:41:45 +0200 2009

Multiple ids can be supplied as an array or as a list of arguments:

 api.send('Hello everybody', ['999314159265', '999271828182'])
 api.send('Hello everybody', '999314159265', '999271828182')

If you want to request status for a single message but still want to get a hash response, put the id in an array:

 api.message_status(['141421'])

It is strongly encouraged to setup callbacks to receive updates on message status instead of using this method.

This method is also aliased as status

Source: show | on GitHub

# File lib/api.rb, line 140
    def message_status(*ids)
      single = ids.size == 1 && ids.first.is_a?(String)
      ids.flatten!
      raise TextMagic::API::Error.new(4, 'Insufficient parameters') if ids.empty?
      hash = Executor.execute('message_status', @username, @password, :ids => ids.join(','))
      TextMagic::API::Response.message_status(hash, single)
    end

receive(last_retrieved_id = nil)

Executes a receive command by sending a request to the TextMagic’s SMS gateway.

This method returnes an array with retrieved messages. Every member of the array is a string with from, text, timestamp and message_id attributes. The value of every string contains a phone number and text. In case the request to the SMS gateway is not successful or the server returns an error response, an Error is raised.

This method accepts an optional last_retrieved_id value. If called with this argument, the gateway will only return replies newer than the one with specified id.

Example usage:

 replies = api.receive
 # => ['999271828182: Hello Fred', '999314159265: Good day']
 replies.first.text
 # => 'Hello Fred'
 replies.first.from
 # => '999314159265'
 replies.last.message_id
 # => '223606'
 api.receive '223606'
 # => []

It is strongly encouraged to setup callbacks to receive replies instead of using this method.

Source: show | on GitHub

# File lib/api.rb, line 177
    def receive(last_retrieved_id = nil)
      hash = Executor.execute('receive', @username, @password, :last_retrieved_id => last_retrieved_id)
      TextMagic::API::Response.receive(hash)
    end

send(text, *args)

Executes a send command by sending a request to the TextMagic’s SMS gateway.

If called with a single phone number, this method returns a string message id. If called with multiple phone numbers, it will return an hash of message ids with phone numbers as keys. In both cases the returned object is extended with sent_text and parts_count attributes. In case the request to the SMS gateway is not successful or the server returns an error response, an Error is raised.

The optional parameters you can specify in the options Hash are:

unicode: accepted values are true, false, 0 and 1. If not specified, the method will determine the unicode value based on the characters in the text.
max_length: accepted values are nil, 1, 2 and 3, defaults to nil. If not specified, the SMS gateway will apply its own default value.
send_time: allows you to postpone sending of the message. Note that the message will be sent to the SMS gateway immediately and will wait there until the specified time. You can either supply a numeric value denoting number of seconds since 1.1.1970, or a Time object.

Example usage:

 api.send('Hi Wilma', '999314159265')
 # => '141421'
 response = api.send('Hello everybody', '999314159265', '999271828182', :max_length => 2)
 # => { '999314159265' => '141421', '999271828182' => '173205' }
 response.parts_count
 # => 1

Multiple phone numbers can be supplied as an array or as a list of arguments:

 api.send('Hello everybody', ['999314159265', '999271828182'])
 api.send('Hello everybody', '999314159265', '999271828182')

If you want to send a message to a single phone number but still want to get a hash response, put the phone number in an array:

 api.send('Hi Barney', ['999271828182'])

Postponed sending:

 api.send('Two hours later', '999314159265', :send_time => Time.now.to_i + 7200)

Source: show | on GitHub

# File lib/api.rb, line 81
    def send(text, *args)
      raise Error.new(1, 'Message text is empty') if text.nil? || text.blank?
      options = args.last.is_a?(Hash) ? args.pop : {}
      unicode = API.is_unicode(text)
      options[:unicode] = case options[:unicode]
      when 1, true: 1
      when 0, false: 0
      when nil: unicode ? 1 : 0
      else raise Error.new(10, "Wrong parameter value #{options[:unicode]} for parameter unicode")
      end
      raise Error.new(6, 'Message contains invalid characters') if unicode && options[:unicode] == 0
      raise Error.new(7, 'Message too long') unless API.validate_text_length(text, unicode)
      single = args.size == 1 && args.first.is_a?(String)
      phones = args.flatten
      raise Error.new(9, 'Invalid phone number format') unless API.validate_phones(phones)
      options[:send_time] = options[:send_time].to_i if options[:send_time]
      hash = Executor.execute('send', @username, @password, options.merge(:text => text, :phone => phones.join(',')))
      TextMagic::API::Response.send(hash, single)
    end

status(*ids)

Alias for message_status

Class TextMagic::API < Object