> 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/build/conversation-settings/human-handoff/handoff-notification.md).

# 有人担当者への引き継ぎ通知

会話が有人サポート担当者に割り当てられたときに通知センターと Email で社内スタッフに通知し、有人への引き継ぎの発生・割り当て・AI への差し戻し・待機のタイムアウトの際には Webhook で外部システムに通知します

会話が AI から有人へ引き継がれ、**サポート担当者に割り当てられる**と、MaiAgent は <mark style="color:blue;">Email</mark>、<mark style="color:blue;">通知センター</mark>、<mark style="color:blue;">Webhook 通知（システム連携）</mark>で通知を送信できます。前の 2 つのチャネルは担当者と管理者に知らせるためのもので、Webhook は割り当てシステム、アラート、CRM などの外部システムが後続の処理を引き継げるようにするものです。AI が有人への引き継ぎを判定したとき、会話が AI に戻されたとき、待機がタイムアウトしたときにもイベントを送信するため、独自の有人サポートを持つ外部システムでも完全に引き継ぐことができます。

{% hint style="info" %}
**ガイドの案内**：このページは対話プラットフォーム設定の手順の 1 つです。テキストサポートの導入手順全体については、[テキストサポート：ゼロから本番運用まで](/maiagent-user-guide/ja/serve/text-service.md)をご覧ください。
{% endhint %}

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

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

通知には、個別にオン・オフできる 3 つのチャネルがあります。**Email と通知センター**は、会話が担当者に割り当てられたとき（Human Assigned）に送信されます。**Webhook** は、次の 4 つの有人引き継ぎライフサイクルイベントを対象とします。

* **Email 通知**：割り当てられた担当者に送信されます。CC の通知対象（たとえば管理者）にも同じメールが届きます（すべての受信者が互いに見えます）。
* **通知センターのお知らせ**：管理画面右上のベル（通知センター）で、割り当てられた担当者と CC の通知対象に「有人引き継ぎ通知」のお知らせを送信します。該当の会話へのリンクが含まれます。
* **Webhook 通知（システム連携）**：管理者が設定した HTTPS の URL に、有人引き継ぎライフサイクルの JSON イベントを送信します。外部システムでの自動チケット作成、引き継ぎ、アラートに利用できます。AI が有人への引き継ぎを判定したときは `handoff.requested`、会話が担当者に割り当てられたときは `handoff.assigned`、担当者が<mark style="color:blue;">AI Agent に戻す</mark>を押して会話を AI に返したときは `handoff.returned_to_ai`、待機のタイムアウトで自動的に AI に戻されたときは `handoff.queue_timeout` です。この 4 つのイベントは、会話のタイムラインにある「引き継ぎ発生」「有人担当者が引き受け」「AI Agent に差し戻し」「待機タイムアウト」に対応します。

{% hint style="warning" %}
**Email と通知センター**は、会話が「**割り当てられた**」ときにのみ通知を送信します。会話が有人引き継ぎの待機列に入っていても、特定の担当者に**まだ割り当てられていない**場合、この 2 つのチャネルは通知を送信しません。有効化済みの **Webhook** は、AI が有人への引き継ぎを判定した時点で `handoff.requested` を送信します。
{% 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.assigned` イベントを受信して自動的にチケットを作成します。担当者が対応を終えて「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>に移動し、設定したい対話プラットフォームで<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" %}
有人への引き継ぎがまだ有効でない場合、左側メニューの<mark style="color:blue;">有人サポートへの引き継ぎ設定</mark>には「未設定」と表示され、ページには<mark style="color:blue;">有人サポートへの引き継ぎを有効化</mark>のスイッチだけが表示されます。<mark style="color:blue;">通知</mark>などのサブタブは表示されません。先に有人サポートへの引き継ぎをオンにして保存してから、以下の設定を行ってください。
{% 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>：AI が有人への引き継ぎを判定したとき、会話が割り当てられたとき、AI に戻されたとき、待機がタイムアウトしたときに、指定した外部システムへイベントを送信します。**デフォルトはオフ**です。連携が必要なときにオンにしてください。

いずれか 1 つのチャネルだけをオフにした場合でも、有効な他のチャネルは通常どおり送信されます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-9bfb10b279b20accd92ea73ee04f8236a1948139%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://` を入力すると「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-3badb22c7c48cd5e0a21af1a1acde0bae07922e0%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}` | 該当の会話へのリンク          |

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-e8a5d6b0e7eb74e9dfcd8ec9e386fd2fe9fbe5a8%2Fhandoff-notification-templates.png?alt=media" alt="通知テンプレートの編集"><figcaption><p>4 つのテンプレート欄と利用できる変数のヒント</p></figcaption></figure>

<details>

<summary>デフォルトテンプレートの内容（参考）</summary>

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

```
【轉真人】對話已指派給您 — {inboxName}
```

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

```
您好 {agentName}，

