Telnyx Numbers Config - Ruby

Installation

bash

gem install telnyx

Setup

ruby

require "telnyx"

client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted
)

All examples below assume

client

is already initialized as shown above.

Error Handling

All API calls can fail with network errors, rate limits (429), validation errors (422), or authentication errors (401). Always handle errors in production code:

ruby

begin
  result = client.messages.send_(to: "+13125550001", from: "+13125550002", text: "Hello")
rescue Telnyx::Errors::APIConnectionError
  puts "Network error — check connectivity and retry"
rescue Telnyx::Errors::RateLimitError
  # 429: rate limited — wait and retry with exponential backoff
  sleep(1) # Check Retry-After header for actual delay
rescue Telnyx::Errors::APIStatusError => e
  puts "API error #{e.status}: #{e.message}"
  if e.status == 422
    puts "Validation error — check required fields and formats"
  end
end

Common error codes:

invalid API key,

insufficient permissions,

resource not found,

validation error (check field formats),

rate limited (retry with exponential backoff).

Important Notes

Phone numbers must be in E.164 format (e.g.,
```
+13125550001
```
). Include the
```
+
```
prefix and country code. No spaces, dashes, or parentheses.

Pagination: Use

.auto_paging_each

for automatic iteration:

page.auto_paging_each { |item| puts item.id }

Bulk update phone number profiles

POST /messaging_numbers_bulk_updates

— Required:

messaging_profile_id

numbers

Optional:

assign_only

(boolean)

ruby

messaging_numbers_bulk_update = client.messaging_numbers_bulk_updates.create(
  messaging_profile_id: "00000000-0000-0000-0000-000000000000",
  numbers: ["+18880000000", "+18880000001", "+18880000002"]
)

puts(messaging_numbers_bulk_update)

Returns:

failed

(array[string]),

order_id

(uuid),

pending

(array[string]),

record_type

(enum: messaging_numbers_bulk_update),

success

(array[string])

Retrieve bulk update status

GET /messaging_numbers_bulk_updates/{order_id}

ruby

messaging_numbers_bulk_update = client.messaging_numbers_bulk_updates.retrieve("order_id")

puts(messaging_numbers_bulk_update)

Returns:

failed

(array[string]),

order_id

(uuid),

pending

(array[string]),

record_type

(enum: messaging_numbers_bulk_update),

success

(array[string])

List mobile phone numbers with messaging settings

GET /mobile_phone_numbers/messaging

ruby

page = client.mobile_phone_numbers.messaging.list

puts(page)

Returns:

country_code

(string),

created_at

(date-time),

features

(object),

id

(string),

messaging_product

(string),

messaging_profile_id

(string | null),

organization_id

(string),

phone_number

(string),

record_type

(enum: messaging_phone_number, messaging_settings),

tags

(array[string]),

traffic_type

(string),

type

(enum: longcode),

updated_at

(date-time)

Retrieve a mobile phone number with messaging settings

GET /mobile_phone_numbers/{id}/messaging

ruby

messaging = client.mobile_phone_numbers.messaging.retrieve("550e8400-e29b-41d4-a716-446655440000")

puts(messaging)

Returns:

country_code

(string),

created_at

(date-time),

features

(object),

id

(string),

messaging_product

(string),

messaging_profile_id

(string | null),

organization_id

(string),

phone_number

(string),

record_type

(enum: messaging_phone_number, messaging_settings),

tags

(array[string]),

traffic_type

(string),

type

(enum: longcode),

updated_at

(date-time)

List phone numbers

GET /phone_numbers

ruby

page = client.phone_numbers.list

puts(page)

Returns:

billing_group_id

(string | null),

call_forwarding_enabled

(boolean),

call_recording_enabled

(boolean),

caller_id_name_enabled

(boolean),

cnam_listing_enabled

(boolean),

connection_id

(string | null),

connection_name

(string | null),

