Back to Details

telnyx-account-java

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->
<!-- 由Telnyx OpenAPI规范自动生成，请勿编辑。 -->

Telnyx Account - Java

Telnyx 账户管理 - Java

Installation

安装

text
<!-- Maven -->
<dependency>
    <groupId>com.telnyx.sdk</groupId>
    <artifactId>telnyx</artifactId>
    <version>6.36.0</version>
</dependency>

// Gradle
implementation("com.telnyx.sdk:telnyx:6.36.0")
text
<!-- Maven -->
<dependency>
    <groupId>com.telnyx.sdk</groupId>
    <artifactId>telnyx</artifactId>
    <version>6.36.0</version>
</dependency>

// Gradle
implementation("com.telnyx.sdk:telnyx:6.36.0")

Setup

配置

java
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

TelnyxClient client = TelnyxOkHttpClient.fromEnv();
All examples below assume 
client
is already initialized as shown above.
java
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

TelnyxClient client = TelnyxOkHttpClient.fromEnv();
以下所有示例均假设
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:
java
import com.telnyx.sdk.errors.TelnyxServiceException;

try {
    var result = client.messages().send(params);
} catch (TelnyxServiceException e) {
    System.err.println("API error " + e.statusCode() + ": " + e.getMessage());
    if (e.statusCode() == 422) {
        System.err.println("Validation error — check required fields and formats");
    } else if (e.statusCode() == 429) {
        // Rate limited — wait and retry with exponential backoff
        Thread.sleep(1000);
    }
}
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)。在生产代码中请务必处理错误：
java
import com.telnyx.sdk.errors.TelnyxServiceException;

try {
    var result = client.messages().send(params);
} catch (TelnyxServiceException e) {
    System.err.println("API error " + e.statusCode() + ": " + e.getMessage());
    if (e.statusCode() == 422) {
        System.err.println("Validation error — check required fields and formats");
    } else if (e.statusCode() == 429) {
        // Rate limited — wait and retry with exponential backoff
        Thread.sleep(1000);
    }
}
常见错误码：
401
API密钥无效，
403
权限不足，
404
资源不存在，
422
校验错误（请检查字段格式），
429
触发速率限制（请使用指数退避策略重试）。

Important Notes

重要说明

  • Pagination: List methods return a page. Use 
    .autoPager()
    for automatic iteration: 
    for (var item : page.autoPager()) { ... }
    . For manual control, use 
    .hasNextPage()
    and 
    .nextPage()
    .
  • 分页： 列表方法返回单页数据。使用
    .autoPager()
    可实现自动遍历：
    for (var item : page.autoPager()) { ... }
    。如果需要手动控制，可使用
    .hasNextPage()
    和
    .nextPage()
    方法。

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
java
import com.telnyx.sdk.models.auditevents.AuditEventListPage;
import com.telnyx.sdk.models.auditevents.AuditEventListParams;

AuditEventListPage page = client.auditEvents().list();
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
java
import com.telnyx.sdk.models.auditevents.AuditEventListPage;
import com.telnyx.sdk.models.auditevents.AuditEventListParams;

AuditEventListPage page = client.auditEvents().list();
返回字段：
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
java
import com.telnyx.sdk.models.balance.BalanceRetrieveParams;
import com.telnyx.sdk.models.balance.BalanceRetrieveResponse;

BalanceRetrieveResponse balance = client.balance().retrieve();
Returns: 
available_credit
(string), 
balance
(string), 
credit_limit
(string), 
currency
(string), 
pending
(string), 
record_type
(enum: balance)
GET /balance
java
import com.telnyx.sdk.models.balance.BalanceRetrieveParams;
import com.telnyx.sdk.models.balance.BalanceRetrieveResponse;

BalanceRetrieveResponse balance = client.balance().retrieve();
返回字段：
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
java
import com.telnyx.sdk.models.chargesbreakdown.ChargesBreakdownRetrieveParams;
import com.telnyx.sdk.models.chargesbreakdown.ChargesBreakdownRetrieveResponse;
import java.time.LocalDate;

ChargesBreakdownRetrieveParams params = ChargesBreakdownRetrieveParams.builder()
    .startDate(LocalDate.parse("2025-05-01"))
    .build();
