即時通訊平台 API 端點

聊天平台 API 端點可存取聊天物件。系統會為每個與 Contact Center AI 平台 (CCAI 平台) 進行的即時通訊建立即時通訊物件。

以下是聊天平台 API 端點：

• 更新對話

• 在即時通訊中傳送訊息

• 將虛擬服務專員的對話轉給真人服務專員

• 更新升級要求

• 將上傳的相片新增至對話

• 從對話中擷取所有相片

• 取得預先簽署的相片上傳網址

• 在對話中新增上傳的影片

• 從對話中擷取所有影片

• 取得預先簽署的影片上傳網址

• 建立對話

• 傳回即時通訊 ID

• 在即時通訊期間取得預留的資料屬性

• 在即時通訊期間更新預留的資料屬性

• 在即時通訊中傳送自訂資料

• 在進行中的即時通訊工作階段中更新終端使用者

對話物件

CCAI Platform 上的每個行動裝置和網頁即時通訊工作階段都會建立一個即時通訊物件。以下是聊天物件：

{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

更新對話

參數	必填	資料類型	定義
id	TRUE	整數	要更新的即時通訊 ID

端點：

Method: PATCH
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:id

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

內文：

{
    "finished_by_user_id": "integer",
    "chat": {
        "deflection_channel": "string",
        "status": "string",
        "escalation_id": "integer"
    }
}

要求和回應範例

下列各節提供端點的要求範例。

更新對話

這個範例說明如何成功更新現有對話

要求

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

查詢：

鍵	值	說明
id	整數	(必填)

內文：

{
    "finished_by_user_id": "integer",
    "chat": {
        "deflection_channel": "string",
        "status": "finished",
        "escalation_id": "integer"
    }
}

回應

{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

狀態碼：200

在對話中傳送訊息

這個方法可在現有即時通訊工作階段中傳送訊息。

參數	必填	資料類型	定義
id	TRUE	整數	要傳送訊息的即時通訊 ID。

端點：

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:id/message

標題：

鍵	值	說明
Content-Type	application/json

內文：

{
    "from_user_id": integer,
    "message": {
            "type": "string",
            "content": "string"
            }
    }
}

要求和回應範例

下列各節提供端點的要求範例。

成功傳送訊息

這個範例說明如何將訊息成功提交至現有即時通訊工作階段。

要求

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

查詢：

鍵	值	說明
id	整數	(必填)

內文：

{
    "from_user_id": integer,
    "message": {
            "type": "string",
            "content": : "string"
            }
    }
}

回應

{
}

狀態碼：200

將虛擬服務專員對話轉接給真人服務專員

將虛擬服務專員的即時通訊轉介給真人服務專員。

參數	必填	資料類型	定義
chat_id	TRUE	整數	升級所需的即時通訊 ID。

端點：

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/escalations

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

內文：

{
    "reason": "string",
    "force_escalate": "boolean"
}

要求和回應範例

下列各節提供端點的要求範例。

成功將對話轉交給專員

這個範例示範如何要求將現有對話轉交給真人服務專員。

要求

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

查詢：

鍵	值	說明
chat_id	整數	(必填)

內文：

{
    "reason": "by_end_user_ask",
    "force_escalate": true
}

回應

{
    "id": "integer",
    "chat_id": "integer",
    "status": "string"
}

狀態碼：200

更新提報

僅用於選取偏轉通道。

參數	必填	資料類型	定義
chat_id	TRUE	整數	更新轉移選單 ID 時所需的即時通訊 ID。
id	TRUE	整數	必要選單 ID。

端點：

Method: PATCH
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/escalations/:id

標題：

鍵	值	說明
Content-Type	application/json

內文：

{
    "deflection_channel": "string"
}

要求和回應範例

下列各節提供端點的要求範例。

成功更新提報

這個範例說明如何成功更新提報管道。

要求

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

查詢：

鍵	值	說明
chat_id	整數	(必填)
id	整數	(必填)

內文：

{
    "deflection_channel": "string"
}

回應

{
    "id": "integer",
    "chat_id": "integer",
    "status": "string"
}

狀態碼：200

將上傳的相片加入對話

將上傳至媒體儲存空間的相片新增到對話中

參數	必填	資料類型	定義
chat_id	TRUE	整數	要新增相片的必要對話 ID。

端點：

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}/apps/api/v1/chats/:chat_id/photos

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

內文：

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}

要求和回應範例

下列各節提供端點的要求範例。

已成功在對話中加入相片

以下範例說明如何將上傳至媒體儲存空間的相片新增至現有即時通訊對話。

要求

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

查詢：

鍵	值	說明
chat_id	整數	(必填)

內文：

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}

回應

{
    "url": "string",
    "media_id": "integer"
}

狀態碼：200

擷取對話中的所有相片

取得附加至對話的所有相片之媒體 ID 和儲存空間網址。

