For the complete documentation index, see llms.txt. This page is also available as Markdown.

Genesys Cloud 連携

Genesys Cloud Open Messaging で MaiAgent 対話プラットフォームを連携:アーキテクチャ、OAuth 認証情報と API、メッセージの双方向フロー、署名検証、エラー処理と制限事項

このページは、MaiAgent 対話プラットフォームを Genesys Cloud に接続する連携開発者およびお客様の IT 担当者向けです。連携には Genesys Cloud の Open Messaging を使用します。訪問者が MaiAgent の対話プラットフォーム(Web Chat、LINE など)で会話すると、MaiAgent がメッセージをリアルタイムで Genesys Cloud に送信し、Genesys Cloud 側(オペレーターまたは bot)の返信が MaiAgent に送り返され、MaiAgent が訪問者へ転送します。

これはサードパーティ製カスタマーサービスシステム連携の「シナリオ B」(訪問者は MaiAgent 対話プラットフォーム、オペレーターはお客様のシステム)を組み込みで実現するものです。MaiAgent には Genesys Cloud のメッセージ形式、OAuth によるトークン取得、署名検証があらかじめ組み込まれているため、独自の中継プログラムを作成する必要はありません。

管理画面での操作手順(どこに入力し、どのボタンを押すか)は、ユーザーマニュアルの Webhook › Genesys Cloud 連携を参照してください。このページでは、その背後にあるプロトコル、API、動作について説明します。

API のフィールド名は camelCase です。以下の API 例では、ベース URL として https://api.maiagent.ai/api/v1/ を使用します。認証方法はクイックスタートを参照してください。

連携アーキテクチャ

連携は、同じ対話プラットフォーム上の 3 つの設定で構成されます。

設定
方向
役割

Genesys Cloud 連携(対話プラットフォームごとに 1 つ)

—

リージョン、Open Messaging Integration ID、OAuth Client Credentials を保存します。MaiAgent はこれを使ってアクセストークンを取得し、Genesys API の URL を組み立てます。その対話プラットフォーム配下のすべての Genesys 形式 Webhook で共有されます

Incoming/Outgoing Webhook(Payload 形式に Genesys Cloud を選択)

MaiAgent → Genesys Cloud

訪問者のメッセージ(Incoming)と Agent または有人オペレーターの返信(Outgoing)を Genesys Cloud Open Messaging Inbound API に送信します

Receive Webhook(Payload のデフォルト形式に Genesys Cloud を選択)

Genesys Cloud → MaiAgent

Genesys Cloud が返信を MaiAgent に送り返すための受信 URL を提供します

事前準備

Genesys Cloud 側で次を準備します。

  1. Open Messaging 連携:Integration ID を取得します(管理画面:Genesys Cloud Admin → Message → Platforms)。

  2. OAuth Client:付与タイプは Client Credentials とし、conversation:message:create 権限が必要です。Client ID と Client Secret を取得します。

  3. Genesys Cloud 組織が所在するリージョンを確認し、下記の対応リージョンと照合します。

MaiAgent 側で、下記の連携 API を呼び出すために必要な権限は次のとおりです。

  • アクセスできる対話プラットフォーム:組織オーナーは組織内のすべての対話プラットフォームにアクセスできます。その他のメンバーは、グループを通じてアクセス権を得た対話プラットフォームのみにアクセスでき、組織の MaiGPT 対話プラットフォームには一切アクセスできません。アクセスできない対話プラットフォームには 404 が返ります。

  • 書き込み(PUT、DELETE、認証情報のテスト):メンバーに「対話プラットフォーム」権限も必要です(組織のプランにこの権限が含まれている場合、オーナーは保有しています)。権限がない場合は 403 が返ります。参照(GET)はログインしていれば可能です。

Genesys Cloud 連携の設定

各対話プラットフォームには、Genesys Cloud 連携を最大 1 つ設定できます。

フィールド

フィールド
型
説明

region

string

Genesys Cloud のリージョンコード。対応リージョンを参照してください。必須

integrationId

string

Open Messaging Integration ID。最大 64 文字。必須

clientId

string

OAuth Client ID。最大 64 文字。必須

clientSecret

string

OAuth Client Secret。書き込み専用で、どのレスポンスにも返されません。作成時は必須で、その後の更新では省略すると既存の値が引き継がれます。暗号化して保存されます

hasClientSecret

boolean

読み取り専用。Client Secret が保存されているかどうか

tokenStatus

string

読み取り専用。アクセストークンの状態:active(使用可能、またはまだトークンを取得していない)/expired(キャッシュされたトークンが期限切れで、次回の送信時に自動的に更新されます)/invalidated(Genesys Cloud がこの認証情報を拒否したため、Client Secret の再入力が必要です)

