telnyx-messaging-profiles-javascript

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telnyx Messaging Profiles - JavaScript

Telnyx 消息配置文件 - 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:

invalid API key,

insufficient permissions,

resource not found,

validation error (check field formats),

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('网络错误 — 检查网络连接后重试');
  } else if (err instanceof Telnyx.RateLimitError) {
    // 429: 触发限流 — 等待后使用指数退避策略重试
    const retryAfter = err.headers?.['retry-after'] || 1;
    await new Promise(r => setTimeout(r, retryAfter * 1000));
  } else if (err instanceof Telnyx.APIError) {
    console.error(`API错误 ${err.status}: ${err.message}`);
    if (err.status === 422) {
      console.error('校验错误 — 检查必填字段和格式');
    }
  }
}

常见错误码：

无效API密钥，

权限不足，

资源不存在，

校验错误（检查字段格式），

触发限流（使用指数退避策略重试）。

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 messaging profiles

查询消息配置文件列表

GET /messaging_profiles

javascript

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

Returns:

ai_assistant_id

(string | null),

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

organization_id

(string),

record_type

(enum: messaging_profile),

redaction_enabled

(boolean),

redaction_level

(integer),

resource_group_id

(string | null),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

GET /messaging_profiles

javascript

// 按需自动拉取更多分页内容
for await (const messagingProfile of client.messagingProfiles.list()) {
  console.log(messagingProfile.id);
}

返回参数：

ai_assistant_id

(string | null),

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

organization_id

(string),

record_type

(enum: messaging_profile),

redaction_enabled

(boolean),

redaction_level

(integer),

resource_group_id

(string | null),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

Create a messaging profile

创建消息配置文件

POST /messaging_profiles

— Required:

name

whitelisted_destinations

Optional:

ai_assistant_id

(string | null),

alpha_sender

(string | null),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

number_pool_settings

(object | null),

resource_group_id

(string | null),

smart_encoding

(boolean),

url_shortener_settings

(object | null),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url)

javascript

const messagingProfile = await client.messagingProfiles.create({
  name: 'My name',
  whitelisted_destinations: ['US'],
});

console.log(messagingProfile.data);

Returns:

ai_assistant_id

(string | null),

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

organization_id

(string),

record_type

(enum: messaging_profile),

redaction_enabled

(boolean),

redaction_level

(integer),

resource_group_id

(string | null),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

POST /messaging_profiles

— 必填参数：

name

whitelisted_destinations

可选参数：

ai_assistant_id

(string | null),

alpha_sender

(string | null),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

number_pool_settings

(object | null),

resource_group_id

(string | null),

smart_encoding

(boolean),

url_shortener_settings

(object | null),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url)

javascript

const messagingProfile = await client.messagingProfiles.create({
  name: 'My name',
  whitelisted_destinations: ['US'],
});

console.log(messagingProfile.data);

返回参数：

ai_assistant_id

(string | null),

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

organization_id

(string),

record_type

(enum: messaging_profile),

redaction_enabled

(boolean),

redaction_level

(integer),

resource_group_id

(string | null),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

Retrieve a messaging profile

获取单个消息配置文件

GET /messaging_profiles/{id}

javascript

const messagingProfile = await client.messagingProfiles.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(messagingProfile.data);

Returns:

ai_assistant_id

(string | null),

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

organization_id

(string),

record_type

(enum: messaging_profile),

redaction_enabled

(boolean),

redaction_level

(integer),

resource_group_id

(string | null),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

GET /messaging_profiles/{id}

javascript

