telnyx-messaging-java

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Telnyx Messaging - 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.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;
MessageSendParams params = MessageSendParams.builder()
    .to("+18445550001")
    .from("+18005550101")
    .text("Hello from Telnyx!")
    .build();
MessageSendResponse response = client.messages().send(params);

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）而失败，生产环境代码务必添加错误处理逻辑：

java

import com.telnyx.sdk.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;
MessageSendParams params = MessageSendParams.builder()
    .to("+18445550001")
    .from("+18005550101")
    .text("Hello from Telnyx!")
    .build();
MessageSendResponse response = client.messages().send(params);

常见错误码：

API密钥无效，

权限不足，

资源不存在，

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

请求被限流（请使用指数退避策略重试）。

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 a page. Use
```
.autoPager()
```
for automatic iteration:
```
for (var item : page.autoPager()) { ... }
```
. For manual control, use
```
.hasNextPage()
```
and
```
.nextPage()
```
.

电话号码必须遵循E.164格式（例如
```
+13125550001
```
），需包含
```
+
```
前缀和国家代码，不得包含空格、短横线或括号。
分页： 列表类方法返回单页数据，可使用
```
.autoPager()
```
实现自动遍历：
```
for (var item : page.autoPager()) { ... }
```
；如需手动控制分页，可使用
```
.hasNextPage()
```
和
```
.nextPage()
```
方法。

Operational Caveats

使用限制说明

The sending number must already be assigned to the correct messaging profile before you send traffic from it.
US A2P long-code traffic must complete 10DLC registration before production sending or carriers will block or heavily filter messages.
Delivery webhooks are asynchronous. Treat the send response as acceptance of the request, not final carrier delivery.

发送消息前，发送号码必须已关联到正确的消息配置文件。
美国A2P长码消息需完成10DLC注册后才可在生产环境发送，否则运营商会拦截或过滤消息。
投递状态Webhook为异步触发，发送接口的响应仅代表请求已被接收，不代表运营商已完成最终投递。

Reference Use Rules

参考使用规则

Do not invent Telnyx parameters, enums, response fields, or webhook fields.

If the parameter, enum, or response field you need is not shown inline in this skill, read references/api-details.md before writing code.
Before using any operation in
```
## Additional Operations
```
, read the optional-parameters section and the response-schemas section.
Before reading or matching webhook fields beyond the inline examples, read the webhook payload reference.

请勿自行编造Telnyx的参数、枚举值、响应字段或Webhook字段。

若本文档未列出你需要的参数、枚举值或响应字段，编写代码前请先阅读references/api-details.md。
使用
```
## 其他操作
```
中的接口前，请先阅读可选参数章节和响应结构章节。
如需使用文档示例外的Webhook字段，请先阅读Webhook payload参考。

Core Tasks

核心功能

Send an SMS

发送SMS

Primary outbound messaging flow. Agents need exact request fields and delivery-related response fields.

client.messages().send()

—

POST /messages