regionLabel

string

読み取り専用。リージョンの表示名

id、createdAt、updatedAt

—

読み取り専用

アクセストークンは MaiAgent 内部にのみ保存され、API レスポンスには含まれません。

API

  • PUT で clientSecret を指定した場合:MaiAgent はまず Genesys Cloud の /oauth/token に対して Client Credentials でトークンを 1 回取得し(タイムアウト 10 秒)、認証情報を検証します。失敗すると 400 を返し、保存されません。検証に成功すると、それまでの無効化フラグとキャッシュされたトークンがクリアされます。

  • PUT で clientSecret を指定しない場合(リージョンまたは ID のみ変更):再検証は行わず、既存の Secret を引き続き使用します。連携がすでに invalidated の場合、状態は変わらず、新しい Secret を入力しないと復旧しません。

  • テストエンドポイントで clientSecret を指定しない場合:保存済みのリージョン、Client ID、Secret を使ってテストします。渡した region/clientId は無視されます。保存済みの Secret がない場合は 400 を返します。

  • 連携の削除:その対話プラットフォーム配下の Genesys 形式の Incoming/Outgoing Webhook は、以降送信されなくなります(送信ログも残りません)。Webhook 自体の設定は保持されます。

設定または認証情報のテストに失敗すると 400 が返ります。主な detail は次のとおりです(Accept-Language に応じて翻訳されます)。

detail(英語の原文)

原因

Unsupported Genesys Cloud region.

region が対応リストにありません(テストエンドポイント。PUT の場合はフィールド検証が先に拒否し、フィールドエラーを返します)

Genesys Cloud rejected the client credentials. Please double-check clientId/clientSecret.

Genesys Cloud が invalid_client または unauthorized_client を返した

Genesys Cloud token endpoint returned an error.

Genesys Cloud がその他のエラーステータスを返した

Network error talking to Genesys Cloud

Genesys Cloud に接続できない

client_secret is required for new Genesys Cloud integrations.

作成時に clientSecret が指定されていない

client_secret is required to test credentials.

テストエンドポイントで clientSecret が指定されておらず、この対話プラットフォームに保存済みの Secret もない

対応リージョン

MaiAgent は、リージョンに応じてトークン取得とメッセージ送信のドメインを決定します。ネットワークでアウトバウンド通信を制限している場合は、対応する 2 つのドメインを許可してください。

region

表示名

トークン取得ドメイン

API ドメイン

us-east-1

Americas (US East)

login.mypurecloud.com

api.mypurecloud.com

us-east-2

US East 2 (FedRAMP)

login.use2.us-gov-pure.cloud

api.use2.us-gov-pure.cloud

us-west-2

Americas (US West)

login.usw2.pure.cloud

api.usw2.pure.cloud

ca-central-1

Canada

login.cac1.pure.cloud

api.cac1.pure.cloud

sa-east-1

South America

login.sae1.pure.cloud

api.sae1.pure.cloud

eu-west-1

EMEA (Ireland)

login.mypurecloud.ie

api.mypurecloud.ie

eu-west-2

EMEA (London)

login.euw2.pure.cloud

api.euw2.pure.cloud

eu-central-1

EMEA (Frankfurt)

login.mypurecloud.de

api.mypurecloud.de

eu-central-2

EMEA (Zurich)

login.euc2.pure.cloud

api.euc2.pure.cloud

ap-northeast-1

Asia Pacific (Tokyo)

login.mypurecloud.jp

api.mypurecloud.jp

ap-northeast-2

Asia Pacific (Seoul)

login.apne2.pure.cloud

api.apne2.pure.cloud

ap-northeast-3

Asia Pacific (Osaka)

login.apne3.pure.cloud

api.apne3.pure.cloud

ap-southeast-2

Asia Pacific (Sydney)

login.mypurecloud.com.au

api.mypurecloud.com.au

ap-south-1

Asia Pacific (Mumbai)

login.aps1.pure.cloud

api.aps1.pure.cloud

me-central-1

Middle East (UAE)

login.mec1.pure.cloud

api.mec1.pure.cloud

Webhook の設定

Webhook の共通フィールドと管理 API(/inboxes/{inboxId}/webhooks/)は、Webhook › API で Webhook を管理するを参照してください。Genesys Cloud で使用する設定は次のとおりです。

