OpenMarket
We use HTTParty to send SMS messages using the OpenMarket API. See USAGE below for details.
Installation
Add this line to your application's Gemfile:
gem 'openmarket'
And then execute:
$ bundle
Or install it yourself as:
$ gem install openmarket
Usage
Configuration
The openmarket gem requires you to provide an id, password, program_id and short_code. Configure them before attempting any API calls.
OpenMarket.configure do |config|
config.id = "000-000-000-00000"
config.password = "Re@llyL0ngR&om$tr1ng"
config.program_id = "ABC"
config.short_code = 99999 # You can override this on an individual message if necessary
end
Since the openmarket gem depends on sms_validation (https://github.com/betesh/sms_validation/), it is also recommended that you configure sms_validation. openmarket uses sms_validation's logger. In a Rails environment, you will probably want to rely on the default configuration, but outside of Rails, you will need to configure it if you want any logging:
SmsValidation.configure do |config|
config.logger = ::Logger.new(STDOUT)
end
API calls
OpenMarket::API
supports 3 API calls: carrier_lookup
, send_sms
, and status
.
carrier_lookup
require 'openmarket'
phone = 2125551212
result = OpenMarket::API.carrier_lookup(phone)
# First, make sure the call succeeded
puts result.code # should be 0
puts result.description # should be 'No Error'
# If the call succeeded, you can check the carrier_id:
puts result.carrier_id # You are probably most interested in the carrier_id
puts result.inspect # But there are a lot of other attributes returned by this API call as well
send_sms
require 'openmarket'
phone = 2125551212
message = "Hello, this is a test of the OpenMarket API"
result = OpenMarket::API.send_sms(phone, message)
# First, make sure the call succeeded
puts result.code # should be 2
puts result.description # should be 'Message received.'
# Save the ticket ID for later. We'll use this to query the status of the ticket.
ticket_id = result.ticket_id
# Save the carrier ID for later. We'll use this next time we send an SMS to this number.
carrier_id = result.carrier_id
# There are some options you can pass along as well:
result = OpenMarket::API.send_sms(
phone,
message,
# If you want to receive DR's, you must pass a dr_url option. If you don't pass a URL, no DR will be sent to the default URL.
dr_url: "http://www.example.com/drs",
# It is highly recommended to pass a carrier_id. If you don't, the openmarket gem will make an extra API call to look up the carrier before sending the message.
carrier_id: carrier_id, # Remember the carrier ID we saved from the previous SMS?
# If you don't want to the short_code you configured above, provide another short_code to send to:
short_code: 33333,
# By default, OpenMarket re-attempts delivery for 3 days. To make OpenMarket give up and report it as a failure sooner, pass a number of minutes you would like to retry for:
minutes_to_retry: 120, # 2 hours
note: "Information that will be passed on to the DR",
ticket_id_for_retry: ticket_id # If this is a re-try of a failed ticket.
)
status
require 'openmarket'
result = OpenMarket::API.status(ticket_id) # Remember the ticket ID we saved from #send_sms?
# First, make sure the call succeeded
puts result.code # should be 0
puts result.description # should be 'No Error'
# Check the result of the SMS message
puts result.status_code
puts result.status_description
Processing MO's
require 'openmarket/mo'
# In a Rails controller or Sinatra app environment, params will be defined
mo = OpenMarket::MO.new(params['xml'])
puts mo.inspect
# Do something with the MO...
# Just send a HTTP 200
render nothing: true # Rails
return [200] # Sinatra
Processing DR's
require 'openmarket/dr'
# In a Rails controller or Sinatra app environment, params will be defined
dr = OpenMarket::DR.new(params['xml'])
puts dr.inspect
# Do something with the DR...
# Just send a HTTP 200
render nothing: true # Rails
return [200] # Sinatra
Contributing
- Fork it ( https://github.com/betesh/open_market/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request