country_iso_alpha2

(string),

created_at

(date-time),

customer_reference

(string | null),

deletion_lock_enabled

(boolean),

emergency_address_id

(string | null),

emergency_enabled

(boolean),

emergency_status

(enum: active, deprovisioning, disabled, provisioning, provisioning-failed),

external_pin

(string | null),

hd_voice_enabled

(boolean),

id

(string),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

messaging_profile_id

(string | null),

messaging_profile_name

(string | null),

phone_number

(string),

phone_number_type

(enum: local, toll_free, mobile, national, shared_cost, landline, tollfree, shortcode, longcode),

purchased_at

(string),

record_type

(string),

source_type

(object),

status

(enum: purchase-pending, purchase-failed, port-pending, port-failed, active, deleted, emergency-only, ported-out, port-out-pending, requirement-info-pending, requirement-info-under-review, requirement-info-exception, provision-pending),

t38_fax_gateway_enabled

(boolean),

tags

(array[string]),

updated_at

(string)

Verify ownership of phone numbers

Verifies ownership of the provided phone numbers and returns a mapping of numbers to their IDs, plus a list of numbers not found in the account.

POST /phone_numbers/actions/verify_ownership

— Required:

phone_numbers

ruby

response = client.phone_numbers.actions.verify_ownership(phone_numbers: ["+15551234567"])

puts(response)

Returns:

found

(array[object]),

not_found

(array[string]),

record_type

(string)

Lists the phone numbers jobs

GET /phone_numbers/jobs

ruby

page = client.phone_numbers.jobs.list

puts(page)

Returns:

created_at

(string),

etc

(date-time),

failed_operations

(array[object]),

id

(uuid),

pending_operations

(array[object]),

phone_numbers

(array[object]),

record_type

(string),

status

(enum: pending, in_progress, completed, failed, expired),

successful_operations

(array[object]),

type

(enum: update_emergency_settings, delete_phone_numbers, update_phone_numbers),

updated_at

(string)

Delete a batch of numbers

Creates a new background job to delete a batch of numbers. At most one thousand numbers can be updated per API call.

POST /phone_numbers/jobs/delete_phone_numbers

— Required:

phone_numbers

ruby

response = client.phone_numbers.jobs.delete_batch(phone_numbers: ["+19705555098", "+19715555098", "32873127836"])

puts(response)

Returns:

created_at

(string),

etc

(date-time),

failed_operations

(array[object]),

id

(uuid),

pending_operations

(array[object]),

phone_numbers

(array[object]),

record_type

(string),

status

(enum: pending, in_progress, completed, failed, expired),

successful_operations

(array[object]),

type

(enum: update_emergency_settings, delete_phone_numbers, update_phone_numbers),

updated_at

(string)

Update the emergency settings from a batch of numbers

Creates a background job to update the emergency settings of a collection of phone numbers. At most one thousand numbers can be updated per API call.

POST /phone_numbers/jobs/update_emergency_settings

— Required:

emergency_enabled

phone_numbers

Optional:

emergency_address_id

(string | null)

ruby

response = client.phone_numbers.jobs.update_emergency_settings_batch(
  emergency_enabled: true,
  phone_numbers: ["+19705555098", "+19715555098", "32873127836"]
)

puts(response)

Returns:

created_at

(string),

etc

(date-time),

failed_operations

(array[object]),

id

(uuid),

pending_operations

(array[object]),

phone_numbers

(array[object]),

record_type

(string),

status

(enum: pending, in_progress, completed, failed, expired),

successful_operations

(array[object]),

type

(enum: update_emergency_settings, delete_phone_numbers, update_phone_numbers),

updated_at

(string)

Update a batch of numbers

Creates a new background job to update a batch of numbers. At most one thousand numbers can be updated per API call. At least one of the updateable fields must be submitted.

POST /phone_numbers/jobs/update_phone_numbers

— Required:

phone_numbers

