Class: Sendly::NumbersResource

Inherits:
Object
  • Object
show all
Defined in:
lib/sendly/numbers_resource.rb

Overview

Numbers resource — search, list, and purchase phone numbers.

Examples:

List supported countries

result = client.numbers.list_countries
result[:countries].each { |c| puts "#{c.code} #{c.name}" }

Find available mobile numbers in the UK

result = client.numbers.list_available(country: "GB", type: "mobile")
number = result[:numbers].first

Buy a number (may pause for a hosted step)

purchase = client.numbers.buy(
  phone_number: number.phone_number,
  country_code: number.country,
  phone_number_type: number.number_type,
  monthly_cost: number.monthly_cost
)
if purchase.documents_required? || purchase.payment_required?
  # Show the user the URL + display code; keep the 32-hex identifier for re-buy
  puts "Visit #{purchase.action_url} and enter code #{purchase.action_code}"
  # ...once they finish, re-call buy with action_code: purchase.action_identifier
end

Instance Method Summary collapse

Constructor Details

#initialize(client) ⇒ NumbersResource

Returns a new instance of NumbersResource.



173
174
175
 
# File 'lib/sendly/numbers_resource.rb', line 173

def initialize(client)
  @client = client
end

Instance Method Details

#buy(phone_number:, country_code:, phone_number_type:, monthly_cost:, action_code: nil) ⇒ NumberPurchase

Buy a number.

Returns a Sendly::NumberPurchase. When its status is documents_required or payment_required, hand the user purchase.action_url + purchase.action_code (the short display code), wait for that hosted step to complete, then re-call buy with the SAME arguments plus action_code: set to purchase.action_identifier (the 32-hex action identifier) — NOT the display code.

Parameters:

  • phone_number (String)
  • country_code (String)
  • phone_number_type (String)
  • monthly_cost (String) —

    Customer-priced monthly cost (as returned by #list_available)

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

    The 32-hex action identifier of a completed hosted action (see Sendly::NumberPurchase#action_identifier), on re-call

Returns:

Raises:



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/sendly/numbers_resource.rb', line 230

def buy(phone_number:, country_code:, phone_number_type:, monthly_cost:, action_code: nil)
  raise ValidationError, "phone_number is required" if phone_number.nil? || phone_number.to_s.empty?
  raise ValidationError, "country_code is required" if country_code.nil? || country_code.to_s.empty?
  raise ValidationError, "phone_number_type is required" if phone_number_type.nil? || phone_number_type.to_s.empty?
  raise ValidationError, "monthly_cost is required" if monthly_cost.nil? || monthly_cost.to_s.empty?

  body = {
    phoneNumber: phone_number,
    countryCode: country_code,
    phoneNumberType: phone_number_type,
    monthlyCost: monthly_cost
  }
  body[:actionCode] = action_code if action_code

  response = @client.post("/numbers/buy", body)
  NumberPurchase.new(response)
end

#list ⇒ Hash

List the numbers owned by the account.

Returns:

  • (Hash) —

    { numbers: Array<PhoneNumber> }



208
209
210
211
212
 
# File 'lib/sendly/numbers_resource.rb', line 208

def list
  response = @client.get("/numbers")
  numbers = (response["numbers"] || []).map { |n| PhoneNumber.new(n) }
  { numbers: numbers }
end

#list_available(country:, type:, contains: nil) ⇒ Hash

Search for numbers available to purchase in a country.

Parameters:

  • country (String) —

    ISO country code (e.g. “GB”)

  • type (String) —

    Number type (e.g. “mobile”, “local”, “toll_free”)

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

    Optional digit/letter filter

Returns:

  • (Hash) —

    { numbers: Array<AvailableNumber> }

Raises:



193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/sendly/numbers_resource.rb', line 193

def list_available(country:, type:, contains: nil)
  raise ValidationError, "country is required" if country.nil? || country.to_s.empty?
  raise ValidationError, "type is required" if type.nil? || type.to_s.empty?

  params = { country: country, type: type }
  params[:contains] = contains if contains

  response = @client.get("/numbers/available", params)
  numbers = (response["numbers"] || []).map { |n| AvailableNumber.new(n) }
  { numbers: numbers }
end

#list_countries ⇒ Hash

List the countries in which numbers can be searched and purchased, along with the number types available in each.

Returns:

  • (Hash) —

    { countries: Array<NumberCountry> }



181
182
183
184
185
 
# File 'lib/sendly/numbers_resource.rb', line 181

def list_countries
  response = @client.get("/numbers/countries")
  countries = (response["countries"] || []).map { |c| NumberCountry.new(c) }
  { countries: countries }
end