キャンペーンのエンドポイント

キャンペーンとは、連絡先リストに順番に連絡し、アウトバウンド通話を開始して、各連絡先を対応可能なエージェントに接続するアウトバウンド自動ダイヤル機能のことです。キャンペーン エンドポイントはキャンペーン関連データへのアクセスを提供し、キャンペーン オブジェクトと連絡先オブジェクトの取得を可能にします。

• Campaign オブジェクトは、プラットフォーム内の 1 つのキャンペーンを表します。

• Contact オブジェクトは、特定のキャンペーン内の個々のキャンペーンの連絡先を表します。

キャンペーン エンドポイントを使用すると、既存のキャンペーンの連絡先を追加、更新、削除できます。使用可能なエンドポイントは次のとおりです。

• 1 人の連絡先をキャンペーンに追加する

• キャンペーンの連絡先を取得する

• 複数の連絡先をキャンペーンにインポートする

• ジョブ

• 単一の連絡先を更新する

• 1 件の連絡先を削除する

キャンペーンの連絡先のステータス

ステータス フィールドは次のいずれかの状態になります。

キャンペーンの連絡先のステータス	説明
今後	連絡先が次にダイヤルされます。
Dialing	現在、連絡先に電話をかけています。
キューに格納済み	指定された連絡先への通話がキューに登録されます。
接続済み	エージェントと連絡が取れている。
終了	通話が完了しました。
移行済み	通話は転送されました。
転送済み、完了	通話が転送され、完了しました。
受け取り未完了	エンドユーザーからの回答がない、またはエンドユーザーに連絡が取れなかった。
Not Reached to Contact（連絡先に到達していません）	通話が連絡先に届かなかった。
Abandoned by Contact（連絡先による放棄）	プレビューの場合、エージェントに接続する前にエンドユーザーが電話を切ります。プログレッシブと予測の両方で、エンドユーザーがエージェントに接続してから 5 秒以内に電話を切ります。
スキップ	エージェントが連絡先をスキップしたため、別のエージェントに接続できるようになります。
スキップして終了	プレビューで、エージェントが連絡先をスキップして閉じます。これで、このキャンペーンではこの連絡先が常にスキップされるようになります。
番号が無効です	電話番号が無効な連絡先。
携帯通信会社のエラー	このエラーは携帯通信会社によって発生します。
Abandoned by Dialer（電話アプリによる放棄）	ダイヤラーによって連絡が放棄されました。
ボイスメールが切断された	予測ダイヤルでは、エンドユーザーがマシン（ボイスメールなど）であると判断されます。
電話アプリの一般的なエラー	ダイヤラー エラーのため通話に失敗しました。
リダイヤル スケジュール	一時的なステータス。今後、リダイヤルが予定されています。
電話をかけないでください	電話番号が電話勧誘拒否リストに含まれていた。
無効な発信番号	送信番号が無効な連絡先。
ブロックされた電話番号	無効な国際電話番号またはブロックされた国際電話番号の連絡先。

キャンペーンに 1 人の連絡先を追加する

パラメータ	必須	データ型	定義
campaign_id	TRUE	Integer	連絡先を追加するキャンペーンの 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"
}

リクエストとレスポンスの例

以降のセクションでは、エンドポイントに対するリクエストの例を示します。

キャンペーンに 1 人の連絡先を追加する

この例では、特定のキャンペーン ID に連絡先を追加する方法を示します。

リクエスト

ヘッダー:

キー	値	説明
Content-Type	application/json

クエリ:

キー	値	説明
campaign_id	integer	連絡先を追加するキャンペーンの 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	Integer	連絡先を取得するキャンペーンの ID。

エンドポイント:

Method: GET
Type:
URL: https://{subdomain}.​{domain}​/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts

ヘッダー:

キー	値	説明
Content-Type	application/json

クエリ:

キー	値	説明
campaign_id	integer	連絡先を追加するキャンペーンの ID

リクエストとレスポンスの例

以降のセクションでは、エンドポイントに対するリクエストの例を示します。

キャンペーンの連絡先を取得する

次の例は、指定されたキャンペーン ID の連絡先を取得する方法を示しています。

リクエスト

ヘッダー:

キー	値	説明
Content-Type	application/json

クエリ:

キー	値	説明
campaign_id	integer	クエリするキャンペーンのキャンペーン ID

レスポンス

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

ステータス コード: 200

複数の連絡先をキャンペーンにインポートする

パラメータ	必須	データ型	定義
ファイル	TRUE	文字列	キャンペーンに追加する複数の連絡先を含む json ファイル。
campaign_id	TRUE	Integer	連絡先を追加するキャンペーンの 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": "[e-mail]",
      "phone_number": "[phone]",
      "outbound_number": "[phone]",
      "external_unique_id": "UID_123456"
  }
]

リクエストとレスポンスの例

以降のセクションでは、エンドポイントに対するリクエストの例を示します。

ファイルから複数の連絡先をインポートする

この例では、エンドポイントに投稿されたファイルに基づいてキャンペーンに連絡先を追加する方法を示します。ファイルはフォームデータとして投稿されます。

リクエスト

ヘッダー:

キー	値	説明
Content-Type	multipart/form-data

クエリ:

キー	値	説明
campaign_id	integer	連絡先を追加するキャンペーンの ID

ファイルの内容:

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

レスポンス

None

ステータス コード: 202（承諾済み）

ジョブ

パラメータ	必須	データ型	定義
job_id	TRUE	Integer	取得するジョブ ID
campaign_id	TRUE	Integer	ジョブ 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

1 件の連絡先を更新する

パラメータ	必須	データ型	定義
campaign_id	TRUE	Integer	ジョブ 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	Integer	ジョブ 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