Optional:

billing_group_id

(string),

connection_id

(string),

customer_reference

(string),

deletion_lock_enabled

(boolean),

external_pin

(string),

hd_voice_enabled

(boolean),

tags

(array[string]),

voice

(object)

ruby

response = client.phone_numbers.jobs.update_batch(phone_numbers: ["1583466971586889004", "+13127367254"])

puts(response)

Returns:

created_at

(string),

etc

(date-time),

failed_operations

(array[object]),

id

(uuid),

pending_operations

(array[object]),

phone_numbers

(array[object]),

record_type

(string),

status

(enum: pending, in_progress, completed, failed, expired),

successful_operations

(array[object]),

type

(enum: update_emergency_settings, delete_phone_numbers, update_phone_numbers),

updated_at

(string)

Retrieve a phone numbers job

GET /phone_numbers/jobs/{id}

ruby

job = client.phone_numbers.jobs.retrieve("550e8400-e29b-41d4-a716-446655440000")

puts(job)

Returns:

created_at

(string),

etc

(date-time),

failed_operations

(array[object]),

id

(uuid),

pending_operations

(array[object]),

phone_numbers

(array[object]),

record_type

(string),

status

(enum: pending, in_progress, completed, failed, expired),

successful_operations

(array[object]),

type

(enum: update_emergency_settings, delete_phone_numbers, update_phone_numbers),

updated_at

(string)

List phone numbers with messaging settings

GET /phone_numbers/messaging

ruby

page = client.phone_numbers.messaging.list

puts(page)

Returns:

country_code

(string),

created_at

(date-time),

eligible_messaging_products

(array[string]),

features

(object),

health

(object),

id

(string),

messaging_product

(string),

messaging_profile_id

(string | null),

organization_id

(string),

phone_number

(string),

record_type

(enum: messaging_phone_number, messaging_settings),

tags

(array[string]),

traffic_type

(string),

type

(enum: long-code, toll-free, short-code, longcode, tollfree, shortcode),

updated_at

(date-time)

Slim List phone numbers

List phone numbers, This endpoint is a lighter version of the /phone_numbers endpoint having higher performance and rate limit.

GET /phone_numbers/slim

ruby

page = client.phone_numbers.slim_list

puts(page)

Returns:

billing_group_id

(string),

call_forwarding_enabled

(boolean),

call_recording_enabled

(boolean),

caller_id_name_enabled

(boolean),

cnam_listing_enabled

(boolean),

connection_id

(string),

country_iso_alpha2

(string),

created_at

(string),

customer_reference

(string),

emergency_address_id

(string),

emergency_enabled

(boolean),

emergency_status

(enum: active, deprovisioning, disabled, provisioning, provisioning-failed),

external_pin

(string),

hd_voice_enabled

(boolean),

id

(string),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

phone_number

(string),

phone_number_type

(enum: local, toll_free, mobile, national, shared_cost, landline, tollfree, shortcode, longcode),

purchased_at

(string),

record_type

(string),

status

t38_fax_gateway_enabled

(boolean),

updated_at

(string)

List phone numbers with voice settings

GET /phone_numbers/voice

ruby

page = client.phone_numbers.voice.list

puts(page)

Returns:

call_forwarding

(object),

call_recording

(object),

cnam_listing

(object),

connection_id

(string),

customer_reference

(string),

emergency

(object),

id

(string),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

media_features

(object),

phone_number

(string),

record_type

(string),

tech_prefix_enabled

(boolean),

translated_number

(string),

usage_payment_method

(enum: pay-per-minute, channel)

Retrieve a phone number

GET /phone_numbers/{id}

ruby

phone_number = client.phone_numbers.retrieve("1293384261075731499")

puts(phone_number)

Returns:

billing_group_id

(string | null),

call_forwarding_enabled

(boolean),

call_recording_enabled

(boolean),

caller_id_name_enabled

