class TextMagic::API

Public Class Methods

new(username, password) click to toggle source

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")
# File lib/textmagic/api.rb, line 16
def initialize(username, password)
  @username = username
  @password = password
end

Public Instance Methods

account() click to toggle source

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
# File lib/textmagic/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) click to toggle source

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"])
# File lib/textmagic/api.rb, line 237
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
Also aliased as: check
delete(*ids)
Alias for: delete_reply
delete_reply(*ids) click to toggle source

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"])
# File lib/textmagic/api.rb, line 194
def delete_reply(*ids)
  ids.flatten!
  raise TextMagic::API::Error.new(4, "Insufficient parameters") if ids.empty?
  Executor.execute("delete_reply", @username, @password, ids: ids.join(","))
  true
end
Also aliased as: delete
message_status(*ids) click to toggle source

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.

# File lib/textmagic/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
Also aliased as: status
receive(last_retrieved_id = nil) click to toggle source

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.

# File lib/textmagic/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) click to toggle source

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)
# File lib/textmagic/api.rb, line 81
def send(text, *args)
  raise Error.new(1, "Message text is empty") unless text
  options = args.last.is_a?(Hash) ? args.pop : {}
  unicode = API.is_unicode(text)
  options[:unicode] = case options[:unicode]
  when 1, true then 1
  when 0, false then 0
  when nil then 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].zero?
  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