摘要

当您通过 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 参数

参数

类型

位置

描述

tenantId

String

路径 (Path)

您的 Wati 租户 ID。

target

String

路径 (Path)

收件人的电话号码、联系人 ID 或业务范围用户 ID (BSUID)。

caption

String

查询参数

附件要显示的文件名。

file

File

多部分请求主体

您要发送的文件。使用 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_v2 Webhook 事件来确认消息送达。

遵循这些指南有助于防止通过 Wati API 发送文件时附件名称显示为 null 或 untitled。

Did this answer your question?