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.



230
231
232
 
# File 'lib/sendly/numbers_resource.rb', line 230

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:



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/sendly/numbers_resource.rb', line 287

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

#get(id) ⇒ PhoneNumber

Get a single number owned by the account.

Unlike the entries #list returns, this includes is_default — whether the number is the workspace's default sender.

Parameters:

  • id (String) —

    The number's id

Returns:

Raises:



313
314
315
316
317
318
319
 
# File 'lib/sendly/numbers_resource.rb', line 313

def get(id)
  raise ValidationError, "id is required" if id.nil? || id.to_s.empty?

  encoded_id = URI.encode_www_form_component(id)
  response = @client.get("/numbers/#{encoded_id}")
  PhoneNumber.new(response)
end

#list ⇒ Hash

List the numbers owned by the account.

Returns:

  • (Hash) —

    { numbers: Array<PhoneNumber> }



265
266
267
268
269
 
# File 'lib/sendly/numbers_resource.rb', line 265

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:



250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/sendly/numbers_resource.rb', line 250

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> }



238
239
240
241
242
 
# File 'lib/sendly/numbers_resource.rb', line 238

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

#release(id) ⇒ NumberRelease

Release a number you own. A live paid purchase is cancelled at the end of the paid period (the result then reports scheduled? true with a scheduled_release_at); everything else is released immediately.

Parameters:

  • id (String) —

    The number's id

Returns:

Raises:



359
360
361
362
363
364
365
 
# File 'lib/sendly/numbers_resource.rb', line 359

def release(id)
  raise ValidationError, "id is required" if id.nil? || id.to_s.empty?

  encoded_id = URI.encode_www_form_component(id)
  response = @client.delete("/numbers/#{encoded_id}")
  NumberRelease.new(response)
end

#update(id, is_default: nil, pending_cancellation: nil) ⇒ PhoneNumber

Update a number you own. Supply at least one supported mutation — these are the only two the API supports:

  • is_default: true — make this the workspace's default sending number (the number must be active).
  • pending_cancellation: false — cancel a previously scheduled release and keep the number.

Parameters:

  • id (String) —

    The number's id

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

    Pass true to make this the default sender

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

    Pass false to cancel a scheduled release

Returns:

  • (PhoneNumber) —

    The updated number (including is_default)

Raises:



336
337
338
339
340
341
342
343
344
345
346
347
348
349
 
# File 'lib/sendly/numbers_resource.rb', line 336

def update(id, is_default: nil, pending_cancellation: nil)
  raise ValidationError, "id is required" if id.nil? || id.to_s.empty?
  if is_default.nil? && pending_cancellation.nil?
    raise ValidationError, "Provide is_default: true and/or pending_cancellation: false"
  end

  body = {}
  body[:isDefault] = is_default unless is_default.nil?
  body[:pendingCancellation] = pending_cancellation unless pending_cancellation.nil?

  encoded_id = URI.encode_www_form_component(id)
  response = @client.patch("/numbers/#{encoded_id}", body)
  PhoneNumber.new(response)
end