摘要

當您透過 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 參數

參數

類型

位置

說明

tenantId

字串

路徑

您的 Wati 租戶 ID。

target

字串

路徑

收件人的電話號碼、聯絡人 ID 或業務範圍用戶 ID (BSUID)。

caption

字串

查詢參數

附件要顯示的檔案名稱。

file

檔案

Multipart 請求主體

您要發送的檔案。請使用 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 建立範圍存取權杖 (scoped API token)。

target 欄位也支援 Channel:PhoneNumber 格式。

請參閱 Wati 開發者文件以了解 v3 端點所需的參數與請求格式。

4. 重要注意事項

  • 包含標題:請將 caption 參數作為查詢參數傳遞,以指定附件名稱。

  • 使用正確的檔案欄位:請將檔案上傳為名為 file 的 multipart 表單欄位。

  • 正確檢查 API 回應:HTTP 200 回應僅表示請求已被接受;並不代表檔案已成功送達收件人。

  • 追蹤送達狀態:請使用 sentMessageDELIVERED_v2 webhook 事件來確認訊息是否送達。

遵循這些準則有助於防止在使用 Wati API 發送檔案時,附件名稱顯示為 null 或 untitled。

Did this answer your question?