FreePublished on GitHub

telnyx-numbers-config-javascript

Configure phone number settings including caller ID, call forwarding, messaging enablement, and connection assignments. This skill provides JavaScript SDK examples.

The English summary is being prepared. Showing the original description.

team-telnyx/ai

See how to install

Files included (1)

SKILL.md28.7 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

Telnyx Numbers Config - JavaScript

Installation

npm install telnyx@6.74.2

Setup

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
  publicKey: process.env['TELNYX_PUBLIC_KEY'], // Required for client.webhooks.unwrap() (webhook verification)
});

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:

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, then retry the request (bounded exponential backoff)
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    // ...retry the call here (give up after a few attempts)
  } 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');
    }
  }
  throw err; // Re-throw: a failed request must never look like success to the caller
}

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

Phone numbers must be in E.164 format (e.g., +13125550001). Include the + prefix and country code. No spaces, dashes, or parentheses.
Pagination: List methods return an auto-paginating iterator. Use for await (const item of result) { ... } to iterate through all pages automatically.

Bulk update phone number profiles

Starts a bulk update of messaging-profile assignments for the supplied phone numbers. The response identifies the order used to monitor processing.

POST /messaging_numbers_bulk_updates — Required: messaging_profile_id, numbers

Optional: assign_only (boolean)

const messagingNumbersBulkUpdate = await client.messagingNumbersBulkUpdates.create({
  messaging_profile_id: '00000000-0000-0000-0000-000000000000',
  numbers: ['+18880000000', '+18880000001', '+18880000002'],
});

console.log(messagingNumbersBulkUpdate.data);

Returns: failed (array[string]), order_id (uuid), pending (array[string]), record_type (enum: messaging_numbers_bulk_update), success (array[string])

Retrieve bulk update status

Returns processing status and results for a bulk messaging-settings update order.

GET /messaging_numbers_bulk_updates/{order_id}

const messagingNumbersBulkUpdate = await client.messagingNumbersBulkUpdates.retrieve('order_id');

console.log(messagingNumbersBulkUpdate.data);

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

Returns mobile phone numbers with their current messaging configuration.

GET /mobile_phone_numbers/messaging

// Automatically fetches more pages as needed.
for await (const messagingListResponse of client.mobilePhoneNumbers.messaging.list()) {
  console.log(messagingListResponse.id);
}

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

Returns the messaging configuration for the specified mobile phone number.

GET /mobile_phone_numbers/{id}/messaging

const messaging = await client.mobilePhoneNumbers.messaging.retrieve('550e8400-e29b-41d4-a716-446655440000');

console.log(messaging.data);

List phone numbers

Returns phone numbers associated with the account. Results support pagination, sorting, and filters for number attributes, status, source, connections, billing groups, emergency addresses, tags, and customer references.

GET /phone_numbers

// Automatically fetches more pages as needed.
for await (const phoneNumberDetailed of client.phoneNumbers.list()) {
  console.log(phoneNumberDetailed.id);
}

Returns: activated_at (object), 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_campaign_id (string | null), 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

const response = await client.phoneNumbers.actions.verifyOwnership({
  phone_numbers: ['+15551234567'],
});

console.log(response.data);

Returns: found (array[object]), not_found (array[string]), record_type (string)

Lists the phone numbers jobs

Returns background jobs that operate on phone numbers. Filter by job type, target phone numbers, job status, or creation-time customer reference, and sort by creation time. Multiple phone-number or status values use OR semantics within that filter; different filter categories use AND semantics.

GET /phone_numbers/jobs

// Automatically fetches more pages as needed.
for await (const phoneNumbersJob of client.phoneNumbers.jobs.list()) {
  console.log(phoneNumbersJob.id);
}

Returns: created_at (string), etc (date-time), failed_operations (array[object]), id (uuid), parameters (object), 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

const response = await client.phoneNumbers.jobs.deleteBatch({
  phone_numbers: ['+19705555098', '+19715555098', '32873127836'],
});

console.log(response.data);

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)

const response = await client.phoneNumbers.jobs.updateEmergencySettingsBatch({
  emergency_enabled: true,
  phone_numbers: ['+19705555098', '+19715555098', '32873127836'],
});

console.log(response.data);

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)

const response = await client.phoneNumbers.jobs.updateBatch({
  phone_numbers: ['1583466971586889004', '+13127367254'],
});

console.log(response.data);

Retrieve a phone numbers job

Returns the status and details of the phone-number background job identified by id.

GET /phone_numbers/jobs/{id}

const job = await client.phoneNumbers.jobs.retrieve('550e8400-e29b-41d4-a716-446655440000');

console.log(job.data);

List phone numbers with messaging settings

Returns phone numbers with their current messaging product and messaging-profile assignments.

GET /phone_numbers/messaging

// Automatically fetches more pages as needed.
for await (const phoneNumberWithMessagingSettings of client.phoneNumbers.messaging.list()) {
  console.log(phoneNumberWithMessagingSettings.id);
}

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

// Automatically fetches more pages as needed.
for await (const phoneNumberSlimListResponse of client.phoneNumbers.slimList()) {
  console.log(phoneNumberSlimListResponse.id);
}

Returns: activated_at (object), 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 (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), updated_at (string)

List phone numbers with voice settings

Returns account phone numbers together with their voice settings. Results support pagination, sorting, and filters for number, connection name, customer reference, and voice usage payment method.

GET /phone_numbers/voice