(boolean),

cnam_listing_enabled

(boolean),

connection_id

(string | null),

connection_name

(string | null),

country_iso_alpha2

(string),

created_at

(date-time),

customer_reference

(string | null),

deletion_lock_enabled

(boolean),

emergency_address_id

(string | null),

emergency_enabled

(boolean),

emergency_status

(enum: active, deprovisioning, disabled, provisioning, provisioning-failed),

external_pin

(string | null),

hd_voice_enabled

(boolean),

id

(string),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

messaging_profile_id

(string | null),

messaging_profile_name

(string | null),

phone_number

(string),

phone_number_type

(enum: local, toll_free, mobile, national, shared_cost, landline, tollfree, shortcode, longcode),

purchased_at

(string),

record_type

(string),

source_type

(object),

status

t38_fax_gateway_enabled

(boolean),

tags

(array[string]),

updated_at

(string)

Update a phone number

PATCH /phone_numbers/{id}

Optional:

address_id

(string),

billing_group_id

(string),

connection_id

(string),

customer_reference

(string),

external_pin

(string),

hd_voice_enabled

(boolean),

id

(string),

tags

(array[string])

ruby

phone_number = client.phone_numbers.update("1293384261075731499")

puts(phone_number)

Returns:

billing_group_id

(string | null),

call_forwarding_enabled

(boolean),

call_recording_enabled

(boolean),

caller_id_name_enabled

(boolean),

cnam_listing_enabled

(boolean),

connection_id

(string | null),

connection_name

(string | null),

country_iso_alpha2

(string),

created_at

(date-time),

customer_reference

(string | null),

deletion_lock_enabled

(boolean),

emergency_address_id

(string | null),

emergency_enabled

(boolean),

emergency_status

(enum: active, deprovisioning, disabled, provisioning, provisioning-failed),

external_pin

(string | null),

hd_voice_enabled

(boolean),

id

(string),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

messaging_profile_id

(string | null),

messaging_profile_name

(string | null),

phone_number

(string),

phone_number_type

(enum: local, toll_free, mobile, national, shared_cost, landline, tollfree, shortcode, longcode),

purchased_at

(string),

record_type

(string),

source_type

(object),

status

t38_fax_gateway_enabled

(boolean),

tags

(array[string]),

updated_at

(string)

Delete a phone number

DELETE /phone_numbers/{id}

ruby

phone_number = client.phone_numbers.delete("1293384261075731499")

puts(phone_number)

Returns:

billing_group_id

(string),

call_forwarding_enabled

(boolean),

call_recording_enabled

(boolean),

caller_id_name_enabled

(boolean),

cnam_listing_enabled

(boolean),

connection_id

(string),

connection_name

(string),

created_at

(string),

customer_reference

(string),

deletion_lock_enabled

(boolean),

emergency_address_id

(string),

emergency_enabled

(boolean),

external_pin

(string),

hd_voice_enabled

(boolean),

id

(string),

messaging_profile_id

(string),

messaging_profile_name

(string),

phone_number

(string),

phone_number_type

(enum: local, toll_free, mobile, national, shared_cost, landline),

purchased_at

(string),

record_type

(string),

status

(enum: purchase-pending, purchase-failed, port-pending, port-failed, active, deleted, emergency-only, ported-out, port-out-pending),

t38_fax_gateway_enabled

(boolean),

tags

(array[string]),

updated_at

(string)

Change the bundle status for a phone number (set to being in a bundle or remove from a bundle)

PATCH /phone_numbers/{id}/actions/bundle_status_change

— Required:

bundle_id

ruby

response = client.phone_numbers.actions.change_bundle_status(
  "1293384261075731499",
  bundle_id: "5194d8fc-87e6-4188-baa9-1c434bbe861b"
)

puts(response)

Returns:

call_forwarding

(object),

call_recording

(object),

cnam_listing

(object),

connection_id

(string),

