呼叫 API 端點可提供呼叫物件的存取權。系統會為撥打至 Contact Center AI 平台 (CCAI 平台) 和從該平台撥出的每通電話建立通話物件。
以下是通話 API 端點：
通話物件
以下是通話物件的範例：
[
{
"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 並結束時，就會發生這個狀態 |
| 碰到其他球員後轉向 | 根據過量佇列或下班後通話的設定而發生的狀態。轉接選項包括語音信箱、安排通話時間等。轉移率會因管道 (應用程式內、IVR、網頁內) 而異 |
| 語音留言 | 使用者轉接至語音信箱選項，並選擇留言供日後收聽時，就會進入這個狀態。使用者留言時會處於這個狀態 |
| 已收到語音留言 | 終端使用者留下語音留言後，服務專員尚未收聽語音留言時的狀態 |
| 已讀取語音留言 | 服務專員開啟語音留言並聆聽時的狀態。 |
通話類型定義
call_type 欄位只能是下列其中一個值：
| 通話類型 | 說明 |
|---|---|
| 語音外撥 (API) | 透過 Outbound Call API 撥打的電話。 |
| Voice Inbound (API) | 透過 Incoming Call API 發出的呼叫。 |
| Voice Scheduled (API) | 透過 Scheduled Call API 發出的通話。 |
常見的 API 回應代碼
以下是最常見的 API 回應：
| 回應代碼 | 意義 |
|---|---|
| 201 | API 要求已成功，系統將建立通話 |
| 202 | API 要求已成功，但必須在小工具中手動介入，才能完成動作 |
| 400 | 無效的通話類型 - 請確認系統支援 call_type |
| 400 | 專員無法接聽這通電話 |
| 400 | 缺少參數 - 請檢查是否已新增必要參數 |
| 404 | 找不到資源 - 請檢查子網域 |
撥出電話 - end_user_number
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| call_tye | TRUE | 字串 | 呼叫型別即可建立。目前可使用「Voice Outbound (API)」、「OutboundCall」(已淘汰) |
| agent_email | TRUE | 字串 | 將指派處理撥出電話的服務專員電子郵件地址。 |
| ticket_id | FALSE | 字串 | 客戶關係管理系統工單 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
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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"
}
要求和回應範例
下列各節提供端點的要求範例。
錯誤：專員無法接聽這通電話
這個範例說明專員無法接聽電話時的失敗情境。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
使用使用者號碼撥出電話
本範例說明如何撥打特定使用者號碼的外撥電話。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 建立撥出電話。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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"
}
回應：Create an outbound call with 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 或使用者號碼，但未提供。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
回應：錯誤：必須提供 ticket_id 或 end_user_number
{
"message": "ticket_id or end_user_number required"
}
狀態碼：400
錯誤：代理商電子郵件地址無效
這個範例會說明代理商提供的電子郵件地址無效時，系統會如何失敗。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：必須提供代理商電子郵件地址
這個範例說明未提供代理商電子郵件地址時發生的失敗情形。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
回覆：錯誤：必須提供服務專員的電子郵件地址
{
"message": "Agent email required"
}
狀態碼：400
錯誤：代理程式無法撥打電話
這個範例說明指定代理程式沒有撥出電話的權限時，會發生什麼情況。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
Error : end_user_number is not well-formed
這個範例說明失敗情境，即提供的使用者號碼格式不正確。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：找不到聯絡人
這個範例說明提供的聯絡人不存在時的失敗情況。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
已接受：必須選擇去電號碼
在本例中，系統會接受撥出電話，但專員必須先選擇要使用的撥出號碼，才能撥打電話。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：通話類型無效
這個範例說明呼叫類型無效時的失敗情況。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
透過多個去電號碼提示通話轉接器
在這種情況下，通話轉接器會收到多個外撥號碼的提示。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 撥打外撥電話。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
狀態碼：202
Outbound Call - ticket_id
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| call_type | TRUE | 字串 | 要建立的通話類型。目前可使用「Voice Outbound (API)」、「OutboundCall」(已淘汰) |
| agent_email | TRUE | 字串 | 將指派處理撥出電話的服務專員電子郵件地址。 |
| ticket_id | FALSE | 字串 | 客戶關係管理系統工單 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
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 或使用者編號遺失，但這些資訊是必要欄位，因此會導致失敗。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
回應：錯誤：必須提供 ticket_id 或 end_user_number
{
"message": "ticket_id or end_user_number required"
}
狀態碼：400
錯誤：必須提供代理商電子郵件地址
在這個範例中，我們顯示代理商電子郵件未提供但為必要資訊的失敗情境。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
回覆：錯誤：必須提供服務專員的電子郵件地址
{
"message": "Agent email required"
}
狀態碼：400
使用使用者號碼撥出電話
在這個範例中，我們將說明如何提供使用者號碼來建立撥出電話。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：通話類型無效
在這個範例中，我們顯示呼叫類型無效的失敗情境。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
透過多個去電號碼提示通話轉接器
在這個範例中，我們將說明如何使用多個外撥電話號碼提示通話轉接程式。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 撥打外撥電話，以及專員如何接受要求。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 建立外撥電話。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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"
}
回應：Create an outbound call with 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
已接受：必須選擇去電號碼
在這個範例中，我們顯示建立外撥電話要求的情境，需要選擇外撥號碼，然後接受要求。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Outbound (API)",
"agent_email": "allen@somedomain.com",
"end_user_number": "+1 205-123-4567",
"lang": "en"
}
狀態碼：202
錯誤：專員無法接聽這通電話
在這個範例中，我們顯示通話建立失敗的情境，也就是建立通話後，專員無法接聽。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：使用者號碼格式不正確
在這個範例中，我們顯示失敗情境，也就是提供的使用者電話號碼格式不正確。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：代理商電子郵件地址無效
在這個範例中，我們顯示提供的代理商電子郵件地址無效時的失敗情境。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：找不到聯絡人
在這個範例中，我們顯示找不到所提供聯絡人的失敗情境。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 | 字串 | 客戶關係管理系統的案件 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
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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"
}
要求和回應範例
下列各節提供端點的要求範例。
錯誤：使用者號碼格式不正確
在這個範例中，我們顯示失敗情境，也就是建立來電，但提供的使用者號碼格式不正確。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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，但該選單處於手動重新導向狀態，因此無法接聽來電。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：通話類型無效
在本範例中，我們會顯示失敗情境，也就是建立來電，但提供的通話類型無效。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 無效。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
使用使用者號碼建立來電
這個範例說明如何使用特定使用者號碼建立來電。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 處於營業時間外狀態時，會發生失敗情況。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：不支援這個語言
這個範例會示範指定語言不可用時的失敗要求。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：找不到語言
這個範例說明找不到所提供語言時發生的失敗情況。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 時會發生的失敗情況。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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"
}
回應：Error : menu_id is not found
{
"message": "menu_id 9999 is not found"
}
狀態碼：400
錯誤：menu_id 格式不正確
這個範例會說明提供的菜單 ID 不正確時，系統會如何回報失敗。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：必須提供使用者號碼
在這個範例中，我們顯示失敗情境，也就是已建立來電，但未提供使用者電話號碼。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"call_type": "Voice Inbound (API)",
"lang": "en",
"menu_id": 9,
"recording_permission": "recording_permission_granted"
}
回應：Error : end_user_number is required
{
"message": "end_user_number is required"
}
狀態碼：400
預約通話
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| call_type | TRUE | 字串 | 要建立的通話類型。使用「Voice Scheduled (API)」或「ScheduledCall」(已淘汰) 建立排程通話。 |
| menu_id | TRUE | 整數 | 要將通話歸因於哪個選單的 ID。系統只接受行動版和網站選單 ID。 |
| call_id | FALSE | 整數 | 先前通話的 ID，系統會將其連結為新建立的預約通話的父項通話。使用通話 ID 時，menu_id 為選填。 |
| end_user_number | TRUE | 字串 | 要撥打的電話號碼。如果同時傳入 ticket_id 和 end_user_number，系統會優先採用 ticket_id。 |
| lang | FALSE | 字串 | 通話語言。使用 ISO 639-1 代碼。(預設值為「en」) |
| ticket_id | FALSE | 字串 | 客戶關係管理系統的案件 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
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 格式不正確而導致的失敗。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 設為選單重新導向，且無法接聽電話時發生的失敗情況。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：通話類型無效
這個範例說明要求無效且呼叫類型無效時發生的失敗情形。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 時的要求和回應。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 時，要求會失敗。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 建立預約通話。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 建立預約通話。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：菜單處於「非營業時間」狀態，無法接聽來電
在這個範例中，我們顯示排定通話時間但提供的菜單不在營業時間內，因此無法接聽來電的失敗情境。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：不支援這個語言
這個範例會說明指定無效語言時發生的失敗情況。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：找不到語言
在這個範例中，我們顯示排定通話建立後，語言無效或無法使用的失敗情境。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 無效且找不到。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 格式不正確。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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
錯誤：必須提供使用者號碼
在這個例子中，我們顯示的是失敗情境，也就是已建立排定的通話，但未提供使用者號碼。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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"
}
回應：Error : end_user_number is required
{
"message": "end_user_number is required"
}
狀態碼：400
錯誤：必須提供 scheduled_at
在這個範例中，我們顯示失敗情境，也就是已建立排定通話，但缺少必要排定時間值。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| 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 在通話期間將資料參數傳遞至虛擬服務專員，請參閱「在通話期間將資料參數傳遞至虛擬服務專員」。