> 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/maiagent-user-guide/ja/conversations/human-handoff/handoff-notification.md).

# 有人対応への引き継ぎ通知

対話が有人オペレーターに割り当てられた際、通知センター、Email、または Webhook を通じて社内スタッフと外部システムに通知します

対話が AI から有人対応に切り替わり、**カスタマーサポートのオペレーターに割り当てられた**とき、MaiAgent は <mark style="color:blue;">Email</mark>、<mark style="color:blue;">通知センター</mark>、<mark style="color:blue;">Webhook 通知（システム連携）</mark>を通じて通知できます。最初の 2 つのチャネルはオペレーターと管理者に通知し、Webhook はディスパッチ、アラート、CRM などの外部システムによる後続処理を可能にします。

{% hint style="info" %}
この機能は「**有人対応設定**」の一部です。通知は、対話プラットフォームで<mark style="color:blue;">有人対応への引き継ぎ</mark>が有効になっている場合にのみ送信されます。
{% endhint %}

## どのような場合に通知が送信されますか？ <a href="#when-notified" id="when-notified"></a>

通知は、対話が**特定のオペレーターに割り当てられた**（Human Assigned）瞬間に送信され、以下の 3 つのチャネルを個別にオンまたはオフにできます。

* **Email 通知**：割り当てられたオペレーターに送信されます。CC 通知対象（管理者など）にも同じメールのコピーが送信されます（すべての受信者は互いに確認できます）。
* **通知センターのお知らせ**：ダッシュボード右上のベルアイコン（通知センター）に、割り当て先のオペレーターと CC 通知対象に対して「引き継ぎ通知」のお知らせが表示されます。お知らせには該当する対話へのリンクが含まれます。
* **Webhook 通知（システム連携）**：管理者が設定した HTTPS URL に `handoff.created` JSON イベントを送信し、外部システムでチケットやアラートを自動作成できるようにします。その後、オペレーターが<mark style="color:blue;">AI Agent に戻す</mark>をクリックして対話を AI に戻すと、同じ URL に `handoff.returned_to_ai` イベントも送信され、今回の有人対応が終了したことを外部システムに通知します。

{% hint style="warning" %}
通知は対話が「**割り当てられた**」ときにのみ送信されます。対話が有人対応キューに入っていても、特定のオペレーターに**まだ割り当てられていない**場合、この段階では通知は送信されません。
{% endhint %}

### 通知で行われないこと <a href="#what-it-does-not-do" id="what-it-does-not-do"></a>

* Email やお知らせのリンクをクリックすると、該当する対話が**開かれるだけ**であり、対話が自動的に有人応答モードに切り替わる**わけではありません**。対話に入った後、オペレーターは対話上部の<mark style="color:blue;">引き継ぎ</mark>ボタンをクリックして、AI の自動応答を停止し、手動で対応を引き継ぐ必要があります。
* 通知はお客様には送信されません。これは純粋に**社内スタッフ向け**のリマインダーであり、お客様に表示される引き継ぎメッセージには影響しません。
* Webhook は、イベントに必要な識別情報とダッシュボードの対話リンクのみを送信します。対話のテキストは含まれず、特定のサードパーティシステム専用の変換機能も提供しません。

## 利用シーン <a href="#scenario" id="scenario"></a>

カスタマーサポートの管理者は、お知らせや Email を人が監視するのではなく、有人対応への引き継ぎが発生するたびに、社内のディスパッチシステムへ自動的に登録されるようにしたいと考えています。対象の対話プラットフォームで<mark style="color:blue;">有人対応設定</mark>を開き、<mark style="color:blue;">通知</mark>タブで<mark style="color:blue;">Webhook 通知（システム連携）</mark>を有効にして、社内ディスパッチシステムの HTTPS 受信 URL を入力し、設定を保存します。次に対話がオペレーターへ割り当てられると、ディスパッチシステムは直ちに `handoff.created` イベントを受信し、チケットを自動作成します。対応を終えたオペレーターが「AI Agent に戻す」をクリックすると、ディスパッチシステムは `handoff.returned_to_ai` を受信してチケットを自動的にクローズします。この一連の流れで、管理者が情報を手動で転送する必要はありません。

## 通知の設定方法 <a href="#setup" id="setup"></a>

{% stepper %}
{% step %}

### 通知設定に入る <a href="#enter-settings" id="enter-settings"></a>

1. <mark style="color:blue;">設定</mark>に移動し、設定したい<mark style="color:blue;">対話プラットフォーム</mark>を開きます。
2. <mark style="color:blue;">有人対応設定</mark>タブに切り替え、上部の<mark style="color:blue;">有人対応への引き継ぎを有効にする</mark>がオンになっていることを確認します。
3. <mark style="color:blue;">通知</mark>サブタブをクリックします。

{% hint style="info" %}
有人対応がまだ有効になっていない場合、通知タブには「**現在、有人対応は無効です。有効にすると通知が送信されます。**」というメッセージが表示されます。まず有人対応への引き継ぎを有効にしてください。
{% endhint %}
{% endstep %}

{% step %}

### 通知チャネルの選択 <a href="#channels" id="channels"></a>

