Back to Details

telnyx-account-javascript

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

Telnyx Account - JavaScript

Installation

安装

bash
npm install telnyx
bash
npm install telnyx

Setup

设置

javascript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});
All examples below assume 
client
is already initialized as shown above.
javascript
import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.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:
javascript
try {
  const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: rate limited — wait and retry with exponential backoff
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}
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）而失败。在生产代码中务必处理错误：
javascript
try {
  const result = await client.messages.send({ to: '+13125550001', from: '+13125550002', text: 'Hello' });
} catch (err) {
  if (err instanceof Telnyx.APIConnectionError) {
    console.error('Network error — check connectivity and retry');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: rate limited — wait and retry with exponential backoff
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API error ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('Validation error — check required fields and formats');
    }
  }
}
常见错误码：
401
无效API密钥，
403
权限不足，
404
资源未找到，
422
验证错误（检查字段格式），
429
速率限制（使用指数退避策略重试）。

Important Notes

重要说明

  • Pagination: List methods return an auto-paginating iterator. Use 
    for await (const item of result) { ... }
    to iterate through all pages automatically.
  • 分页： 列表方法会返回一个自动分页的迭代器。使用
    for await (const item of result) { ... }
    可自动遍历所有页面。

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
javascript
// Automatically fetches more pages as needed.
for await (const auditEventListResponse of client.auditEvents.list()) {
  console.log(auditEventListResponse.id);
}
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
javascript
// Automatically fetches more pages as needed.
for await (const auditEventListResponse of client.auditEvents.list()) {
  console.log(auditEventListResponse.id);
}
返回字段：
alternate_resource_id
（字符串 | 空值）、
change_made_by
（枚举值：telnyx、account_manager、account_owner、organization_member）、
change_type
（字符串）、
changes
（数组 | 空值）、
created_at
（日期时间）、
id
（uuid）、
organization_id
（uuid）、
record_type
（字符串）、
resource_id
（字符串）、
user_id
（uuid）

Get user balance details

获取用户余额详情

GET /balance
javascript
const balance = await client.balance.retrieve();

console.log(balance.data);
Returns: 
available_credit
(string), 
balance
(string), 
credit_limit
(string), 
currency
(string), 
pending
(string), 
record_type
(enum: balance)
GET /balance
javascript
const balance = await client.balance.retrieve();

console.log(balance.data);
返回字段：
available_credit
（字符串）、
balance
（字符串）、
credit_limit
（字符串）、
currency
（字符串）、
pending
（字符串）、
record_type
（枚举值：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
javascript
const chargesBreakdown = await client.chargesBreakdown.retrieve({ start_date: '2025-05-01' });

console.log(chargesBreakdown.data);
Returns: 
currency
(string), 
end_date
(date), 
results
(array[object]), 
start_date
(date), 
user_email
(email), 
user_id
(string)
检索指定日期范围内电话号码的月度费用详细明细。日期范围不能超过31天。
GET /charges_breakdown
javascript
const chargesBreakdown = await client.chargesBreakdown.retrieve({ start_date: '2025-05-01' });

console.log(chargesBreakdown.data);
返回字段：
currency
（字符串）、
end_date
（日期）、
results
（对象数组）、
start_date
（日期）、
user_email
（邮箱）、
user_id
（字符串）

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
javascript
const chargesSummary = await client.chargesSummary.retrieve({
  end_date: '2025-06-01',
  start_date: '2025-05-01',
});

console.log(chargesSummary.data);
Returns: 
currency
(string), 
end_date
(date), 
start_date
(date), 
summary
(object), 
total
(object), 
user_email
(email), 
user_id
(string)
检索指定日期范围内的月度费用汇总。日期范围不能超过31天。
GET /charges_summary
javascript
const chargesSummary = await client.chargesSummary.retrieve({
  end_date: '2025-06-01',
  start_date: '2025-05-01',
});

console.log(chargesSummary.data);
返回字段：
currency
（字符串）、
end_date
（日期）、
start_date
（日期）、
summary
（对象）、
total
（对象）、
user_email
（邮箱）、
user_id
（字符串）

Search detail records

搜索明细记录

Search for any detail record across the Telnyx Platform
GET /detail_records
javascript
// Automatically fetches more pages as needed.
for await (const detailRecordListResponse of client.detailRecords.list()) {
  console.log(detailRecordListResponse);
}
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
javascript
// Automatically fetches more pages as needed.
for await (const detailRecordListResponse of client.detailRecords.list()) {
  console.log(detailRecordListResponse);
}
返回字段：
carrier
（字符串）、
carrier_fee
（字符串）、
cld
（字符串）、
cli
（字符串）、
completed_at
（日期时间）、
cost
（字符串）、
country_code
（字符串）、
created_at
（日期时间）、
currency
（字符串）、
delivery_status
（字符串）、
delivery_status_failover_url
（字符串）、
delivery_status_webhook_url
（字符串）、
direction
（枚举值：inbound、outbound）、
errors
（字符串数组）、
fteu
（布尔值）、
mcc
（字符串）、
message_type
（枚举值：SMS、MMS、RCS）、
mnc
（字符串）、
on_net
（布尔值）、
parts
（整数）、
profile_id
（字符串）、
profile_name
（字符串）、
rate
（字符串）、
record_type
（字符串）、
sent_at
（日期时间）、
source_country_code
（字符串）、
status
（枚举值：gw_timeout、delivered、dlr_unconfirmed、dlr_timeout、received、gw_reject、failed）、
tags
（字符串）、
updated_at
（日期时间）、
user_id
（字符串）、
uuid
（字符串）