customer_reference

(string),

emergency

(object),

id

(string),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

media_features

(object),

phone_number

(string),

record_type

(string),

tech_prefix_enabled

(boolean),

translated_number

(string),

usage_payment_method

(enum: pay-per-minute, channel)

Enable emergency for a phone number

POST /phone_numbers/{id}/actions/enable_emergency

— Required:

emergency_enabled

emergency_address_id

ruby

response = client.phone_numbers.actions.enable_emergency(
  "1293384261075731499",
  emergency_address_id: "53829456729313",
  emergency_enabled: true
)

puts(response)

Returns:

call_forwarding

(object),

call_recording

(object),

cnam_listing

(object),

connection_id

(string),

customer_reference

(string),

emergency

(object),

id

(string),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

media_features

(object),

phone_number

(string),

record_type

(string),

tech_prefix_enabled

(boolean),

translated_number

(string),

usage_payment_method

(enum: pay-per-minute, channel)

Retrieve a phone number with messaging settings

GET /phone_numbers/{id}/messaging

ruby

messaging = client.phone_numbers.messaging.retrieve("550e8400-e29b-41d4-a716-446655440000")

puts(messaging)

Returns:

country_code

(string),

created_at

(date-time),

eligible_messaging_products

(array[string]),

features

(object),

health

(object),

id

(string),

messaging_product

(string),

messaging_profile_id

(string | null),

organization_id

(string),

phone_number

(string),

record_type

(enum: messaging_phone_number, messaging_settings),

tags

(array[string]),

traffic_type

(string),

type

(enum: long-code, toll-free, short-code, longcode, tollfree, shortcode),

updated_at

(date-time)

Update the messaging profile and/or messaging product of a phone number

PATCH /phone_numbers/{id}/messaging

Optional:

messaging_product

(string),

messaging_profile_id

(string),

tags

(array[string])

ruby

messaging = client.phone_numbers.messaging.update("550e8400-e29b-41d4-a716-446655440000")

puts(messaging)

Returns:

country_code

(string),

created_at

(date-time),

eligible_messaging_products

(array[string]),

features

(object),

health

(object),

id

(string),

messaging_product

(string),

messaging_profile_id

(string | null),

organization_id

(string),

phone_number

(string),

record_type

(enum: messaging_phone_number, messaging_settings),

tags

(array[string]),

traffic_type

(string),

type

(enum: long-code, toll-free, short-code, longcode, tollfree, shortcode),

updated_at

(date-time)

Retrieve a phone number with voice settings

GET /phone_numbers/{id}/voice

ruby

voice = client.phone_numbers.voice.retrieve("1293384261075731499")

puts(voice)

Returns:

call_forwarding

(object),

call_recording

(object),

cnam_listing

(object),

connection_id

(string),

customer_reference

(string),

emergency

(object),

id

(string),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

media_features

(object),

phone_number

(string),

record_type

(string),

tech_prefix_enabled

(boolean),

translated_number

(string),

usage_payment_method

(enum: pay-per-minute, channel)

Update a phone number with voice settings

PATCH /phone_numbers/{id}/voice

Optional:

call_forwarding

(object),

call_recording

(object),

caller_id_name_enabled

(boolean),

cnam_listing

(object),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

media_features

(object),

tech_prefix_enabled

(boolean),

translated_number

(string),

usage_payment_method

(enum: pay-per-minute, channel)

ruby

voice = client.phone_numbers.voice.update("1293384261075731499")

puts(voice)

Returns:

call_forwarding

(object),

call_recording

(object),

cnam_listing

(object),

connection_id

(string),

customer_reference

(string),

emergency

(object),

id

(string),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

media_features

(object),

phone_number

(string),

record_type

(string),

tech_prefix_enabled

(boolean),

translated_number

(string),

usage_payment_method

(enum: pay-per-minute, channel)

List Mobile Phone Numbers