通知タブには 3 つの独立したトグルがあり、必要に応じて個別にオンまたはオフにできます。

* <mark style="color:blue;">通知センターのお知らせ</mark>：対話が割り当てられると、通知センターに割り当て先のオペレーターと CC 通知対象に対してお知らせが投稿されます。
* <mark style="color:blue;">Email 通知</mark>：対話が割り当てられると、割り当て先のオペレーターに Email が送信され、指定された対象に CC 通知が送信されます。
* <mark style="color:blue;">Webhook 通知（システム連携）</mark>：対話が割り当てられると、指定した外部システムへイベントを送信します。**デフォルトではオフ**になっており、連携が必要な場合に有効にします。

いずれか 1 つのチャネルをオフにしても、ほかの有効なチャネルは通常どおり送信されます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-a0c1b268a0453c8251191987be723209651f720e%2Fhandoff-notification-channels.png?alt=media" alt="有人対応設定の通知サブタブ"><figcaption><p>有人対応設定 →「通知」サブタブ：3 つのチャネルトグル、CC 通知対象、通知テンプレート</p></figcaption></figure>
{% endstep %}

{% step %}

### Webhook の設定（任意） <a href="#webhook" id="webhook"></a>

1. <mark style="color:blue;">Webhook 通知（システム連携）</mark>を有効にすると、その下に Webhook の入力欄が表示されます。
2. <mark style="color:blue;">Webhook URL</mark>に外部システムの受信 URL を入力します。URL は `https://` で始まる必要があります。空欄の場合は「Webhook を有効にする場合は Webhook URL を入力してください」、`http://` の URL を入力した場合は「Webhook URL には HTTPS を使用してください」と表示され、いずれの場合も保存できません。
3. 受信側でイベントの送信元を検証する必要がある場合は、<mark style="color:blue;">署名シークレット（任意）</mark>に双方で合意したシークレットを入力します。署名を有効にすると、すべての配信に `X-MaiAgent-Signature-256` ヘッダーが付与されます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-bd4f18f9d851932ab6c6ec362c5f39e06005b1b5%2Fhandoff-notification-webhook.png?alt=media" alt="Webhook 通知を有効にした後に表示される URL と署名シークレットの入力欄"><figcaption><p>Webhook 通知（システム連携）を有効にした後に表示される「Webhook URL」と「署名シークレット（任意）」の入力欄</p></figcaption></figure>

**保存後のシークレット管理**：

* シークレットは保存後に**再表示されません**。入力欄には「設定済み — 空欄のままにすると変更されません」と表示されます。シークレットを変更するには新しい値を入力して保存し、既存のシークレットを維持する場合は空欄のままにします。
* 署名を停止するには、入力欄の横にある<mark style="color:blue;">シークレットをクリア</mark>をクリックして確認します。クリア後の配信には署名ヘッダーが付与されません。受信側で署名を検証している場合は配信が拒否されるようになるため、先に受信側を調整してからクリアしてください。