Parameter	Type	Required	Description
`to`	string (E.164)	Yes	Receiving address (+E.164 formatted phone number or short co...
`from`	string (E.164)	Yes	Sending address (+E.164 formatted phone number, alphanumeric...
`text`	string	Yes	Message body (i.e., content) as a non-empty string.
`messagingProfileId`	string (UUID)	No	Unique identifier for a messaging profile.
`mediaUrls`	array[string]	No	A list of media URLs.
`webhookUrl`	string (URL)	No	The URL where webhooks related to this message will be sent.
...			+7 optional params in references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;

MessageSendParams params = MessageSendParams.builder()
    .to("+18445550001")
    .from("+18005550101")

    .text("Hello from Telnyx!")
    .build();
MessageSendResponse response = client.messages().send(params);

Primary response fields:

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.text
```
```
response.data.sentAt
```
```
response.data.errors
```

核心外发消息流程，Agent需要明确请求字段和投递相关的响应字段。

client.messages().send()

—

POST /messages

参数	类型	必填	说明
`to`	string (E.164)	是	接收方地址（符合+E.164格式的手机号或短码...）
`from`	string (E.164)	是	发送方地址（符合+E.164格式的手机号、字母数字发送ID...）
`text`	string	是	消息内容，不能为空字符串
`messagingProfileId`	string (UUID)	否	消息配置文件的唯一标识
`mediaUrls`	array[string]	否	媒体资源URL列表
`webhookUrl`	string (URL)	否	接收该消息相关Webhook事件的URL
...			还有7个可选参数见references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageSendParams;
import com.telnyx.sdk.models.messages.MessageSendResponse;

MessageSendParams params = MessageSendParams.builder()
    .to("+18445550001")
    .from("+18005550101")

    .text("Hello from Telnyx!")
    .build();
MessageSendResponse response = client.messages().send(params);

核心响应字段：

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.text
```
```
response.data.sentAt
```
```
response.data.errors
```

Send an SMS with an alphanumeric sender ID

使用字母数字发送ID发送SMS

Common sender variant that requires different request shape.

client.messages().sendWithAlphanumericSender()

—

POST /messages/alphanumeric_sender_id

Parameter	Type	Required	Description
`from`	string (E.164)	Yes	A valid alphanumeric sender ID on the user's account.
`to`	string (E.164)	Yes	Receiving address (+E.164 formatted phone number or short co...
`text`	string	Yes	The message body.
`messagingProfileId`	string (UUID)	Yes	The messaging profile ID to use.
`webhookUrl`	string (URL)	No	Callback URL for delivery status updates.
`webhookFailoverUrl`	string (URL)	No	Failover callback URL for delivery status updates.
`useProfileWebhooks`	boolean	No	If true, use the messaging profile's webhook settings.

java

import com.telnyx.sdk.models.messages.MessageSendWithAlphanumericSenderParams;
import com.telnyx.sdk.models.messages.MessageSendWithAlphanumericSenderResponse;

MessageSendWithAlphanumericSenderParams params = MessageSendWithAlphanumericSenderParams.builder()
    .from("MyCompany")
    .messagingProfileId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
    .text("Hello from Telnyx!")
    .to("+13125550001")
    .build();
MessageSendWithAlphanumericSenderResponse response = client.messages().sendWithAlphanumericSender(params);

Primary response fields:

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.text
```
```
response.data.sentAt
```
```
response.data.errors
```

常见的发送方变体，请求结构和普通发送不同。

client.messages().sendWithAlphanumericSender()

—

POST /messages/alphanumeric_sender_id

参数	类型	必填	说明
`from`	string (E.164)	是	用户账户下有效的字母数字发送ID
`to`	string (E.164)	是	接收方地址（符合+E.164格式的手机号或短码...）
`text`	string	是	消息内容
`messagingProfileId`	string (UUID)	是	要使用的消息配置文件ID
`webhookUrl`	string (URL)	否	接收投递状态更新的回调URL
`webhookFailoverUrl`	string (URL)	否	接收投递状态更新的备用回调URL
`useProfileWebhooks`	boolean	否	设为true则使用消息配置文件的Webhook设置

java

import com.telnyx.sdk.models.messages.MessageSendWithAlphanumericSenderParams;
import com.telnyx.sdk.models.messages.MessageSendWithAlphanumericSenderResponse;

MessageSendWithAlphanumericSenderParams params = MessageSendWithAlphanumericSenderParams.builder()
    .from("MyCompany")
    .messagingProfileId("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e")
    .text("Hello from Telnyx!")
    .to("+13125550001")
    .build();
MessageSendWithAlphanumericSenderResponse response = client.messages().sendWithAlphanumericSender(params);

核心响应字段：

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.text
```
```
response.data.sentAt
```
```
response.data.errors
```

Webhook Verification

Webhook验签

Telnyx signs webhooks with Ed25519. Each request includes

telnyx-signature-ed25519

and

telnyx-timestamp

headers. Always verify signatures in production:

java

import com.telnyx.sdk.core.UnwrapWebhookParams;
import com.telnyx.sdk.core.http.Headers;

// In your webhook handler (e.g., Spring — use raw body):
@PostMapping("/webhooks")
public ResponseEntity<String> handleWebhook(
    @RequestBody String payload,
    HttpServletRequest request) {
  try {
    Headers headers = Headers.builder()
        .put("telnyx-signature-ed25519", request.getHeader("telnyx-signature-ed25519"))
        .put("telnyx-timestamp", request.getHeader("telnyx-timestamp"))
        .build();
    var event = client.webhooks().unwrap(
        UnwrapWebhookParams.builder()
            .body(payload)
            .headers(headers)
            .build());
    // Signature valid — process the event
    System.out.println("Received webhook event");
    return ResponseEntity.ok("OK");
  } catch (Exception e) {
    System.err.println("Webhook verification failed: " + e.getMessage());
    return ResponseEntity.badRequest().body("Invalid signature");
  }
}

Telnyx使用Ed25519对Webhook进行签名，每个请求都会携带

telnyx-signature-ed25519

和

telnyx-timestamp

请求头，生产环境务必验证签名：

java

import com.telnyx.sdk.core.UnwrapWebhookParams;
import com.telnyx.sdk.core.http.Headers;

// 在你的Webhook处理器中（例如Spring，请使用原始请求体）：
@PostMapping("/webhooks")
public ResponseEntity<String> handleWebhook(
    @RequestBody String payload,
    HttpServletRequest request) {
  try {
    Headers headers = Headers.builder()
        .put("telnyx-signature-ed25519", request.getHeader("telnyx-signature-ed25519"))
        .put("telnyx-timestamp", request.getHeader("telnyx-timestamp"))
        .build();
    var event = client.webhooks().unwrap(
        UnwrapWebhookParams.builder()
            .body(payload)
            .headers(headers)
            .build());
    // 签名有效，处理事件
    System.out.println("Received webhook event");
    return ResponseEntity.ok("OK");
  } catch (Exception e) {
    System.err.println("Webhook verification failed: " + e.getMessage());
    return ResponseEntity.badRequest().body("Invalid signature");
  }
}

Webhooks

Webhook说明

These webhook payload fields are inline because they are part of the primary integration path.

以下是核心集成流程中用到的Webhook payload字段。

Delivery Update

投递状态更新

Field	Type	Description
`data.event_type`	enum: message.sent, message.finalized	The type of event being delivered.
`data.payload.id`	uuid	Identifies the type of resource.
`data.payload.to`	array[object]
`data.payload.text`	string	Message body (i.e., content) as a non-empty string.
`data.payload.sent_at`	date-time	ISO 8601 formatted date indicating when the message was sent.
`data.payload.completed_at`	date-time	ISO 8601 formatted date indicating when the message was finalized.
`data.payload.cost`	object \| null
`data.payload.errors`	array[object]	These errors may point at addressees when referring to unsuccessful/unconfirm...

字段	类型	说明
`data.event_type`	枚举: message.sent, message.finalized	事件类型
`data.payload.id`	uuid	资源唯一标识
`data.payload.to`	array[object]	收件人信息
`data.payload.text`	string	消息内容，不能为空字符串
`data.payload.sent_at`	date-time	消息发送时间，ISO 8601格式
`data.payload.completed_at`	date-time	消息最终状态确认时间，ISO 8601格式
`data.payload.cost`	object \| null	消息费用
`data.payload.errors`	array[object]	投递失败相关的错误信息

Inbound Message

入站消息

Field	Type	Description
`data.event_type`	enum: message.received	The type of event being delivered.
`data.payload.id`	uuid	Identifies the type of resource.
`data.payload.direction`	enum: inbound	The direction of the message.
`data.payload.to`	array[object]
`data.payload.text`	string	Message body (i.e., content) as a non-empty string.
`data.payload.type`	enum: SMS, MMS	The type of message.
`data.payload.media`	array[object]
`data.record_type`	enum: event	Identifies the type of the resource.

If you need webhook fields that are not listed inline here, read the webhook payload reference before writing the handler.

字段	类型	说明
`data.event_type`	枚举: message.received	事件类型
`data.payload.id`	uuid	资源唯一标识
`data.payload.direction`	枚举: inbound	消息方向
`data.payload.to`	array[object]	收件人信息
`data.payload.text`	string	消息内容，不能为空字符串
`data.payload.type`	枚举: SMS, MMS	消息类型
`data.payload.media`	array[object]	媒体资源信息
`data.record_type`	枚举: event	资源类型

如果你需要使用本文档未列出的Webhook字段，编写处理器前请先阅读Webhook payload参考。

Important Supporting Operations

重要扩展功能

Use these when the core tasks above are close to your flow, but you need a common variation or follow-up step.

当核心功能接近你的业务需求，但需要常见变体或后续操作时可使用以下功能。

Send a group MMS message

发送群组MMS消息

Send one MMS payload to multiple recipients.

client.messages().sendGroupMms()

—

POST /messages/group_mms

Parameter	Type	Required	Description
`from`	string (E.164)	Yes	Phone number, in +E.164 format, used to send the message.
`to`	array[object]	Yes	A list of destinations.
`mediaUrls`	array[string]	No	A list of media URLs.
`webhookUrl`	string (URL)	No	The URL where webhooks related to this message will be sent.
`webhookFailoverUrl`	string (URL)	No	The failover URL where webhooks related to this message will...
...			+3 optional params in references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageSendGroupMmsParams;
import com.telnyx.sdk.models.messages.MessageSendGroupMmsResponse;

MessageSendGroupMmsParams params = MessageSendGroupMmsParams.builder()
    .from("+13125551234")
    .addTo("+18655551234")
    .addTo("+14155551234")
    .text("Hello from Telnyx!")
    .build();
MessageSendGroupMmsResponse response = client.messages().sendGroupMms(params);

Primary response fields:

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.text
```

发送同一份MMS内容给多个收件人。

client.messages().sendGroupMms()

—

POST /messages/group_mms

参数	类型	必填	说明
`from`	string (E.164)	是	发送方号码，符合+E.164格式
`to`	array[object]	是	收件人列表
`mediaUrls`	array[string]	否	媒体资源URL列表
`webhookUrl`	string (URL)	否	接收该消息相关Webhook事件的URL
`webhookFailoverUrl`	string (URL)	否	接收该消息相关Webhook事件的备用URL
...			还有3个可选参数见references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageSendGroupMmsParams;
import com.telnyx.sdk.models.messages.MessageSendGroupMmsResponse;

MessageSendGroupMmsParams params = MessageSendGroupMmsParams.builder()
    .from("+13125551234")
    .addTo("+18655551234")
    .addTo("+14155551234")
    .text("Hello from Telnyx!")
    .build();
MessageSendGroupMmsResponse response = client.messages().sendGroupMms(params);

核心响应字段：

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.text
```

Send a long code message

发送长码消息

Force a long-code sending path instead of the generic send endpoint.

client.messages().sendLongCode()

—

POST /messages/long_code

Parameter	Type	Required	Description
`from`	string (E.164)	Yes	Phone number, in +E.164 format, used to send the message.
`to`	string (E.164)	Yes	Receiving address (+E.164 formatted phone number or short co...
`mediaUrls`	array[string]	No	A list of media URLs.
`webhookUrl`	string (URL)	No	The URL where webhooks related to this message will be sent.
`webhookFailoverUrl`	string (URL)	No	The failover URL where webhooks related to this message will...
...			+6 optional params in references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageSendLongCodeParams;
import com.telnyx.sdk.models.messages.MessageSendLongCodeResponse;

MessageSendLongCodeParams params = MessageSendLongCodeParams.builder()
    .from("+18445550001")
    .to("+13125550002")
    .text("Hello from Telnyx!")
    .build();
MessageSendLongCodeResponse response = client.messages().sendLongCode(params);

Primary response fields:

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.text
```

强制使用长码发送路径，而非通用发送接口。

client.messages().sendLongCode()

—

POST /messages/long_code

参数	类型	必填	说明
`from`	string (E.164)	是	发送方号码，符合+E.164格式
`to`	string (E.164)	是	接收方地址（符合+E.164格式的手机号或短码...）
`mediaUrls`	array[string]	否	媒体资源URL列表
`webhookUrl`	string (URL)	否	接收该消息相关Webhook事件的URL
`webhookFailoverUrl`	string (URL)	否	接收该消息相关Webhook事件的备用URL
...			还有6个可选参数见references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageSendLongCodeParams;
import com.telnyx.sdk.models.messages.MessageSendLongCodeResponse;

MessageSendLongCodeParams params = MessageSendLongCodeParams.builder()
    .from("+18445550001")
    .to("+13125550002")
    .text("Hello from Telnyx!")
    .build();
MessageSendLongCodeResponse response = client.messages().sendLongCode(params);

核心响应字段：

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.text
```

Send a message using number pool

使用号码池发送消息

Let a messaging profile or number pool choose the sender for you.

client.messages().sendNumberPool()

—

POST /messages/number_pool

Parameter	Type	Required	Description
`messagingProfileId`	string (UUID)	Yes	Unique identifier for a messaging profile.
`to`	string (E.164)	Yes	Receiving address (+E.164 formatted phone number or short co...
`mediaUrls`	array[string]	No	A list of media URLs.
`webhookUrl`	string (URL)	No	The URL where webhooks related to this message will be sent.
`webhookFailoverUrl`	string (URL)	No	The failover URL where webhooks related to this message will...
...			+6 optional params in references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageSendNumberPoolParams;
import com.telnyx.sdk.models.messages.MessageSendNumberPoolResponse;

MessageSendNumberPoolParams params = MessageSendNumberPoolParams.builder()
    .messagingProfileId("abc85f64-5717-4562-b3fc-2c9600000000")
    .to("+13125550002")
    .text("Hello from Telnyx!")
    .build();
MessageSendNumberPoolResponse response = client.messages().sendNumberPool(params);

Primary response fields:

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.text
```

由消息配置文件或号码池自动选择发送方号码。

client.messages().sendNumberPool()

—

POST /messages/number_pool

参数	类型	必填	说明
`messagingProfileId`	string (UUID)	是	消息配置文件的唯一标识
`to`	string (E.164)	是	接收方地址（符合+E.164格式的手机号或短码...）
`mediaUrls`	array[string]	否	媒体资源URL列表
`webhookUrl`	string (URL)	否	接收该消息相关Webhook事件的URL
`webhookFailoverUrl`	string (URL)	否	接收该消息相关Webhook事件的备用URL
...			还有6个可选参数见references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageSendNumberPoolParams;
import com.telnyx.sdk.models.messages.MessageSendNumberPoolResponse;

MessageSendNumberPoolParams params = MessageSendNumberPoolParams.builder()
    .messagingProfileId("abc85f64-5717-4562-b3fc-2c9600000000")
    .to("+13125550002")
    .text("Hello from Telnyx!")
    .build();
MessageSendNumberPoolResponse response = client.messages().sendNumberPool(params);

核心响应字段：

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.text
```

Send a short code message

发送短码消息

Force a short-code sending path when the sender must be a short code.

client.messages().sendShortCode()

—

POST /messages/short_code

Parameter	Type	Required	Description
`from`	string (E.164)	Yes	Phone number, in +E.164 format, used to send the message.
`to`	string (E.164)	Yes	Receiving address (+E.164 formatted phone number or short co...
`mediaUrls`	array[string]	No	A list of media URLs.
`webhookUrl`	string (URL)	No	The URL where webhooks related to this message will be sent.
`webhookFailoverUrl`	string (URL)	No	The failover URL where webhooks related to this message will...
...			+6 optional params in references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageSendShortCodeParams;
import com.telnyx.sdk.models.messages.MessageSendShortCodeResponse;

MessageSendShortCodeParams params = MessageSendShortCodeParams.builder()
    .from("+18445550001")
    .to("+18445550001")
    .text("Hello from Telnyx!")
    .build();
MessageSendShortCodeResponse response = client.messages().sendShortCode(params);

Primary response fields:

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.text
```

强制使用短码发送路径，要求发送方为短码号码。

client.messages().sendShortCode()

—

POST /messages/short_code

参数	类型	必填	说明
`from`	string (E.164)	是	发送方号码，符合+E.164格式
`to`	string (E.164)	是	接收方地址（符合+E.164格式的手机号或短码...）
`mediaUrls`	array[string]	否	媒体资源URL列表
`webhookUrl`	string (URL)	否	接收该消息相关Webhook事件的URL
`webhookFailoverUrl`	string (URL)	否	接收该消息相关Webhook事件的备用URL
...			还有6个可选参数见references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageSendShortCodeParams;
import com.telnyx.sdk.models.messages.MessageSendShortCodeResponse;

MessageSendShortCodeParams params = MessageSendShortCodeParams.builder()
    .from("+18445550001")
    .to("+18445550001")
    .text("Hello from Telnyx!")
    .build();
MessageSendShortCodeResponse response = client.messages().sendShortCode(params);

核心响应字段：

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.text
```

Schedule a message

定时发送消息

Queue a message for future delivery instead of sending immediately.

client.messages().schedule()

—

POST /messages/schedule

Parameter	Type	Required	Description
`to`	string (E.164)	Yes	Receiving address (+E.164 formatted phone number or short co...
`messagingProfileId`	string (UUID)	No	Unique identifier for a messaging profile.
`mediaUrls`	array[string]	No	A list of media URLs.
`webhookUrl`	string (URL)	No	The URL where webhooks related to this message will be sent.
...			+8 optional params in references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageScheduleParams;
import com.telnyx.sdk.models.messages.MessageScheduleResponse;

MessageScheduleParams params = MessageScheduleParams.builder()
    .to("+18445550001")
    .from("+18005550101")

    .text("Appointment reminder")

    .sendAt("2025-07-01T15:00:00Z")
    .build();
MessageScheduleResponse response = client.messages().schedule(params);

Primary response fields:

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.text
```

将消息加入队列，在指定时间发送而非立即发送。

client.messages().schedule()

—

POST /messages/schedule

参数	类型	必填	说明
`to`	string (E.164)	是	接收方地址（符合+E.164格式的手机号或短码...）
`messagingProfileId`	string (UUID)	否	消息配置文件的唯一标识
`mediaUrls`	array[string]	否	媒体资源URL列表
`webhookUrl`	string (URL)	否	接收该消息相关Webhook事件的URL
...			还有8个可选参数见references/api-details.md

java

import com.telnyx.sdk.models.messages.MessageScheduleParams;
import com.telnyx.sdk.models.messages.MessageScheduleResponse;

MessageScheduleParams params = MessageScheduleParams.builder()
    .to("+18445550001")
    .from("+18005550101")

    .text("Appointment reminder")

    .sendAt("2025-07-01T15:00:00Z")
    .build();
MessageScheduleResponse response = client.messages().schedule(params);

核心响应字段：

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.text
```

Send a WhatsApp message

发送WhatsApp消息

Send WhatsApp traffic instead of SMS/MMS.

client.messages().sendWhatsapp()

—

POST /messages/whatsapp

Parameter	Type	Required	Description
`from`	string (E.164)	Yes	Phone number in +E.164 format associated with Whatsapp accou...
`to`	string (E.164)	Yes	Phone number in +E.164 format
`whatsappMessage`	object	Yes
`type`	enum (WHATSAPP)	No	Message type - must be set to "WHATSAPP"
`webhookUrl`	string (URL)	No	The URL where webhooks related to this message will be sent.

java

import com.telnyx.sdk.models.messages.MessageSendWhatsappParams;
import com.telnyx.sdk.models.messages.MessageSendWhatsappResponse;
import com.telnyx.sdk.models.messages.WhatsappMessageContent;

MessageSendWhatsappParams params = MessageSendWhatsappParams.builder()
    .from("+13125551234")
    .to("+13125551234")
    .whatsappMessage(WhatsappMessageContent.builder().build())
    .build();
MessageSendWhatsappResponse response = client.messages().sendWhatsapp(params);

Primary response fields:

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.body
```

发送WhatsApp消息而非SMS/MMS。

client.messages().sendWhatsapp()

—

POST /messages/whatsapp

参数	类型	必填	说明
`from`	string (E.164)	是	绑定WhatsApp账号的手机号，符合+E.164格式
`to`	string (E.164)	是	接收方手机号，符合+E.164格式
`whatsappMessage`	object	是	WhatsApp消息内容
`type`	枚举 (WHATSAPP)	否	消息类型，必须设为"WHATSAPP"
`webhookUrl`	string (URL)	否	接收该消息相关Webhook事件的URL

java

import com.telnyx.sdk.models.messages.MessageSendWhatsappParams;
import com.telnyx.sdk.models.messages.MessageSendWhatsappResponse;
import com.telnyx.sdk.models.messages.WhatsappMessageContent;

MessageSendWhatsappParams params = MessageSendWhatsappParams.builder()
    .from("+13125551234")
    .to("+13125551234")
    .whatsappMessage(WhatsappMessageContent.builder().build())
    .build();
MessageSendWhatsappResponse response = client.messages().sendWhatsapp(params);

核心响应字段：

```
response.data.id
```
```
response.data.to
```
```
response.data.from
```
```
response.data.type
```
```
response.data.direction
```
```
response.data.body
```

Additional Operations

其他操作

Use the core tasks above first. The operations below are indexed here with exact SDK methods and required params; use references/api-details.md for full optional params, response schemas, and lower-frequency webhook payloads. Before using any operation below, read the optional-parameters section and the response-schemas section so you do not guess missing fields.

Operation	SDK method	Endpoint	Use when	Required params
Retrieve a message	`client.messages().retrieve()`	`GET /messages/{id}`	Fetch the current state before updating, deleting, or making control-flow decisions.	`id`
Cancel a scheduled message	`client.messages().cancelScheduled()`	`DELETE /messages/{id}`	Remove, detach, or clean up an existing resource.	`id`
List alphanumeric sender IDs	`client.alphanumericSenderIds().list()`	`GET /alphanumeric_sender_ids`	Inspect available resources or choose an existing resource before mutating it.	None
Create an alphanumeric sender ID	`client.alphanumericSenderIds().create()`	`POST /alphanumeric_sender_ids`	Create or provision an additional resource when the core tasks do not cover this flow.	`alphanumericSenderId` , `messagingProfileId`
Retrieve an alphanumeric sender ID	`client.alphanumericSenderIds().retrieve()`	`GET /alphanumeric_sender_ids/{id}`	Fetch the current state before updating, deleting, or making control-flow decisions.	`id`
Delete an alphanumeric sender ID	`client.alphanumericSenderIds().delete()`	`DELETE /alphanumeric_sender_ids/{id}`	Remove, detach, or clean up an existing resource.	`id`
Retrieve group MMS messages	`client.messages().retrieveGroupMessages()`	`GET /messages/group/{message_id}`	Fetch the current state before updating, deleting, or making control-flow decisions.	`messageId`
List messaging hosted numbers	`client.messagingHostedNumbers().list()`	`GET /messaging_hosted_numbers`	Inspect available resources or choose an existing resource before mutating it.	None
Retrieve a messaging hosted number	`client.messagingHostedNumbers().retrieve()`	`GET /messaging_hosted_numbers/{id}`	Fetch the current state before updating, deleting, or making control-flow decisions.	`id`
Update a messaging hosted number	`client.messagingHostedNumbers().update()`	`PATCH /messaging_hosted_numbers/{id}`	Modify an existing resource without recreating it.	`id`
List opt-outs	`client.messagingOptouts().list()`	`GET /messaging_optouts`	Inspect available resources or choose an existing resource before mutating it.	None
List high-level messaging profile metrics	`client.messagingProfileMetrics().list()`	`GET /messaging_profile_metrics`	Inspect available resources or choose an existing resource before mutating it.	None
Regenerate messaging profile secret	`client.messagingProfiles().actions().regenerateSecret()`	`POST /messaging_profiles/{id}/actions/regenerate_secret`	Trigger a follow-up action in an existing workflow rather than creating a new top-level resource.	`id`
List alphanumeric sender IDs for a messaging profile	`client.messagingProfiles().listAlphanumericSenderIds()`	`GET /messaging_profiles/{id}/alphanumeric_sender_ids`	Fetch the current state before updating, deleting, or making control-flow decisions.	`id`
Get detailed messaging profile metrics	`client.messagingProfiles().retrieveMetrics()`	`GET /messaging_profiles/{id}/metrics`	Fetch the current state before updating, deleting, or making control-flow decisions.	`id`
List Auto-Response Settings	`client.messagingProfiles().autorespConfigs().list()`	`GET /messaging_profiles/{profile_id}/autoresp_configs`	Fetch the current state before updating, deleting, or making control-flow decisions.	`profileId`
Create auto-response setting	`client.messagingProfiles().autorespConfigs().create()`	`POST /messaging_profiles/{profile_id}/autoresp_configs`	Create or provision an additional resource when the core tasks do not cover this flow.	`op` , `keywords` , `countryCode` , `profileId`
Get Auto-Response Setting	`client.messagingProfiles().autorespConfigs().retrieve()`	`GET /messaging_profiles/{profile_id}/autoresp_configs/{autoresp_cfg_id}`	Fetch the current state before updating, deleting, or making control-flow decisions.	`profileId` , `autorespCfgId`
Update Auto-Response Setting	`client.messagingProfiles().autorespConfigs().update()`	`PUT /messaging_profiles/{profile_id}/autoresp_configs/{autoresp_cfg_id}`	Modify an existing resource without recreating it.	`op` , `keywords` , `countryCode` , `profileId` , +1 more
Delete Auto-Response Setting	`client.messagingProfiles().autorespConfigs().delete()`	`DELETE /messaging_profiles/{profile_id}/autoresp_configs/{autoresp_cfg_id}`	Remove, detach, or clean up an existing resource.	`profileId` , `autorespCfgId`

请优先使用上述核心功能，以下操作仅列出了SDK方法和必填参数，完整的可选参数、响应结构和低频率Webhook payload请查看references/api-details.md。使用以下任意操作前，请先阅读可选参数章节和响应结构章节，请勿自行猜测缺失字段。

操作	SDK方法	接口地址	使用场景	必填参数
查询消息详情	`client.messages().retrieve()`	`GET /messages/{id}`	在更新、删除消息或做流程控制前查询当前状态	`id`
取消定时消息	`client.messages().cancelScheduled()`	`DELETE /messages/{id}`	删除已有的定时消息资源	`id`
查询字母数字发送ID列表	`client.alphanumericSenderIds().list()`	`GET /alphanumeric_sender_ids`	修改资源前查看可用的发送ID	无
创建字母数字发送ID	`client.alphanumericSenderIds().create()`	`POST /alphanumeric_sender_ids`	核心功能未覆盖的发送ID创建场景	`alphanumericSenderId` , `messagingProfileId`
查询字母数字发送ID详情	`client.alphanumericSenderIds().retrieve()`	`GET /alphanumeric_sender_ids/{id}`	在更新、删除发送ID或做流程控制前查询当前状态	`id`
删除字母数字发送ID	`client.alphanumericSenderIds().delete()`	`DELETE /alphanumeric_sender_ids/{id}`	清理不再使用的发送ID资源	`id`
查询群组MMS消息详情	`client.messages().retrieveGroupMessages()`	`GET /messages/group/{message_id}`	在更新、删除群组消息或做流程控制前查询当前状态	`messageId`
查询托管消息号码列表	`client.messagingHostedNumbers().list()`	`GET /messaging_hosted_numbers`	修改资源前查看可用的托管号码	无
查询托管消息号码详情	`client.messagingHostedNumbers().retrieve()`	`GET /messaging_hosted_numbers/{id}`	在更新、删除托管号码或做流程控制前查询当前状态	`id`
更新托管消息号码	`client.messagingHostedNumbers().update()`	`PATCH /messaging_hosted_numbers/{id}`	修改已有托管号码的配置，无需重新创建	`id`
查询退订列表	`client.messagingOptouts().list()`	`GET /messaging_optouts`	修改退订配置前查看现有退订列表	无
查询消息配置文件核心指标	`client.messagingProfileMetrics().list()`	`GET /messaging_profile_metrics`	修改配置前查看现有配置文件的指标数据	无
重新生成消息配置文件密钥	`client.messagingProfiles().actions().regenerateSecret()`	`POST /messaging_profiles/{id}/actions/regenerate_secret`	现有工作流中的后续触发操作，无需创建新资源	`id`
查询指定消息配置文件的字母数字发送ID列表	`client.messagingProfiles().listAlphanumericSenderIds()`	`GET /messaging_profiles/{id}/alphanumeric_sender_ids`	在更新、删除发送ID或做流程控制前查询当前状态	`id`
查询消息配置文件详细指标	`client.messagingProfiles().retrieveMetrics()`	`GET /messaging_profiles/{id}/metrics`	在更新、删除配置文件或做流程控制前查询当前状态	`id`
查询自动回复配置列表	`client.messagingProfiles().autorespConfigs().list()`	`GET /messaging_profiles/{profile_id}/autoresp_configs`	在更新、删除自动回复配置前查询当前状态	`profileId`
创建自动回复配置	`client.messagingProfiles().autorespConfigs().create()`	`POST /messaging_profiles/{profile_id}/autoresp_configs`	核心功能未覆盖的自动回复配置创建场景	`op` , `keywords` , `countryCode` , `profileId`
查询自动回复配置详情	`client.messagingProfiles().autorespConfigs().retrieve()`	`GET /messaging_profiles/{profile_id}/autoresp_configs/{autoresp_cfg_id}`	在更新、删除自动回复配置前查询当前状态	`profileId` , `autorespCfgId`
更新自动回复配置	`client.messagingProfiles().autorespConfigs().update()`	`PUT /messaging_profiles/{profile_id}/autoresp_configs/{autoresp_cfg_id}`	修改已有自动回复配置，无需重新创建	`op` , `keywords` , `countryCode` , `profileId` , +1其他参数
删除自动回复配置	`client.messagingProfiles().autorespConfigs().delete()`	`DELETE /messaging_profiles/{profile_id}/autoresp_configs/{autoresp_cfg_id}`	清理不再使用的自动回复配置资源	`profileId` , `autorespCfgId`

Other Webhook Events

其他Webhook事件

Event	`data.event_type`	Description
`replacedLinkClick`	`message.link_click`	Replaced Link Click

For exhaustive optional parameters, full response schemas, and complete webhook payloads, see references/api-details.md.

事件	`data.event_type`	说明
`replacedLinkClick`	`message.link_click`	替换链接被点击

完整的可选参数、响应结构和全量Webhook payload请查看references/api-details.md。