發送訊息

開發者可透過 API 向指定的 conversation ID 發送訊息。

請求方式

POST

請求 URL

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   
    }
}'

此代碼塊在浮窗中顯示

請求 Headers

Field	Type	Description
Authorization	string	使用 `Authorization: Basic base64(API Key:API Secret)` 進行身分驗證。請前往 API Key 頁面取得 API Key 與 API Secret，並以冒號連接後進行 Base64 編碼。
Content-Type	application/json	資料類型，純文字訊息請使用 `application/json`。

路徑參數

Field	Type	Required	Description
conversation_id	string	Yes	對話 ID。

請求 Body 參數

Field	Type	Required	Description
content	String	Yes	訊息內容。
private	Boolean	No	是否為私訊，預設為 `false`。
content_attributes	Object	No	內容屬性，例如回覆某條訊息時，可透過 `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": ""
    }
}

此代碼塊在浮窗中顯示

回應參數

Field	Type	Description
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=圖片詳情如下"

此代碼塊在浮窗中顯示

路徑參數

Field	Type	Required	Description
conversation_id	string	Yes	對話 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
        }
    ]
}

此代碼塊在浮窗中顯示

回應參數

Field	Type	Description
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": "聊天介面顯示文字", "message_type": "outgoing", "template_params": { "name": "order_update", "namespace": "optional_namespace", "language": "en_US", "category": "MARKETING", "processed_params": { "1": "John", "2": "已出貨" }, "header_params": { "type": "text", "text_variables": { "1": "訂單 #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": "聊天介面顯示文字",
    "message_type": "outgoing",
    "template_params": {
      "name": "order_update",
      "namespace": "optional_namespace",
      "language": "en_US",
      "category": "MARKETING",
      "processed_params": {
        "1": "John",
        "2": "已出貨"
      },
      "header_params": {
        "type": "text",
        "text_variables": {
         "1": "訂單 #456" }
      },
      "footer_params": {
        "text_variables": { "1": "Acme Corp" }
      },
      "button_params": [
        {
          "index": 0,
          "sub_type": "url",
          "text": "track/12345"
        }
      ]
    }
  }'

此代碼塊在浮窗中顯示

路徑參數

Field	Type	Required	Description
conversation_id	string	Yes	對話 ID。

請求 Body 參數

Field	Type	Required	Description
content	String	Yes	訊息內容，會顯示於聊天 UI。
message_type	String	Yes	訊息類型，發送範本訊息時固定為 `outgoing`。
template_params	Object	Yes	範本訊息參數物件。
name	String	Yes	範本名稱。
namespace	String	No	範本命名空間，適用於 WhatsApp Cloud / 360Dialog。
language	String	Yes	範本語言代碼，例如 `en_US`。
category	String	No	範本分類，例如 `MARKETING`。
processed_params	Object	No	範本本文變數值。key 為變數位置如 `"1"`、`"2"`，或變數名稱。
header_params	Object	No	範本 Header 元件參數，詳見下方說明。
footer_params	Object	No	範本 Footer 元件參數，詳見下方說明。
button_params	Array	No	範本按鈕元件參數，詳見下方說明。

`header_params` 參數說明

依 Header 類型不同，header_params 結構也會不同：

文字類型：

{ "type": "text", "text_variables": { "1": "訂單 #456" } }

              
              {
  "type": "text",
  "text_variables": { "1": "訂單 #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"
  }
}

此代碼塊在浮窗中顯示

Field	Type	Required	Description
type	String	Yes	Header 類型，支援 `text`、`image`、`video`、`document`、`location`。
text_variables	Object	No	文字類型使用。key 為變數位置，value 為替換內容。
media_url	String	No	媒體類型使用，表示媒體檔案的 URL。
filename	String	No	文件類型使用，表示檔名。
location	Object	No	位置類型使用。
latitude	Float	Yes	緯度。
longitude	Float	Yes	經度。
name	String	No	地點名稱。
address	String	No	地點地址。

`footer_params` 參數說明

{ "text_variables": { "1": "Acme Corp" } }

              
              {
  "text_variables": { "1": "Acme Corp" }
}

此代碼塊在浮窗中顯示

Field	Type	Required	Description
text_variables	Object	No	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"
  }
]

此代碼塊在浮窗中顯示

Field	Type	Required	Description
index	Int	Yes	按鈕索引，從 `0` 開始。
sub_type	String	Yes	按鈕類型，支援 `url`、`quick_reply`。
text	String	No	URL 類型按鈕使用，表示 URL 後綴或跳轉路徑。
payload	String	No	quick_reply 類型按鈕使用，表示回傳的 payload 內容。

回應範例

成功回應

{ "id": 123, "content": "聊天介面顯示文字", "message_type": 1, "status": "sent", "additional_attributes": { "template_params": { "name": "order_update", "language": "en_US", "category": "MARKETING" } } }

              
              {
  "id": 123,
  "content": "聊天介面顯示文字",
  "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"
  }
}

此代碼塊在浮窗中顯示

回應參數

Field	Type	Description
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，可透過以下 API 重置訊息狀態並重新發送：

請求 URL

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

路徑參數

Field	Type	Required	Description
conversation_id	string	Yes	對話 ID。
message_id	string	Yes	訊息 ID。

發送訊息

請求方式

請求 URL

身分驗證

文字訊息請求

請求範例

請求 Headers

路徑參數

請求 Body 參數

文字訊息回應範例

回應範例

回應參數

圖片/音訊/檔案請求

請求範例

路徑參數

圖片/音訊/檔案回應範例

回應範例

回應參數

WhatsApp 範本訊息請求範例

請求範例

路徑參數

請求 Body 參數

header_params 參數說明

footer_params 參數說明

button_params 參數說明

回應範例

成功回應

失敗回應

回應參數

重試失敗訊息

請求 URL

路徑參數

`header_params` 參數說明

`footer_params` 參數說明

`button_params` 參數說明