List invoices

列出发票

Retrieve a paginated list of invoices.
GET /invoices
javascript
// Automatically fetches more pages as needed.
for await (const invoiceListResponse of client.invoices.list()) {
  console.log(invoiceListResponse.file_id);
}
Returns: 
file_id
(uuid), 
invoice_id
(uuid), 
paid
(boolean), 
period_end
(date), 
period_start
(date), 
url
(uri)
检索分页的发票列表。
GET /invoices
javascript
// Automatically fetches more pages as needed.
for await (const invoiceListResponse of client.invoices.list()) {
  console.log(invoiceListResponse.file_id);
}
返回字段：
file_id
（uuid）、
invoice_id
（uuid）、
paid
（布尔值）、
period_end
（日期）、
period_start
（日期）、
url
（uri）

Get invoice by ID

根据ID获取发票

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

console.log(invoice.data);
Returns: 
download_url
(uri), 
file_id
(uuid), 
invoice_id
(uuid), 
paid
(boolean), 
period_end
(date), 
period_start
(date), 
url
(uri)
通过唯一标识符检索单个发票。
GET /invoices/{id}
javascript
const invoice = await client.invoices.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

console.log(invoice.data);
返回字段：
download_url
（uri）、
file_id
（uuid）、
invoice_id
（uuid）、
paid
（布尔值）、
period_end
（日期）、
period_start
（日期）、
url
（uri）

List auto recharge preferences

列出自动充值偏好设置

Returns the payment auto recharge preferences.
GET /payment/auto_recharge_prefs
javascript
const autoRechargePrefs = await client.payment.autoRechargePrefs.list();

console.log(autoRechargePrefs.data);
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
javascript
const autoRechargePrefs = await client.payment.autoRechargePrefs.list();

console.log(autoRechargePrefs.data);
返回字段：
enabled
（布尔值）、
id
（字符串）、
invoice_enabled
（布尔值）、
preference
（枚举值：credit_paypal、ach）、
recharge_amount
（字符串）、
record_type
（字符串）、
threshold_amount
（字符串）

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)
javascript
const autoRechargePref = await client.payment.autoRechargePrefs.update();

console.log(autoRechargePref.data);
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
（布尔值）、
invoice_enabled
（布尔值）、
preference
（枚举值：credit_paypal、ach）、
recharge_amount
（字符串）、
threshold_amount
（字符串）
javascript
const autoRechargePref = await client.payment.autoRechargePrefs.update();

console.log(autoRechargePref.data);
返回字段：
enabled
（布尔值）、
id
（字符串）、
invoice_enabled
（布尔值）、
preference
（枚举值：credit_paypal、ach）、
recharge_amount
（字符串）、
record_type
（字符串）、
threshold_amount
（字符串）

List User Tags

列出用户标签

List all user tags.
GET /user_tags
javascript
const userTags = await client.userTags.list();

console.log(userTags.data);
Returns: 
number_tags
(array[string]), 
outbound_profile_tags
(array[string])
列出所有用户标签。
GET /user_tags
javascript
const userTags = await client.userTags.list();

console.log(userTags.data);
返回字段：
number_tags
（字符串数组）、
outbound_profile_tags
（字符串数组）

Create a stored payment transaction

创建存储支付交易

POST /v2/payment/stored_payment_transactions
— Required: 
amount
javascript
const response = await client.payment.createStoredPaymentTransaction({ amount: '120.00' });

console.log(response.data);
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
javascript
const response = await client.payment.createStoredPaymentTransaction({ amount: '120.00' });

console.log(response.data);
返回字段：
amount_cents
（整数）、
amount_currency
（字符串）、
auto_recharge
（布尔值）、
created_at
（日期时间）、
id
（字符串）、
processor_status
（字符串）、
record_type
（枚举值：transaction）、
transaction_processing_type
（枚举值：stored_payment）

List webhook deliveries

列出Webhook投递记录

Lists webhook_deliveries for the authenticated user
GET /webhook_deliveries
javascript
// Automatically fetches more pages as needed.
for await (const webhookDeliveryListResponse of client.webhookDeliveries.list()) {
  console.log(webhookDeliveryListResponse.id);
}
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
javascript
// Automatically fetches more pages as needed.
for await (const webhookDeliveryListResponse of client.webhookDeliveries.list()) {
  console.log(webhookDeliveryListResponse.id);
}
返回字段：
attempts
（对象数组）、
finished_at
（日期时间）、
id
（uuid）、
record_type
（字符串）、
started_at
（日期时间）、
status
（枚举值：delivered、failed）、
user_id
（uuid）、
webhook
（对象）

Find webhook_delivery details by ID

根据ID查找Webhook投递详情

Provides webhook_delivery debug data, such as timestamps, delivery status and attempts.
GET /webhook_deliveries/{id}
javascript
const webhookDelivery = await client.webhookDeliveries.retrieve(
  'C9C0797E-901D-4349-A33C-C2C8F31A92C2',
);

console.log(webhookDelivery.data);
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}
javascript
const webhookDelivery = await client.webhookDeliveries.retrieve(
  'C9C0797E-901D-4349-A33C-C2C8F31A92C2',
);

console.log(webhookDelivery.data);
返回字段：
attempts
（对象数组）、
finished_at
（日期时间）、
id
（uuid）、
record_type
（字符串）、
started_at
（日期时间）、
status
（枚举值：delivered、failed）、
user_id
（uuid）、
webhook
（对象）