參數	必填	資料類型	定義
chat_id	TRUE	整數	取得媒體資訊所需的即時通訊 ID。

端點：

Method: GET
Type:
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/photos

標題：

鍵	值	說明
接受	application/json

要求和回應範例

下列各節提供端點的要求範例。

成功擷取對話的相片資訊

本例示範如何成功呼叫 API，取得現有對話工作階段的相片資訊。

要求

標題：

鍵	值	說明
接受	application/json

查詢：

鍵	值	說明
chat_id	整數	(必填)

回應

[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

狀態碼：200

取得預先簽署的相片上傳網址

用於取得相片的預先簽署上傳網址。

參數	必填	資料類型	定義
chat_id	TRUE	整數	必要聊天室 ID，將與預先簽署的相片網址建立關聯。

端點：

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/photos/upload

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

要求和回應範例

下列各節提供端點的要求範例。

已成功擷取上傳用的簽署網址

以下是成功要求的範例，其中包含用於上傳相片的簽署網址。

要求

標題：

鍵	值	說明
接受	application/json

查詢：

鍵	值	說明
chat_id	整數	(必填)

回應

{
    "url": "string",
    "fields": {
        "key": "string",
        "success_action_status": "string",
        "Content-Type": "string",
        "Cache-Control": "string",
        "acl": "string",
        "policy": "string",
        "x-amz-credential": "string",
        "x-amz-algorithm": "string",
        "x-amz-date": "string",
        "x-amz-security-token": "string",
        "x-amz-signature": "string",
        "x-goog-algorithm": "string",
        "x-goog-credential": "string",
        "x-goog-date": "string",
        "x-goog-signature": "string"
    }
}

狀態碼：200

將上傳的影片新增至對話

將上傳至媒體儲存空間的影片新增至對話。

參數	必填	資料類型	定義
chat_id	TRUE	整數	影片應與這個必要聊天室 ID 建立關聯。

端點：

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

內文：

{
    "video": {
        "s3_path": "string",
        "gcs_path": "string"
    }
}

要求和回應範例

下列各節提供端點的要求範例。

已成功將影片上傳至對話工作階段

這個範例示範如何將影片成功上傳至對話工作階段。

要求

標題：

鍵	值	說明
接受	application/json

查詢：

鍵	值	說明
chat_id	整數	(必填)

內文：

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}

回應

Body
{
    "url": "string",
    "media_id": "integer"
}

狀態碼：200

從對話中擷取所有影片

取得附加至對話的所有影片的媒體 ID 和儲存網址。

參數	必填	資料類型	定義
chat_id	TRUE	整數	必要聊天室 ID，系統會擷取該聊天室的影片網址。

端點：

Method: GET
Type:
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

要求和回應範例

下列各節提供端點的要求範例。

擷取即時通訊的所有影片網址

這個範例示範如何擷取現有對話的所有影片網址。

要求

標題：

鍵	值	說明
接受	application/json

查詢：

鍵	值	說明
chat_id	整數	(必填)

回應

