Logo Site EngageLab Mark Colored Transparent文件
LiveDesk
文檔首頁
概覽對話渠道Agents洞察設定API更新日誌管理
搜尋
登錄
API/聯絡人,使用者/傳送訊息
API聯絡人,使用者傳送訊息...

傳送訊息

最新更新：3 天前

開發人員可以透過 API 向指定的對話 ID傳送訊息。

請求方式

POST

呼叫位址

https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages

呼叫驗證

詳情請參閱 API 概述 中的驗證方式說明。

一般文字請求

請求範例

curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages' \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)' \ -d '{ "content": "客服傳送訊息，正常嗎", "private": false, "content_attributes": { "in_reply_to": 29 } }'
              
              curl -X POST 'https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)' \
-d '{
    "content": "客服傳送訊息，正常嗎",  
    "private": false,
    "content_attributes": {
        "in_reply_to": 29   
    }
}'
此代碼塊在浮窗中顯示

請求標頭

欄位 類型 說明
Authorization string 使用 Authorization: Basic base64(API Key:API Secret) 進行身分驗證。請前往 API 金鑰頁面取得 API Key 和 API Secret，並以冒號連接兩者後進行 Base64 編碼。
Content-Type application/json 資料類型，一般文字訊息使用 application/json。

路徑參數

欄位 類型 必填 說明
conversation_id string 是 對話 ID。

請求主體參數

欄位 類型 必填 說明
content String 是 訊息內容。
private Boolean 否 是否為私訊，預設為 false。
content_attributes Object 否 內容屬性，例如回覆某則訊息時，使用 in_reply_to 欄位指定訊息 ID。

一般文字回應範例

回應範例

{ "id": 3030, "content": "客服傳送訊息，正常嗎", "inbox_id": 79, "conversation_id": 141, "message_type": 1, "content_type": "text", "status": "sent", "content_attributes": {}, "created_at": 1762331029, "private": false, "source_id": null, "sorting_id": 4, "sender": { "id": 3, "name": "TEST", "available_name": "TEST", "avatar_url": "", "type": "user", "availability_status": "offline", "thumbnail": "" } }
              
              {
    "id": 3030,
    "content": "客服傳送訊息，正常嗎",
    "inbox_id": 79,
    "conversation_id": 141,
    "message_type": 1,
    "content_type": "text",
    "status": "sent",
    "content_attributes": {},
    "created_at": 1762331029,
    "private": false,
    "source_id": null,
    "sorting_id": 4,
    "sender": {
        "id": 3,
        "name": "TEST",
        "available_name": "TEST",
        "avatar_url": "",
        "type": "user",
        "availability_status": "offline",
        "thumbnail": ""
    }
}
此代碼塊在浮窗中顯示

回應參數

欄位 類型 說明
id Int 訊息 ID。
content String 訊息內容。
inbox_id Int 收件匣 ID。
conversation_id Int 對話 ID。
message_type Int 訊息類型。
content_type String 內容類型。
status String 訊息狀態，例如 "sent"、"delivered" 等。
content_attributes Object 內容屬性。
created_at Int 訊息建立時間戳記。
private Boolean 是否為私訊。
source_id Int 來源 ID。
sorting_id Int 排序 ID。
sender Object 傳送者資訊。
id Int 傳送者 ID。
name String 傳送者名稱。
available_name String 傳送者顯示名稱。
avatar_url String 傳送者頭像 URL。
type String 傳送者類型（例如 user）。
availability_status String 傳送者線上狀態（例如 offline）。
thumbnail String 傳送者縮圖。

圖片／音訊等檔案請求

請求範例

curl -X POST "https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages" \ -H "Authorization: Basic base64(api_key:api_secret)" \ -F "attachments[]=@attachments[]=@/path/to/your/file.jpg" \ -F "content=詳細圖片如下" 
              
              curl -X POST "https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages" \
  -H "Authorization: Basic base64(api_key:api_secret)" \
  -F "attachments[]=@attachments[]=@/path/to/your/file.jpg" \
  -F "content=詳細圖片如下"
此代碼塊在浮窗中顯示

路徑參數

欄位 類型 必填 說明
conversation_id string 是 對話 ID。

圖片／音訊等檔案回應範例

回應範例

