> 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/choose-channel/whatsapp.md).

# 会話プラットフォーム連携：WhatsApp

WhatsApp チャネルを連携します。Meta Business アカウントと WhatsApp Business API の認証情報を準備し、MaiAgent でチャネルを追加して Agent を紐付けます。

## 連携前の確認事項 <a href="#pre-integration-checklist" id="pre-integration-checklist"></a>

* [MaiAgent プラットフォーム](https://admin.maiagent.ai/)で「AI アシスタント」を作成済みであること
* [Meta Business](https://business.facebook.com/) アカウントを持っていること
* 連携する電話番号を用意してください。次のいずれでも構いません。
  * WhatsApp Business アカウントに紐付け済みの番号、または Meta の認可ウィンドウで追加する番号
  * スマートフォンの WhatsApp Business App で現在使用中の番号。連携後も App を引き続き使用できます。[WhatsApp Business App と番号を共有する](#business-app-coexistence)を参照してください

## 連携を開始する <a href="#start-integration" id="start-integration"></a>

### 1. チャネル連携ページを開く <a href="#step-go-to-channel-page" id="step-go-to-channel-page"></a>

左側のメニューで<mark style="color:blue;">チャネル</mark>をクリックし、右上の<mark style="color:blue;">チャネルを連携</mark>ボタンをクリックします。

### 2. WhatsApp を選択する <a href="#step-select-whatsapp" id="step-select-whatsapp"></a>

プラットフォーム選択ページで<mark style="color:blue;">WhatsApp</mark>をクリックします。

### 3. Facebook アカウントを接続する <a href="#step-connect-facebook-account" id="step-connect-facebook-account"></a>

<mark style="color:blue;">WhatsApp を接続</mark>ボタンをクリックすると、Facebook OAuth のログインウィンドウが開きます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-09c1beb016a12dcb7030760d06d8b163e178d65c%2Fwhatsapp-connect-button.png?alt=media" alt="チャネル連携の WhatsApp ステップ。画面中央に WhatsApp を接続ボタンがある"><figcaption><p>WhatsApp を接続をクリックして Meta の認可ウィンドウを開きます</p></figcaption></figure>

1. Facebook アカウントにログインします
2. MaiAgent に WhatsApp Business の管理権限へのアクセスを許可します
3. Meta ウィンドウの指示に従って、WhatsApp Business アカウントと電話番号を選択または作成します。WhatsApp Business App で使用中の番号を連携する場合は、既存の WhatsApp Business App を接続するオプションを選択し、指示に従ってスマートフォンの App で確認を完了します
4. 認可が完了すると、ウィンドウが自動的に閉じて設定ページに戻ります

{% hint style="warning" %}
ブラウザーでポップアップが許可されていることを確認してください。許可されていないと、OAuth ログインウィンドウがブロックされる場合があります。
{% endhint %}

### 4. WhatsApp Business アカウントと電話番号を選択する <a href="#step-select-whatsapp-business-account-and-phone" id="step-select-whatsapp-business-account-and-phone"></a>

OAuth 認可が完了したら：

1. <mark style="color:blue;">WhatsApp Business アカウントを選択</mark>のドロップダウンから、Meta ウィンドウで選択したビジネスアカウントを選びます。選択肢はアカウント名ではなく、「WABA」にアカウントの数字 ID を付けた形式で表示されます
2. <mark style="color:blue;">電話番号を選択</mark>のドロップダウンから、メッセージを受信する電話番号を選びます。Meta ウィンドウで番号を選択済みの場合は、その番号だけが一覧に表示されます。WhatsApp Business App の番号を連携する場合や、Meta ウィンドウでビジネスアカウントだけを選択した場合は、そのビジネスアカウントに属する番号が一覧に表示されます

アカウントや番号を間違えた場合は、保存する前に右上の<mark style="color:blue;">再読み込み</mark>をクリックして再認可してください。

{% hint style="warning" %}
保存後はビジネスアカウントと電話番号を変更できず、編集ページに<mark style="color:blue;">再読み込み</mark>も表示されません。別のアカウントや番号を使用するには、この WhatsApp チャネルを削除して作り直してください。
{% endhint %}

### 5. 基本設定 <a href="#step-basic-settings" id="step-basic-settings"></a>

| 項目            | 説明                                                                                                                                                             |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **チャネル名**     | この連携に、識別しやすい名前を付けます                                                                                                                                            |
| **AI アシスタント** | 紐付ける Agent を選択します                                                                                                                                              |
| **リセットコマンド**  | （任意）オンにすると、1 つ以上のコマンド文字列（例：「最初からやり直す」）を追加できます。ユーザーが WhatsApp で送ったメッセージがそのいずれかと完全に一致すると、そのユーザーのために新しい会話が始まります。コマンド自体には返信されず、ユーザーが次のメッセージを送ったときに、AI が新しい会話で回答します |

### 6. 設定を保存する <a href="#step-save-settings" id="step-save-settings"></a>

設定に誤りがないことを確認したら、<mark style="color:blue;">保存</mark>をクリックして連携を完了します。

連携が完了すると、ユーザーが WhatsApp からその電話番号にメッセージを送ったときに、Agent が自動的に返信します。

{% hint style="info" %}
連携に成功すると、チャネル一覧にこの連携が表示されます。編集をクリックすると、機能オプション（OCR 認識、時間帯別の返信、権限管理など）をさらに設定できます。
{% endhint %}

## WhatsApp Business App と番号を共有する <a href="#business-app-coexistence" id="business-app-coexistence"></a>

スマートフォンの WhatsApp Business App で既に運用している番号は、新しい番号に切り替えなくても MaiAgent と連携できます。[Facebook アカウントを接続する](#step-connect-facebook-account)の Meta ウィンドウで既存の WhatsApp Business App を接続することを選択し、完了後に[WhatsApp Business アカウントと電話番号を選択する](#step-select-whatsapp-business-account-and-phone)の手順でその番号を選びます。MaiAgent 側で別途有効化する必要はありません。

連携後、番号は App と MaiAgent の両方で動作します。

* **App は従来どおり使えます**：番号はスマートフォンの WhatsApp Business App に残り、引き続き App で顧客の確認や返信ができます
* **Agent が顧客からのメッセージに返信します**：顧客がこの番号に送ったメッセージは MaiAgent に届き、紐付けた Agent が自動で返信します

{% hint style="warning" %}

* **App での返信は MaiAgent に取り込まれません**：スマートフォンの App で顧客に直接返信したメッセージは MaiAgent の会話履歴に表示されず、それによって Agent が返信を止めることもありません。同じ顧客の次のメッセージにも、Agent はこれまでどおり回答します。有人対応に切り替える必要がある場合は、MaiAgent で対応を引き継いで返信してください。[有人サポートへの引き継ぎと返信](https://docs.maiagent.ai/maiagent-user-guide/ja/serve/daily-operations/human-handoff-operations.md)を参照してください
* **連携前の会話は取り込まれません**：連携前の App のチャット履歴は MaiAgent に取り込まれず、MaiAgent の会話履歴は、連携後に顧客から届いた最初のメッセージから始まります
  {% endhint %}

{% hint style="info" %}
この方法で番号を連携できるかどうか（例：国・地域、App のバージョン）は、Meta の認可ウィンドウに表示されるオプションに従います。
{% endhint %}

## メッセージ形式と連続メッセージ <a href="#message-format-and-merging" id="message-format-and-merging"></a>

* **Markdown は自動的にテキストへ変換されます**：Agent の返信に含まれる見出し、リンク、表、コードなどの Markdown 記法は、WhatsApp に送信される前に自動でプレーンテキストに変換されます（リンクは「テキスト URL」の形になります）。太字は WhatsApp 独自の `*太字*` 形式になります。有人対応の担当者が入力した文字は影響を受けません。[メッセージ内容のレンダリング最適化：メッセージングチャネル](https://docs.maiagent.ai/maiagent-user-guide/ja/build/choose-channel/web-chat/markdown-rendering.md#messaging-channels-plain-text)を参照してください
* **連続メッセージは 1 ラウンドにまとめられます**：ユーザーが複数の画像を続けて送った場合や、画像を送ってからテキストを入力した場合、Agent は一連のメッセージが揃うのを待ってから一度に回答します（画像のみのメッセージは、最後のメッセージから約 4 秒間新しいメッセージがなければ回答し、最長で約 20 秒待ちます。テキストを受信した場合はすぐに回答します）。同じ会話では、一度に 1 ラウンドずつ処理されます

## トラブルシューティング <a href="#troubleshooting" id="troubleshooting"></a>

| 状況またはエラーメッセージ                                                                                | 原因                                                                                                                                                                                                                                                        | 対処方法                                                                                                                                                             |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 組織にプラットフォームのお知らせ「WhatsApp integration requires reconnection」が届き、その WhatsApp チャネルが顧客に返信しなくなった | Meta が MaiAgent に保存されている認可を無効にし、自動更新もできなくなっています。主な原因：この連携を認可した Facebook アカウントのパスワードが変更された、Facebook の設定で MaiAgent のアプリ権限が削除された、認可の有効期限が切れた、または Meta がセキュリティ上の理由でログイン状態をリセットした場合です。システムは認可を 1 日 1 回確認し、更新に失敗したときにのみお知らせを出すため、チャネルが先に返信を止め、お知らせが後から届く場合があります | <mark style="color:blue;">チャネル</mark>でこの WhatsApp チャネルを削除し、[連携を開始する](#start-integration)に従って同じ電話番号で作り直してください。削除するとお知らせは自動的に終了します                                 |
| 接続後に「WhatsApp の登録が完了していません。もう一度お試しください。」と表示される                                               | Meta ウィンドウでの認可完了後に、連携する WhatsApp Business アカウントがシステムに届かなかった（例：Meta ウィンドウでビジネスアカウントを選択しなかった）か、MaiAgent がこの認可を処理する際に失敗しました。Meta ウィンドウを途中で閉じた場合は、画面には何も表示されず、元のページにとどまります                                                                                    | もう一度<mark style="color:blue;">WhatsApp を接続</mark>をクリックし、Meta ウィンドウでビジネスアカウントと電話番号を選択する手順を最後まで進めてください。再試行しても同じメッセージが表示される場合は、カスタマーサポートにお問い合わせください                 |
| <mark style="color:blue;">電話番号を選択</mark>のドロップダウンが空になっている                                     | 選択した WhatsApp Business アカウントに、まだ電話番号がありません                                                                                                                                                                                                                | Meta の WhatsApp 管理ツールで、このビジネスアカウントに電話番号を追加して認証するか、Meta の認可ウィンドウで直接番号を追加してください。完了後、右上の<mark style="color:blue;">再読み込み</mark>をクリックして再認可します                         |
| 保存時に「WhatsApp 電話番号の登録に失敗しました。」と表示される                                                         | Meta がこの番号での WhatsApp Cloud API の利用開始を拒否しました。たとえば、番号の認証が完了していない、または Meta で 2 段階認証の PIN コードが設定されている場合です。WhatsApp Business App で使用中の番号の場合は、システムがその時点で Meta に番号の状態を確認できず、通常の番号の登録手順に誤って進んだ可能性があります                                                           | 通常の番号：Meta の WhatsApp 管理ツールで番号の認証が完了していることを確認してください。2 段階認証を設定している場合は、いったんオフにしてから再度保存します。WhatsApp Business App で使用中の番号：2 段階認証をオフにしても効果はありません。しばらくしてからもう一度保存してください |
| 保存時に「この WhatsApp 電話番号は既に使用されています。」と表示される                                                     | この電話番号は既に別の WhatsApp チャネル（別の組織にある場合もあります）に連携されています。同じ番号は 1 つのチャネルにしか連携できません                                                                                                                                                                               | この番号を使用している元の WhatsApp チャネルを先に削除し（別の組織の場合はその組織の管理者に依頼してください）、あらためて作成してください                                                                                       |


---

# 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/choose-channel/whatsapp.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.