const messagingProfile = await client.messagingProfiles.retrieve(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(messagingProfile.data);

返回参数：

ai_assistant_id

(string | null),

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

organization_id

(string),

record_type

(enum: messaging_profile),

redaction_enabled

(boolean),

redaction_level

(integer),

resource_group_id

(string | null),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

Update a messaging profile

更新消息配置文件

PATCH /messaging_profiles/{id}

Optional:

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

record_type

(enum: messaging_profile),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

javascript

const messagingProfile = await client.messagingProfiles.update(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(messagingProfile.data);

Returns:

ai_assistant_id

(string | null),

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

organization_id

(string),

record_type

(enum: messaging_profile),

redaction_enabled

(boolean),

redaction_level

(integer),

resource_group_id

(string | null),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

PATCH /messaging_profiles/{id}

可选参数：

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

record_type

(enum: messaging_profile),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

javascript

const messagingProfile = await client.messagingProfiles.update(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(messagingProfile.data);

返回参数：

ai_assistant_id

(string | null),

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

organization_id

(string),

record_type

(enum: messaging_profile),

redaction_enabled

(boolean),

redaction_level

(integer),

resource_group_id

(string | null),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

Delete a messaging profile

删除消息配置文件

DELETE /messaging_profiles/{id}

javascript

const messagingProfile = await client.messagingProfiles.delete(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(messagingProfile.data);

Returns:

ai_assistant_id

(string | null),

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

organization_id

(string),

record_type

(enum: messaging_profile),

redaction_enabled

(boolean),

redaction_level

(integer),

resource_group_id

(string | null),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

DELETE /messaging_profiles/{id}

javascript

const messagingProfile = await client.messagingProfiles.delete(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
);

console.log(messagingProfile.data);

返回参数：

ai_assistant_id

(string | null),

alpha_sender

(string | null),

created_at

(date-time),

daily_spend_limit

(string),

daily_spend_limit_enabled

(boolean),

enabled

(boolean),

health_webhook_url

(url),

id

(uuid),

mms_fall_back_to_sms

(boolean),

mms_transcoding

(boolean),

mobile_only

(boolean),

name

(string),

number_pool_settings

(object | null),

organization_id

(string),

record_type

(enum: messaging_profile),

redaction_enabled

(boolean),

redaction_level

(integer),

resource_group_id

(string | null),

smart_encoding

(boolean),

updated_at

(date-time),

url_shortener_settings

(object | null),

v1_secret

(string),

webhook_api_version

(enum: 1, 2, 2010-04-01),

webhook_failover_url

(url),

webhook_url

(url),

whitelisted_destinations

(array[string])

List phone numbers associated with a messaging profile

查询消息配置文件关联的手机号列表

GET /messaging_profiles/{id}/phone_numbers

javascript

// Automatically fetches more pages as needed.
for await (const phoneNumberWithMessagingSettings of client.messagingProfiles.listPhoneNumbers(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
)) {
  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)

GET /messaging_profiles/{id}/phone_numbers

javascript

// 按需自动拉取更多分页内容
for await (const phoneNumberWithMessagingSettings of client.messagingProfiles.listPhoneNumbers(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
)) {
  console.log(phoneNumberWithMessagingSettings.id);
}

返回参数：

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)

List short codes associated with a messaging profile

查询消息配置文件关联的短代码列表

GET /messaging_profiles/{id}/short_codes

javascript

// Automatically fetches more pages as needed.
for await (const shortCode of client.messagingProfiles.listShortCodes(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
)) {
  console.log(shortCode.messaging_profile_id);
}

Returns:

country_code

(string),

created_at

(date-time),

id

(uuid),

messaging_profile_id

(string | null),

record_type

(enum: short_code),

short_code

(string),

tags

(array),

updated_at

(date-time)

GET /messaging_profiles/{id}/short_codes

javascript

// 按需自动拉取更多分页内容
for await (const shortCode of client.messagingProfiles.listShortCodes(
  '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
)) {
  console.log(shortCode.messaging_profile_id);
}

返回参数：

country_code

(string),

created_at

(date-time),

id

(uuid),

messaging_profile_id

(string | null),

record_type

(enum: short_code),

short_code

(string),

tags

(array),

updated_at

(date-time)

List short codes

查询短代码列表

GET /short_codes

javascript

// Automatically fetches more pages as needed.
for await (const shortCode of client.shortCodes.list()) {
  console.log(shortCode.messaging_profile_id);
}

Returns:

country_code

(string),

created_at

(date-time),

id

(uuid),

messaging_profile_id

(string | null),

record_type

(enum: short_code),

short_code

(string),

tags

(array),

updated_at

(date-time)

GET /short_codes

javascript

// 按需自动拉取更多分页内容
for await (const shortCode of client.shortCodes.list()) {
  console.log(shortCode.messaging_profile_id);
}

返回参数：

country_code

(string),

created_at

(date-time),

id

(uuid),

messaging_profile_id

(string | null),

record_type

(enum: short_code),

short_code

(string),

tags

(array),

updated_at

(date-time)

Retrieve a short code

获取单个短代码

GET /short_codes/{id}

javascript

const shortCode = await client.shortCodes.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

console.log(shortCode.data);

Returns:

country_code

(string),

created_at

(date-time),

id

(uuid),

messaging_profile_id

(string | null),

record_type

(enum: short_code),

short_code

(string),

tags

(array),

updated_at

(date-time)

GET /short_codes/{id}

javascript

const shortCode = await client.shortCodes.retrieve('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e');

console.log(shortCode.data);

返回参数：

country_code

(string),

created_at

(date-time),

id

(uuid),

messaging_profile_id

(string | null),

record_type

(enum: short_code),

short_code

(string),

tags

(array),

updated_at

(date-time)

Update short code

更新短代码

Update the settings for a specific short code. To unbind a short code from a profile, set the

messaging_profile_id

null

or an empty string. To add or update tags, include the tags field as an array of strings.

PATCH /short_codes/{id}

— Required:

messaging_profile_id

Optional:

tags

(array)

javascript

const shortCode = await client.shortCodes.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
  messaging_profile_id: 'abc85f64-5717-4562-b3fc-2c9600000000',
});

console.log(shortCode.data);

Returns:

country_code

(string),

created_at

(date-time),

id

(uuid),

messaging_profile_id

(string | null),

record_type

(enum: short_code),

short_code

(string),

tags

(array),

updated_at

(date-time)

更新指定短代码的配置。若要将短代码从配置文件解绑，将

messaging_profile_id

设为

null

或空字符串即可。若要新增或更新标签，传入字符串数组格式的tags字段即可。

PATCH /short_codes/{id}

— 必填参数：

messaging_profile_id

可选参数：

tags

(array)

javascript

const shortCode = await client.shortCodes.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', {
  messaging_profile_id: 'abc85f64-5717-4562-b3fc-2c9600000000',
});

console.log(shortCode.data);

返回参数：

country_code

(string),

created_at

(date-time),

id

(uuid),

messaging_profile_id

(string | null),

record_type

(enum: short_code),

short_code

(string),

tags

(array),

updated_at

(date-time)