GET /v2/mobile_phone_numbers

ruby

page = client.mobile_phone_numbers.list

puts(page)

Returns:

call_forwarding

(object),

call_recording

(object),

caller_id_name_enabled

(boolean),

cnam_listing

(object),

connection_id

(string | null),

connection_name

(string | null),

connection_type

(string | null),

country_iso_alpha2

(string),

created_at

(date-time),

customer_reference

(string | null),

id

(string),

inbound

(object),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

mobile_voice_enabled

(boolean),

noise_suppression

(enum: inbound, outbound, both, disabled),

outbound

(object),

phone_number

(string),

record_type

(string),

sim_card_id

(uuid),

status

(string),

tags

(array[string]),

updated_at

(date-time)

Retrieve a Mobile Phone Number

GET /v2/mobile_phone_numbers/{id}

ruby

mobile_phone_number = client.mobile_phone_numbers.retrieve("550e8400-e29b-41d4-a716-446655440000")

puts(mobile_phone_number)

Returns:

call_forwarding

(object),

call_recording

(object),

caller_id_name_enabled

(boolean),

cnam_listing

(object),

connection_id

(string | null),

connection_name

(string | null),

connection_type

(string | null),

country_iso_alpha2

(string),

created_at

(date-time),

customer_reference

(string | null),

id

(string),

inbound

(object),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

mobile_voice_enabled

(boolean),

noise_suppression

(enum: inbound, outbound, both, disabled),

outbound

(object),

phone_number

(string),

record_type

(string),

sim_card_id

(uuid),

status

(string),

tags

(array[string]),

updated_at

(date-time)

Update a Mobile Phone Number

PATCH /v2/mobile_phone_numbers/{id}

Optional:

call_forwarding

(object),

call_recording

(object),

caller_id_name_enabled

(boolean),

cnam_listing

(object),

connection_id

(string | null),

customer_reference

(string | null),

inbound

(object),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

noise_suppression

(boolean),

outbound

(object),

tags

(array[string])

ruby

mobile_phone_number = client.mobile_phone_numbers.update("550e8400-e29b-41d4-a716-446655440000")

puts(mobile_phone_number)

Returns:

call_forwarding

(object),

call_recording

(object),

caller_id_name_enabled

(boolean),

cnam_listing

(object),

connection_id

(string | null),

connection_name

(string | null),

connection_type

(string | null),

country_iso_alpha2

(string),

created_at

(date-time),

customer_reference

(string | null),

id

(string),

inbound

(object),

inbound_call_screening

(enum: disabled, reject_calls, flag_calls),

mobile_voice_enabled

(boolean),

noise_suppression

(enum: inbound, outbound, both, disabled),

outbound

(object),

phone_number

(string),

record_type

(string),

sim_card_id

(uuid),

status

(string),

tags

(array[string]),

updated_at

(date-time)

telnyx-numbers-config-ruby

NPX Install

Tags

SKILL.md Content

Telnyx Numbers Config - Ruby

Installation

Setup

Error Handling

Important Notes

Bulk update phone number profiles

Retrieve bulk update status

List mobile phone numbers with messaging settings

Retrieve a mobile phone number with messaging settings

List phone numbers

Verify ownership of phone numbers

Lists the phone numbers jobs

Delete a batch of numbers

Update the emergency settings from a batch of numbers

Update a batch of numbers

Retrieve a phone numbers job

List phone numbers with messaging settings

Slim List phone numbers

List phone numbers with voice settings

Retrieve a phone number

Update a phone number

Delete a phone number

Change the bundle status for a phone number (set to being in a bundle or remove from a bundle)

Enable emergency for a phone number

Retrieve a phone number with messaging settings

Update the messaging profile and/or messaging product of a phone number

Retrieve a phone number with voice settings

Update a phone number with voice settings

List Mobile Phone Numbers

Retrieve a Mobile Phone Number

Update a Mobile Phone Number