{ "id": 3031, "content": "詳細圖片如下", "inbox_id": 79, "conversation_id": 141, "message_type": 1, "content_type": "text", "status": "sent", "content_attributes": {}, "created_at": 1762331762, "private": false, "source_id": null, "sorting_id": 5, "sender": { "id": 3, "name": "Wenjie Yu", "available_name": "Wenjie Yu", "avatar_url": "", "type": "user", "availability_status": "offline", "thumbnail": "" }, "attachments": [ { "id": 199, "message_id": 3031, "file_type": "image", "account_id": 14, "extension": null, "data_url": "https://livedesk.engagelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/android-icon-48x48.png", "thumb_url": "https://livedesk.engagelab.com/rails/active_storage/representations/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCem9MWm05eWJXRjBTU0lJY0c1bkJqb0dSVlE2RTNKbGMybDZaVjkwYjE5bWFXeHNXd2RwQWZvdyIsImV4cCI6bnVsbCwicHVyIjoidmFyaWF0aW9uIn19--63c890cbf173eb3dc92a8786fcc3e120c329852d/android-icon-48x48.png", "file_size": 589136, "width": null, "height": null } ] }
              
              {
    "id": 3031,
    "content": "詳細圖片如下",
    "inbox_id": 79,
    "conversation_id": 141,
    "message_type": 1,
    "content_type": "text",
    "status": "sent",
    "content_attributes": {},
    "created_at": 1762331762,
    "private": false,
    "source_id": null,
    "sorting_id": 5,
    "sender": {
        "id": 3,
        "name": "Wenjie Yu",
        "available_name": "Wenjie Yu",
        "avatar_url": "",
        "type": "user",
        "availability_status": "offline",
        "thumbnail": ""
    },
    "attachments": [
        {
            "id": 199,
            "message_id": 3031,
            "file_type": "image",
            "account_id": 14,
            "extension": null,
            "data_url": "https://livedesk.engagelab.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/android-icon-48x48.png",
            "thumb_url": "https://livedesk.engagelab.com/rails/active_storage/representations/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBamNUIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--727ba7469d64f90790d242c743f254b5c9013fe1/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCem9MWm05eWJXRjBTU0lJY0c1bkJqb0dSVlE2RTNKbGMybDZaVjkwYjE5bWFXeHNXd2RwQWZvdyIsImV4cCI6bnVsbCwicHVyIjoidmFyaWF0aW9uIn19--63c890cbf173eb3dc92a8786fcc3e120c329852d/android-icon-48x48.png",
            "file_size": 589136,
            "width": null,
            "height": null
        }
    ]
}
此代碼塊在浮窗中顯示

回應參數

欄位 類型 說明
id Int 訊息 ID。
content String 訊息內容。
inbox_id Int 收件匣 ID。
conversation_id Int 對話 ID。
message_type Int 訊息類型。
content_type String 內容類型。
status String 訊息狀態，例如 "sent"、"delivered" 等。
content_attributes Object 內容屬性。
created_at Int 訊息建立時間戳記。
private Boolean 是否為私訊。
source_id Int 來源 ID。
sorting_id Int 排序 ID。
sender Object 傳送者資訊。
id Int 傳送者 ID。
name String 傳送者名稱。
available_name String 傳送者顯示名稱。
avatar_url String 傳送者頭像 URL。
type String 傳送者類型（例如 user）。
availability_status String 傳送者線上狀態（例如 offline）。
thumbnail String 傳送者縮圖。
attachments Array 附件資訊清單。
id Int 附件 ID。
message_id Int 所屬訊息 ID。
file_type String 檔案類型（例如 image）。
account_id Int 帳戶 ID。
extension String 檔案副檔名。
data_url String 檔案 URL。
thumb_url String 縮圖 URL（僅限圖片類型）。
file_size Int 檔案大小（位元組）。
width Int 檔案寬度（僅限圖片類型）。
height Int 檔案高度（僅限圖片類型）。

WhatsApp 範本訊息請求範例

請求範例

curl -X POST 'https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages'\ -H 'Content-Type: application/json' \ -H 'Authorization: Basic base64(api_key:api_secret)'\ -d '{ "content": "Display text for chat UI", "message_type": "outgoing", "template_params": { "name": "order_update", "namespace": "optional_namespace", "language": "en_US", "category": "MARKETING", "processed_params": { "1": "John", "2": "shipped" }, "header_params": { "type": "text", "text_variables": { "1": "Order #456" } }, "footer_params": { "text_variables": { "1": "Acme Corp" } }, "button_params": [ { "index": 0, "sub_type": "url", "text": "track/12345" } ] } }'
              
              curl -X POST 'https://livedesk.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages'\
-H 'Content-Type: application/json' \
-H 'Authorization: Basic base64(api_key:api_secret)'\
-d '{
    "content": "Display text for chat UI",
    "message_type": "outgoing",
    "template_params": {
      "name": "order_update",
      "namespace": "optional_namespace",
      "language": "en_US",
      "category": "MARKETING",
      "processed_params": {
        "1": "John",
        "2": "shipped"
      },
      "header_params": {
        "type": "text",
        "text_variables": {
         "1": "Order #456" }
      },
      "footer_params": {
        "text_variables": { "1": "Acme Corp" }
      },
      "button_params": [
        {
          "index": 0,
          "sub_type": "url",
          "text": "track/12345"
        }
      ]
    }
  }'
此代碼塊在浮窗中顯示

路徑參數

欄位 類型 必填 說明
conversation_id string 是 對話 ID。

請求主體參數