ChargesBreakdownRetrieveResponse chargesBreakdown = client.chargesBreakdown().retrieve(params);
Returns: 
currency
(string), 
end_date
(date), 
results
(array[object]), 
start_date
(date), 
user_email
(email), 
user_id
(string)
查询指定日期范围内电话号码的月度费用详细明细。日期范围不可超过31天。
GET /charges_breakdown
java
import com.telnyx.sdk.models.chargesbreakdown.ChargesBreakdownRetrieveParams;
import com.telnyx.sdk.models.chargesbreakdown.ChargesBreakdownRetrieveResponse;
import java.time.LocalDate;

ChargesBreakdownRetrieveParams params = ChargesBreakdownRetrieveParams.builder()
    .startDate(LocalDate.parse("2025-05-01"))
    .build();
ChargesBreakdownRetrieveResponse chargesBreakdown = client.chargesBreakdown().retrieve(params);
返回字段：
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
java
import com.telnyx.sdk.models.chargessummary.ChargesSummaryRetrieveParams;
import com.telnyx.sdk.models.chargessummary.ChargesSummaryRetrieveResponse;
import java.time.LocalDate;

ChargesSummaryRetrieveParams params = ChargesSummaryRetrieveParams.builder()
    .endDate(LocalDate.parse("2025-06-01"))
    .startDate(LocalDate.parse("2025-05-01"))
    .build();
ChargesSummaryRetrieveResponse chargesSummary = client.chargesSummary().retrieve(params);
Returns: 
currency
(string), 
end_date
(date), 
start_date
(date), 
summary
(object), 
total
(object), 
user_email
(email), 
user_id
(string)
查询指定日期范围内的月度费用汇总。日期范围不可超过31天。
GET /charges_summary
java
import com.telnyx.sdk.models.chargessummary.ChargesSummaryRetrieveParams;
import com.telnyx.sdk.models.chargessummary.ChargesSummaryRetrieveResponse;
import java.time.LocalDate;

ChargesSummaryRetrieveParams params = ChargesSummaryRetrieveParams.builder()
    .endDate(LocalDate.parse("2025-06-01"))
    .startDate(LocalDate.parse("2025-05-01"))
    .build();
ChargesSummaryRetrieveResponse chargesSummary = client.chargesSummary().retrieve(params);
返回字段：
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
java
import com.telnyx.sdk.models.detailrecords.DetailRecordListPage;
import com.telnyx.sdk.models.detailrecords.DetailRecordListParams;

DetailRecordListPage page = client.detailRecords().list();
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
java
import com.telnyx.sdk.models.detailrecords.DetailRecordListPage;
import com.telnyx.sdk.models.detailrecords.DetailRecordListParams;

DetailRecordListPage page = client.detailRecords().list();
返回字段：
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
java
import com.telnyx.sdk.models.invoices.InvoiceListPage;
import com.telnyx.sdk.models.invoices.InvoiceListParams;

InvoiceListPage page = client.invoices().list();
Returns: 
file_id
(uuid), 
invoice_id
(uuid), 
paid
(boolean), 
period_end
(date), 
period_start
(date), 
url
(uri)
获取分页的发票列表。
GET /invoices
java
import com.telnyx.sdk.models.invoices.InvoiceListPage;
import com.telnyx.sdk.models.invoices.InvoiceListParams;

InvoiceListPage page = client.invoices().list();
返回字段：
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}
java
import com.telnyx.sdk.models.invoices.InvoiceRetrieveParams;
import com.telnyx.sdk.models.invoices.InvoiceRetrieveResponse;

InvoiceRetrieveResponse invoice = client.invoices().retrieve("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e");
Returns: 
download_url
(uri), 
file_id
(uuid), 
invoice_id
(uuid), 
paid
(boolean), 
period_end
(date), 
period_start
(date), 
url
(uri)
根据唯一标识符获取单张发票信息。
GET /invoices/{id}
java
import com.telnyx.sdk.models.invoices.InvoiceRetrieveParams;
import com.telnyx.sdk.models.invoices.InvoiceRetrieveResponse;

InvoiceRetrieveResponse invoice = client.invoices().retrieve("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e");
返回字段：
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
java
import com.telnyx.sdk.models.payment.autorechargeprefs.AutoRechargePrefListParams;
import com.telnyx.sdk.models.payment.autorechargeprefs.AutoRechargePrefListResponse;