客服「{inboxName}」有一筆來自 {customerName} 的對話已指派給您。
請點擊以下連結進入後台對話：
{conversationUrl}
```

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

```
對話已指派：{customerName}
```

**お知らせ本文のテンプレート**

```
客服「{inboxName}」有一筆來自 {customerName} 的對話已指派給 {agentName}，請進入後台確認。
```

</details>
{% endstep %}

{% step %}

### 設定を保存する <a href="#save" id="save"></a>

完了したら保存します。設定はすぐに有効になります。その後、システムは各チャネルのスイッチとイベントの対象範囲に従って通知を送信します。Email と通知センターは割り当て時にのみ送信され、Webhook は AI が有人への引き継ぎを判定したとき、割り当て時、AI への差し戻し時、待機のタイムアウト時に送信されます。

{% 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 の通知対象には、同じメールが **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>をクリックすると、該当の会話を直接開けます。通知センターの詳細については、[通知センター](/maiagent-user-guide/ja/start/notifications.md)をご覧ください。

{% hint style="info" %}
有人引き継ぎ通知は、発生頻度の高いトランザクション系のイベントです。お知らせ一覧があふれないよう、これらのお知らせは送信から **7 日後に自動的に期限切れ**になります。
{% endhint %}

### 外部システムに届く内容 <a href="#what-webhook-receives" id="what-webhook-receives"></a>

外部システムには JSON イベントが 1 件届きます。内容は識別情報のみで、イベント名、イベント ID と発生時刻、会話、対話プラットフォーム、組織、お客様、そのイベント時点で割り当てられていた担当者の ID、そして管理画面の会話へのリンクが含まれます。会話のテキストは一切含まれません。4 種類のイベントのフィールドは共通で、担当者が割り当てられていないイベント（引き継ぎ発生、AI への差し戻し、待機タイムアウト）では、割り当て担当者は空になります。詳しいフィールドと検証例については、API ドキュメントの[有人引き継ぎ Webhook イベント](https://docs.maiagent.ai/api/preparation/handoff-webhook)をご覧ください。

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

* **権限**：通知設定を閲覧・編集できるのは、該当の対話プラットフォームの設定権限を持つ方のみです。既存の有人引き継ぎ設定の権限がそのまま適用されます。
* **担当者に Email がない場合**：割り当てられた担当者に Email が設定されていない場合、システムは Email チャネルを自動的にスキップしますが、**通知センターのお知らせは通常どおり送信され**、他の受信者には影響しません。
* **チャネルは互いに独立**：Email、通知センター、Webhook はそれぞれ独立して動作します。いずれか 1 つの送信に失敗しても、他のチャネルや会話の割り当て処理には影響しません。
* **Webhook の失敗時の処理**：外部エンドポイントがタイムアウトしたりエラーを返したりした場合、システムはバックグラウンドで自動的に 3 回再試行します。この間も、有人への引き継ぎと他の通知チャネルは通常どおり動作します。受信側では、イベント ID を使って重複イベントを除外してください。
* **対話プラットフォームの「Webhook」との違い**：対話プラットフォームには、会話メッセージそのものを送信する [Webhook](/maiagent-user-guide/ja/build/conversation-settings/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 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/maiagent-user-guide/ja/build/conversation-settings/human-handoff/handoff-notification.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.
