摘要
當您透過 Wati API 在啟用中的 WhatsApp 工作階段發送檔案時,若未在請求中包含 caption 參數,附件名稱可能會顯示為 null 或 untitled。
若要修正此問題,請將 caption 參數作為查詢參數 (query parameter) 納入請求中,並將其設定為您想要顯示的檔案名稱。本文說明如何使用舊版 v1 API 套用此修正,並提供推薦使用的 v3 API 相關指引。
操作說明
1. 修正附件名稱
caption 參數用於指定檔案附件顯示的名稱。若省略此參數,附件名稱可能會顯示為 null 或 untitled。
若要顯示正確的檔案名稱,請在 API 請求中將 caption 作為查詢參數納入。

重要:請將 caption 放在查詢字串 (query string) 中,而非請求主體 (request body) 中。檔案本身應作為名為 file 的 multipart 表單欄位進行發送。
2. 使用舊版 v1 API 修正問題
您可以使用舊版 v1 端點在啟用中的 WhatsApp 工作階段發送檔案。
端點:
POST https://live-mt-server.wati.io/{tenantId}/api/v1/sendSessionFile/{target}
API 參數
參數 | 類型 | 位置 | 說明 |
| 字串 | 路徑 | 您的 Wati 租戶 ID。 |
| 字串 | 路徑 | 收件人的電話號碼、聯絡人 ID 或業務範圍用戶 ID (BSUID)。 |
| 字串 | 查詢參數 | 附件要顯示的檔案名稱。 |
| 檔案 | Multipart 請求主體 | 您要發送的檔案。請使用 |
請求範例
以下範例會發送一個名為 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 建立範圍存取權杖 (scoped API token)。
target 欄位也支援 Channel:PhoneNumber 格式。
請參閱 Wati 開發者文件以了解 v3 端點所需的參數與請求格式。
4. 重要注意事項
包含標題:請將
caption參數作為查詢參數傳遞,以指定附件名稱。使用正確的檔案欄位:請將檔案上傳為名為
file的 multipart 表單欄位。正確檢查 API 回應:HTTP
200回應僅表示請求已被接受;並不代表檔案已成功送達收件人。追蹤送達狀態:請使用
sentMessageDELIVERED_v2webhook 事件來確認訊息是否送達。
遵循這些準則有助於防止在使用 Wati API 發送檔案時,附件名稱顯示為 null 或 untitled。
Did this answer your question?