[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

狀態碼：200

取得預先簽署的影片上傳網址

用於取得影片的預先簽署上傳網址。

參數	必填	資料類型	定義
chat_id	TRUE	整數	必要聊天室 ID，將與預先簽署的影片網址建立關聯。

端點：

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos/upload

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

要求和回應範例

下列各節提供端點的要求範例。

成功擷取影片上傳的簽署網址

以下是成功要求範例，可擷取影片上傳的簽署網址。

要求

標題：

鍵	值	說明
接受	application/json

查詢：

鍵	值	說明
chat_id	整數	(必填)

回應

{
    "url": "string",
    "fields": {
        "key": "string",
        "success_action_status": "string",
        "Content-Type": "string",
        "Cache-Control": "string",
        "acl": "string",
        "policy": "string",
        "x-amz-credential": "string",
        "x-amz-algorithm": "string",
        "x-amz-date": "string",
        "x-amz-security-token": "string",
        "x-amz-signature": "string",
        "x-goog-algorithm": "string",
        "x-goog-credential": "string",
        "x-goog-date": "string",
        "x-goog-signature": "string"
    }
}

狀態碼：200

建立即時通訊

發起新的即時通訊工作階段。

要求範例

方法：POST

網址：https://{subdomain}.{domain}/apps/api/v1/chats

標頭

鍵	值	說明
Content-Type	application/json
接受	application/json

內文

{
    "chat": {
        "menu_id": "integer",
        "end_user_id": "integer",
        "lang": "string",
        "email": "string",
        "context": "object",
        "transcript": "object"
    },
    "end_user": {
        "phone": "string"
    }
}

背景資訊：

context 物件包含 value 物件，可將中繼資料傳遞至即時通訊對話。您可以將 context 物件做為未簽署的資料參數傳遞至虛擬代理程式。請參閱以下範例：

{
    "context": {
        {"value":
            {"foo": "bar",
             "key": "value"}
        }
    }
}

在本例中，傳入欄位的未簽署資料參數值為 context，目的地欄位可設為 context。這樣您就能使用 $session.params.context.foo 或 $session.params.context.key。

回覆範例

{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

依 ID 傳回對話

這個方法會傳回指定即時通訊 ID 的即時通訊物件。

端點：

Method: GET
Type:
URL: https://{subdomain}.​{domain}/apps/api/v1/chats/:id

標題：

鍵	值	說明
Content-Type	application/json
接受	application/json

查詢：

鍵	值	說明
chat_id	整數	(必填)

要求和回應範例

下列各節提供端點的要求範例。

成功擷取對話

以下範例顯示現有即時通訊 ID 的要求成功。

要求

標題：

鍵	值	說明
內容類型	application/json
接受	application/json

查詢：

鍵	值	說明
chat_id	整數	(必填)

回應

{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

狀態碼：200

在即時通訊期間取得保留的資料屬性

端點

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/customer_flag

要求和回應範例

本節包含端點的範例要求和回應。

成功

這個範例顯示呼叫成功。

要求

標題

鍵	值	說明
接受	application/json

網址變數

鍵	值	說明
id	整數	(必填)

回應

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

狀態碼 0

在即時通訊期間更新保留的資料屬性

端點

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/customer_flag

網址變數

鍵	值	說明
id	整數	(必填)

內文

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customers": "boolean"
}

在即時通訊中傳送自訂資料

在對話中傳送自訂資料。

要求範例

方法：POST

網址：https//{subdomain}.{domain}/apps/api/v1/chats/:id/custom_data

標頭

金鑰	值	說明
Content-Type	application/json

網址變數

金鑰	值	說明
id		(必要)

回覆範例

// Use unsecured parameter
{
"signed": false,
"data": {
// Start customer_flag fields
"reserved_verified_customer": {
"label": "LABEL 1",
"value": true
},
"reserved_bad_actor": {
"label": "LABEL 2",
"value": false
},
"reserved_repeat_customer": {
"label": "LABEL 3",
"value": true
},
// End customer_flag fields
"field1": {
"label": "LABEL 4",
"value": "dummy1"
},
"field2": {
"label": "LABEL 5",
"value": "dummy2"
}
}
}
// Use secured parameter
// {
// "signed": true,
// "signed_data": "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21fZGF0YSI6eyJyZXNlcnZlZF92ZXJpZmllZF9jdXN0b21lciI6eyJ2YWx1ZSI6ZmFsc2V9LCJyZXNlcnZlZF9iYWRfYWN0b3IiOnsidmFsdWUiOnRydWV9LCJyZXNlcnZlZF9yZXBlYXRfY3VzdG9tZXIiOnsidmFsdWUiOmZhbHNlfSwiZmllbGQxIjp7InZhbHVlIjoiZHVtbXkxMTEifSwiZmllbGQyIjp7InZhbHVlIjoiZHVtbXkyMjIifX0sImV4cCI6MTcyOTY4MzU5MywiaWF0IjoxNzI5Njc5OTkzfQ.BMskgKTM3DbgrMLWjI46ZJ1K73H25JRd16SgHK0A1Ts"
// }
// ======================= How to create <signed_data> =======================
// payload = {
// "custom_data": {
// // Start customer_flag fields
// "reserved_verified_customer": {
// "label": "LABEL 1",
// "value": true
// },
// "reserved_bad_actor": {
// "label": "LABEL 2",
// "value": false
// },
// "reserved_repeat_customer": {
// "label": "LABEL 3",
// "value": true
// },
// // End customer_flag fields
// "field1": {
// "label": "LABEL 4",
// "value": "dummy1"
// },
// "field2": {
// "label": "LABEL 5",
// "value": "dummy2"
// }
// },
// "exp": 1734567890, // expiration timestamp
// "iat": 1734560000 // issue timestamp
// }
// signed_data = JWT.encode(payload, 'Company secret', 'HS256')
// ======================= End how to create <signed_data> =======================

在進行中的即時通訊工作階段中更新使用者

更新與目前有效即時通訊工作階段相關聯的終端使用者。 此外，這項功能也會更新與 CRM 服務單連結的聯絡資訊。 _Identifier 為必填欄位，name、email 和 phone 則為選填欄位。

注意： 如果已設定電話號碼，提供電話參數不會更新電話號碼。

要求範例

方法：POST

網址：https//{subdomain}.{domain}/apps/api/v1/chats/:chat_id/end-user

標頭

金鑰	值	說明
Content-Type	application/json

網址變數

金鑰	值	說明
chat_id

內文

{
    "identifier": "string",
    "name": "string",
    "email": "string",
    "phone": "string"
}

回覆範例

{
    "message": "accepted"
}