通話 API 端點可讓您存取通話物件。每當有來電或去電，Contact Center AI 平台 (CCAI Platform) 都會建立通話物件。
以下是通話 API 端點：
Call 物件
以下是呼叫物件的範例：
[
{
"id": 0,
"parent_id": 0,
"lang": "en",
"call_type": "Voice Scheduled (API)",
"status": "scheduled",
"created_at": "2018-06-07T19:49:52.896Z",
"queued_at": "2018-06-07T19:49:52.896Z",
"assigned_at": "2018-06-07T19:49:52.896Z",
"connected_at": "2018-06-07T19:49:52.896Z",
"ends_at": "2018-06-07T19:49:52.896Z",
"scheduled_at": "2018-06-07T19:49:52.896Z",
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": 0,
"has_feedback": true,
"voip_provider": "voip_provider_twilio",
"out_ticket_id": "string",
"out_ticket_url": "string",
"verified": true,
"recording_url": "string",
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_details": "string",
"fail_reason": "nothing",
"support_number": "string",
"selected_menu": {
"id": 0,
"name": "string",
"parent_id": 0,
"position": 0,
"deleted": true,
"hidden": "string",
"menu_type": "ivr_menu",
"output_msg": "string"
},
"menu_path": {
"items_count": 0,
"name": "string",
"materialized_path": "string"
},
"agent_info": {
"id": 0,
"name": "string",
"last_name": "string",
"first_name": "string",
"agent_number": "string",
"avatar_url": "string"
},
"end_user": {
"id": 0,
"identifier": "string",
"out_contact_id": "string"
},
"photos": [
{
"id": 0,
"photo_type": "photo",
"url": "string"
}
],
"videos": [
{
"id": 0,
"url": "string"
}
],
"transfers": [
{
"id": 0,
"status": "transferring",
"fail_reason": "nothing",
"created_at": "2018-06-07T19:49:52.896Z",
"from_menu": {
"items_count": 0,
"name": "string",
"materialized_path": "string"
},
"to_menu": {
"items_count": 0,
"name": "string",
"materialized_path": "string"
},
"from_agent": {
"id": 0,
"name": "string",
"last_name": "string",
"first_name": "string",
"agent_number": "string",
"avatar_url": "string"
},
"to_agent": {
"id": 0,
"name": "string",
"last_name": "string",
"first_name": "string",
"agent_number": "string",
"avatar_url": "string"
}
}
],
"participants": [
{
"id": 0,
"type": "end_user",
"status": "waiting",
"call_id": 0,
"user_id": 0,
"end_user_id": 0,
"call_duration": 0,
"hold_duration": 0,
"connected_at": "2018-06-07T19:49:52.896Z",
"ended_at": "2018-06-07T19:49:52.896Z",
"fail_reason": "nothing"
}
]
}
]
通話狀態定義
狀態欄位可能顯示下列任一狀態：
| 通話狀態 | 說明 |
|---|---|
| 選取中 | 使用者撥入客服中心，但仍在瀏覽選單選項，尚未進入葉選單。 |
| 已排入佇列 | 使用者選取葉選單節點，並發出呼叫要求，要將呼叫要求傳送或多點傳送給代理，就會進入這個狀態。 |
| 已指派 | 選取服務專員接聽使用者來電時，就會進入這個狀態。當服務專員接聽來電時，就會發生這種情況。 |
| 連線中 | 指派服務專員後，使用者與服務專員建立連線時的狀態。 |
| 已連線 | 通話已建立連線，且服務專員和使用者都已加入通話時，就會進入這個狀態。 |
| 已完成 | 通話接通後結束的狀態。 |
| 失敗 | 通話在成功連線前結束時的狀態。並提供失敗原因，供您參考。 |
| 切換中 | 嘗試連線時通話失敗，且 CCAI Platform 嘗試透過其他 VOIP 供應商連線通話時，就會發生這種狀態。 |
| 已復原 | 回撥失敗通話時的狀態。這項新呼叫是原始呼叫的子項。已復原的附註，表示回呼已完成，未發生錯誤。 |
| 已排定 | 使用者透過網頁或應用程式安排日後通話時，就會進入這個狀態。 |
| 僅限動作 | 當客戶自有電話服務供應商處理的通話連線至我們的 iOS 或 Android SDK 時，就會進入這個狀態。 |
| 僅限已完成的動作 | 由客戶的電話服務供應商處理的通話，在連線至 iOS 或 Android SDK 並結束時，會進入這個狀態 |
| 碰到其他球員後轉向 | 根據超額佇列或非上班時間來電的設定，所產生的狀態。轉移選項包括語音留言、預約通話等。轉移率會因管道而異 (應用程式內、互動式語音應答、網頁內) |
| 語音留言 | 使用者轉接至語音留言選項，並選擇留下語音留言供日後聆聽時，就會進入這個狀態。使用者留言時，系統會顯示這個狀態 |
| 已收到語音留言 | 使用者留下語音留言後，服務專員尚未聽取留言的狀態 |
| 語音留言讀取 | 服務專員開啟語音留言聆聽時的狀態。 |
呼叫類型定義
call_type 欄位只能是下列其中一個值：
| 通話類型 | 說明 |
|---|---|
| Voice Outbound (API) | 透過 Outbound Call API 撥打的電話。 |
| Voice Inbound (API) | 透過 Incoming Call API 撥打的電話。 |
| 語音排定 (API) | 透過 Scheduled Call API 撥打的電話。 |
常見的 API 回應代碼
以下是最常見的 API 回應：
| 回應代碼 | 意義 |
|---|---|
| 201 | API 要求已成功，將建立通話 |
| 202 | API 要求已成功，但必須在小工具中手動介入才能完成動作 |
| 400 | 呼叫類型無效 - 請確認 call_type 受到支援 |
| 400 | 服務專員無法接聽這通電話 |
| 400 | 缺少參數：請確認已新增必要參數 |
| 404 | 找不到資源 - 請檢查子網域 |
外撥通話 - end_user_number
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| call_tye | TRUE | 字串 | 呼叫 tye 即可建立。目前可使用「Voice Outbound (API)」和「OutboundCall」(已淘汰) |
| agent_email | TRUE | 字串 | 指派給外撥通話的服務專員電子郵件地址。 |
| ticket_id | FALSE | 字串 | CRM 支援單 ID，系統就會撥號給與支援單相關聯的使用者。 |
| end_user_number | FALSE | 字串 | 要撥打的使用者電話號碼。ticket_id 的優先順序高於 end_user_number。 |
| outbound_number | FALSE | 字串 | 格式正確的外撥號碼，可透過「設定」>「電話號碼」>「電話號碼管理」進行管理。如果留空，系統會使用預設撥出號碼 |
| lang | FALSE | 字串 | 通話語言。使用 ISO 639-1 代碼。(預設值：「en」) |
端點：
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "agent@somedomain.com",
"outbound_number": "+1 760-867-5309",
"end_user_number": "123123",
"lang": "en"
}
要求和回應範例
以下各節提供傳送至端點的要求範例。
錯誤：服務專員無法接聽這通電話
這個範例說明服務專員無法接聽來電時的失敗情境。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "agent@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
回覆：錯誤：服務專員無法接聽這通電話
{
"message": "Agent is not available to take this call"
}
狀態碼：400
使用使用者號碼建立外撥通話
這個範例說明如何撥打外撥通話給特定使用者號碼。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 859-657-9625",
"outbound_number": "+1 339-219-5276",
"lang": "en"
}
回覆：使用 end_user_number 建立外撥通話
{
"id": 397,
"lang": "en",
"call_type": "Voice Outbound (API)",
"status": "assigned",
"created_at": "2019-06-07T01:27:30.406Z",
"queued_at": null,
"assigned_at": "2019-06-07T01:27:30.441Z",
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"voip_provider": "voip_provider_twilio",
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": null,
"menu_path": null,
"agent_info": {
"id": 1,
"agent_number": null,
"name": "Admin UJET",
"last_name": "UJET",
"first_name": "Admin",
"avatar_url": "https://somedomain.com/avatar.jpg"
},
"end_user": null,
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 610,
"type": "agent",
"status": "waiting",
"call_id": 397,
"user_id": 1,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
},
{
"id": 611,
"type": "end_user",
"status": "waiting",
"call_id": 397,
"user_id": null,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": null,
"offer_events": [],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
狀態碼：201
使用票證 ID 建立外撥通話
這個範例示範如何建立具有特定票證 ID 的外撥通話。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "agent@somedomain.com",
"ticket_id": "71450",
"outbound_number": "+1 339-219-5276",
"lang": "en"
}
回覆：建立外撥通話並附上 ticket_id
{
"id": 398,
"lang": "en",
"call_type": "Voice Outbound (API)",
"status": "assigned",
"created_at": "2019-06-07T01:28:47.955Z",
"queued_at": null,
"assigned_at": "2019-06-07T01:28:47.971Z",
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"voip_provider": "voip_provider_twilio",
"out_ticket_id": "71450",
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": null,
"menu_path": null,
"agent_info": {
"id": 1,
"agent_number": null,
"name": "Admin UJET",
"last_name": "UJET",
"first_name": "Admin",
"avatar_url": "https://somedomain.com/avatar.png"
},
"end_user": {
"id": 67,
"identifier": null,
"out_contact_id": "381630957514"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 612,
"type": "agent",
"status": "waiting",
"call_id": 398,
"user_id": 1,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
},
{
"id": 613,
"type": "end_user",
"status": "waiting",
"call_id": 398,
"user_id": null,
"end_user_id": 67,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": null,
"offer_events": [],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
狀態碼：201
錯誤：必須提供支援單 ID 或使用者號碼
這個範例說明失敗案例，其中票證 ID 或使用者號碼為必要資訊，但未提供。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
Response: Error : ticket_id or end_user_number required
{
"message": "ticket_id or end_user_number required"
}
狀態碼：400
錯誤：代理電子郵件地址無效
這個範例說明提供的代理電子郵件地址無效時，會發生失敗。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
回應：錯誤：不是有效的服務專員電子郵件
{
"message": "Not a valid agent email"
}
狀態碼：400
錯誤：必須提供服務專員電子郵件地址
這個範例說明未提供代理電子郵件地址時，會發生失敗。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
Response: Error : Agent email required
{
"message": "Agent email required"
}
狀態碼：400
錯誤：代理沒有撥打電話的權限
這個範例說明當指定的代理不允許撥出電話時，會發生失敗。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
回覆：錯誤：代理沒有撥打電話的權限
{
"message": "Agent does not have access to make calls"
}
狀態碼：400
錯誤：end_user_number 格式不正確
這個範例示範失敗情境，其中提供的使用者號碼格式不正確。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"end_user_number": "123123",
"lang": "en"
}
回應：錯誤：end_user_number 格式不正確
{
"message": "end_user_number is not well-formed"
}
狀態碼：400
錯誤：找不到聯絡人
這個範例示範了提供的聯絡人不存在時的失敗情境。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"ticket_id": 1,
"lang": "en"
}
回覆：錯誤：找不到聯絡人
{
"message": "Contact not found"
}
狀態碼：400
已接受：需要選擇撥出號碼
在這個範例中，外撥通話會被接受，但服務專員必須先選擇要使用的外撥號碼，才能撥打電話。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "agent@somedomain.com",
"outbound_number": "+1 760-867-5309",
"end_user_number": "123123",
"lang": "en"
}
回應
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
狀態碼：200
錯誤：呼叫類型無效
這個範例示範提供的呼叫類型無效時，失敗的情境。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"end_user_number": "123123",
"lang": "en"
}
回應：錯誤：呼叫類型無效
{
"message": "Invalid call type"
}
狀態碼：400
透過多個去電號碼提示通話轉接器
在這種情況下，通話轉接器會顯示多個外撥號碼。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "agent@somedomain.com",
"outbound_number": "+1 760-867-5309",
"end_user_number": "123123",
"lang": "en"
}
回應
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 859-657-9625",
"lang": "en"
}
狀態碼：200
已接受：服務專員必須撥打外撥通話，並提供支援單 ID
這個範例示範的要求，是代理必須根據提供的票證 ID 撥打外撥通話。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
狀態碼：202
外撥通話 - ticket_id
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| call_type | TRUE | 字串 | 要建立的通話類型。目前可使用「Voice Outbound (API)」和「OutboundCall」(已淘汰) |
| agent_email | TRUE | 字串 | 指派給外撥通話的服務專員電子郵件地址。 |
| ticket_id | FALSE | 字串 | CRM 支援單 ID，系統就會撥號給與支援單相關聯的使用者。 |
| end_user_number | FALSE | 字串 | 要撥打的使用者電話號碼。ticket_id 的優先順序高於 end_user_number。 |
| outbound_number | FALSE | 字串 | 格式正確的外撥號碼，可透過「設定」>「電話號碼」>「電話號碼管理」進行管理。如果留空，系統會使用預設撥出號碼 |
| lang | FALSE | 字串 | 通話語言。使用 ISO 639-1 代碼。(預設值：「en」) |
端點：
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-867-5309",
"ticket_id": "123123",
"lang": "en"
}
要求和回應範例
以下各節提供傳送至端點的要求範例。
錯誤：必須提供支援單 ID 或使用者號碼
在這個範例中，失敗情境是缺少必要的票證 ID 或使用者號碼。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
Response: Error : ticket_id or end_user_number required
{
"message": "ticket_id or end_user_number required"
}
狀態碼：400
錯誤：必須提供服務專員電子郵件地址
在這個範例中，我們展示了未提供必要代理電子郵件的失敗情境。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
Response: Error : Agent email required
{
"message": "Agent email required"
}
狀態碼：400
使用使用者號碼建立外撥通話
在這個範例中，我們會說明如何提供使用者號碼，建立外撥通話。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 859-657-9625",
"outbound_number": "+1 339-219-5276",
"lang": "en"
}
回覆：使用 end_user_number 建立外撥通話
{
"id": 397,
"lang": "en",
"call_type": "Voice Outbound (API)",
"status": "assigned",
"created_at": "2019-06-07T01:27:30.406Z",
"queued_at": null,
"assigned_at": "2019-06-07T01:27:30.441Z",
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"voip_provider": "voip_provider_twilio",
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reaso": "not_voicemail",
"deflection": "n_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": null,
"menu_path": null,
"agent_info": {
"id": 1,
"agent_number": null,
"name": "Admin UJET",
"last_name": "UJET",
"first_name": "Admin",
"avatar_url": "https://somedomain.com/default-profile.png"
},
"end_user": null,
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 610,
"type": "agent",
"status": "waiting",
"call_id": 397,
"user_id": 1,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
},
{
"id": 611,
"type": "end_user",
"status": "waiting",
"call_id": 397,
"user_id": null,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": null,
"offer_events": [],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
狀態碼：201
錯誤：呼叫類型無效
在這個範例中，我們展示了提供的呼叫類型無效時的失敗情境。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "ScheduledCall",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"end_user_number": "123123",
"lang": "en"
}
回應：錯誤：呼叫類型無效
{
"message": "Invalid call type"
}
狀態碼：400
透過多個去電號碼提示通話轉接器
在這個範例中，我們會說明如何使用多個外撥電話號碼提示通話轉接器。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 859-657-9625",
"lang": "en"
}
狀態碼：202
已接受：服務專員必須撥打外撥通話，並提供支援單 ID
在這個範例中，我們將說明如何使用票證 ID 撥打外撥通話，以及服務專員接受要求。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
回覆：錯誤：代理沒有撥打電話的權限
{
"message": "Agent does not have access to make calls"
}
狀態碼：400
使用票證 ID 建立外撥通話。
在這個範例中，我們示範如何使用票證 ID 建立外撥通話。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"ticket_id": "71450",
"outbound_number": "+1 339-219-5276",
"lang": "en"
}
回覆：建立外撥通話並附上 ticket_id
{
"id": 398,
"lang": "en",
"call_type": "Voice Outbound (API)",
"status": "assigned",
"created_at": "2019-06-07T01:28:47.955Z",
"queued_at": null,
"assigned_at": "2019-06-07T01:28:47.971Z",
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"voip_provider": "voip_provider_twilio",
"out_ticket_id": "71450",
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": null,
"menu_path": null,
"agent_info": {
"id": 1,
"agent_number": null,
"name": "Admin UJET",
"last_name": "UJET",
"first_name": "Admin",
"avatar_url": "https://somedomain.com/default-profile.png"
},
"end_user": {
"id": 67,
"identifier": null,
"out_contact_id": "381630957514"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 612,
"type": "agent",
"status": "waiting",
"call_id": 398,
"user_id": 1,
"end_user_id": null,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
},
{
"id": 613,
"type": "end_user",
"status": "waiting",
"call_id": 398,
"user_id": null,
"end_user_id": 67,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": null,
"offer_events": [],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
狀態碼：201
已接受：需要選擇撥出號碼
在這個範例中，我們展示了建立外撥通話要求、選擇外撥號碼，然後接受要求的流程。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
狀態碼：202
錯誤：服務專員無法接聽這通電話
在這個範例中，我們展示了失敗情境，即通話已建立，但服務專員無法接聽。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
回覆：錯誤：服務專員無法接聽這通電話
{
"message": "Agent is not available to take this call"
}
狀態碼：400
錯誤：使用者號碼格式不正確
在這個範例中，我們展示了使用者提供的電話號碼格式不正確，導致失敗的情境。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"end_user_number": "123123",
"lang": "en"
}
回應：錯誤：end_user_number 格式不正確
{
"message": "end_user_number is not well-formed"
}
狀態碼：400
錯誤：代理電子郵件地址無效
在這個範例中，我們展示了提供的代理電子郵件無效時的失敗情境。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "admin@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
回應：錯誤：不是有效的服務專員電子郵件
{
"message": "Not a valid agent email"
}
狀態碼：400
錯誤：找不到聯絡人
在這個範例中，我們展示了無法找到所提供聯絡人的失敗情境。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"outbound_number": "+1 760-410-8538",
"ticket_id": 1,
"lang": "en"
}
回覆：錯誤：找不到聯絡人
{
"message": "Contact not found"
}
狀態碼：400
來電
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| call_type | TRUE | 字串 | 要建立的通話類型。使用「Voice Inbound (API)」或「IncomingCall」(已淘汰) 建立來電。 |
| menu_id | TRUE | 整數 | 要歸因來電的選單 ID。系統只接受 IVR 和網頁選單 ID。 |
| end_user_number | TRUE | 字串 | 要撥打的使用者電話號碼。如果同時傳入 ticket_id 和 end_user_number，系統會優先採用 ticket_id。 |
| lang | FALSE | 字串 | 通話語言。使用 ISO 639-1 代碼。(預設值：「en」) |
| ticket_id | FALSE | 字串 | CRM 支援單 ID。系統會撥打與支援單連結的使用者電話號碼。如果同時傳入 ticket_id 和 end_user_number，系統會優先採用 ticket_id。 |
| outbound_number | FALSE | 字串 | 通話使用的撥出電話號碼。如果未傳入輸入內容或輸入內容無效，系統會使用預設的全域外撥電話號碼。如要管理外撥號碼，請依序前往「設定」>「佇列」>「編輯 / 查看」> 選取佇列 >「外撥電話號碼」。 |
| recording_permission | FALSE | 字串 | 只有在「通話錄音選項」功能設為「要求使用者授予錄音權限」時，系統才會評估這個值。如要設定，請依序前往「設定」>「佇列」>「編輯 / 查看」> 選取佇列 >「通話錄音選項」。如果值為「recording_permission_not_asked」(預設) 或「recording_permission_denied」，系統就不會錄製通話。如果值為「recording_permission_granted」，系統就會錄下通話內容。 |
端點：
Method: POST
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/calls
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"ticket_id": "76517",
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
要求和回應範例
以下各節提供傳送至端點的要求範例。
錯誤：使用者號碼格式不正確
在這個範例中，我們展示了失敗情境，其中建立了來電，但提供的使用者號碼格式不正確。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 999-657-12",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：end_user_number 格式不正確
{
"message": "end_user_number is not well formed"
}
狀態碼：400
錯誤：選單處於「手動重新導向」狀態，無法接聽來電
在這個範例中，我們展示了失敗情境：來電轉接至選單 ID，但選單處於手動重新導向狀態，因此無法接聽來電。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：選單處於「手動重新導向」狀態，無法接聽來電
{
"message": "Menu is in 'manual redirection' state, can't accept calls"
}
狀態碼：400
錯誤：呼叫類型無效
在本範例中，我們示範了失敗情境，其中建立了來電，但提供的通話類型無效。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "InvalidCallType",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：呼叫類型無效
{
"message": "Invalid call type"
}
狀態碼：400
錯誤：必須提供選單 ID
在這個範例中，我們展示了失敗情境：來電已建立，但提供的選單 ID 無效。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：必須提供 menu_id
{
"message": "menu_id is required"
}
狀態碼：400
錯誤：只能使用 IVR 和行動選單 ID
在本範例中，我們展示了失敗情境，其中建立了來電，但提供的選單 ID 不是 IVR 或行動選單 ID。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 50,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：只能使用 IVR 和行動選單 ID
{
"message": "Only IVR and mobile menu IDs are permitted"
}
狀態碼：400
使用使用者號碼建立來電
以下範例說明如何建立特定使用者號碼的來電。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+82-10-6861-2345",
"recording_permission": "recording_permission_granted"
}
回覆：使用 end_user_number 建立來電
{
"id": 515,
"lang": "en",
"call_type": "Voice Inbound (API)",
"status": "queued",
"created_at": "2019-09-10T00:19:14.000Z",
"queued_at": "2019-09-10T00:19:14.421Z",
"assigned_at": null,
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": {
"id": 9,
"name": "Lock Star",
"parent_id": null,
"position": 0,
"deleted": false,
"menu_type": "ivr_menu",
"output_msg": "You selected Lock Star.",
"hidden": false
},
"menu_path": {
"items_count": 1,
"name": "Lock Star",
"materialized_path": "9"
},
"agent_info": null,
"end_user": {
"id": 75,
"identifier": null,
"out_contact_id": "389391400633"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 820,
"type": "end_user",
"status": "waiting",
"call_id": 515,
"user_id": null,
"end_user_id": 75,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": "cascade",
"offer_events": [
{
"casting_time": "2019-09-10T00:19:14.000Z",
"group": "Group 1"
}
],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
狀態碼：201
錯誤：選單處於「非營業時間」狀態，無法接聽來電
這個範例說明提供的菜單 ID 處於非營業時間狀態時，會發生失敗。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：選單處於「非營業時間」狀態，無法接聽來電
{
"message": "Menu is in 'after hours' state, can't accept incoming calls"
}
狀態碼：400
錯誤：不支援這個語言
這個範例說明指定語言無法使用時，系統會傳送失敗要求。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "fr",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：不支援這個語言
{
"message": "Language 'fr' is not available"
}
狀態碼：400
建立來電並附上支援單 ID
以下範例說明如何建立與特定票證 ID 相關聯的來電。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"ticket_id": "76517",
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
回應：建立含有 ticket_id 的來電
{
"id": 519,
"lang": "en",
"call_type": "Voice Inbound (API)",
"status": "queued",
"created_at": "2019-09-10T05:12:26.000Z",
"queued_at": "2019-09-10T05:12:26.295Z",
"assigned_at": null,
"connected_at": null,
"ends_at": null,
"scheduled_at": null,
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"out_ticket_id": "76517",
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": {
"id": 9,
"name": "Lock Star",
"parent_id": null,
"position": 0,
"deleted": false,
"menu_type": "ivr_menu",
"output_msg": "You selected Lock Star.",
"hidden": false
},
"menu_path": {
"items_count": 1,
"name": "Lock Star",
"materialized_path": "9"
},
"agent_info": null,
"end_user": {
"id": 75,
"identifier": null,
"out_contact_id": "389391400633"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 826,
"type": "end_user",
"status": "waiting",
"call_id": 519,
"user_id": null,
"end_user_id": 75,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": "cascade",
"offer_events": [
{
"casting_time": "2019-09-10T05:12:26.000Z",
"group": "Group 1"
}
],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
狀態碼：201
錯誤：找不到語言
這個範例說明找不到指定語言時，系統會顯示失敗訊息。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "xy",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：找不到語言
{
"message": "Language 'xy' is not found"
}
狀態碼：400
錯誤：找不到 menu_id
這個範例說明找不到提供的菜單 ID 時，會發生什麼錯誤。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9999,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：找不到 menu_id
{
"message": "menu_id 9999 is not found"
}
狀態碼：400
錯誤：menu_id 格式不正確
這個範例說明提供的菜單 ID 不正確時，會發生失敗。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": "menu_999",
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：menu_id 格式不正確
{
"message": "menu_id is not well formed"
}
狀態碼：400
錯誤：必須提供使用者號碼
在這個範例中，我們展示了失敗情境，其中建立了來電，但未提供使用者電話號碼。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"recording_permission": "recording_permission_granted"
}
回應：錯誤：必須提供 end_user_number
{
"message": "end_user_number is required"
}
狀態碼：400
預約通話
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| call_type | TRUE | 字串 | 要建立的通話類型。使用「Voice Scheduled (API)」或「ScheduledCall」(已淘汰) 建立預約通話。 |
| menu_id | TRUE | 整數 | 要歸因來電的選單 ID。僅接受行動版和網頁版選單 ID。 |
| call_id | FALSE | 整數 | 先前通話的通話 ID，會連結為新建立排定通話的父項通話。使用 call ID 時，menu_id 為選填。 |
| end_user_number | TRUE | 字串 | 要撥打的使用者電話號碼。如果同時傳入 ticket_id 和 end_user_number，系統會優先採用 ticket_id。 |
| lang | FALSE | 字串 | 通話語言。使用 ISO 639-1 代碼。(預設值：「en」) |
| ticket_id | FALSE | 字串 | CRM 支援單 ID。系統會撥打與支援單連結的使用者電話號碼。如果同時傳入 ticket_id 和 end_user_number，系統會優先採用 ticket_id。 |
| scheduled_at | TRUE | 字串 | 排定的通話時間。請使用 ISO 8601 格式，並指定有效的未來時間。 |
| recording_permission | FALSE | 字串 | 只有在「通話錄音選項」功能設為「要求使用者授予錄音權限」時，系統才會評估這個值。如要設定，請依序前往「設定」>「佇列」>「編輯 / 查看」> 選取佇列 >「通話錄音選項」。如果值為「recording_permission_not_asked」(預設) 或「recording_permission_denied」，系統就不會錄製通話。如果值為「recording_permission_granted」，系統就會錄下通話內容。 |
端點：
Method: POST
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/calls
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"ticket_id": "76517",
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
要求和回應範例
以下各節提供傳送至端點的要求範例。
錯誤：end_user_number 格式不正確
這個範例說明因 end_user_namber 格式不正確而失敗。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 999-657-12",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：end_user_number 格式不正確
{
"message": "end_user_number is not well formed"
}
狀態碼：400
錯誤：選單處於「手動重新導向」狀態，無法接聽來電
這個範例示範當指定的選單 ID 設為選單重新導向，且無法接聽來電時，會發生失敗。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：選單處於「手動重新導向」狀態，無法接聽來電
{
"message": "Menu is in 'manual redirection' state, can't accept calls"
}
狀態碼：400
錯誤：呼叫類型無效
這個範例說明在提出要求且呼叫類型無效時，會發生失敗。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "InvalidCallType",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：呼叫類型無效
{
"message": "Invalid call type"
}
狀態碼：400
錯誤：必須提供 menu_id
這個範例說明未提供必要選單 ID 時，系統會傳送的要求和回應。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：必須提供 menu_id
{
"message": "menu_id is required"
}
狀態碼：400
錯誤：只能使用行動版和網頁版選單 ID
這個範例示範了當提供的選單 ID 不是網站或行動選單 ID 時，要求失敗的情況。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 50,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：僅允許行動和網頁選單 ID
{
"message": "Only mobile and web menu IDs are permitted"
}
狀態碼：400
使用選單 ID 建立排定的呼叫
以下範例說明如何使用特定選單 ID 建立排定的呼叫。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+82-10-6861-2345",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回覆：建立排定通話，並提供選單 ID
{
"id": 515,
"lang": "en",
"call_type": "Voice Inbound (API)",
"status": "queued",
"created_at": "2019-09-10T00:19:14.000Z",
"queued_at": null,
"assigned_at": null,
"connected_at": null,
"ends_at": null,
"scheduled_at": "2019-09-15T00:19:14.421Z",
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": {
"id": 9,
"name": "Lock Star",
"parent_id": null,
"position": 0,
"deleted": false,
"menu_type": "ivr_menu",
"output_msg": "You selected Lock Star.",
"hidden": false
},
"menu_path": {
"items_count": 1,
"name": "Lock Star",
"materialized_path": "9"
},
"agent_info": null,
"end_user": {
"id": 75,
"identifier": null,
"out_contact_id": "389391400633"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 820,
"type": "end_user",
"status": "waiting",
"call_id": 515,
"user_id": null,
"end_user_id": 75,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": "cascade",
"offer_events": [
{
"casting_time": "2019-09-10T00:19:14.000Z",
"group": "Group 1"
}
],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
狀態碼：201
使用通話 ID 建立排定的通話
以下範例說明如何建立具有特定通話 ID 的排定通話。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"call_id": 514,
"end_user_number": "+82-10-6861-2345",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回覆：建立排定通話並提供通話 ID
{
"id": 515,
"lang": "en",
"call_type": "Voice Inbound (API)",
"status": "queued",
"created_at": "2019-09-10T00:19:14.000Z",
"queued_at": null,
"assigned_at": null,
"connected_at": null,
"ends_at": null,
"scheduled_at": "2019-09-15T00:19:14.421Z",
"wait_duration": 0,
"call_duration": 0,
"hold_duration": 0,
"rating": null,
"has_feedback": false,
"out_ticket_id": null,
"out_ticket_url": null,
"verified": false,
"recording_url": null,
"recording_permission": "not_asked",
"voicemail_reason": "not_voicemail",
"deflection": "no_deflection",
"disconnected_by": "disconnected_by_unknown",
"fail_reason": "nothing",
"fail_details": null,
"support_number": null,
"selected_menu": {
"id": 9,
"name": "Lock Star",
"parent_id": null,
"position": 0,
"deleted": false,
"menu_type": "ivr_menu",
"output_msg": "You selected Lock Star.",
"hidden": false
},
"menu_path": {
"items_count": 1,
"name": "Lock Star",
"materialized_path": "9"
},
"agent_info": null,
"end_user": {
"id": 75,
"identifier": null,
"out_contact_id": "389391400633"
},
"photos": [],
"videos": [],
"transfers": [],
"deflection_details": [],
"participants": [
{
"id": 820,
"type": "end_user",
"status": "waiting",
"call_id": 515,
"user_id": null,
"end_user_id": 75,
"call_duration": null,
"hold_duration": null,
"connected_at": null,
"ended_at": null,
"fail_reason": "nothing"
}
],
"offer_type": "cascade",
"offer_events": [
{
"casting_time": "2019-09-10T00:19:14.000Z",
"group": "Group 1"
}
],
"answer_type": "manual",
"outbound_number": "+1 339-219-5276"
}
狀態碼：201
錯誤：選單處於「非營業時間」狀態，無法接聽來電
在這個範例中，我們展示了失敗情境：已建立排定的通話，但提供的選單不在營業時間內，因此無法接聽來電。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：選單處於「非營業時間」狀態，無法接聽來電
{
"message": "Menu is in 'after hours' state, can't accept incoming calls"
}
狀態碼：400
錯誤：不支援這個語言
這個範例說明指定語言無效時的失敗情況。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "fr",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：不支援這個語言
{
"message": "Language 'fr' is not available"
}
狀態碼：400
錯誤：找不到語言
在這個範例中，我們展示了失敗情境，其中建立了排定的通話，但語言無效或無法使用。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "xy",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：找不到語言
{
"message": "Language 'xy' is not found"
}
狀態碼：400
錯誤：找不到選單 ID
在這個範例中，我們展示了失敗情境：已建立排定的呼叫，但提供的選單 ID 無效且找不到。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9999,
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：找不到菜單 ID
{
"message": "menu_id 9999 is not found"
}
狀態碼：400
錯誤：選單 ID 格式不正確
在這個範例中，我們將示範失敗情境：已建立排定的呼叫，但提供的選單 ID 格式不正確。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": "menu_999",
"end_user_number": "+1 859-657-9625",
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：menu_id 格式不正確
{
"message": "menu_id is not well formed"
}
狀態碼：400
錯誤：必須提供使用者號碼
在這個範例中，我們展示了失敗情境，其中建立了排定的通話，但未提供使用者號碼。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"scheduled_at": "2019-09-15T00:19:14.421Z",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：必須提供 end_user_number
{
"message": "end_user_number is required"
}
狀態碼：400
錯誤：必須提供 scheduled_at
在這個範例中，我們展示了失敗情境：已建立排定的呼叫，但缺少必要的排定時間值。
要求
Headers:
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Scheduled (API)",
"lang": "en",
"menu_id": 9,
"end_user_number": "+1 859-657-9625",
"recording_permission": "recording_permission_granted"
}
回應：錯誤：必須提供 scheduled_at
{
"message": "scheduled_at is required"
}
狀態碼：400
在通話期間取得保留的資料屬性
端點
Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag
要求和回應範例
本節提供端點的要求和回應範例。
成功
這個範例顯示呼叫成功。
要求
網址變數
| 鍵 | 值 | 說明 |
|---|---|---|
| id | 整數 | (必填) |
回應
{
"verified_customer": "boolean",
"bad_actor": "boolean",
"repeat_customer": "boolean"
}
狀態碼 0
在通話期間更新保留的資料屬性
端點
Method: PATCH
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/calls/:id/customer_flag
網址變數
| 鍵 | 值 | 說明 |
|---|---|---|
| id | 整數 | (必填) |
內文
{
"verified_customer": "boolean",
"bad_actor": "boolean",
"repeat_customers": "boolean"
}
在工作階段中將資料參數傳遞給虛擬服務專員
如要使用應用程式 API，在通話期間將資料參數傳遞給虛擬服務專員，請參閱「在通話期間將資料參數傳遞給虛擬服務專員」。