Back to Details

telnyx-account-ruby

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Account - Ruby

Telnyx 账户 - Ruby

Installation

安装

bash
gem install telnyx
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.
ruby
require "telnyx"

client = Telnyx::Client.new(
  api_key: ENV["TELNYX_API_KEY"], # This is the default and can be omitted
)
以下所有示例均假定
client
已按上述方式初始化完成。

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: 
401
invalid API key, 
403
insufficient permissions, 
404
resource not found, 
422
validation error (check field formats), 
429
rate limited (retry with exponential backoff).
所有API调用都可能因网络错误、速率限制（429）、校验错误（422）或身份认证错误（401）而失败。生产代码中请务必做好错误处理：
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
常见错误码：
401
无效API密钥，
403
权限不足，
404
资源不存在，
422
校验错误（请检查字段格式），
429
速率受限（请使用指数退避策略重试）。

Important Notes

重要说明

  • Pagination: Use 
    .auto_paging_each
    for automatic iteration: 
    page.auto_paging_each { |item| puts item.id }
    .
  • 分页： 使用
    .auto_paging_each
    实现自动遍历：
    page.auto_paging_each { |item| puts item.id }
    。

List Audit Logs

列出审计日志

Retrieve a list of audit log entries. Audit logs are a best-effort, eventually consistent record of significant account-related changes.
GET /audit_events
ruby
page = client.audit_events.list

puts(page)
Returns: 
alternate_resource_id
(string | null), 
change_made_by
(enum: telnyx, account_manager, account_owner, organization_member), 
change_type
(string), 
changes
(array | null), 
created_at
(date-time), 
id
(uuid), 
organization_id
(uuid), 
record_type
(string), 
resource_id
(string), 
user_id
(uuid)
获取审计日志条目列表。审计日志是尽力而为、最终一致的重要账户相关变更记录。
GET /audit_events
ruby
page = client.audit_events.list

puts(page)
返回参数：
alternate_resource_id
(string | null), 
change_made_by
(enum: telnyx, account_manager, account_owner, organization_member), 
change_type
(string), 
changes
(array | null), 
created_at
(date-time), 
id
(uuid), 
organization_id
(uuid), 
record_type
(string), 
resource_id
(string), 
user_id
(uuid)

Get user balance details

获取用户余额详情

GET /balance
ruby
balance = client.balance.retrieve

puts(balance)
Returns: 
available_credit
(string), 
balance
(string), 
credit_limit
(string), 
currency
(string), 
pending
(string), 
record_type
(enum: balance)
GET /balance
ruby
balance = client.balance.retrieve

puts(balance)
返回参数：
available_credit
(string), 
balance
(string), 
credit_limit
(string), 
currency
(string), 
pending
(string), 
record_type
(enum: balance)

Get monthly charges breakdown

获取月度费用明细

Retrieve a detailed breakdown of monthly charges for phone numbers in a specified date range. The date range cannot exceed 31 days.
GET /charges_breakdown
ruby
charges_breakdown = client.charges_breakdown.retrieve(start_date: "2025-05-01")

puts(charges_breakdown)
Returns: 
currency
(string), 
end_date
(date), 
results
(array[object]), 
start_date
(date), 
user_email
(email), 
user_id
(string)
获取指定日期范围内电话号码月度费用的详细拆分。日期范围不得超过31天。
GET /charges_breakdown
ruby
charges_breakdown = client.charges_breakdown.retrieve(start_date: "2025-05-01")

puts(charges_breakdown)
返回参数：
currency
(string), 
end_date
(date), 
results
(array[object]), 
start_date
(date), 
user_email
(email), 
user_id
(string)

Get monthly charges summary

获取月度费用汇总

Retrieve a summary of monthly charges for a specified date range. The date range cannot exceed 31 days.
GET /charges_summary
ruby
charges_summary = client.charges_summary.retrieve(end_date: "2025-06-01", start_date: "2025-05-01")

puts(charges_summary)
Returns: 
currency
(string), 
end_date
(date), 
start_date
(date), 
summary
(object), 
total
(object), 
user_email
(email), 
user_id
(string)
获取指定日期范围内的月度费用汇总。日期范围不得超过31天。
GET /charges_summary
ruby
charges_summary = client.charges_summary.retrieve(end_date: "2025-06-01", start_date: "2025-05-01")

puts(charges_summary)
返回参数：
currency
(string), 
end_date
(date), 
start_date
(date), 
summary
(object), 
total
(object), 
user_email
(email), 
user_id
(string)

