所謂的「活動」是指外撥自動撥號器功能，可依序聯絡聯絡人清單中的對象、發起外撥電話，並將每位聯絡人轉接給可用的服務專員。廣告活動端點可存取廣告活動相關資料，並擷取廣告活動和聯絡人物件。
廣告活動物件代表平台中的單一廣告活動。
聯絡人物件代表特定廣告活動中的個別廣告活動聯絡人。
使用者可透過廣告活動端點，新增、更新及刪除現有廣告活動的聯絡人。可用的端點包括：
廣告活動聯絡人狀態
狀態欄位可能處於下列任一狀態：
| 廣告活動聯絡人狀態 | 說明 |
|---|---|
| 即將開始 | 系統即將撥打電話給聯絡人。 |
| 撥號 | 系統目前正在撥打電話給聯絡人。 |
| 已排入佇列 | 系統已將指定聯絡人的通話加入佇列。 |
| 已連線 | 聯絡人已與服務專員連線。 |
| 已完成 | 通話已結束。 |
| 已轉移 | 通話已轉接。 |
| 已轉移並完成 | 通話已轉接並結束。 |
| 尚未取貨 | 使用者未接聽電話或無法聯絡到使用者。 |
| 無法聯絡 | 電話並未接通。 |
| 聯絡人已放棄 | 預覽：使用者在與服務專員連線前掛斷電話。 無論是漸進式或預測式撥號，使用者在與服務專員通話後 5 秒內掛斷電話。 |
| 已略過 | 服務專員已略過聯絡人，但可與其他服務專員連線。 |
| 已略過並關閉 | 在「預覽」中，服務專員會略過並關閉聯絡人。這個廣告活動現在應該會一律略過這位聯絡人。 |
| 無效號碼 | 聯絡人的電話號碼無效。 |
| 貨運公司錯誤 | 這個錯誤是由電信業者造成。 |
| 撥號程式已放棄 | 撥號器已捨棄聯絡人。 |
| 語音信箱已掛斷 | 在預測模式下，撥號器會判斷使用者是機器 (即語音信箱)。 |
| 撥號程式一般錯誤 | 撥號器發生錯誤，因此通話失敗。 |
| 已排定重撥 | 暫時狀態。系統已排定在日後重撥。 |
| 請勿撥打 | 該號碼位於「謝絕來電」號碼清單中。 |
| 無效的外撥號碼 | 聯絡人使用的外撥號碼無效。 |
| 已封鎖的電話號碼 | 聯絡人有無效/遭封鎖的國際電話號碼。 |
將單一聯絡人新增至廣告活動
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| campaign_id | TRUE | 整數 | 要新增聯絡人的廣告活動 ID。 |
端點：
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
要求和回應範例
下列各節提供端點的要求範例。
將單一聯絡人新增至廣告活動
這個範例說明如何將聯絡人新增至特定廣告活動 ID。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
查詢：
| 鍵 | 值 | 說明 |
|---|---|---|
| campaign_id | 整數 | 要將聯絡人加入的廣告活動 ID |
內文：
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
回應
{
"valid_contacts": [
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
],
"invalid_contacts": []
}
狀態碼：200
取得廣告活動的聯絡人
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| campaign_id | TRUE | 整數 | 要從中擷取聯絡人的廣告活動 ID。 |
端點：
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
查詢：
| 鍵 | 值 | 說明 |
|---|---|---|
| campaign_id | 整數 | 要將聯絡人加入的廣告活動 ID |
要求和回應範例
下列各節提供端點的要求範例。
取得廣告活動的聯絡人
下列範例示範如何擷取指定廣告活動 ID 的聯絡人。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
查詢：
| 鍵 | 值 | 說明 |
|---|---|---|
| campaign_id | 整數 | 要查詢的廣告活動的廣告活動 ID |
回應
[
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
]
狀態碼：200
將多位聯絡人匯入廣告活動
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| 檔案 | TRUE | 字串 | 包含要新增至廣告活動的多位聯絡人的 JSON 檔案。 |
| campaign_id | TRUE | 整數 | 要將聯絡人加入的廣告活動 ID。 |
端點：
Method: POST
Type: FORM DATA
URL: https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts/import
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | multipart/form-data |
內文：
'FORM DATA'
檔案內容：
[
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
]
要求和回應範例
下列各節提供端點的要求範例。
從檔案匯入多個聯絡人
這個範例說明如何根據發布至端點的檔案，將聯絡人新增至廣告活動。檔案會以表單資料的形式發布。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | multipart/form-data |
查詢：
| 鍵 | 值 | 說明 |
|---|---|---|
| campaign_id | 整數 | 要將聯絡人新增至哪個廣告活動的 ID |
檔案內容：
[
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
]
回應
None
狀態碼：202 (已接受)
工作
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| job_id | TRUE | 整數 | 要擷取的工作 ID |
| campaign_id | TRUE | 整數 | 工作 ID 所屬的廣告活動 ID。 |
端點：
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts/jobs/{job_id}
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
要求和回應範例
下列各節提供端點的要求範例。
順利完成
以下範例說明如何擷取工作，並判斷工作是否已順利完成。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
查詢：
| 鍵 | 值 | 說明 |
|---|---|---|
| campaign_id | 1 | 這項工作所屬的廣告活動 ID |
| job_id | 530 | 要檢查狀態的工作 ID |
回應
{
"id": 530,
"status": "completed",
"type": "Jobs::Bulk::Campaign::ParentJob"
}
狀態碼：200
匯入作業仍在進行中
下列範例示範如何擷取工作，並判斷匯入作業是否仍在進行中。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
查詢：
| 鍵 | 值 | 說明 |
|---|---|---|
| campaign_id | 1 | 這項工作所屬的廣告活動 ID |
| job_id | 530 | 要檢查狀態的工作 ID |
回應
{
"id": 530,
"status": "in_progress",
"type": "Jobs::Bulk::Campaign::ParentJob"
}
狀態碼：200
失敗的工作
以下範例說明如何擷取工作，並判斷工作是否失敗。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
查詢：
| 鍵 | 值 | 說明 |
|---|---|---|
| campaign_id | 1 | 這項工作所屬的廣告活動 ID |
| job_id | 523 | 要檢查狀態的工作 ID |
回應
{
"error_details": "NativePowerDial::ContactService::DuplicateContactPhoneOnCampaign",
"error_message": "Internal Error",
"id": 523,
"status": "failed",
"type": "Jobs::Bulk::Campaign::StartImport"
}
狀態碼：200
更新單一聯絡人
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| campaign_id | TRUE | 整數 | 工作 ID 所屬的廣告活動 ID。 |
端點：
Method: PATCH
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contact
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"contact_id": 16312,
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"external_unique_id": "UID_123456"
}
要求和回應範例
下列各節提供端點的要求範例。
更新廣告活動的聯絡人
這個範例示範如何更新特定宣傳活動中的聯絡人。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"contact_id": 7,
"name": "Bob Smith",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"external_unique_id": "UID_123456"
}
回應
{
"id": 7,
"name": "Bob Smith",
"campaign_id": 6,
"assigned_call_id": null,
"assigned_participant_id": null,
"outbound_number": "+1-(201)-471-6992",
"priority": null,
"created_at": "2024-08-05T14:51:49.000Z",
"updated_at": "2024-08-05T21:01:16.000Z",
"status": "Upcoming",
"user_custom_metadata": {
"NAME (REQUIRED)": "Bob Smith",
"PHONE (REQUIRED)": "+1 111-111-1111",
"EMAIL (REQUIRED)": "customer@somedomain.com"
}
}
狀態碼：200
移除單一聯絡人
| 參數 | 必填 | 資料類型 | 定義 |
|---|---|---|---|
| campaign_id | TRUE | 整數 | 工作 ID 所屬的廣告活動 ID。 |
端點：
Method: DELETE
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contact
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"contact_id": integer,
"phone_number": "string",
"external_unique_id": "string"
}
要求和回應範例
下列各節提供端點的要求範例。
依聯絡人 ID 移除聯絡人
這個範例示範如何根據聯絡人的聯絡人 ID，從廣告活動中移除聯絡人。
要求
標題：
| 鍵 | 值 | 說明 |
|---|---|---|
| Content-Type | application/json |
內文：
{
"contact_id": 7,
}
查詢：
| 鍵 | 值 | 說明 |
|---|---|---|
| campaign_id | 1 | 這項工作所屬的廣告活動 ID |
回應
{
"id": 7,
"name": "Bob Smith",
"campaign_id": 6,
"assigned_call_id": null,
"assigned_participant_id": null,
"outbound_number": "+1-(201)-471-6992",
"priority": null,
"created_at": "2024-08-05T14:51:49.000Z",
"updated_at": "2024-08-05T21:01:16.000Z",
"status": "Upcoming",
"user_custom_metadata": {
"NAME (REQUIRED)": "Bob Smith",
"PHONE (REQUIRED)": "+1 111-111-1111",
"EMAIL (REQUIRED)": "customer@somedomain.com"
}
}
狀態碼：200