// Automatically fetches more pages as needed.
for await (const phoneNumberWithVoiceSettings of client.phoneNumbers.voice.list()) {
  console.log(phoneNumberWithVoiceSettings.id);
}

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

Returns the detailed configuration and current state of the phone number identified by id.

GET /phone_numbers/{id}

const phoneNumber = await client.phoneNumbers.retrieve('1293384261075731499');

console.log(phoneNumber.data);

Update a phone number

Updates the configurable settings of the specified phone number. The response contains the complete updated phone-number representation.

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

const phoneNumber = await client.phoneNumbers.update('1293384261075731499');

console.log(phoneNumber.data);

Delete a phone number

Deletes the specified phone number from the account. The response contains the phone number's final deleted representation.

DELETE /phone_numbers/{id}

const phoneNumber = await client.phoneNumbers.delete('1293384261075731499');

console.log(phoneNumber.data);

Returns: activated_at (object), 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)

Adds the specified phone number to a bundle or removes it from a bundle according to the requested status change. The response contains the phone number with its updated bundle state.

PATCH /phone_numbers/{id}/actions/bundle_status_change — Required: bundle_id

const response = await client.phoneNumbers.actions.changeBundleStatus('1293384261075731499', {
  bundle_id: '5194d8fc-87e6-4188-baa9-1c434bbe861b',
});

console.log(response.data);

Enable emergency for a phone number

Associates emergency-service settings with the specified phone number. The operation returns the updated phone-number configuration when completed immediately or an accepted state when processing continues asynchronously.

POST /phone_numbers/{id}/actions/enable_emergency — Required: emergency_enabled, emergency_address_id

const response = await client.phoneNumbers.actions.enableEmergency('1293384261075731499', {
  emergency_address_id: '53829456729313',
  emergency_enabled: true,
});

console.log(response.data);

Retrieve a phone number with messaging settings

Returns the messaging product and messaging-profile assignment for the specified phone number.

GET /phone_numbers/{id}/messaging

const messaging = await client.phoneNumbers.messaging.retrieve('550e8400-e29b-41d4-a716-446655440000');

console.log(messaging.data);

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

Updates the messaging product, messaging profile, or both for the specified phone number.

PATCH /phone_numbers/{id}/messaging

Optional: messaging_product (string), messaging_profile_id (string), tags (array[string])

const messaging = await client.phoneNumbers.messaging.update('550e8400-e29b-41d4-a716-446655440000');

console.log(messaging.data);

Retrieve a phone number with voice settings

Returns the specified phone number together with its current voice configuration.

GET /phone_numbers/{id}/voice

const voice = await client.phoneNumbers.voice.retrieve('1293384261075731499');

console.log(voice.data);

Update a phone number with voice settings

Updates the voice configuration for the specified phone number. The response contains the phone number with its updated 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)

const voice = await client.phoneNumbers.voice.update('1293384261075731499');

console.log(voice.data);

List Mobile Phone Numbers

Retrieve a paginated list of mobile phone numbers on your account.

GET /v2/mobile_phone_numbers

// Automatically fetches more pages as needed.
for await (const mobilePhoneNumber of client.mobilePhoneNumbers.list()) {
  console.log(mobilePhoneNumber.id);
}

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

Retrieve the details of a specific mobile phone number.

GET /v2/mobile_phone_numbers/{id}

const mobilePhoneNumber = await client.mobilePhoneNumbers.retrieve('550e8400-e29b-41d4-a716-446655440000');

console.log(mobilePhoneNumber.data);

Update a Mobile Phone Number

Update the settings of a specific 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])

const mobilePhoneNumber = await client.mobilePhoneNumbers.update('550e8400-e29b-41d4-a716-446655440000');

console.log(mobilePhoneNumber.data);

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

More skills from this repository

push-notification-tester

Free

Test VoIP push notifications for Telnyx WebRTC iOS (APNs) and Android (FCM) apps. Use when debugging push notification delivery, validating certificate/credential setup, or testing that a device receives VoIP pushes correctly.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

telnyx-10dlc-curl

Free

10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

telnyx-10dlc-go

Free

10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

telnyx-10dlc-java

Free

10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

telnyx-10dlc-javascript

Free

10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

telnyx-10dlc-python

Free

10DLC brand and campaign registration for US A2P messaging compliance. Assign phone numbers to campaigns.

The English summary is being prepared. Showing the original description.

team-telnyx/ai222Updated Oct 21, 2026

See all skills by team-telnyx

Report a problem with this skill

Install

Install with a command

npx skills add https://github.com/team-telnyx/ai --skill telnyx-numbers-config-javascript

Paste it into your terminal and run it (requires Node.js). You can choose which agents to install it for, such as Claude Code or Codex.

Ask your agent

Please install the following Agent Skill.
https://github.com/team-telnyx/ai/tree/main/skills/telnyx-numbers-config-javascript

First review SKILL.md and the bundled files and confirm there is nothing suspicious (such as sending data externally or reading credentials). Then place it in ~/.claude/skills/telnyx-numbers-config-javascript/ for Claude Code, or ~/.agents/skills/telnyx-numbers-config-javascript/ for Codex.

Send this text to Claude Code or Codex as is. It checks the contents before installing.

View source on GitHub

Repository: team-telnyx/ai
Stars: 222
Forks: 24
Category: Development
License: MIT
Original language: English
Last updated: Oct 21, 2026

A skill is a set of instructions and scripts for an agent. cccskills does not guarantee that skills are safe. Review the contents before you install.