AutoRechargePrefListResponse autoRechargePrefs = client.payment().autoRechargePrefs().list();
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
java
import com.telnyx.sdk.models.payment.autorechargeprefs.AutoRechargePrefListParams;
import com.telnyx.sdk.models.payment.autorechargeprefs.AutoRechargePrefListResponse;

AutoRechargePrefListResponse autoRechargePrefs = client.payment().autoRechargePrefs().list();
返回字段：
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)
java
import com.telnyx.sdk.models.payment.autorechargeprefs.AutoRechargePrefUpdateParams;
import com.telnyx.sdk.models.payment.autorechargeprefs.AutoRechargePrefUpdateResponse;

AutoRechargePrefUpdateResponse autoRechargePref = client.payment().autoRechargePrefs().update();
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)
java
import com.telnyx.sdk.models.payment.autorechargeprefs.AutoRechargePrefUpdateParams;
import com.telnyx.sdk.models.payment.autorechargeprefs.AutoRechargePrefUpdateResponse;

AutoRechargePrefUpdateResponse autoRechargePref = client.payment().autoRechargePrefs().update();
返回字段：
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
java
import com.telnyx.sdk.models.usertags.UserTagListParams;
import com.telnyx.sdk.models.usertags.UserTagListResponse;

UserTagListResponse userTags = client.userTags().list();
Returns: 
number_tags
(array[string]), 
outbound_profile_tags
(array[string])
查询所有用户标签。
GET /user_tags
java
import com.telnyx.sdk.models.usertags.UserTagListParams;
import com.telnyx.sdk.models.usertags.UserTagListResponse;

UserTagListResponse userTags = client.userTags().list();
返回字段：
number_tags
(array[string]), 
outbound_profile_tags
(array[string])

Create a stored payment transaction

创建预存支付交易

POST /v2/payment/stored_payment_transactions
— Required: 
amount
java
import com.telnyx.sdk.models.payment.PaymentCreateStoredPaymentTransactionParams;
import com.telnyx.sdk.models.payment.PaymentCreateStoredPaymentTransactionResponse;

PaymentCreateStoredPaymentTransactionParams params = PaymentCreateStoredPaymentTransactionParams.builder()
    .amount("120.00")
    .build();
PaymentCreateStoredPaymentTransactionResponse response = client.payment().createStoredPaymentTransaction(params);
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
java
import com.telnyx.sdk.models.payment.PaymentCreateStoredPaymentTransactionParams;
import com.telnyx.sdk.models.payment.PaymentCreateStoredPaymentTransactionResponse;

PaymentCreateStoredPaymentTransactionParams params = PaymentCreateStoredPaymentTransactionParams.builder()
    .amount("120.00")
    .build();
PaymentCreateStoredPaymentTransactionResponse response = client.payment().createStoredPaymentTransaction(params);
返回字段：
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
java
import com.telnyx.sdk.models.webhookdeliveries.WebhookDeliveryListPage;
import com.telnyx.sdk.models.webhookdeliveries.WebhookDeliveryListParams;

WebhookDeliveryListPage page = client.webhookDeliveries().list();
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
java
import com.telnyx.sdk.models.webhookdeliveries.WebhookDeliveryListPage;
import com.telnyx.sdk.models.webhookdeliveries.WebhookDeliveryListParams;

WebhookDeliveryListPage page = client.webhookDeliveries().list();
返回字段：
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}
java
import com.telnyx.sdk.models.webhookdeliveries.WebhookDeliveryRetrieveParams;
import com.telnyx.sdk.models.webhookdeliveries.WebhookDeliveryRetrieveResponse;

WebhookDeliveryRetrieveResponse webhookDelivery = client.webhookDeliveries().retrieve("C9C0797E-901D-4349-A33C-C2C8F31A92C2");
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}
java
import com.telnyx.sdk.models.webhookdeliveries.WebhookDeliveryRetrieveParams;
import com.telnyx.sdk.models.webhookdeliveries.WebhookDeliveryRetrieveResponse;

WebhookDeliveryRetrieveResponse webhookDelivery = client.webhookDeliveries().retrieve("C9C0797E-901D-4349-A33C-C2C8F31A92C2");
返回字段：
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)