Numbers

Order a number, read its SMS, close it — client.numbers.

An operation (tzid) is one ordered number. Order it with get/get_with_number, read the SMS with state_one or wait_code, finish it with close (or ban). Countries are phone codes (7, 44, …), services are slugs (google, vkcom, …) as returned by tariffs.

price

Price of one number, USD; nil when the country has no price for the service.

price(service, country = 7) # => Float or nil
ParamTypeDefaultDescription
serviceString—Service slug.
countryInteger7Country code.
usd = client.numbers.price("google", 44)

Errors: ApiError ERROR_NO_SERVICE, UNDEFINED_COUNTRY.

get

Order a number; returns the operation id. Freezes the price on the balance.

get(service, country = 7, reject: nil) # => Integer (tzid)
ParamTypeDefaultDescription
serviceString—Service slug.
countryInteger7Country code.
reject:Arrayprofile listNumber prefixes to skip, e.g. ["4470"].
tzid = client.numbers.get("google", 44, reject: ["4470"])

Errors: NoNumberError; ApiError WARNING_LOW_BALANCE, ERROR_NO_SERVICE, UNDEFINED_COUNTRY, EXCEEDED_CONCURRENT_OPERATIONS, INTERVAL_CONCURRENT_REQUESTS_ERROR, TRY_AGAIN_LATER.

get_with_number

Same as get, but returns the number right away.

get_with_number(service, country = 7, reject: nil) # => Hash

Returns {"tzid", "number", "country", "time", "service", "title"?, "guard_interval_remaining_seconds"?} — number with +, time in seconds left.

order = client.numbers.get_with_number("google", 44)
puts order["number"]

Errors: as get.

state

All operations of the account; [] when there are none.

state(message_to_code: true, order_by: "asc", msg_list: false) # => Array of Hash
OptionTypeDefaultDescription
message_to_code:Booleantruemsg is the code only; false — the full SMS text.
order_by:"asc", "desc""asc"Order of operations.
msg_list:Booleanfalsemsg is a list of all SMS ([{"service", "msg"}]).

An operation: {"tzid", "response", "number"?, "service"?, "country"?, "sum"?, "time"?, "msg"?, "guard_interval_remaining_seconds"?, …}. response is the state: TZ_INPOOL (number being assigned), TZ_NUM_WAIT (waiting for SMS), TZ_NUM_ANSWER (SMS arrived), TZ_OVER_OK (finished), ERROR_NO_ITEMS (failed). msg is absent until the first SMS. The server caches answers for a few seconds.

client.numbers.state(order_by: "desc").each do |op|
  puts [op["tzid"], op["response"], op["msg"]].join(" ")
end

state_one

One operation.

state_one(tzid, message_to_code: true, msg_list: false) # => Hash
op = client.numbers.state_one(tzid)
puts op["msg"] if op["response"] == "TZ_NUM_ANSWER"

Errors: ApiError ERROR_NO_OPERATIONS when the operation does not exist (any more).

wait_code

Poll the operation until a code arrives, then close it and return the code.

wait_code(tzid, interval: 5, timeout: 600, keep_open: false, full_message: false, since: nil) # => String
OptionTypeDefaultDescription
interval:Numeric5Poll interval, seconds.
timeout:Numeric600Give up after, seconds.
keep_open:BooleanfalseCall next(tzid) instead of close(tzid), to wait for another SMS.
full_message:BooleanfalseReturn the full SMS text instead of the code.
since:String, nilnilIgnore this value (the previous code).
sleep:, now:callablesKernel#sleep, monotonic clockInjectable for tests (seconds).

Transient errors are retried until the timeout: TransportError, and ApiError TRY_AGAIN_LATER (the HTTP 429 rate limit), ERROR_UNDEFINED and INTERVAL_CONCURRENT_REQUESTS_ERROR. Any other ApiError is raised at once. Also available as OnlineSim.wait_code(numbers, tzid, **options).

first = client.numbers.wait_code(tzid, keep_open: true)
second = client.numbers.wait_code(tzid, since: first)

Errors: TimeoutError; ApiError with code TZ_OVER_OK or ERROR_NO_ITEMS when the operation ended without a new code; any other ApiError from state_one/close/next.

next

Switch the operation to its next SMS and keep it open (for services that send several SMS).

next(tzid) # => true
client.numbers.next(tzid)

Errors: ApiError ERROR_WRONG_TZID (not an operation of your account), ERROR_NO_TZID.

close

Finish the operation. An operation without SMS can be closed only after its guard interval (guard_interval_remaining_seconds); every attempt locks the tzid for 5 s.

close(tzid) # => true
client.numbers.close(tzid)

Errors: ApiError NO_COMPLETE_TZID, INTERVAL_CONCURRENT_REQUESTS_ERROR, ERROR_WRONG_TZID.

ban

Finish the operation and report the number as bad. Only before any SMS arrived.

ban(tzid) # => true
client.numbers.ban(tzid)

Errors: as close; ApiError with code "0" when the operation already has an SMS — nothing is changed then.

tariffs

Services, prices and stock of every country, keyed by country code (a String). No API key needed. The answer is large (a few MB); prefer tariffs_one.

tariffs # => Hash of country code => Hash

A country: {"name", "locale_name"?, "position", "code", "other"?, "new", "enabled", "services"}; services maps service_<slug> to {"count", "popular", "code", "price", "id", "service", "slug"}.

all = client.numbers.tariffs
puts "#{all.size} countries"

tariffs_one

Services, prices and stock of one country.

tariffs_one(country = 7) # => Hash
uk = client.numbers.tariffs_one(44)
uk["services"].each_value { |s| puts [s["slug"], s["price"], s["count"]].join(" ") }

Errors: ApiError NO_COUNTRY.