Class: SmsRu

Inherits:
Object
  • Object
show all
Defined in:
lib/sms_ru/client.rb,
lib/sms_ru/my.rb,
lib/sms_ru/auth.rb,
lib/sms_ru/data.rb,
lib/sms_ru/coerce.rb,
lib/sms_ru/errors.rb,
lib/sms_ru/events.rb,
lib/sms_ru/version.rb,
lib/sms_ru/webhook.rb,
lib/sms_ru/statuses.rb,
lib/sms_ru/stoplist.rb,
lib/sms_ru/callbacks.rb,
lib/sms_ru/call_check.rb

Overview

Ruby client for the SMS.ru HTTP API (sms.ru/api).

client = SmsRu.new("YOUR_API_ID")
client.deliver("79991234567", "Hello!")

Defined Under Namespace

Modules: Coerce, DeliveryStatus, Events, MessageCollection, Statuses, Webhook Classes: Auth, AuthError, Call, CallCheck, CallCheckResult, CallCheckStatus, Callbacks, ConnectionError, Cost, CostItem, Error, FreeLimit, InsufficientFundsError, Limit, My, ResponseError, SendResult, Sms, Status, Stoplist, StoplistEntry

Constant Summary collapse

BASE_URL =

Base URL of the SMS.ru HTTP API.

"https://sms.ru"
RETRIABLE =

Transport-level exceptions that warrant a retry.

[
  Net::OpenTimeout, Net::ReadTimeout, IOError, EOFError, SocketError,
  Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, OpenSSL::SSL::SSLError
].freeze
VERSION =

The gem version.

"1.0.0"

Instance Method Summary collapse

Constructor Details

#initialize(api_id, timeout: 30, test: false, retries: 5, from: nil, logger: nil) ⇒ SmsRu

Returns a new instance of SmsRu.

Parameters:

  • api_id (String) —

    your SMS.ru API id

  • timeout (Integer) (defaults to: 30) —

    open/read timeout in seconds

  • test (Boolean) (defaults to: false) —

    when true, every deliver defaults to test mode (no charge)

  • retries (Integer) (defaults to: 5) —

    retry attempts on transport failure (0 disables; PHP default is 5)

  • from (String, nil) (defaults to: nil) —

    default sender name for #deliver (overridable per call)

  • logger (Logger, nil) (defaults to: nil) —

    optional logger; logs the request path and transport failures only — never the api_id, phone numbers, or message text



24
25
26
27
28
29
30
31
 
# File 'lib/sms_ru/client.rb', line 24

def initialize(api_id, timeout: 30, test: false, retries: 5, from: nil, logger: nil)
  @api_id = api_id
  @timeout = timeout
  @test = test
  @retries = retries
  @from = from
  @logger = logger
end

Instance Method Details

#auth ⇒ SmsRu::Auth

Returns the authentication sub-resource.

Returns:



109
 
# File 'lib/sms_ru/client.rb', line 109

def auth = @auth ||= Auth.new(method(:request))

#call(phone, ip: "-1", partner_id: nil) ⇒ SmsRu::Call

