發送訊息給聯絡人
POST /communicateSrvCloudAPI/message/v1/sendToContact請求標頭、Base URL 與回應碼的說明,請參閱概覽。
向指定聯絡人發送文字、圖片、影片或檔案。訊息會經由該聯絡人所屬的 WhatsApp 頻道發出。
發送前請注意
- 訊息會真的發給你的客戶,發出後無法撤回。
- 此接口發送的是一般訊息,不支援 WhatsApp 範本訊息。按 WhatsApp 的規則,一般訊息只能在客戶最後一次來訊後的 24 小時內送達。
- 接口不會按
RequestID自動去重,重複呼叫會重複發送。請在你的系統中避免重試造成的重複發送。
請求參數
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
RequestID | String | 是 | 由你產生的請求識別碼,8–48 個字元,可用英文字母、數字、- 與 _ |
ContactID | String | 是 | 聯絡人在 ChatBooster 的 ID(數字,以字串傳入) |
Text | String | 視情況 | 純文字訊息時必填;發送媒體時作為說明文字,可留空 |
MediaURL | String | 否 | 可公開存取的媒體網址。留空即為純文字訊息 |
FileName | String | 否 | 檔案名稱,用於判斷檔案類型及在對話中顯示 |
MimeType | String | 否 | 媒體的 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": "這是你的收據。"
}'回應
| 欄位 | 類型 | 說明 |
|---|---|---|
Code | Integer | 200 表示成功 |
Message | String | 狀態訊息 |
Data.RequestID | String | 請求中傳入的 RequestID |
Data.MessageID | String | 已發出訊息的 ID |
Data.ChannelID | String | 發送所用頻道的 ID |
json
{
"Code": 200,
"Message": "ok",
"Data": {
"RequestID": "order-10086-shipped",
"MessageID": "wamid.HBgM...",
"ChannelID": "channel-id"
}
}錯誤情況
| Code | 原因 |
|---|---|
400 | ContactID 格式不正確、純文字訊息未提供 Text、媒體類型不支援,或聯絡人沒有可用的 WhatsApp 頻道 |
401 | API key 無效,或工作區方案不包含平台 API |
404 | 聯絡人不存在,或不屬於此工作區 |
500 | 訊息發送失敗,詳情見 Message |