ActieSmsc
This gem implements SMSC service API and based on this library: https://smsc.ru/api/code/libraries/http_smtp/ruby/
Installation
Add this line to your application's Gemfile:
gem 'actie_smsc'
And then execute:
$ bundle
Or install it yourself as:
$ gem install actie_smsc
Configuration
To change the configuration, create the file config/initializers/actie_smsc.rb
in your project. Like shown in example:
ActieSmsc.configure do |config|
config.login = ENV.fetch('SMSC_LOGIN')
config.password = ENV.fetch('SMSC_PASSWORD')
config.charset = 'windows-1251'
end
There are two required parameters: login
and password
.
The full parameters list for configuration with default values:
use_post = true # Use POST request instead of GET
use_https = true # Use HTTPS request instead of HTTP
charset = 'utf-8' # valid charsets are: utf-8, koi8-r and windows-1251
debug = false
logger = Logger.new($stdout)
Usage
There are four public methods for different API endpoints. Each method returns a result hash, or number (balance). In case of invalid response SmscError
will be raised with error code in message.
Send sms
ActieSmsc.send_sms(phones, message, translit: 0, time: nil, id: 0, format: nil, sender: nil, fmt: 1, query_params: {})
The required parameters are: phones
- array or string separated by commas and message
as string. Other parameters have default values and described in SMSC library.
- translit - transliterate message text. Values:1,2 or 0
- time - delivery time (could be a
Time, Date, DateTime
object, or a string). There are several string formats: +m (e.g.+10
) - Send the message 10 minutes later. h1-h2 (e.g.9-20
) - Message can be sent only in the period from 9 am to 20 pm. If it's too late, it'll be sent next day. DDMMYYhhmm - string format for the exact time, it's also used for a Time object. 0ts (e.g.01568230028
) - UNIX time format with a0
as a prefix. - id - message id. Value - integer from 1 to 2147483647.
- format - message format. Values: [:flash, :push, :hlr, :bin, :bin_hex, :ping, :mms, :mail, :call, :viber, :soc]
- sender - Sender name. To disable default name use empty line, or '.'
- query - hash with additional parameters which will be added to the request (e.g.
{ valid: '01:00', maxsms: 3, tz: 2 }
)
Method returns result hash:
{ id: 7600, cnt: 1, cost: 12.32, balance: 1234.12 }
Sms cost
ActieSmsc.sms_cost(phones, message, translit: 0, format: nil, sender: nil, fmt: 1, query_params: {})
This method checks the message cost. It receives the same parameters as send_sms
method.
Returns the result hash:
{ cost: 12.32, cnt: 2 }
Status
ActieSmsc.status(id, phone, all: false, fmt: 1)
Returns the delivery status for exact message and exact phone. Receives the message ID and phone number. The additional parameter all
used to increase the number of returned values.
Returns the result hash:
{ status: 1, change_time: 2019-09-08 15:00:00 +0300, error_code: 0 }
If parameter all
changed to true
, result hash will additionaly include values:
{
send_time: 2019-09-08 15:00:00 +0300,
phone: '+71234567890',
cost: 2.12,
sender: 'GLOBUS',
status_message: 'Доставлено',
message: 'Текст собщения'
}
Balance
ActieSmsc.balance(fmt: 1)
This method returns the balance of your SMSC account as float number.
Response format
There is poorly described parameter fmt
which changes the response format. (You can find description here: https://smsc.ru/api/http/send/sms/).
The default value is 1 - it returns the string with numbers, which then parsed to the result hash.
2 - is an XML response, returned as a string.
3 - json response, returned as parsed hash.
0 - another form of string response (OK - 1 SMS, ID - 1234)
.
Formats 2 and 3 are usefull for the debugging. Because you can find more detaild error descriptions:
{"error"=>"duplicate request, wait a minute", "error_code"=>9}
Additionaly you can use fmt: :response
to get the full Faraday::Response
object.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/actie/actie_smsc. T
License
The gem is available as open source under the terms of the MIT License.