跳轉到內容

發送訊息給聯絡人 ​

POST /communicateSrvCloudAPI/message/v1/sendToContact

請求標頭、Base URL 與回應碼的說明,請參閱概覽。

向指定聯絡人發送文字、圖片、影片或檔案。訊息會經由該聯絡人所屬的 WhatsApp 頻道發出。

發送前請注意

  • 訊息會真的發給你的客戶,發出後無法撤回。
  • 此接口發送的是一般訊息,不支援 WhatsApp 範本訊息。按 WhatsApp 的規則,一般訊息只能在客戶最後一次來訊後的 24 小時內送達。
  • 接口不會按 RequestID 自動去重,重複呼叫會重複發送。請在你的系統中避免重試造成的重複發送。

請求參數 ​

欄位類型必填說明
RequestIDString是由你產生的請求識別碼,8–48 個字元,可用英文字母、數字、- 與 _
ContactIDString是聯絡人在 ChatBooster 的 ID(數字,以字串傳入)
TextString視情況純文字訊息時必填;發送媒體時作為說明文字,可留空
MediaURLString否可公開存取的媒體網址。留空即為純文字訊息
FileNameString否檔案名稱,用於判斷檔案類型及在對話中顯示
MimeTypeString否媒體的 MIME 類型。有提供時優先採用,否則按 FileName 或網址的副檔名判斷

支援的媒體類型

類型副檔名
圖片.jpg .jpeg .png
影片.mp4 .3gp
檔案.pdf .doc .docx .xls .xlsx .ppt .pptx .txt

其他類型(例如 .gif、.webp、.zip)會回傳 400,Message 為 unsupported media type。

請求範例 ​

純文字:

bash
curl -X POST "https://api.chatbooster.ai/communicateSrvCloudAPI/message/v1/sendToContact" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "RequestID": "order-10086-shipped",
    "ContactID": "1234567890",
    "Text": "你的訂單已出貨。"
  }'

圖片加說明文字:

bash
curl -X POST "https://api.chatbooster.ai/communicateSrvCloudAPI/message/v1/sendToContact" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "RequestID": "order-10086-receipt",
    "ContactID": "1234567890",
    "MediaURL": "https://example.com/receipt.jpg",
    "FileName": "receipt.jpg",
    "Text": "這是你的收據。"
  }'

回應 ​

欄位類型說明
CodeInteger200 表示成功
MessageString狀態訊息
Data.RequestIDString請求中傳入的 RequestID
Data.MessageIDString已發出訊息的 ID
Data.ChannelIDString發送所用頻道的 ID
json
{
  "Code": 200,
  "Message": "ok",
  "Data": {
    "RequestID": "order-10086-shipped",
    "MessageID": "wamid.HBgM...",
    "ChannelID": "channel-id"
  }
}

錯誤情況

Code原因
400ContactID 格式不正確、純文字訊息未提供 Text、媒體類型不支援,或聯絡人沒有可用的 WhatsApp 頻道
401API key 無效,或工作區方案不包含平台 API
404聯絡人不存在,或不屬於此工作區
500訊息發送失敗,詳情見 Message