MaiAgent → Genesys Cloud:Incoming/Outgoing

  • templatePreset を genesys_cloud に設定します。url は空のままで構いません。送信時は常に連携設定から URL を組み立てるため、url フィールドの値は使用されません。

  • 送信時に MaiAgent が自動的に Authorization: Bearer <access token> を付与するため、headers に自分でトークンを入れる必要はありません。

  • 方向に応じて、Genesys Cloud Open Messaging Inbound API の異なるエンドポイントに送信されます。

direction

送信されるメッセージ

送信先

incoming

訪問者のメッセージ

https://{API ドメイン}/api/v2/conversations/messages/{integrationId}/inbound/open/message

outgoing

MaiAgent での Agent または有人オペレーターの返信

https://{API ドメイン}/api/v2/conversations/messages/{integrationId}/inbound/open/receipt

  • genesys_cloud 形式は incoming/outgoing でのみ使用できます。receive で使用すると 400 が返ります。

  • 対話プラットフォームに Genesys Cloud 連携が設定されていない場合、この種の Webhook は送信されず、送信ログも残りません。

Genesys Cloud → MaiAgent:Receive

  • payloadPreset と secretToken はどちらも必須で、不足している場合は 400 が返ります。secretToken は書き込み専用で、参照時には返されません。

  • 作成後にこの Webhook を参照すると、レスポンスに receiveUrl が含まれます。形式は https://<MaiAgent ドメイン>/api/webhooks/inbox/{inboxId}/{webhookId}/ です。Genesys Cloud の Open Messaging 連携で、outbound webhook の URL を receiveUrl に、署名シークレットを同じ secretToken に設定してください。

メッセージ形式:MaiAgent から Genesys Cloud へ

Content-Type: application/json です。Incoming と Outgoing は構造が同じで、direction で区別します。

フィールド
内容

channel.messageId

MaiAgent のメッセージ ID

channel.time

メッセージの作成日時(ISO 8601)

channel.to.id

MaiAgent 対話プラットフォームの ID

channel.from.id

MaiAgent の連絡先 ID(訪問者)。Genesys Cloud は返信時にこの ID を返し、MaiAgent はこれを使って返信先の訪問者を特定します

channel.from.idType

連絡先に Email がある場合は email、ない場合は opaque

channel.from.firstName

連絡先の名前。lastName は常に空文字列

text

メッセージのテキスト。添付ファイルのみでテキストがないメッセージでは空文字列

direction

Incoming Webhook では Inbound、Outgoing Webhook では Outbound

content[]

添付ファイルがある場合のみ含まれます。mediaType の対応:画像とスタンプは Image、動画は Video、音声は Audio、その他は File。url は MaiAgent に保存されているファイルの URL を優先し、ない場合は元の URL を使用します。mime はファイル名から推定され、推定できない場合は application/octet-stream

メッセージ形式:Genesys Cloud から MaiAgent へ

署名検証

MaiAgent は、正しい署名を持つリクエストのみを受け付けます。ヘッダー X-Hub-Signature-256 は、sha256= に続けて、secretToken をキーとして元の request body に対して計算した HMAC-SHA256 の Base64 エンコード値(16 進数ではありません)と等しくなければならず、比較は定数時間で行われます。ヘッダーがない、署名が一致しない、または Webhook に secretToken が設定されていない場合は、いずれも 403 が返ります。

この署名は Genesys Cloud が生成し、MaiAgent が検証します。MaiAgent がプッシュ時に付与する X-MaiAgent-Signature-256(16 進数、タイムスタンプ付き)とは別の仕組みです。

処理される内容

MaiAgent は、Genesys Cloud outbound webhook の body から次を読み取ります。

フィールド
用途

type

Text のみ処理します。その他のタイプ(受信確認やイベントなど)はメッセージを作成せず、すぐに 200 を返します

text

返信テキスト(前後の空白は除去)

content[]

contentType が Attachment で attachment.url を持つ項目から添付ファイルを作成します。mediaType が Image/Video/Audio の場合は同じタイプに対応し、それ以外は通常のファイルになります

channel.to.id

返信先の MaiAgent 連絡先 ID。先に送信した際の channel.from.id にあたります

channel.from

返信者の情報(id、idType、firstName、lastName、nickname)。メッセージの metadata.genesys_from に保存されます

originatingEntity

返信の発信元(例:Human、Bot)。メッセージの metadata.originating_entity に保存されます

id

Genesys Cloud のメッセージ ID。重複排除に使用します

テキストも添付ファイルもない場合、または channel.to.id がない場合は、メッセージを作成せずに 200 を返します。

