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 側で次を準備します。
Open Messaging 連携:Integration ID を取得します(管理画面:Genesys Cloud Admin → Message → Platforms)。
OAuth Client:付与タイプは Client Credentials とし、
conversation:message:create権限が必要です。Client ID と Client Secret を取得します。Genesys Cloud 組織が所在するリージョンを確認し、下記の対応リージョンと照合します。
MaiAgent 側で、下記の連携 API を呼び出すために必要な権限は次のとおりです。
アクセスできる対話プラットフォーム:組織オーナーは組織内のすべての対話プラットフォームにアクセスできます。その他のメンバーは、グループを通じてアクセス権を得た対話プラットフォームのみにアクセスでき、組織の MaiGPT 対話プラットフォームには一切アクセスできません。アクセスできない対話プラットフォームには
404が返ります。書き込み(PUT、DELETE、認証情報のテスト):メンバーに「対話プラットフォーム」権限も必要です(組織のプランにこの権限が含まれている場合、オーナーは保有しています)。権限がない場合は
403が返ります。参照(GET)はログインしていれば可能です。
Genesys Cloud 連携の設定
各対話プラットフォームには、Genesys Cloud 連携を最大 1 つ設定できます。
フィールド
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 が返ります。
処理される内容
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 を返します。
対話への書き込みと訪問者への転送
channel.to.idでこの対話プラットフォーム内の連絡先を探し、その連絡先がこの対話プラットフォームで最後にメッセージのあった対話を取得します。連絡先または対話が見つからない場合は、メッセージを作成せずに200を返します。同じ Genesys メッセージ
idがすでに書き込まれている場合はスキップされるため、Genesys Cloud が再送しても重複メッセージは作成されません。返信メッセージ(Outgoing)を作成します。送信者は対話プラットフォームに紐づけられた Agent です。対話プラットフォームに Agent が紐づけられていない場合は、対話プラットフォームの作成者が使われます。この返信が Genesys の有人オペレーターと bot のどちらからのものかを区別するには、
metadata.originating_entityを参照してください。メッセージは訪問者がいる対話プラットフォームを通じて送信され、MaiAgent の他の返信と同じ送信フローを通ります。添付ファイルがある場合は、先にダウンロードしてから送信します。個々の添付ファイルのダウンロードに失敗しても、テキストとその他の添付ファイルは通常どおり送信されます。
このメッセージは、その対話プラットフォームの 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 による書き戻し方式をご利用ください。
関連ページ
Webhook › Genesys Cloud 連携(ユーザーマニュアル):管理画面でのフィールド入力と接続テスト
Webhook:共通フィールド、送信ログ、自動再送、API による Webhook の管理
サードパーティ製カスタマーサービスシステム連携(有人引き継ぎを含む):Genesys Cloud を使用しない場合に、API と Webhook でカスタマーサービスシステムを自分で連携する方法
最終更新
役に立ちましたか?