> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/ja/serve/customer-service-system-integration/genesys-cloud-integration.md).

# 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 が訪問者へ転送します。

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

管理画面での操作手順（どこに入力し、どのボタンを押すか）は、ユーザーマニュアルの [Webhook › Genesys Cloud 連携](https://docs.maiagent.ai/build/conversation-settings/webhook#genesys-cloud-integration)を参照してください。このページでは、その背後にあるプロトコル、API、動作について説明します。

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

## 連携アーキテクチャ <a href="#architecture" id="architecture"></a>

```mermaid
sequenceDiagram
    participant V as 訪問者
    participant M as MaiAgent 対話プラットフォーム
    participant G as Genesys Cloud

    V->>M: メッセージを送信
    M->>G: Incoming Webhook（Genesys 形式）<br/>POST …/inbound/open/message
    M-->>V: Agent の返信
    M->>G: Outgoing Webhook（Genesys 形式）<br/>POST …/inbound/open/receipt
    Note over G: オペレーターまたは bot が返信
    G->>M: Genesys outbound webhook<br/>POST MaiAgent 受信 URL（X-Hub-Signature-256）
    M-->>V: 返信を訪問者に転送
```

連携は、同じ対話プラットフォーム上の 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 を提供します                                                                                                                         |

## 事前準備 <a href="#prerequisites" id="prerequisites"></a>

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 組織が所在するリージョンを確認し、下記の[対応リージョン](#regions)と照合します。

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

* **アクセスできる対話プラットフォーム**：組織オーナーは組織内のすべての対話プラットフォームにアクセスできます。その他のメンバーは、グループを通じてアクセス権を得た対話プラットフォームのみにアクセスでき、組織の MaiGPT 対話プラットフォームには一切アクセスできません。アクセスできない対話プラットフォームには `404` が返ります。
* **書き込み**（PUT、DELETE、認証情報のテスト）：メンバーに「対話プラットフォーム」権限も必要です（組織のプランにこの権限が含まれている場合、オーナーは保有しています）。権限がない場合は `403` が返ります。参照（GET）はログインしていれば可能です。

## Genesys Cloud 連携の設定 <a href="#integration-settings" id="integration-settings"></a>

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

### フィールド <a href="#integration-fields" id="integration-fields"></a>

| フィールド                        | 型       | 説明                                                                                                                                                                      |
| ---------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `region`                     | string  | Genesys Cloud のリージョンコード。[対応リージョン](#regions)を参照してください。必須                                                                                                                 |
| `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 <a href="#integration-api" id="integration-api"></a>

```bash
# 参照（未設定の場合は 200 を返し、内容は null）
GET    https://api.maiagent.ai/api/v1/inboxes/{inboxId}/genesys-cloud-integration/

# 作成または更新（同じエンドポイント）
PUT    https://api.maiagent.ai/api/v1/inboxes/{inboxId}/genesys-cloud-integration/

# 削除（未設定の場合も 204 を返す）
DELETE https://api.maiagent.ai/api/v1/inboxes/{inboxId}/genesys-cloud-integration/

# 認証情報のテスト。データは一切保存されず、成功時は 204 を返す
POST   https://api.maiagent.ai/api/v1/inboxes/{inboxId}/genesys-cloud-integration/test/
```

```json
{
  "region": "ap-northeast-1",
  "integrationId": "your-open-messaging-integration-id",
  "clientId": "your-oauth-client-id",
  "clientSecret": "your-oauth-client-secret"
}
```

* **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 もない    |

### 対応リージョン <a href="#regions" id="regions"></a>

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 の設定 <a href="#webhooks" id="webhooks"></a>

Webhook の共通フィールドと管理 API（`/inboxes/{inboxId}/webhooks/`）は、[Webhook › API で Webhook を管理する](https://docs.maiagent.ai/tech/ja/serve/webhook.md#manage-by-api)を参照してください。Genesys Cloud で使用する設定は次のとおりです。

### MaiAgent → Genesys Cloud：Incoming／Outgoing <a href="#outbound-webhooks" id="outbound-webhooks"></a>

```json
{
  "name": "訪問者メッセージを Genesys Cloud へ送信",
  "direction": "incoming",
  "isEnabled": true,
  "templatePreset": "genesys_cloud"
}
```

* `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 <a href="#receive-webhook" id="receive-webhook"></a>

```json
{
  "name": "Genesys Cloud の返信を受信",
  "direction": "receive",
  "isEnabled": true,
  "payloadPreset": "genesys_cloud",
  "secretToken": "Genesys Cloud と共有する署名シークレット"
}
```

* `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 へ <a href="#outbound-payload" id="outbound-payload"></a>

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

```json
{
  "channel": {
    "messageId": "2491074a-6d23-4289-af45-caa12531420e",
    "type": "Private",
    "time": "2026-10-12T02:15:30.123456+00:00",
    "to": { "id": "1f9c1c1e-4d1a-4b1e-9d0e-7b2f4a5c6d7e" },
    "from": {
      "id": "c0ffee00-1111-2222-3333-444455556666",
      "idType": "opaque",
      "firstName": "山田太郎",
      "lastName": ""
    }
  },
  "type": "Text",
  "text": "注文状況を確認したいです",
  "direction": "Inbound",
  "content": [
    {
      "contentType": "Attachment",
      "attachment": {
        "mediaType": "Image",
        "url": "https://example.com/photo.jpg",
        "mime": "image/jpeg",
        "filename": "photo.jpg"
      }
    }
  ]
}
```

| フィールド                    | 内容                                                                                                                                                                                                          |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 へ <a href="#inbound-payload" id="inbound-payload"></a>

### 署名検証 <a href="#receive-signature" id="receive-signature"></a>

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

{% hint style="info" %}
この署名は Genesys Cloud が生成し、MaiAgent が検証します。MaiAgent がプッシュ時に付与する `X-MaiAgent-Signature-256`（16 進数、タイムスタンプ付き）とは別の仕組みです。
{% endhint %}

### 処理される内容 <a href="#receive-parsing" id="receive-parsing"></a>

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` を返します。

### 対話への書き込みと訪問者への転送 <a href="#receive-delivery" id="receive-delivery"></a>

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 に再び送り返されることを防ぐためです。

## 有人対応への引き継ぎとの関係 <a href="#handoff" id="handoff"></a>

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

対話を Agent が自動返信するかどうかは、引き続き MaiAgent の対話の有人引き継ぎ状態（`auto_reply_enabled`）によって決まります。有人引き継ぎの条件、AI に戻すタイミング、API による `return-to-ai` の呼び出しについては、[サードパーティ製カスタマーサービスシステム連携（有人引き継ぎを含む）](https://docs.maiagent.ai/tech/ja/serve/customer-service-system-integration.md#scenario-b)およびユーザーマニュアルの[カスタマーサービス有人引き継ぎの設定](https://docs.maiagent.ai/build/conversation-settings/human-handoff)を参照してください。

## エラー処理 <a href="#error-handling" id="error-handling"></a>

### MaiAgent から Genesys Cloud へ <a href="#outbound-errors" id="outbound-errors"></a>

| 状況                                                                   | 動作                                                                                                                                   |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| アクセストークンがキャッシュにあり、有効期限まで 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 › 自動再送](https://docs.maiagent.ai/tech/ja/serve/webhook.md#retry)に従い、約 1 分後、5 分後、15 分後にそれぞれ 1 回再送します                         |
| その他の `4xx`                                                           | 失敗として記録し、再送しません                                                                                                                      |

送信したリクエストとレスポンスはすべて送信ログに残ります（ヘッダーはマスクされます）。確認場所は [Webhook › 送信の動作](https://docs.maiagent.ai/tech/ja/serve/webhook.md#delivery)を参照してください。

### Genesys Cloud から MaiAgent へ <a href="#inbound-errors" id="inbound-errors"></a>

| レスポンス                                    | 状況                                                                                 |
| ---------------------------------------- | ---------------------------------------------------------------------------------- |
| `404`                                    | Webhook が存在しない、無効化されている、`receive` タイプではない、または URL 内の対話プラットフォーム ID が Webhook と一致しない |
| `403` `{"detail": "Invalid signature."}` | 署名がない、または一致しない、もしくは Webhook に `secretToken` が設定されていない                              |
| `200`                                    | 検証に成功。書き込みに成功した場合に加え、上記のスキップされるケース（`Text` 以外、内容なし、連絡先または対話が見つからない、重複メッセージ）も含まれます   |
| `200`                                    | 処理中にエラーが発生した（例：body が有効な JSON ではない）。MaiAgent はエラーを記録した上で `200` を返します               |

{% hint style="warning" %}
署名の検証に成功した後は、各種のスキップや内部エラーでもすべて `200` が返ります。Genesys Cloud 側で送信成功と表示されても、訪問者が受け取ったとは限りません。MaiAgent の対話履歴で確認してください。
{% endhint %}

## 制限事項 <a href="#limitations" id="limitations"></a>

* 各対話プラットフォームに設定できる Genesys Cloud 連携は 1 つのみで、そのプラットフォーム配下のすべての Genesys 形式 Webhook で共有されます。
* リージョンは、上記の[対応リージョン](#regions)の一覧に限られます。
* Genesys Cloud から返される内容のうち、処理されるのは `Text` タイプのテキストと添付ファイルのみです。その他のメッセージタイプは対話に表示されません。
* 返信は常に、その連絡先がこの対話プラットフォームで最後にメッセージのあった対話に書き込まれます。同じ訪問者に同時に複数の対話がある場合、他の対話を指定することはできません。
* Receive の Payload のデフォルト形式は、現在 Genesys Cloud のみに対応しています。その他の外部プラットフォームについては、[サードパーティ製カスタマーサービスシステム連携](https://docs.maiagent.ai/tech/ja/serve/customer-service-system-integration.md)の API による書き戻し方式をご利用ください。

## 関連ページ <a href="#related" id="related"></a>

* [Webhook › Genesys Cloud 連携](https://docs.maiagent.ai/build/conversation-settings/webhook#genesys-cloud-integration)（ユーザーマニュアル）：管理画面でのフィールド入力と接続テスト
* [Webhook](https://docs.maiagent.ai/tech/ja/serve/webhook.md)：共通フィールド、送信ログ、自動再送、API による Webhook の管理
* [サードパーティ製カスタマーサービスシステム連携（有人引き継ぎを含む）](https://docs.maiagent.ai/tech/ja/serve/customer-service-system-integration.md)：Genesys Cloud を使用しない場合に、API と Webhook でカスタマーサービスシステムを自分で連携する方法


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/ja/serve/customer-service-system-integration/genesys-cloud-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
