エージェント ステータス エンドポイント

エージェント ステータス API エンドポイントは、エージェント ステータス オブジェクトへのアクセスを提供します。エージェント権限を含むロールを持つ、コンタクト センター AI プラットフォーム（CCAI プラットフォーム）で構成されたユーザーごとに、エージェント オブジェクトが作成されます。

エージェント ステータス API エンドポイントは次のとおりです。

エージェント ステータス エンドポイントを使用すると、エージェントのステータスを変更できます。これにより、ステータスを [対応可能] から任意のカスタム ステータスに変更できるようになります。In-Call などのシステム定義ステータスとの間の遷移はエラーをトリガーします。また、これらのエンドポイントは一括更新をサポートしており、チーム全体または選択したエージェント グループのステータスを同時に変更できます。

エージェントのステータスを更新する

このエンドポイントを使用すると、エージェントのステータスを更新できます。次の表に、JSON 本文のプロパティを示します。

プロパティ 必須 データ型 定義
ステータス TRUE 文字列 エージェントに設定するステータス（「対応可能」など）。
agent_ids TRUE Arry Integer エージェント ID の配列。
team_ids TRUE 配列整数 チーム ID の配列。

エンドポイント:

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/agent_statuses

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "status": "Available",
    "agent_ids": [
        11,
        12
    ],
    "team_ids": []
}

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

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

エージェントのステータスを正常に変更する

次の例は、アクションが成功した場合に一部のエージェントのステータスを変更するリクエストと関連するレスポンスを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "status": "Available",
    "agent_ids": [
        11,
        12
    ],
    "team_ids": [
        1
    ]
}
対応:
[
    {
        "agent_id": 11,
        "name": "Darth Vader",
        "email": "notanakinskywalker@empire.com",
        "agent_number": "Agent No.111",
        "previous_status": "lunch",
        "current_status": "Available"
    },
    {
        "agent_id": 12,
        "name": "Craig T",
        "email": "craigT@nelson.com",
        "agent_number": "Agent No.112",
        "previous_status": "In-call",
        "current_status": "In-call",
        "message": "Agent can't be changed from system status 'In-call'"
    },
    {
        "agent_id": 13,
        "name": "Raymond D",
        "email": "rayd@nelson.com",
        "agent_number": "Agent No.113",
        "previous_status": "Offline",
        "current_status": "Offline",
        "message": "Agent's status can't be changed if they are offline or logged out"
    }
]

ステータス コード: 200

ステータスが存在しない

この例は、指定されたステータスが存在しないため無効と見なされるリクエストと関連するレスポンスを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

Body
{
    "status": "Napping",
    "agent_ids": [
        11,
        12
    ],
    "team_ids": []
}
レスポンス: エラー: ステータス「Napping」が存在しません
{
    "message": "status 'Napping' does not exist"
}

ステータス コード: 400

ステータスがシステム ステータスに設定されている

この例は、ステータスがシステム ステータス（この場合は「通話中」）に設定されているリクエストとレスポンスを示しています。エージェントのステータスをシステムで管理されているステータスに設定することはできません。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

Body
{
    "status": "In-call",
    "agent_ids": [
        11,
        12
    ]
}
回答: エラー: エージェントをシステム ステータス「通話中」に変更できません
{
    "message": "Agent can't be changed to system status 'In-call'"
}

ステータス コード: 400

エージェントのステータスを取得する

このエンドポイントを使用すると、エージェントのステータスを取得できます。次の表に、JSON 本文のプロパティを示します。

プロパティ 必須 データ型 定義
ステータス TRUE 文字列 エージェントに設定するステータス（「対応可能」など）。
agent_ids FALSE Arry Integer エージェント ID の配列。
team_ids FALSE 配列整数 チーム ID の配列。

エンドポイント:

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/agent_statuses

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "agent_ids": [
        11,
        12
    ],
    "team_ids": [
        1
    ]
}

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

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

特定のエージェントとチームのステータスを取得する

この例では、ID が 11 と 12 のエージェントと、ID が 1 のチームに所属するエージェントのステータスを取得する方法を示します。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "agent_ids": [
        11,
        12
    ],
    "team_ids": [
        1
    ]
}
レスポンス: リクエストされたエージェントのステータス
[
    {
        "agent_id": 11,
        "name": "Darth Vader",
        "email": "notanakinskywalker@empire.com",
        "agent_number": "Agent No.111",
        "status": "lunch",
        "ip_addrs": [
            "34.211.11.101"
        ]
    },
    {
        "agent_id": 12,
        "name": "Craig T",
        "email": "craigT@nelson.com",
        "agent_number": "Agent No.112",
        "status": "In-call",
        "ip_addrs": [
            "34.211.11.102"
        ]
    },
    {
        "agent_id": 13,
        "name": "Raymond D",
        "email": "rayd@nelson.com",
        "agent_number": "Agent No.113",
        "status": "Offline",
        "ip_addrs": [
            "34.211.11.103"
        ]
    }
]

ステータス コード: 200