Search detail records

搜索明细记录

Search for any detail record across the Telnyx Platform
GET /detail_records
ruby
page = client.detail_records.list

puts(page)
Returns: 
carrier
(string), 
carrier_fee
(string), 
cld
(string), 
cli
(string), 
completed_at
(date-time), 
cost
(string), 
country_code
(string), 
created_at
(date-time), 
currency
(string), 
delivery_status
(string), 
delivery_status_failover_url
(string), 
delivery_status_webhook_url
(string), 
direction
(enum: inbound, outbound), 
errors
(array[string]), 
fteu
(boolean), 
mcc
(string), 
message_type
(enum: SMS, MMS, RCS), 
mnc
(string), 
on_net
(boolean), 
parts
(integer), 
profile_id
(string), 
profile_name
(string), 
rate
(string), 
record_type
(string), 
sent_at
(date-time), 
source_country_code
(string), 
status
(enum: gw_timeout, delivered, dlr_unconfirmed, dlr_timeout, received, gw_reject, failed), 
tags
(string), 
updated_at
(date-time), 
user_id
(string), 
uuid
(string)
搜索Telnyx平台上的所有明细记录
GET /detail_records
ruby
page = client.detail_records.list

puts(page)
返回参数：
carrier
(string), 
carrier_fee
(string), 
cld
(string), 
cli
(string), 
completed_at
(date-time), 
cost
(string), 
country_code
(string), 
created_at
(date-time), 
currency
(string), 
delivery_status
(string), 
delivery_status_failover_url
(string), 
delivery_status_webhook_url
(string), 
direction
(enum: inbound, outbound), 
errors
(array[string]), 
fteu
(boolean), 
mcc
(string), 
message_type
(enum: SMS, MMS, RCS), 
mnc
(string), 
on_net
(boolean), 
parts
(integer), 
profile_id
(string), 
profile_name
(string), 
rate
(string), 
record_type
(string), 
sent_at
(date-time), 
source_country_code
(string), 
status
(enum: gw_timeout, delivered, dlr_unconfirmed, dlr_timeout, received, gw_reject, failed), 
tags
(string), 
updated_at
(date-time), 
user_id
(string), 
uuid
(string)

List invoices

列出发票

Retrieve a paginated list of invoices.
GET /invoices
ruby
page = client.invoices.list

puts(page)
Returns: 
file_id
(uuid), 
invoice_id
(uuid), 
paid
(boolean), 
period_end
(date), 
period_start
(date), 
url
(uri)
获取分页的发票列表。
GET /invoices
ruby
page = client.invoices.list

puts(page)
返回参数：
file_id
(uuid), 
invoice_id
(uuid), 
paid
(boolean), 
period_end
(date), 
period_start
(date), 
url
(uri)

Get invoice by ID

根据ID获取发票

