摘要
当您通过 Wati API 在活跃的 WhatsApp 会话中发送文件时,如果您未在请求中包含 caption 参数,附件名称可能会显示为 null 或 untitled。
要解决此问题,请将 caption 参数作为查询参数包含在请求中,并将其设置为您想要显示的文件名。本文介绍了如何使用旧版 v1 API 应用此修复方案,并提供了推荐使用的 v3 API 指南。
操作指南
1. 修复附件名称
caption 参数用于指定文件附件显示的名称。如果您省略此参数,附件名称可能会显示为 null 或 untitled。
要显示正确的文件名,请在 API 请求中将 caption 作为查询参数包含在内。

重要提示: 请在查询字符串(query string)中传递 caption,而不是在请求主体(request body)中。文件本身应作为名为 file 的多部分(multipart)表单字段发送。
2. 使用旧版 v1 API 修复问题
您可以使用旧版 v1 端点在活跃的 WhatsApp 会话中发送文件。
端点:
POST https://live-mt-server.wati.io/{tenantId}/api/v1/sendSessionFile/{target}
API 参数
参数 | 类型 | 位置 | 描述 |
| String | 路径 (Path) | 您的 Wati 租户 ID。 |
| String | 路径 (Path) | 收件人的电话号码、联系人 ID 或业务范围用户 ID (BSUID)。 |
| String | 查询参数 | 附件要显示的文件名。 |
| File | 多部分请求主体 | 您要发送的文件。使用 |
请求示例
以下示例发送了一个名为 Invoice_October.pdf 的文件,并使用该名称作为附件标题。
curl --location 'https://live-mt-server.wati.io/{tenantId}/api/v1/sendSessionFile/85264318722?caption=Invoice_October.pdf' \
--header 'Authorization: Bearer <Token>' \
--form 'file=@"/path/to/Invoice_October.pdf"'请将以下占位符替换为您实际的值:
{tenantId}— 您的 Wati 租户 ID。85264318722— 收件人的电话号码。<Token>— 您的 Wati API 访问令牌。/path/to/Invoice_October.pdf— 您要上传的文件的路径。
您可以将 Invoice_October.pdf 更改为您想要显示的任何附件名称。
3. 使用推荐的 v3 API
对于新的集成,请在支持的情况下使用 v3 API。
端点:
POST https://live-mt-server.wati.io/api/ext/v3/conversations/messages/file
与旧版 v1 端点不同,v3 端点路径不包含 /{tenantId}/。
在您的 Wati 账户中,通过 Connector > API Tokens > Generate new Token 创建一个范围受限的 API 令牌。
target 字段同样支持 Channel:PhoneNumber 格式。
请参阅 Wati 开发者文档,以了解 v3 端点所需的参数和请求格式。
4. 重要提示
包含 caption: 将
caption参数作为查询参数传递,以指定附件名称。使用正确的文件字段: 将文件作为名为
file的多部分表单字段上传。正确检查 API 响应: HTTP
200响应仅表示请求已被接受;它并不确认文件已送达收件人。跟踪送达情况: 使用
sentMessageDELIVERED_v2Webhook 事件来确认消息送达。
遵循这些指南有助于防止通过 Wati API 发送文件时附件名称显示为 null 或 untitled。
Did this answer your question?