対話への書き込みと訪問者への転送

  1. channel.to.id でこの対話プラットフォーム内の連絡先を探し、その連絡先がこの対話プラットフォームで最後にメッセージのあった対話を取得します。連絡先または対話が見つからない場合は、メッセージを作成せずに 200 を返します。

  2. 同じ Genesys メッセージ id がすでに書き込まれている場合はスキップされるため、Genesys Cloud が再送しても重複メッセージは作成されません。

  3. 返信メッセージ(Outgoing)を作成します。送信者は対話プラットフォームに紐づけられた Agent です。対話プラットフォームに Agent が紐づけられていない場合は、対話プラットフォームの作成者が使われます。この返信が Genesys の有人オペレーターと bot のどちらからのものかを区別するには、metadata.originating_entity を参照してください。

  4. メッセージは訪問者がいる対話プラットフォームを通じて送信され、MaiAgent の他の返信と同じ送信フローを通ります。添付ファイルがある場合は、先にダウンロードしてから送信します。個々の添付ファイルのダウンロードに失敗しても、テキストとその他の添付ファイルは通常どおり送信されます。

  5. このメッセージは、その対話プラットフォームの Outgoing Webhook を再度トリガーしません。同じ返信が Genesys Cloud に再び送り返されることを防ぐためです。

有人対応への引き継ぎとの関係

Incoming Webhook は、対話が現在 Agent と有人オペレーターのどちらで処理されているかにかかわらず、その対話プラットフォームの訪問者メッセージをすべてプッシュします。Outgoing Webhook は、Agent および MaiAgent 管理画面の有人オペレーターの返信をプッシュします。両方向を設定すると、Genesys Cloud 側で対話の全体を確認できます。

対話を Agent が自動返信するかどうかは、引き続き MaiAgent の対話の有人引き継ぎ状態(auto_reply_enabled)によって決まります。有人引き継ぎの条件、AI に戻すタイミング、API による return-to-ai の呼び出しについては、サードパーティ製カスタマーサービスシステム連携(有人引き継ぎを含む)およびユーザーマニュアルのカスタマーサービス有人引き継ぎの設定を参照してください。

エラー処理

MaiAgent から Genesys Cloud へ

状況
動作

アクセストークンがキャッシュにあり、有効期限まで 60 秒を超える

そのまま使用する

トークンがない、または 60 秒以内に期限切れになる

送信前に Genesys Cloud から新しいトークンを取得する(タイムアウト 10 秒)

Genesys Cloud API が 401 を返した

直ちにトークンを強制的に更新して 1 回再送します。自動再送の回数には含まれません。それでも 401 の場合は停止します

トークン取得時に Genesys Cloud が invalid_client/unauthorized_client を返した

連携を無効としてマークし(tokenStatus: invalidated)、そのメッセージは破棄されます。以降、すべての Genesys 形式の Webhook は、PUT で clientSecret を再入力するまで送信を停止し、送信ログも残しません

タイムアウト、接続失敗、5xx、429

Webhook › 自動再送に従い、約 1 分後、5 分後、15 分後にそれぞれ 1 回再送します

その他の 4xx

失敗として記録し、再送しません

送信したリクエストとレスポンスはすべて送信ログに残ります(ヘッダーはマスクされます)。確認場所は Webhook › 送信の動作を参照してください。

Genesys Cloud から MaiAgent へ

レスポンス
状況

404

Webhook が存在しない、無効化されている、receive タイプではない、または URL 内の対話プラットフォーム ID が Webhook と一致しない

403 {"detail": "Invalid signature."}

署名がない、または一致しない、もしくは Webhook に secretToken が設定されていない

200

検証に成功。書き込みに成功した場合に加え、上記のスキップされるケース(Text 以外、内容なし、連絡先または対話が見つからない、重複メッセージ)も含まれます

200

処理中にエラーが発生した(例:body が有効な JSON ではない)。MaiAgent はエラーを記録した上で 200 を返します

制限事項

  • 各対話プラットフォームに設定できる Genesys Cloud 連携は 1 つのみで、そのプラットフォーム配下のすべての Genesys 形式 Webhook で共有されます。

  • リージョンは、上記の対応リージョンの一覧に限られます。

  • Genesys Cloud から返される内容のうち、処理されるのは Text タイプのテキストと添付ファイルのみです。その他のメッセージタイプは対話に表示されません。

  • 返信は常に、その連絡先がこの対話プラットフォームで最後にメッセージのあった対話に書き込まれます。同じ訪問者に同時に複数の対話がある場合、他の対話を指定することはできません。

  • Receive の Payload のデフォルト形式は、現在 Genesys Cloud のみに対応しています。その他の外部プラットフォームについては、サードパーティ製カスタマーサービスシステム連携の API による書き戻し方式をご利用ください。

最終更新

役に立ちましたか?