Retrieve a single invoice by its unique identifier.
GET /invoices/{id}
ruby
invoice = client.invoices.retrieve("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(invoice)
Returns: 
download_url
(uri), 
file_id
(uuid), 
invoice_id
(uuid), 
paid
(boolean), 
period_end
(date), 
period_start
(date), 
url
(uri)
通过唯一标识符获取单张发票。
GET /invoices/{id}
ruby
invoice = client.invoices.retrieve("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")

puts(invoice)
返回参数：
download_url
(uri), 
file_id
(uuid), 
invoice_id
(uuid), 
paid
(boolean), 
period_end
(date), 
period_start
(date), 
url
(uri)

List auto recharge preferences

列出自动充值偏好设置

Returns the payment auto recharge preferences.
GET /payment/auto_recharge_prefs
ruby
auto_recharge_prefs = client.payment.auto_recharge_prefs.list

puts(auto_recharge_prefs)
Returns: 
enabled
(boolean), 
id
(string), 
invoice_enabled
(boolean), 
preference
(enum: credit_paypal, ach), 
recharge_amount
(string), 
record_type
(string), 
threshold_amount
(string)
返回支付自动充值的偏好配置。
GET /payment/auto_recharge_prefs
ruby
auto_recharge_prefs = client.payment.auto_recharge_prefs.list

puts(auto_recharge_prefs)
返回参数：
enabled
(boolean), 
id
(string), 
invoice_enabled
(boolean), 
preference
(enum: credit_paypal, ach), 
recharge_amount
(string), 
record_type
(string), 
threshold_amount
(string)

Update auto recharge preferences

更新自动充值偏好设置

Update payment auto recharge preferences.
PATCH /payment/auto_recharge_prefs
Optional: 
enabled
(boolean), 
invoice_enabled
(boolean), 
preference
(enum: credit_paypal, ach), 
recharge_amount
(string), 
threshold_amount
(string)
ruby
auto_recharge_pref = client.payment.auto_recharge_prefs.update

puts(auto_recharge_pref)
Returns: 
enabled
(boolean), 
id
(string), 
invoice_enabled
(boolean), 
preference
(enum: credit_paypal, ach), 
recharge_amount
(string), 
record_type
(string), 
threshold_amount
(string)
更新支付自动充值的偏好配置。
PATCH /payment/auto_recharge_prefs
可选参数：
enabled
(boolean), 
invoice_enabled
(boolean), 
preference
(enum: credit_paypal, ach), 
recharge_amount
(string), 
threshold_amount
(string)
ruby
auto_recharge_pref = client.payment.auto_recharge_prefs.update

puts(auto_recharge_pref)
返回参数：
enabled
(boolean), 
id
(string), 
invoice_enabled
(boolean), 
preference
(enum: credit_paypal, ach), 
recharge_amount
(string), 
record_type
(string), 
threshold_amount
(string)

List User Tags

列出用户标签

List all user tags.
GET /user_tags
ruby
user_tags = client.user_tags.list

puts(user_tags)
Returns: 
number_tags
(array[string]), 
outbound_profile_tags
(array[string])
列出所有用户标签。
GET /user_tags
ruby
user_tags = client.user_tags.list

puts(user_tags)
返回参数：
number_tags
(array[string]), 
outbound_profile_tags
(array[string])

Create a stored payment transaction

创建存储支付交易

POST /v2/payment/stored_payment_transactions
— Required: 
amount
ruby
response = client.payment.create_stored_payment_transaction(amount: "120.00")

puts(response)
Returns: 
amount_cents
(integer), 
amount_currency
(string), 
auto_recharge
(boolean), 
created_at
(date-time), 
id
(string), 
processor_status
(string), 
record_type
(enum: transaction), 
transaction_processing_type
(enum: stored_payment)
POST /v2/payment/stored_payment_transactions
— 必填参数：
amount
ruby
response = client.payment.create_stored_payment_transaction(amount: "120.00")

puts(response)
返回参数：
amount_cents
(integer), 
amount_currency
(string), 
auto_recharge
(boolean), 
created_at
(date-time), 
id
(string), 
processor_status
(string), 
record_type
(enum: transaction), 
transaction_processing_type
(enum: stored_payment)

List webhook deliveries

列出webhook投递记录

Lists webhook_deliveries for the authenticated user
GET /webhook_deliveries
ruby
page = client.webhook_deliveries.list

puts(page)
Returns: 
attempts
(array[object]), 
finished_at
(date-time), 
id
(uuid), 
record_type
(string), 
started_at
(date-time), 
status
(enum: delivered, failed), 
user_id
(uuid), 
webhook
(object)
列出已认证用户的webhook投递记录
GET /webhook_deliveries
ruby
page = client.webhook_deliveries.list

puts(page)
返回参数：
attempts
(array[object]), 
finished_at
(date-time), 
id
(uuid), 
record_type
(string), 
started_at
(date-time), 
status
(enum: delivered, failed), 
user_id
(uuid), 
webhook
(object)

Find webhook_delivery details by ID

根据ID查询webhook投递详情

Provides webhook_delivery debug data, such as timestamps, delivery status and attempts.
GET /webhook_deliveries/{id}
ruby
webhook_delivery = client.webhook_deliveries.retrieve("C9C0797E-901D-4349-A33C-C2C8F31A92C2")

puts(webhook_delivery)
Returns: 
attempts
(array[object]), 
finished_at
(date-time), 
id
(uuid), 
record_type
(string), 
started_at
(date-time), 
status
(enum: delivered, failed), 
user_id
(uuid), 
webhook
(object)
提供webhook投递的调试数据，例如时间戳、投递状态和尝试次数。
GET /webhook_deliveries/{id}
ruby
webhook_delivery = client.webhook_deliveries.retrieve("C9C0797E-901D-4349-A33C-C2C8F31A92C2")

puts(webhook_delivery)
返回参数：
attempts
(array[object]), 
finished_at
(date-time), 
id
(uuid), 
record_type
(string), 
started_at
(date-time), 
status
(enum: delivered, failed), 
user_id
(uuid), 
webhook
(object)