チャット プラットフォームの API エンドポイント

チャット プラットフォームの API エンドポイントは、チャット オブジェクトへのアクセスを提供します。Contact Center AI プラットフォーム（CCAI プラットフォーム）との間でやり取りされるすべてのチャットに対して、チャット オブジェクトが作成されます。

チャット プラットフォームの API エンドポイントは次のとおりです。

Chat オブジェクト

CCAI Platform のモバイル チャット セッションとウェブ チャット セッションごとにチャット オブジェクトが作成されます。チャット オブジェクトは次のとおりです。

{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

チャットを更新する

パラメータ 必須 データ型 定義
id TRUE Integer 更新するチャット ID

エンドポイント:

Method: PATCH
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:id

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

本文:

{
    "finished_by_user_id": "integer",
    "chat": {
        "deflection_channel": "string",
        "status": "string",
        "escalation_id": "integer"
    }
}

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

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

チャットを更新する

この例は、既存のチャットの更新が成功したことを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

クエリ:

キー 値 説明
id Integer （必須）

本文:

{
    "finished_by_user_id": "integer",
    "chat": {
        "deflection_channel": "string",
        "status": "finished",
        "escalation_id": "integer"
    }
}
レスポンス
{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

ステータス コード: 200

チャットでメッセージを送信する

このメソッドは、既存のチャット セッションでメッセージを送信する機能を提供します。

パラメータ 必須 データ型 定義
id TRUE Integer メッセージを送信するチャット ID。

エンドポイント:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:id/message

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "from_user_id": integer,
    "message": {
            "type": "string",
            "content": "string"
            }
    }
}

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

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

メッセージの送信に成功しました

この例は、既存のチャット セッションへのメッセージの送信が成功した場合を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

クエリ:

キー 値 説明
id Integer （必須）

本文:

{
    "from_user_id": integer,
    "message": {
            "type": "string",
            "content": : "string"
            }
    }
}
レスポンス
{
}

ステータス コード: 200

仮想エージェントのチャットをエスカレーションする

仮想エージェントから人間のエージェントにチャットをエスカレーションします。

パラメータ 必須 データ型 定義
chat_id TRUE Integer エスカレーションに必要なチャット ID。

エンドポイント:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/escalations

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

本文:

{
    "reason": "string",
    "force_escalate": "boolean"
}

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

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

チャットのエスカレーションに成功

この例は、既存のチャットを人間のエージェントにエスカレーションするリクエストを示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

クエリ:

キー 値 説明
chat_id Integer （必須）

本文:

{
    "reason": "by_end_user_ask",
    "force_escalate": true
}
レスポンス
{
    "id": "integer",
    "chat_id": "integer",
    "status": "string"
}

ステータス コード: 200

エスカレーションを更新する

偏向チャネルの選択にのみ使用されます。

パラメータ 必須 データ型 定義
chat_id TRUE Integer 偏向メニュー ID を更新するために必要なチャット ID。
id TRUE Integer 必須のメニュー ID。

エンドポイント:

Method: PATCH
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/escalations/:id

ヘッダー:

キー 値 説明
Content-Type application/json

本文:

{
    "deflection_channel": "string"
}

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

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

エスカレーションの更新が成功しました

この例は、エスカレーション チャネルの更新が成功した場合を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

クエリ:

キー 値 説明
chat_id Integer （必須）
id Integer （必須）

本文:

{
    "deflection_channel": "string"
}
レスポンス
{
    "id": "integer",
    "chat_id": "integer",
    "status": "string"
}

ステータス コード: 200

アップロードした写真をチャットに追加する

メディア ストレージにアップロードされた写真をチャットに追加する

パラメータ 必須 データ型 定義
chat_id TRUE Integer 写真を追加するのに必要なチャット ID。

エンドポイント:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}/apps/api/v1/chats/:chat_id/photos

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

本文:

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}

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

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

チャットに写真を追加しました

次の例は、メディア ストレージにアップロードされた写真を既存のチャット会話に追加する方法を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

クエリ:

キー 値 説明
chat_id Integer （必須）

本文:

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}
レスポンス
{
    "url": "string",
    "media_id": "integer"
}

ステータス コード: 200

チャットからすべての写真を取得する

チャットに添付されているすべての写真のメディア ID とストレージ URL を取得します。

パラメータ 必須 データ型 定義
chat_id TRUE Integer メディア情報を取得するために必要なチャット ID。

エンドポイント:

Method: GET
Type:
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/photos

ヘッダー:

キー 値 説明
同意する application/json

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

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

チャットのチャット写真情報の取得に成功しました

この例は、既存のチャット セッションの写真情報を取得するための API 呼び出しが成功した場合を示しています。

リクエスト

ヘッダー:

キー 値 説明
同意する application/json

クエリ:

キー 値 説明
chat_id Integer （必須）
レスポンス
[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

ステータス コード: 200

署名付きの写真アップロード URL を取得する

写真の事前署名付きアップロード URL を取得するために使用されます。

パラメータ 必須 データ型 定義
chat_id TRUE Integer 事前署名付き写真 URL に関連付けられる必須のチャット ID。

エンドポイント:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/photos/upload

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

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

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

アップロード用の署名付き URL の取得に成功しました

次の例は、写真のアップロード用の署名付き URL の取得に成功したリクエストの例です。

リクエスト

ヘッダー:

キー 値 説明
同意する application/json

クエリ:

キー 値 説明
chat_id Integer （必須）
レスポンス
{
    "url": "string",
    "fields": {
        "key": "string",
        "success_action_status": "string",
        "Content-Type": "string",
        "Cache-Control": "string",
        "acl": "string",
        "policy": "string",
        "x-amz-credential": "string",
        "x-amz-algorithm": "string",
        "x-amz-date": "string",
        "x-amz-security-token": "string",
        "x-amz-signature": "string",
        "x-goog-algorithm": "string",
        "x-goog-credential": "string",
        "x-goog-date": "string",
        "x-goog-signature": "string"
    }
}

ステータス コード: 200

アップロードした動画をチャットに追加する

メディア ストレージにアップロードした動画をチャットに追加します。

パラメータ 必須 データ型 定義
chat_id TRUE Integer 動画を関連付ける必要がある必須のチャット ID。

エンドポイント:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

本文:

{
    "video": {
        "s3_path": "string",
        "gcs_path": "string"
    }
}

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

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

チャット セッションへの動画のアップロードが成功した

この例は、チャット セッションへの動画のアップロードが成功したことを示しています。

リクエスト

ヘッダー:

キー 値 説明
同意する application/json

クエリ:

キー 値 説明
chat_id Integer （必須）

本文:

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}
レスポンス
Body
{
    "url": "string",
    "media_id": "integer"
}

ステータス コード: 200

チャットからすべての動画を取得する

チャットに添付されているすべての動画のメディア ID とストレージ URL を取得します。

パラメータ 必須 データ型 定義
chat_id TRUE Integer 動画 URL を取得するのに必要なチャット ID。

エンドポイント:

Method: GET
Type:
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

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

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

チャットのすべての動画 URL を取得する

この例は、既存のチャットのすべての動画 URL を取得する方法を示しています。

リクエスト

ヘッダー:

キー 値 説明
同意する application/json

クエリ:

キー 値 説明
chat_id Integer （必須）
レスポンス
[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

ステータス コード: 200

事前署名付き動画アップロード URL を取得する

動画の事前署名付きアップロード URL を取得するために使用されます。

パラメータ 必須 データ型 定義
chat_id TRUE Integer 事前署名付き動画 URL に関連付けられる必須のチャット ID。

エンドポイント:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos/upload

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

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

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

動画アップロード用の署名付き URL の取得に成功しました

以下は、動画アップロード用の署名付き URL の取得を含むリクエストが成功した場合の例です。

リクエスト

ヘッダー:

キー 値 説明
同意する application/json

クエリ:

キー 値 説明
chat_id Integer （必須）
レスポンス
{
    "url": "string",
    "fields": {
        "key": "string",
        "success_action_status": "string",
        "Content-Type": "string",
        "Cache-Control": "string",
        "acl": "string",
        "policy": "string",
        "x-amz-credential": "string",
        "x-amz-algorithm": "string",
        "x-amz-date": "string",
        "x-amz-security-token": "string",
        "x-amz-signature": "string",
        "x-goog-algorithm": "string",
        "x-goog-credential": "string",
        "x-goog-date": "string",
        "x-goog-signature": "string"
    }
}

ステータス コード: 200

チャットを作成する

新しいチャット セッションを開始します。

リクエストの例

メソッド: POST

URL: https://{subdomain}.{domain}/apps/api/v1/chats

ヘッダー

キー 値 説明
Content-Type application/json
同意する application/json

本文

{
    "chat": {
        "menu_id": "integer",
        "end_user_id": "integer",
        "lang": "string",
        "email": "string",
        "context": "object",
        "transcript": "object"
    },
    "end_user": {
        "phone": "string"
    }
}

Context:（コンテキスト:）

context オブジェクトには value オブジェクトが含まれており、このオブジェクトがチャットの会話にメタデータを渡します。context オブジェクトを符号なしデータ パラメータとして仮想エージェントに渡すことができます。次の例をご覧ください。

{
    "context": {
        {"value":
            {"foo": "bar",
             "key": "value"}
        }
    }
}

この例では、受信フィールドの符号なしデータ パラメータ値は context で、宛先フィールドは context に設定できます。これにより、$session.params.context.foo または $session.params.context.key を使用できるようになります。

レスポンスの例

{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

ID でチャットを返します

このメソッドは、指定されたチャット ID のチャット オブジェクトを返します。

エンドポイント:

Method: GET
Type:
URL: https://{subdomain}.​{domain}/apps/api/v1/chats/:id

ヘッダー:

キー 値 説明
Content-Type application/json
同意する application/json

クエリ:

キー 値 説明
chat_id Integer （必須）

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

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

チャットを正常に取得する

次の例は、既存のチャット ID のリクエストが成功した場合を示しています。

リクエスト

ヘッダー:

キー 値 説明
Content-type application/json
同意する application/json

クエリ:

キー 値 説明
chat_id Integer （必須）
レスポンス
{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

ステータス コード: 200

チャット中に予約済みデータ属性を取得する

エンドポイント

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

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

このセクションでは、エンドポイントのリクエストとレスポンスの例を示します。

成功

この例は、呼び出しが成功した場合を示しています。

リクエスト

ヘッダー

キー 値 説明
同意する application/json

URL 変数

キー 値 説明
id integer （必須）
レスポンス
{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

ステータス コード 0

チャット中に予約済みデータ属性を更新する

エンドポイント

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

URL 変数

キー 値 説明
id integer （必須）

本文

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customers": "boolean"
}

チャットでカスタムデータを送信する

チャットでカスタムデータを送信します。

リクエストの例

メソッド: POST

URL: https//{subdomain}.{domain}/apps/api/v1/chats/:id/custom_data

ヘッダー

キー 値 説明
Content-Type application/json

URL 変数

キー 値 説明
id （必須）

レスポンスの例

// Use unsecured parameter
{
"signed": false,
"data": {
// Start customer_flag fields
"reserved_verified_customer": {
"label": "LABEL 1",
"value": true
},
"reserved_bad_actor": {
"label": "LABEL 2",
"value": false
},
"reserved_repeat_customer": {
"label": "LABEL 3",
"value": true
},
// End customer_flag fields
"field1": {
"label": "LABEL 4",
"value": "dummy1"
},
"field2": {
"label": "LABEL 5",
"value": "dummy2"
}
}
}
// Use secured parameter
// {
// "signed": true,
// "signed_data": "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21fZGF0YSI6eyJyZXNlcnZlZF92ZXJpZmllZF9jdXN0b21lciI6eyJ2YWx1ZSI6ZmFsc2V9LCJyZXNlcnZlZF9iYWRfYWN0b3IiOnsidmFsdWUiOnRydWV9LCJyZXNlcnZlZF9yZXBlYXRfY3VzdG9tZXIiOnsidmFsdWUiOmZhbHNlfSwiZmllbGQxIjp7InZhbHVlIjoiZHVtbXkxMTEifSwiZmllbGQyIjp7InZhbHVlIjoiZHVtbXkyMjIifX0sImV4cCI6MTcyOTY4MzU5MywiaWF0IjoxNzI5Njc5OTkzfQ.BMskgKTM3DbgrMLWjI46ZJ1K73H25JRd16SgHK0A1Ts"
// }
// ======================= How to create <signed_data> =======================
// payload = {
// "custom_data": {
// // Start customer_flag fields
// "reserved_verified_customer": {
// "label": "LABEL 1",
// "value": true
// },
// "reserved_bad_actor": {
// "label": "LABEL 2",
// "value": false
// },
// "reserved_repeat_customer": {
// "label": "LABEL 3",
// "value": true
// },
// // End customer_flag fields
// "field1": {
// "label": "LABEL 4",
// "value": "dummy1"
// },
// "field2": {
// "label": "LABEL 5",
// "value": "dummy2"
// }
// },
// "exp": 1734567890, // expiration timestamp
// "iat": 1734560000 // issue timestamp
// }
// signed_data = JWT.encode(payload, 'Company secret', 'HS256')
// ======================= End how to create <signed_data> =======================

進行中のチャット セッション中にエンドユーザーに最新情報を伝える

現在のアクティブなチャット セッションに関連付けられているエンドユーザーを更新します。また、CRM チケットにリンクされている連絡先情報も更新します。_Identifier は必須ですが、name、email、phone は省略可能です。

リクエストの例

メソッド: POST

URL: https//{subdomain}.{domain}/apps/api/v1/chats/:chat_id/end-user

ヘッダー

キー 値 説明
Content-Type application/json

URL 変数

キー 値 説明
chat_id

本文

{
    "identifier": "string",
    "name": "string",
    "email": "string",
    "phone": "string"
}

レスポンスの例

{
    "message": "accepted"
}