欄位 類型 必填 說明
content String 是 訊息內容，用於在聊天介面中顯示。
message_type String 是 訊息類型，傳送範本訊息時固定為 outgoing。
template_params Object 是 範本訊息參數物件。
name String 是 範本名稱。
namespace String 否 範本命名空間（WhatsApp Cloud／360Dialog 使用）。
language String 是 範本語言代碼，例如 en_US。
category String 否 範本類別，例如 MARKETING。
processed_params Object 否 範本本文變數值。Key 為變數位置（"1"、"2"）或變數名稱。
header_params Object 否 範本標頭元件參數，詳見下方說明。
footer_params Object 否 範本頁尾元件參數，詳見下方說明。
button_params Array 否 範本按鈕元件參數，詳見下方說明。

header_params 參數說明

根據標頭類型不同，header_params 的結構也有所不同：

文字類型：

{ "type": "text", "text_variables": { "1": "Order #456" } }
              
              {
  "type": "text",
  "text_variables": { "1": "Order #456" }
}
此代碼塊在浮窗中顯示

圖片類型：

{ "type": "image", "media_url": "https://example.com/image.jpg" }
              
              {
  "type": "image",
  "media_url": "https://example.com/image.jpg"
}
此代碼塊在浮窗中顯示

影片類型：

{ "type": "video", "media_url": "https://example.com/video.mp4" }
              
              {
  "type": "video",
  "media_url": "https://example.com/video.mp4"
}
此代碼塊在浮窗中顯示

檔案類型：

{ "type": "document", "media_url": "https://example.com/invoice.pdf", "filename": "invoice.pdf" }
              
              {
  "type": "document",
  "media_url": "https://example.com/invoice.pdf",
  "filename": "invoice.pdf"
}
此代碼塊在浮窗中顯示

位置類型：

{ "type": "location", "location": { "latitude": 37.7749, "longitude": -122.4194, "name": "Acme HQ", "address": "123 Main St, San Francisco" } }
              
              {
  "type": "location",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "name": "Acme HQ",
    "address": "123 Main St, San Francisco"
  }
}
此代碼塊在浮窗中顯示
欄位 類型 必填 說明
type String 是 標頭類型，支援 text、image、video、document、location。
text_variables Object 否 文字類型時使用，Key 為變數位置，Value 為替換內容。
media_url String 否 媒體類型時使用，媒體檔案的 URL 位址。
filename String 否 檔案類型時使用，檔案名稱。
location Object 否 位置類型時使用。
latitude Float 是 緯度。
longitude Float 是 經度。
name String 否 位置名稱。
address String 否 位置地址。
{ "text_variables": { "1": "Acme Corp" } }
              
              {
  "text_variables": { "1": "Acme Corp" }
}
此代碼塊在浮窗中顯示
欄位 類型 必填 說明
text_variables Object 否 Key 為變數位置，Value 為替換內容。

button_params 參數說明

[ { "index": 0, "sub_type": "url", "text": "track/12345" }, { "index": 1, "sub_type": "quick_reply", "payload": "OPT_OUT" } ]
              
              [
  {
    "index": 0,
    "sub_type": "url",
    "text": "track/12345"
  },
  {
    "index": 1,
    "sub_type": "quick_reply",
    "payload": "OPT_OUT"
  }
]
此代碼塊在浮窗中顯示
欄位 類型 必填 說明
index Int 是 按鈕索引，從 0 開始。
sub_type String 是 按鈕類型，支援 url、quick_reply。
text String 否 URL 類型按鈕時使用，URL 後綴或跳轉路徑。
payload String 否 quick_reply 類型按鈕時使用，回傳的 payload 內容。

回應範例

成功回應

{ "id": 123, "content": "Display text for chat UI", "message_type": 1, "status": "sent", "additional_attributes": { "template_params": { "name": "order_update", "language": "en_US", "category": "MARKETING" } } }
              
              {
  "id": 123,
  "content": "Display text for chat UI",
  "message_type": 1,
  "status": "sent",
  "additional_attributes": {
    "template_params": {
      "name": "order_update",
      "language": "en_US",
      "category": "MARKETING"
    }
  }
}
此代碼塊在浮窗中顯示

失敗回應

{ "id": 123, "status": "failed", "content_attributes": { "external_error": "131047: Re-engagement message is not allowed" } }
              
              {
  "id": 123,
  "status": "failed",
  "content_attributes": {
    "external_error": "131047: Re-engagement message is not allowed"
  }
}
此代碼塊在浮窗中顯示

回應參數

欄位 類型 說明
id Int 訊息 ID。
content String 訊息內容。
message_type Int 訊息類型。
status String 訊息狀態，例如 sent、delivered、failed 等。
additional_attributes Object 附加屬性。
template_params Object 已傳送的範本參數資訊。
content_attributes Object 內容屬性，傳送失敗時包含錯誤資訊。
external_error String 外部錯誤資訊，訊息傳送失敗時回傳。

重試失敗訊息

若訊息狀態為 failed，可透過以下介面重設訊息狀態並重新傳送：

呼叫位址

POST https://livedesk-api.engagelab.com/api/v2/accounts/conversations/:conversation_id/messages/:message_id/retry

路徑參數

欄位 類型 必填 說明
conversation_id string 是 對話 ID。
message_id string 是 訊息 ID。
Icon Solid Transparent White Qiyu
聯繫銷售