广告系列端点

“广告系列”是指一种外呼自动拨号器功能，可按顺序联系联系人列表中的联系人、发起外呼，并将每个联系人转接到空闲客服人员。广告系列端点可用于访问与广告系列相关的数据，从而检索广告系列和联系人对象。

• 广告系列对象表示平台中的单个广告系列。

• 联系人对象表示特定广告系列中的单个广告系列联系人。

借助广告系列端点，用户可以添加、更新和删除现有广告系列的联系人。可用的端点包括：

• 向广告系列添加单个联系人

• 获取广告系列的联系人

• 将多位联系人导入到广告系列

• 作业

• 更新单个联系人

• 移除单个联系人

营销活动联系人状态

状态字段可以处于以下任何一种状态：

营销活动联系人状态	说明
即将开始	系统即将拨打相应联系人的电话。
拨号	正在拨打联系人的电话。
已加入队列	针对指定联系人的通话已加入队列。
已连接	联系人已与客服人员建立联系。
已完成	通话已结束。
已转移	通话已转接。
已转移并完成	通话已转接，然后已完成。
未取货	最终用户未回答或从未联系到最终用户。
未联系到	电话始终无法接通联系人。
被联系人放弃	对于预览，最终用户在连接到客服人员之前挂断电话。 无论是渐进式拨号还是预测式拨号，最终用户在接通代理后 5 秒内挂断电话。
已跳过	客服人员已跳过此联系人，该联系人将可供其他客服人员联系。
已跳过并关闭	在预览时，代理跳过并关闭了联系人。系统现在应始终在此广告系列中跳过此联系人。
号码无效	联系人的手机号码无效。
运营商错误	此错误是由运营商造成的。
由拨号器放弃	联系人已被拨号器舍弃。
语音信箱挂断	在预测拨号模式下，拨号器会确定最终用户是机器（即语音留言）。
拨号器常规错误	由于拨号器错误，通话失败。
已安排重新拨号	临时状态。已安排在未来重拨。
Do Not Call	该号码位于“谢绝来电”号码列表中。
无效的拨出号码	联系人包含无效的出站号码。
已屏蔽的电话号码	联系人的国际号码无效/被屏蔽。

向广告系列添加单个联系人

参数	必需	数据类型	定义
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": "[e-mail]",
    "phone_number": "[phone]",
    "outbound_number": "[phone]",
    "external_unique_id": "UID_123456"
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

向广告系列添加单个联系人

此示例演示了如何向特定广告系列 ID 添加联系人。

请求

标头：

键	值	说明
Content-Type	application/json

查询：

键	值	说明
campaign_id	整数	要将相应联系人添加到的广告系列的 ID

正文：

{
    "name": "string",
    "email": "[e-mail]",
    "phone_number": "[phone]",
    "outbound_number": "[phone]",
    "external_unique_id": "UID_123456"
}

响应

{
    "valid_contacts": [
        {
            "name": "string",
            "email": "[e-mail]",
            "phone_number": "[phone]",
            "outbound_number": "[phone]",
            "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

请求和响应示例

以下部分提供了向端点发送的请求示例。

获取广告系列的联系人

以下示例演示了如何检索指定广告系列的联系人。

请求

标头：

键	值	说明
Content-Type	application/json

查询：

键	值	说明
campaign_id	整数	要查询的广告系列的广告系列 ID

响应

[
  {
      "name": "string",
      "email": "[e-mail]",
      "phone_number": "[phone]",
      "outbound_number": "[phone]",
      "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

正文：

'表单数据'

文件内容：

[
  {
      "name": "string",
      "email": "[e-mail]",
      "phone_number": "[phone]",
      "outbound_number": "[phone]",
      "external_unique_id": "UID_123456"
  }
]

请求和响应示例

以下部分提供了向端点发送的请求示例。

从文件导入多位联系人

此示例演示了如何根据发布到端点的文件将联系人添加到广告系列中。文件以表单数据的形式发布。

请求

标头：

键	值	说明
Content-Type	multipart/form-data

查询：

键	值	说明
campaign_id	整数	要将联系人添加到的广告系列的 ID

文件内容：

[
  {
      "name": "string",
      "email": "[e-mail]",
      "phone_number": "[phone]",
      "outbound_number": "[phone]",
      "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": "[e-mail]",
    "phone_number": "[phone]",
    "external_unique_id": "UID_123456"
}

请求和响应示例

以下部分提供了向端点发送的请求示例。

更新广告系列的联系人

此示例演示了如何更新特定广告系列中的联系人。

请求

标头：

键	值	说明
Content-Type	application/json

正文：

{
    "contact_id": 7,
    "name": "Bob Smith",
    "email": "[e-mail]",
    "phone_number": "[phone]",
    "external_unique_id": "UID_123456"
}

响应

{
    "id": 7,
    "name": "Bob Smith",
    "campaign_id": 6,
    "assigned_call_id": null,
    "assigned_participant_id": null,
    "outbound_number": "[phone]",
    "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)": "[phone]",
        "EMAIL (REQUIRED)": "[e-mail]"
    }
}

状态代码： 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": "[phone]",
    "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)": "[phone]",
        "EMAIL (REQUIRED)": "[e-mail]"
    }
}

状态代码： 200