システム・メッセージの取得
post
/engagement/api/consumer/{fqSiteName}/v1/getMessages
この操作は、クライアントに対してポーリングgetループ機能を実装します。 クライアントがシステム・メッセージの取得リクエストを発行すると、チャット・サーバーは、その特定のチャット・エンゲージメントに使用可能なシステム・メッセージを問い合せようとします。 システム・メッセージが使用可能な場合、メッセージはレスポンスにパッケージ化され、クライアントに返送されます。 リクエスト時に使用可能なシステム・メッセージがない場合、チャット・サーバーは、メッセージが表示されるかどうかを確認するために最大30秒間待機します。 システム・メッセージが使用可能になった場合は、パッケージ化され、クライアントに送り返されます。 使用可能なシステム・メッセージがない場合、サーバーは空の収集をクライアントに返します。
チャット・アプリケーションには、このエンドポイントへのリクエストを処理するための個別の取得スレッドが必要です。 チャット・アプリケーションは、これらの取得スレッドのいずれかが常に存在するように設計する必要があります。
'systemMessages'レスポンス・フィールドでは、次のメッセージ・タイプが返されます:
- RNEngagementActivityChangedMessage - このメッセージは、エンド・ユーザーにエージェントの顧客対応アクティビティを通知するために使用されます。 顧客対応アクティビティに許可される値は、NONE、AWAY、LISTENING、RESEARCHINGおよびRESPONDINGです。 このメッセージ・タイプの形式は次のとおりです:
{ "messageName" : "RNEngagementActivityChangedMessage", "clientId" : 0L, "clientIdString" : "string", "mode" : "string", "engagementId" : 0L, "engagementIdString" : "string", "sneakPreviewState" : "string", "sneakPreviewInterval" : 0L, "sneakPreviewIntervalString" : "string", "sneakPreview" : "string", "sneakPreviewFocus" : "boolean", "createdTime" : "string", "sequenceNumber" : 0L, "sequenceNumberString" : "string" } - RNEngagementConcludedMessage - このメッセージは、エージェントがチャット・エンゲージメントを終了したことをエンド・ユーザーに通知するために使用されます。 このメッセージ・タイプの形式は次のとおりです:
{ "messageName" : "RNEngagementConcludedMessage", "reason" : "string", "role" : "string", "createdTime" : "string", "sequenceNumber" : 0L, "sequenceNumberString" : "string" } - RNEngagementConfigurationChangedMessage - このメッセージは、サイトのプールIDが変更されたことをクライアント・アプリケーションに通知するために使用されます。 これは通常、チャット・サーバーが新しいバージョンに移行した結果です。 クライアント・アプリケーションは、後続のすべてのリクエストで新しいプールIDを使用して、このメッセージに対してアクションを実行することが必要です。 このメッセージ・タイプの形式は次のとおりです:
{ "messageName" : "RNEngagementConfigurationChangedMessage", "name" : "string", "domain" : "string", "port" : "string", "pool" : "string", "createdTime" : "string", "sequenceNumber" : 0L, "sequenceNumberString" : "string" } - RNEngagementConsumerErrorOccurredMessage - このメッセージは、現在のチャット・エンゲージメントのチャット・サーバー内でエラーが発生したことをクライアント・アプリケーションに通知するために使用されます。 このメッセージには、エラー状態を説明するテキストが返されます。 このメッセージ・タイプの形式は次のとおりです:
{ "messageName" : "RNEngagementConsumerErrorOccurredMessage", "errorType" : "string", "errorCode" : "string", "errorText" : "string", "createdTime" : "string", "sequenceNumber" : 0L, "sequenceNumberString" : "string" } - RNEngagementMessagePostedMessage - このメッセージには、エージェントがエンド・ユーザーに送信したメッセージが表示されます。 このメッセージ・テキストは、チャット・エンゲージメント・トランスクリプトの一部です。 このメッセージ・タイプの形式は次のとおりです:
{ "messageName" : "RNEngagementMessagePostedMessage", "body" : "string", "clientId" : 0L, "clientIdString" : "string", "messageId" : "string", "richText" : false, "messageDataMap" : null, "createdTime" : "string", "sequenceNumber" : 0L, "sequenceNumberString" : "string" } - RNEngagementParticipantAddedMessage - このメッセージは、別のエージェントが会議または転送プロセスのチャット・エンゲージメントに参加したことをエンド・ユーザーに通知します。 このメッセージ・タイプの形式は次のとおりです:
{ "messageName" : "RNEngagementParticipantAddedMessage", "name" : "string", "greeting" : "string", "clientId" : 0L, "clientIdString" : "string", "role" : "string", "createdTime" : "string", "sequenceNumber" : 0L, "sequenceNumberString" : "string" } - RNEngagementParticipantConnectionStateChangedMessage - このメッセージは、指定されたロールとのエンゲージメントの参加者に、次のいずれかの値への接続状態が変化したことをクライアント・アプリケーションに通知するために使用されます: NONE、ABSENT、ACTIVE、またはDISCONNECTED。 このメッセージ・タイプの形式は次のとおりです:
{ "messageName" : "RNEngagementParticipantConnectionStateChangedMessage", "role" : "string", "clientId" : 0L, "clientIdString" : "string", "connectionState" : "string", "createdTime" : "string", "sequenceNumber" : 0L, "sequenceNumberString" : "string" } - RNEngagementParticipantLeftMessage - このメッセージは、指定されたロールとのチャット・エンゲージメントの参加者が参加者ではなくなったことをクライアント・アプリケーションに通知するために使用されます。 このメッセージ・タイプの形式は次のとおりです:
{ "messageName" : "RNEngagementParticipantLeftMessage", "clientId" : 0L, "clientIdString" : "string", "disconnectReason" : "string", "role" : "string", "createdTime" : "string", "sequenceNumber" : 0L, "sequenceNumberString" : "string" } - RNEngagementRoleChangedMessage - このメッセージは、指定されたクライアントIDを持つエージェントがチャット・エンゲージメントのリード・エージェントになったことをクライアント・アプリケーションに通知するために使用されます。 このメッセージは、通常、チャット・エンゲージメントが別のエージェントに転送された結果です。 このメッセージ・タイプの形式は次のとおりです:
{ "messageName" : "RNEngagementRoleChangedMessage", "leadClientId" : 0L, "leadClientIdString" : "string", "createdTime" : "string", "sequenceNumber" : 0L, "sequenceNumberString" : "string" } - RNEngagementWaitInformationChangedMessage - このメッセージは、エンド・ユーザーにキュー内の現在の位置と、エージェントに割り当てられるまでの予想待機時間を通知するために使用されます。 このメッセージ・タイプの形式は次のとおりです:
{ "messageName" : "RNEngagementWaitInformationChangedMessage", "position" : 0L, "positionString" : "string", "expectedWaitTimeSeconds" : 0L, "expectedWaitTimeSecondsString" : "string", "averageWaitTimeSeconds" : 0L, "averageWaitTimeSecondsString" : "string", "createdTime" : "string", "sequenceNumber" : 0L, "sequenceNumberString" : "string" }
ノート : 'createdTime'の書式は、yyyy-MM-dd'T'HH:mm:ssXXXです。
リクエスト
サポートされるメディア・タイプ
- application/json; charset=utf-8
パス・パラメータ
- fqSiteName: string
セッションを確立するためにコールによって返されるサイトの名前。
問合せパラメータ
- pool: string
セッションの確立レスポンスで指定されている、またはRNEngagementConfigurationChangedMessageシステム・メッセージで指定されているプールID。
ヘッダー・パラメータ
- SessionId: string
コンシューマ・セッションの一意の識別子。
リクエスト情報を含むオブジェクト。
ルート・スキーマ : com.rightnow.chat.rest.consumer_api.model.requests.v1.GetMessagesRequest
タイプ:
ソースを表示
object- clientRequestTime(optional): string
yyyy-MM-dd'T'HH:mm:ssXXX形式のリクエスト・クライアントのローカル時間。
- clientTransactionId(optional): integer(int64)
クライアント・トランザクションの一意の識別子。 このフィールドに指定された値は、レスポンス・オブジェクトでエコー・バックされます。 リクエストをレスポンスにリンクするために使用されます。
- startingSequenceNumber(optional): integer(int64)
オプションのシステム・メッセージ開始連番。 リクエストに値が存在する場合、レスポンスで返されるメッセージは、このシーケンス番号で始まります。 値を省略するかnullにすると、未送信のすべてのメッセージがレスポンスで返されます。
レスポンス
サポートされるメディア・タイプ
- application/json; charset=utf-8
200 レスポンス
リクエストは正常に完了しました。
ルート・スキーマ : com.rightnow.chat.rest.consumer_api.model.responses.v1.GetMessagesResponse
タイプ:
ソースを表示
object- clientId(optional): integer(int64)
クライアントの一意の識別子。
- clientIdString(optional): string
文字列としてのクライアントの一意の識別子。
- clientRequestTime(optional): string
yyyy-MM-dd'T'HH:mm:ssXXX形式のリクエスト・クライアントのローカル時間。
- clientTransactionId(optional): integer(int64)
クライアント・トランザクションの一意の識別子。 このフィールドに指定された値は、レスポンス・オブジェクトでエコー・バックされます。 リクエストをレスポンスにリンクするために使用されます。
- clientTransactionIdString(optional): string
文字列としてのクライアント・トランザクションの一意の識別子。
- errorMessages(optional): array errorMessages
エラーのリスト。
- serviceFinishTime(optional): string
リクエスト処理がyyyy-MM-dd'T'HH:mm:ssXXX形式で完了した時間。
- serviceStartTime(optional): string
リクエスト処理がyyyy-MM-dd'T'HH:mm:ssXXX形式で開始した時間。
- systemMessages(optional): array systemMessages
チャット・クラウドからのシステム・メッセージのリスト。
ネストされたスキーマ : com.rightnow.chat.rest.consumer_api.model.messages.v1.RNEngagementConsumerErrorOccurredMessage
タイプ:
ソースを表示
object- errorCode(optional): string
許可された値:
[ "BAD_REQUEST", "CONFLICT", "FEATURE_NOT_IMPLEMENTED", "FORBIDDEN", "INTERNAL_SERVER_ERROR", "ITEM_NOT_FOUND", "NOT_ACCEPTABLE", "NOT_ALLOWED", "NOT_AUTHORIZED", "RECIPIENT_UNAVAILABLE", "RESOURCE_CONSTRAINT", "SERVICE_UNAVAILABLE", "UNDEFINED_CONDITION", "UNEXPECTED_REQUEST", "SERVLET_SESSION_NOT_FOUND", "CX_SESSION_LOGOUT" ]エラーが発生した場合にチャット・サーバーによって返されるエラー・コード。 - errorText(optional): string
エラーが発生した場合にチャット・サーバーによって返されるテキスト。
- errorType(optional): string
許可された値:
[ "AUTH", "CANCEL", "MODIFY", "WAIT" ]エラーが発生した場合にチャット・サーバーによって返されるエラー・タイプ。
ネストされたスキーマ : com.rightnow.chat.rest.common.model.messages.v1.EngagementBaseSystemMessage
タイプ:
ソースを表示
object- createdTime(optional): string
システム・メッセージがyyyy-MM-dd'T'HH:mm:ssXXX形式で作成された時間。
- messageName(optional): string
許可された値:
[ "RNEngagementActivityChangedMessage", "RNEngagementConcludedMessage", "RNEngagementConfigurationChangedMessage", "RNEngagementConsumerErrorOccurredMessage", "RNEngagementMessagePostedMessage", "RNEngagementParticipantAddedMessage", "RNEngagementParticipantConnectionStateChangedMessage", "RNEngagementParticipantLeftMessage", "RNEngagementRoleChangedMessage", "RNEngagementWaitInformationChangedMessage" ]システム・メッセージ・タイプの名前。
400 レスポンス
リクエスト・オブジェクトの検証に失敗しました。
ルート・スキーマ : スキーマ
タイプ:
object403 レスポンス
コンシューマ・セッション識別子が不明です。
ルート・スキーマ : スキーマ
タイプ:
object404 レスポンス
リソースが見つかりませんでした。
ルート・スキーマ : スキーマ
タイプ:
object500 レスポンス
リクエストの処理中にチャット・サーバーでエラーが発生しました。
ルート・スキーマ : スキーマ
タイプ:
object例
次の例は、cURLを使用してPOSTリクエストを発行してシステム・メッセージを取得する方法を示しています:
cURLコマンドの例
curl -X POST "https://chat_rest_server_domain.com/engagement/api/consumer/sdi_11_20_18_2022_21-3586727808788512-Fusion/v1/getMessages?pool=353:2" -H "Accept: application/json;charset=utf-8" -H "Content-Type: application/json" -H "SessionId: 170c233dfi4gy1vkwyw6yxdq1a" -d "{\"clientRequestTime\" : \"2019-01-14T14:35:14.226Z\",\"clientTransactionId\" : 1}"
リクエスト本文の例
次に、JSON形式のリクエスト本文の例を示します。
{
"clientRequestTime" : "2019-01-14T14:35:14.226Z",
"clientTransactionId" : 1
}
レスポンス・ヘッダーの例
次に、レスポンス・ヘッダーの例を示します。
Status: 200 OK Content-Type: application/json;charset=utf-8
応答本文の例
次に、JSON形式のレスポンス本文の例を示します。
{
"errorMessages": [],
"systemMessages": [
{
"position": 1,
"expectedWaitTimeSeconds": 0,
"averageWaitTimeSeconds": 0,
"messageName": "RNEngagementWaitInformationChangedMessage",
"createdTime": "2019-01-11T10:12:13.303Z",
"positionString": "1",
"expectedWaitTimeSecondsString": "0",
"averageWaitTimeSecondsString": "0"
},
{
"position": 1,
"expectedWaitTimeSeconds": 0,
"averageWaitTimeSeconds": 0,
"messageName": "RNEngagementWaitInformationChangedMessage",
"createdTime": "2019-01-11T10:12:33.241Z",
"positionString": "1",
"expectedWaitTimeSecondsString": "0",
"averageWaitTimeSecondsString": "0"
}
],
"clientRequestTime": "2019-01-14T14:35:14.226Z",
"clientTransactionId": 1,
"clientTransactionIdString": "1",
"serviceStartTime": "2019-01-11T10:12:34.298Z",
"serviceFinishTime": "2019-01-11T10:12:34.322Z",
"clientId": 246,
"clientIdString": "246"
}