# WhatsApp 纯文本消息

纯文本是最简单的自由格式内容分支：仅含正文，无附件，并可为正文中的第一个链接提供可选预览。

## 发送文本消息

设置 `text.body`：

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  text: { body: "Your driver is 2 minutes away." },
});
console.log(msg.id, msg.status);
```

Examples: [TypeScript](/zh-sg/wendang/guides/whatsapp/message-types/plain-text.ts.md) · [Python](/zh-sg/wendang/guides/whatsapp/message-types/plain-text.py.md) · [Go](/zh-sg/wendang/guides/whatsapp/message-types/plain-text.go.md) · [PHP](/zh-sg/wendang/guides/whatsapp/message-types/plain-text.php.md) · [CLI](/zh-sg/wendang/guides/whatsapp/message-types/plain-text.cli.md) · [MCP](/zh-sg/wendang/guides/whatsapp/message-types/plain-text.mcp.md) · [cURL](/zh-sg/wendang/guides/whatsapp/message-types/plain-text.curl.md)

完整结构在 `preview_url` 基础上添加了所有自由格式发送可携带的字段：

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "text": {
    "body": "Your order shipped: https://example.com/track/A1B2C3",
    "preview_url": true
  },
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "tags": [{ "name": "category", "value": "shipping" }],
  "metadata": { "order_id": "A1B2C3" }
}
```

`from` 在每条服务消息中都是必填项：必须是您的工作区拥有的号码，而非 Bird 托管的号码。`in_reply_to_message_id` 引用同一会话中的早期消息；请参阅[引用消息](/docs/guides/whatsapp/sending-whatsapp#quoting-a-message)了解其匹配逻辑及可能遗漏的情况。

## 限制

| 字段          | 约束                   | 执行方                 |
| ------------- | ---------------------- | ---------------------- |
| `body`        | 1 至 4096 个字符       | Bird，在接受时 (`422`) |
| `preview_url` | 布尔值，默认为 `false` | 不适用，仅供参考       |

仅含空白字符的 `body` 可以通过 schema 自身的 `minLength: 1`，但 Bird 仍会拦截：去除首尾空白后为空的 `body` 会被拒绝，返回 `422` [`E15015`](/docs/api/errors/E15015) `WhatsAppContentRequired`。超过 4096 个字符的正文会被拒绝，返回普通的 `422`，且没有专用目录代码。

## 读取入站文本消息

入站文本消息携带相同的 `text.body` 字段，该分支上没有其他内容。请参阅[接收 WhatsApp 文本消息](/docs/guides/whatsapp/receiving-whatsapp/plain-text)了解完整的入站读取、`whatsapp.received` 载荷以及需要注意的事项。

## 限制与边界情况

- **客户服务窗口必须处于打开状态。** 纯文本是服务消息，只能在打开的窗口内投递；请参阅中心的[客户服务窗口](/docs/guides/whatsapp/message-types#the-customer-service-window)。
- **`preview_url` 仅影响第一个链接，且仅影响接收方客户端渲染的内容。** 默认值为 `false`。将其设置为预览 `body` 中的第一个 URL；同一正文中后续的 URL 不会获得预览。如果接收方客户端无法获取该链接的预览，它会静默回退为普通可点击链接。读取时无法得知预览是否实际渲染。
- **WhatsApp markdown 是接收方客户端对 `body` 的渲染，不属于 API 契约的一部分。** Bird 原样传递 `body`；它不会验证、剥离或编码 `*bold*`、`_italic_`、`~strikethrough~` 或三反引号等宽字体标记。这些标记是否渲染完全取决于打开消息的客户端。
- **入站 `body` 不保证非空，尽管读取 schema 如此声明。** Meta 可能将入站消息报告为 `"text": {}` 或带有空的 `body`，而 Bird 会原样存储而非合成占位符。这是一个已知的未解决差异：不要编写信任 schema 的 `required: body` 的消费者。

## 后续步骤

- [WhatsApp 服务消息](/docs/guides/whatsapp/message-types)：客户服务窗口及所有服务消息共享的模型
- [发送 WhatsApp 消息](/docs/guides/whatsapp/sending-whatsapp)：请求信封、`202` 模型与安全重试
- [交互式消息](/docs/guides/whatsapp/message-types/interactive)：当您需要点击操作而非输入回复时

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)