Requests a flash-call verification: SMS.ru calls the number; the last 4 digits of the calling number (returned as ‘code`) are the code the user enters.

Parameters:

  • phone (String, Integer) —

    the number to call

  • ip (String) (defaults to: "-1") —

    the end-user IP (anti-fraud); “-1” for manual/local requests

  • partner_id (Integer, nil) (defaults to: nil) —

    partner program id

Returns:

Raises:



101
102
103
 
# File 'lib/sms_ru/client.rb', line 101

def call(phone, ip: "-1", partner_id: nil)
  Call.build(request("/code/call", **{ phone: phone.to_s, ip:, partner_id: }.compact))
end

#callbacks ⇒ SmsRu::Callbacks

Returns the callbacks sub-resource.

Returns:



115
 
# File 'lib/sms_ru/client.rb', line 115

def callbacks = @callbacks ||= Callbacks.new(method(:request))

#callcheck ⇒ SmsRu::CallCheck

Returns the call-check (incoming-call auth) sub-resource.

Returns:



118
 
# File 'lib/sms_ru/client.rb', line 118

def callcheck = @callcheck ||= CallCheck.new(method(:request))

#cost(to, text = nil, translit: false) ⇒ SmsRu::Cost

Returns the cost and SMS count for a message without sending it.

Examples:

client.cost("79991234567", "How much?").total_cost

Parameters:

  • to (String, Array<String>) —

    recipient(s)

  • text (String, nil) (defaults to: nil) —

    the message text (omit for the price of one SMS)

  • translit (Boolean) (defaults to: false) —

    transliterate Cyrillic to Latin

Returns:

Raises:



75
76
77
78
79
80
 
# File 'lib/sms_ru/client.rb', line 75

def cost(to, text = nil, translit: false)
  # @type var params: Hash[Symbol, untyped]
  params = { to: Array(to).join(","), text: text }.compact
  params[:translit] = 1 if translit
  Cost.build(request("/sms/cost", **params))
end

#deliver(to, text = nil, from: nil, time: nil, ttl: nil, daytime: false, translit: false, test: nil, ip: nil, partner_id: nil) ⇒ SmsRu::SendResult

Sends a message.

Examples:

Send one message

client.deliver("79991234567", "Hello!")

Per-number text

client.deliver({ "79991234567" => "Hi Alice", "79991234568" => "Hi Bob" })

Parameters:

  • to (String, Array<String>, Hash{String => String}) —

    recipient(s): a String for one number, an Array for the same text to many numbers, or a Hash of ‘number => text` pairs for a different text per number.

  • text (String, nil) (defaults to: nil) —

    the message text; required for the String/Array forms, must be omitted for the Hash form

  • from (String, nil) (defaults to: nil) —

    an approved sender name

  • time (Integer, nil) (defaults to: nil) —

    schedule the send at this UNIX timestamp

  • ttl (Integer, nil) (defaults to: nil) —

    message lifetime in minutes (1–1440); undelivered messages are discarded after this period

  • daytime (Boolean) (defaults to: false) —

    when true, defer night-time sends to the recipient’s daytime

  • translit (Boolean) (defaults to: false) —

    transliterate Cyrillic to Latin

  • test (Boolean, nil) (defaults to: nil) —

    override the client’s global test mode for this call

  • ip (String, nil) (defaults to: nil) —

    the end-user IP (anti-fraud for auth codes)

  • partner_id (Integer, nil) (defaults to: nil) —

    partner program id

Returns:

Raises:

  • (ArgumentError) —

    if ‘text` is missing (String/Array) or given (Hash)

  • (SmsRu::ResponseError) —

    if SMS.ru rejects the whole request



56
57
58
59
60
61
62
63
64
 
# File 'lib/sms_ru/client.rb', line 56

def deliver(to, text = nil, from: nil, time: nil, ttl: nil, daytime: false,
            translit: false, test: nil, ip: nil, partner_id: nil)
  params = { from: from || @from, time:, ttl:, ip:, partner_id: }.compact
  params[:translit] = 1 if translit
  params[:daytime] = 1 if daytime
  params[:test] = 1 if test.nil? ? @test : test
  add_recipients(params, to, text)
  SendResult.build(request("/sms/send", **params))
end

#my ⇒ SmsRu::My

Returns the account-info sub-resource (balance, limit, free_limit, senders).

Returns:

  • (SmsRu::My) —

    the account-info sub-resource (balance, limit, free_limit, senders)



106
 
# File 'lib/sms_ru/client.rb', line 106

def my = @my ||= My.new(method(:request))

#status(sms_id) ⇒ SmsRu::Status+

Delivery status for one id or an Array of ids.

Parameters:

  • sms_id (String, Array<String>) —

    one message id or an Array of ids

Returns:

Raises:



88
89
90
91
 
# File 'lib/sms_ru/client.rb', line 88

def status(sms_id)
  statuses = Status.build_all(request("/sms/status", sms_id: Array(sms_id).join(",")))
  sms_id.is_a?(Array) ? statuses : statuses.first
end

#stoplist ⇒ SmsRu::Stoplist

Returns the stoplist sub-resource.

Returns:



112
 
# File 'lib/sms_ru/client.rb', line 112

def stoplist = @stoplist ||= Stoplist.new(method(:request))