telnyx-account-javascript

Original:🇺🇸 English
Translated

Manage account balance, payments, invoices, webhooks, and view audit logs and detail records. This skill provides JavaScript SDK examples.

59installs
Added on

NPX Install

npx skill4agent add team-telnyx/skills telnyx-account-javascript

Tags

Translated version includes tags in frontmatter
<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Account - JavaScript

Installation

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.

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).

Important Notes

  • Pagination: List methods return an auto-paginating iterator. Use
    for await (const item of result) { ... }
    to iterate through all pages automatically.

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

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)

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)

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 invoice by 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)

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)

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)

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])

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)

List webhook deliveries

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)

Find webhook_delivery details by ID

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)