{% hint style="info" %}
イベントのフィールド形式、署名の検証方法、再試行の動作については、API ドキュメントの[有人対応 Webhook イベント](https://docs.maiagent.ai/api/preparation/handoff-webhook)を参照してください。独自のカスタマーサポートシステムで有人対応を行う場合は、同じページの「有人対応への引き継ぎ後に外部システムで対話を引き継ぐ」で、対話プラットフォームの<mark style="color:blue;">Webhook</mark>（メッセージの送受信）とメッセージ API を組み合わせて双方向に同期する方法を説明しています。
{% endhint %}

{% hint style="warning" %}
受信側では、イベント内の識別情報とダッシュボードの対話リンクを適切な担当者のみが閲覧できるようにしてください。この連携を使用しなくなった場合は、Webhook 通知を無効にしてください。
{% endhint %}
{% endstep %}

{% step %}

### CC 通知対象の設定（任意） <a href="#copy-recipients" id="copy-recipients"></a>

管理者や他のスタッフにも有人対応の状況を把握してもらいたい場合、CC 通知対象を設定できます。

* <mark style="color:blue;">CC 通知の送信（メンバー）</mark>：CC 通知を受け取るメンバー（管理者など）を選択します。
* <mark style="color:blue;">CC 通知の送信（グループ）</mark>：CC 通知を受け取るグループを選択します。グループは自動的にすべてのメンバーに展開されます。

割り当てられたオペレーター本人は CC 通知対象から自動的に除外されます（重複通知を防止します）。
{% endstep %}

{% step %}

### 通知テンプレートのカスタマイズ（任意） <a href="#templates" id="templates"></a>

4 つのテンプレート欄で通知テキストをカスタマイズできます。有人対応を有効にすると、デフォルトのテンプレートが自動入力されます。

* <mark style="color:blue;">お知らせタイトルテンプレート</mark>
* <mark style="color:blue;">お知らせ内容テンプレート</mark>
* <mark style="color:blue;">Email 件名テンプレート</mark>
* <mark style="color:blue;">Email 本文テンプレート</mark>

テンプレートでは以下の**変数**を使用でき、送信時に該当する対話の実際の内容に自動的に置き換えられます。

| 変数                  | 置き換え内容                    |
| ------------------- | ------------------------- |
| `{agentName}`       | 割り当てられたカスタマーサポートオペレーターの名前 |
| `{inboxName}`       | 対話プラットフォーム（カスタマーサポート）名    |
| `{customerName}`    | お客様（訪問者）の名前               |
| `{conversationUrl}` | 該当する対話へのリンク               |

<details>

<summary>デフォルトテンプレートの内容リファレンス</summary>

**Email 件名テンプレート**

```
【引き継ぎ】対話が割り当てられました — {inboxName}
```

**Email 本文テンプレート**

```
{agentName} 様、

カスタマーサポート「{inboxName}」にて、{customerName} 様からの対話が割り当てられました。
以下のリンクをクリックしてダッシュボードの対話に入ってください：
{conversationUrl}
```

**お知らせタイトルテンプレート**

```
対話が割り当てられました：{customerName}
```

**お知らせ内容テンプレート**

```
カスタマーサポート「{inboxName}」にて、{customerName} 様からの対話が {agentName} に割り当てられました。ダッシュボードで確認してください。
```

</details>
{% endstep %}

{% step %}

### 設定の保存 <a href="#save" id="save"></a>

保存すると、設定は即座に有効になります。以降、この対話プラットフォームで対話がオペレーターに割り当てられるたびに、上記の設定に従って通知が送信されます。

{% hint style="info" %} <mark style="color:blue;">有人対応への引き継ぎを有効にする</mark>をオフにすると、通知の送信も停止します。ただし、通知設定は**保持されます**。有人対応を再度有効にすると、以前の設定が復元されます。
{% endhint %}
{% endstep %}
{% endstepper %}

## 受信者に届く内容 <a href="#what-recipients-see" id="what-recipients-see"></a>

### Email 通知 <a href="#email" id="email"></a>

割り当てられたオペレーターには、MaiAgent ブランドスタイルの Email が届きます。件名と本文はテンプレートに基づいて生成され、該当する対話へのリンクが含まれます。CC 通知対象には同じメールの**コピー**が送信されます（すべての受信者は互いに確認できます）。

### 通知センターのお知らせ <a href="#notification-center" id="notification-center"></a>

ダッシュボード右上のベルアイコンをクリックして<mark style="color:blue;">通知センター</mark>を開き、<mark style="color:blue;">組織のお知らせ</mark>タブに切り替えると、<mark style="color:blue;">引き継ぎ通知</mark>タイプのお知らせが表示されます。お知らせ内の<mark style="color:blue;">引き継ぎに移動</mark>をクリックすると、該当する対話を直接開くことができます。

{% hint style="info" %}
引き継ぎ通知は高頻度のトランザクションイベントです。お知らせリストの過密を避けるため、これらのお知らせは発行後 **7 日で自動的に期限切れ**になります。
{% endhint %}

### 外部システムが受信する内容 <a href="#what-webhook-receives" id="what-webhook-receives"></a>

外部システムは、イベント名、対話、対話プラットフォーム、組織、お客様、割り当て先オペレーターの各識別子、およびダッシュボードの対話リンクのみを含む JSON イベントを受信します。対話のテキストは含まれません。対話が AI に戻った際に受信する `handoff.returned_to_ai` のフィールドも同じですが、割り当て先オペレーターは空になります。フィールドの詳細と検証例については、API ドキュメントの[有人対応 Webhook イベント](https://docs.maiagent.ai/api/preparation/handoff-webhook)を参照してください。

## 注意事項 <a href="#notes" id="notes"></a>

* **権限**：対話プラットフォームの設定権限を持つユーザーのみが通知設定を閲覧・編集できます。既存の有人対応設定の権限に準じます。
* **オペレーターに Email が未設定の場合**：割り当てられたオペレーターに Email が設定されていない場合、システムは Email チャネルを自動的にスキップしますが、**通知センターのお知らせは通常どおり送信されます**。他の受信者への影響はありません。
* **チャネルは独立して動作**：Email、通知センター、Webhook はそれぞれ独立して動作します。いずれかのチャネルで送信に失敗しても、ほかのチャネルや対話の割り当てプロセスには影響しません。
* **Webhook の失敗処理**：外部エンドポイントがタイムアウトするかエラーを返した場合、システムはバックグラウンドで自動的に 3 回再試行します。その間も有人対応への引き継ぎとほかの通知チャネルは通常どおり動作します。受信側で重複イベントを排除してください。
* **対話プラットフォームの「Webhook」との違い**：対話プラットフォームには、対話メッセージ自体を送信する別の [Webhook](/maiagent-user-guide/ja/conversations/webhook.md) 機能があります。有人対応 Webhook は有人対応のステータスイベントのみを送信します。両者の設定とシークレットはそれぞれ独立しており、相互に影響しません。
* **対話に入った後も引き継ぎが必要**：前述のとおり、リンクは対話自体に移動するだけです。実際の引き継ぎは対話上部の<mark style="color:blue;">引き継ぎ</mark>ボタンで行います。


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/ja/conversations/human-handoff/handoff-notification.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.