Project

openmarket

0.0
Repository is archived
No commit activity in last 3 years
No release in over 3 years
Send SMS messages using the OpenMarket API
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Dependencies

Development

~> 1.7
~> 10.0
~> 3

Runtime

 Project Readme

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

  1. Fork it ( https://github.com/betesh/open_market/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request