> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Chatwoot統合

> WhatsAppの会話をChatwoot受信トレイに反映し、エージェントにChatwootから返信させます。

チャットウッドを有効にすると、GOWA転送のWhatsAppメッセージ(受信) そして、電話から送信されたもの) Chatwoot **APIチャンネル** 受信トレイに送信し、ChatwootからWhatsAppにエージェントの返信を送信します。 テキスト、画像、オーディオ、ビデオ、ドキュメント、ステッカー、場所、連絡先がサポートされます。グループチャットはグループごとに1つの会話として表示され、送信者名がプレフィックスされます。

```mermaid theme={null}
flowchart LR
  WA[WhatsApp] -- messages --> G[GOWA]
  G -- Chatwoot REST API --> CW[Chatwoot inbox]
  CW -- webhook /chatwoot/webhook --> G
  G -- agent reply --> WA
```

## 要件

* パブリックURL(エージェントリプライ用Webフック用)を介してチャットウッドからGOWAアクセス可能です。
* 管理者アクセスとユーザ API アクセストークンを持つ Chatwoot アカウント。
* 少なくとも1つのログインのWhatsAppデバイス。

## 設定

**1. API チャンネル受信トレイを作成**

Chatwoot で **設定 → 受信トレイ → API** に移動します。 受信トレイの URL からの数値の **受信トレイID** とチャンネルの **Webhook シークレット** Chatwoot ショーに注意してください。 あるいは、GOWA に受信トレイを作成させてください ( [Auto-provisioning](#%E8%87%AA%E5%8B%95%E3%83%97%E3%83%AD%E3%83%93%E3%82%B8%E3%83%A7%E3%83%8B%E3%83%B3%E3%82%B0)を参照してください)。

**2. IDとトークンを収集**

**account ID** is the number in `/app/accounts/<id>/...` . Copy a user **access token** from **Profile Settings** . `identifier` または `hmac_token` ではなく、どちらのIDも数値IDでなければなりません。

**3. GOWAの設定**

```bash .env theme={null}
CHATWOOT_ENABLED=true
CHATWOOT_URL=https://chatwoot.example.com
CHATWOOT_API_TOKEN=your_user_access_token
CHATWOOT_ACCOUNT_ID=1
CHATWOOT_INBOX_ID=3
CHATWOOT_DEVICE_ID=my-device              # required with more than one device
CHATWOOT_WEBHOOK_SECRET=secret-shown-by-chatwoot
CHATWOOT_WEBHOOK_URL=https://gowa.example.com/chatwoot/webhook
```

GOWAを再起動: Chatwootルートが起動時に登録されます。

**4. GOWAでのポイントChatwoot**

API チャンネルの webhook URL を `https://gowa.example.com/chatwoot/webhook` に設定します(`APP_BASE_PATH` にベースパスを追加します)。 このルートは公開されています。Basic Authではなく、Webhookのシークレットによって保護されています。

**5. テスト**

別の携帯電話からのWhatsApp番号をメッセージ; それは受信トレイに表示されるはずです. Chatwootから返信し、それがのWhatsAppに到着確認します.

## 設定

| 変数 | デフォルト | 説明 |
| - | - | - |
| `CHATWOOT_ENABLED` | `false` | マスタースイッチ。 |
| `CHATWOOT_URL` | — | Chatwootベース URL、ゴミ箱はありません。 |
| `CHATWOOT_API_TOKEN` | — | ユーザー API アクセストークン。 |
| `CHATWOOT_ACCOUNT_ID` | — | 数字のアカウントID。 |
| `CHATWOOT_INBOX_ID` | — | 数値の受信トレイID。オプションで `CHATWOOT_AUTO_CREATE=true` ; 設定すると常に勝利。 |
| `CHATWOOT_DEVICE_ID` | — | エージェントの返信を送信するデバイス (スロット ID または JID) 。複数のデバイスが存在する場合に必要です。 |
| `CHATWOOT_WEBHOOK_URL` | — | パブリックGOWA Webhook URL; 受信トレイの自動作成時に使用されます。 |
| `CHATWOOT_WEBHOOK_SECRET` | — | 受信するChatwootウェブフックを検証します。明示的な符号なしオーバーライドが有効でない限り、空の有効な秘密の呼び出しを拒否します。 |
| `CHATWOOT_WEBHOOK_ALLOW_UNSIGNED` | `false` | 効果的なシークレットがないリクエストを承認します。信頼できるネットワークに制限してください。 |
| `CHATWOOT_WEBHOOK_SIGNATURE_TOLERANCE` | `5m` | `X-Chatwoot-Timestamp`の最大年齢/クロック傾斜。 |
| `CHATWOOT_AUTO_CREATE` | `false` | 起動時に`CHATWOOT_INBOX_NAME`という名前のAPI受信トレイを再利用または作成します。 |
| `CHATWOOT_INBOX_NAME` | `WhatsApp` | 自動プロビジョニングの受信トレイ名です。 |
| `CHATWOOT_IMPORT_MESSAGES` | `false` | デバイスが接続されたときに自動的に履歴をインポートします。 |
| `CHATWOOT_DAYS_LIMIT_IMPORT_MESSAGES` | `3` | インポートする歴史の日。 |
| `CHATWOOT_IMPORT_DB_URI` | — | 直接履歴インポート用のChatwoot PostgreSQL URI(元のタイムスタンプを保持します)。 |
| `CHATWOOT_IMPORT_PLACEHOLDER_MEDIA_MESSAGE` | `true` | 直接インポート: ダウンロードできないメディアには、`[image]` 形式のプレースホルダーを挿入します。 |
| `CHATWOOT_IMPORT_MEDIA_WITH_REST` | `false` | 直接インポート:添付ファイルが作成されるように REST API を使用してメディアをアップロードします。 |
| `CHATWOOT_REOPEN_CONVERSATION` | `true` | 連絡先が再び書き込まれたときに解決済みの会話を再開します。 |
| `CHATWOOT_CONVERSATION_PENDING` | `false` | `open`の代わりに`pending`として新しい会話を作成します。 |
| `CHATWOOT_IGNORE_JIDS` | — | カンマで区切られたJIDまたはワイルドカード(`@g.us`, `@s.whatsapp.net`, `@lid`) はミラーされません。 |
| `CHATWOOT_SIGN_MSG` | `false` | プレフィックスエージェントはエージェント名を返します。 |
| `CHATWOOT_SIGN_DELIMITER` | `\n\n` | 署名とメッセージの区切り文字。 |
| `CHATWOOT_FORWARD_EDITS` | `true` | ミラーのWhatsAppはプライベートノートとして編集します。 |
| `CHATWOOT_FORWARD_DELETES` | `true` | プライベートノートとして全員削除をミラーします。 |
| `CHATWOOT_EVENTS` | `WHATSAPP_WEBHOOK_EVENTS` をフォロー | コンマで区切られたイベントをChatwootに転送します。 |
| `CHATWOOT_MESSAGE_READ` | `false` | 読み取りステータスを同期する方法は両方あります。 |
| `CHATWOOT_MESSAGE_DELETE` | `false` | 反対側のリンクされたメッセージを削除します。 |
| `CHATWOOT_REVOKE_ON_DELETE` | `false` | エージェントがChatwootメッセージを削除したときにリンクされた送信するWhatsAppメッセージを取り消します。 |
| `CHATWOOT_ALLOWED_HOSTS` | — | デバイス毎の `chatwoot_url` をターゲットとするホストの許可リスト。 |

ほとんどの設定には `--chatwoot-*` フラグがあります。`CHATWOOT_URL`、`CHATWOOT_API_TOKEN`、`CHATWOOT_ACCOUNT_ID`、`CHATWOOT_INBOX_ID`は環境のみです。[設定リファレンス](https://gowa-docs.mintlify.site/ja/configuration.md)を参照してください。

v9.9.0以降のGOWA `main` で、`CHATWOOT_EVENTS=message` を設定すると、通常のWebフック配信を別々にフィルタリングしながら、Chatwootにミラーリングを続けることができます。 `message` セレクターでは、Chatwoot フィルターを使用してリアクション、レシート、編集、削除を行うこともできます。設定の読み取り、編集、削除はまだ適用されます。

`WHATSAPP_WEBHOOK_EVENTS` を継承するには、`CHATWOOT_EVENTS` を空のままにします。有効なフィルタが空の場合、サポートされているすべてのイベントを許可します。 `message`を除外すると、GOWAは起動時に警告を記録し、ChatwootにWhatsAppメッセージのミラーリングを停止します。

これらのビルドでは、GOWA は `api-access-token` ヘッダに Chatwoot ユーザー・トークンを送信するため、nginx はデフォルトのヘッダ設定でそれを渡すことができます。

## Webhook secret

空の有効な webhook シークレットが配信を拒否します。`CHATWOOT_WEBHOOK_ALLOW_UNSIGNED=true` は、効果的なシークレットが空の場合、署名されていない配信を明示的に許可します。 シークレットが設定されている場合、すべてのリクエストは次のいずれかによって証明されなければなりません:

1. **Chatwoot の署名**（`X-Chatwoot-Signature` + `X-Chatwoot-Timestamp`）を推奨します。API チャンネル自身の Webhook シークレットを使用してください。GOWA は `<timestamp>.<raw body>` の HMAC-SHA256 を検証し、設定された許容範囲外のタイムスタンプを拒否します。
2. 体の `X-Hub-Signature-256` HMAC
3. `X-Chatwoot-Webhook-Secret` または `X-Gowa-Chatwoot-Secret` ヘッダーのシークレット。
4. Webhook URLの `?secret=` は、署名またはヘッダーを追加できないChatwootバージョンのみです。シークレットはアクセスログに表示されます。

失敗は`401`を返します。GOWAは理由を記録します。`signature does not match`は間違った秘密を意味し、`timestamp outside the tolerance window` はクロックドリフトを意味します。

デバイスの `webhook_secret` は、デバイスごとの共有エンドポイントとデバイスごとのエンドポイントの両方でそのデバイスのグローバルシークレットを置き換えます。デバイスシークレットがなければ、グローバルシークレットが適用されます。 GOWAは、データの送信、削除、読み取り、書き込みを行う前に、ルーティングされたデバイスの秘密を検証します。 複数のデバイスが同じアカウントと受信トレイIDを使用している場合は、デバイスごとのコールバックURLを優先します。

`2xx`を受け取った繰り返しChatwood-signedリクエストは`200`で認識され、タイムスタンプウィンドウ内でスキップされます。 失敗したリクエストは再実行可能です。同じリクエストが進行中の場合、最大30秒後に`503`を返すことができます。 リプレイメモリはプロセスにローカルであり、再起動時に失われ、65,536個のリクエストに制限されています。GOWAインスタンス間では共有されません。 同じ Chatwoot メッセージの 2 つの別々に署名されたデリバリは、2 回送信できます。 ボディ専用の HMAC 、シークレットヘッダ、およびクエリシークレットは、この配信重複排除を提供しません。

## 自動プロビジョニング

`CHATWOOT_AUTO_CREATE=true` と `CHATWOOT_INBOX_ID` はありません GOWAは起動時に`CHATWOOT_INBOX_NAME`という名前のAPI受信トレイを探し、再利用するか、`CHATWOOT_WEBHOOK_URL`をWebフックとして作成します。

## デバイスごとに1つの受信トレイ

環境変数は、すべてのデバイスで共有される1つの宛先を設定します。 各デバイスを独自の受信トレイ、アカウント、またはChatwootサーバーにルーティングするには、デバイスごとの設定を保存します (Basic Authが適用されます):

```bash theme={null}
curl -u admin:changeme -X PUT http://localhost:3000/devices/sales/chatwoot/config \
  -H "Content-Type: application/json" \
  -d '{
    "chatwoot_url": "https://chatwoot.example.com",
    "account_id": 1,
    "inbox_id": 7,
    "api_token": "token-for-this-inbox",
    "webhook_secret": "secret-of-this-api-channel",
    "enabled": true
  }'
```

レスポンスには `webhook_url`（`<base>/chatwoot/webhook/<device_id>`）が含まれます。これを対象の受信トレイの Webhook に設定してください。その他のルートは、`GET /chatwoot/configs`、および `GET` と `DELETE /devices/{device_id}/chatwoot/config` です。

> [!WARNING]
>
> デバイス毎の設定が存在すると、`CHATWOOT_*`宛先はフォールバックとして使用されなくなります。設定のないデバイスはミラーリングされません。

* `api_token`はGOWAのデータベースに保存され、読み取りにマスクされます。`webhook_secret` は返されません。
* `chatwoot_url`は認証情報なしでHTTPまたはHTTPSでなければなりません。`CHATWOOT_ALLOWED_HOSTS`、private、loopback、link-local、メタデータアドレスは拒否されます。 `CHATWOOT_ALLOWED_HOSTS`内の明示的に一致するホストは信頼されており、プライベートネットワーク上の自己ホストChatwootをターゲットにすることができます。この許可リストはあなたがコントロールしているホストにのみ設定してください。
* 会話がリンクされた後に`chatwoot_url`、`account_id`または`inbox_id`を変更すると`409`が返されます; 代わりに設定を削除して再作成してください。
* 設定はデバイスペアの前に作成できます。
* 直接データベースのインポートは、環境設定モードでのみ動作します。

## 返信と書式設定

エージェントが Chatwoot で **返信** を使用する場合 GOWAは、送信デバイスのローカルストアと同じチャットでそれを解決できる場合、元のWhatsAppメッセージを引用します。 これは、テキストとすべての添付ファイルに適用されます, オーディオ-ファイルフォールバックを含みます. キャプションは、最初の添付ファイルにのみ表示されます.

インバウンドのWhatsAppメッセージの場合、GOWAは`in_reply_to_external_id` を `WAID:<id>` プレフィックスで解決します。 以前のエージェントの返信では、数値の `in_reply_to` は、同じデバイス、会話、アカウント、受信トレイ、設定内の耐久性のあるメッセージリンクで解決します。 複数の添付ファイルを持つメッセージは最初のファイルを引用符で囲みます．ターゲットが解決できない場合は，返信は引用符なしで配信されます．

受信のWhatsAppはChatwootで参照されたメッセージに応答や反応スレッドを返します. エージェントの返信 Markdown リンクと強調は、読み取り可能なWhatsAppのテキストに変換されています. リスト、改行、およびコードは保持されます。空の署名区切り文字は削除されます。`CHATWOOT_SIGN_MSG` は変換後にエージェントの名前をプレフィックスします。

適格な公開送信エージェントメッセージのみが送信されます。プライベートノートと除外チャットは転送されません。 GOWAは、設定されたデバイスとアカウント/受信トレイのIDを使用して共有コールバックをルーティングします。デバイス毎のコールバックは明確なルートを提供します。

### アンケートとエージェントの削除

v9.9.0以降のGOWA `main`では、Chatwootミラーは作成、編集、追加オプションをポーリングします。 個々の投票を処理するには、[WhatsApp webhooks](https://gowa-docs.mintlify.site/ja/concepts/webhooks.md#%E3%82%A2%E3%83%AB%E3%83%90%E3%83%A0%E3%81%A8%E6%A7%8B%E9%80%A0%E5%8C%96%E3%83%A1%E3%83%83%E3%82%BB%E3%83%BC%E3%82%B8)で`message`を購読し、構造化された投票データを読んでください。

これらのビルドでは、`CHATWOOT_REVOKE_ON_DELETE=true` を設定すると、ChatwootからのみのWhatsAppに削除を同期できます。 削除は、アクティブな Chatwoot 設定の送信メッセージへの耐久性のあるリンクと一致する必要があります。 GOWAは、別々に送信された添付ファイルを含む、各リンクされたWhatsAppメッセージを取り消します. とともに `CHATWOOT_FORWARD_DELETES=true` , WhatsAppからの削除はまだプライベートノートとして表示されます. 両方向のリンクされたメッセージを削除するには `CHATWOOT_MESSAGE_DELETE=true` を使用してください。

## インポート履歴

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/chatwoot/sync \
  -H "Content-Type: application/json" \
  -d '{"device_id": "my-device", "days_limit": 7, "include_media": true, "include_groups": true}'

curl -u admin:changeme "http://localhost:3000/chatwoot/sync/status?device_id=my-device"
```

デフォルトは `days_limit=3` 、`include_media=true` 、および `include_groups=true` です。 同期はGOWAのローカルチャットストレージを読み込み、バックグラウンドで実行されます。各デバイスは一度に同期を実行できます。

v9.9.0以降のGOWA `main`では、履歴同期が期限切れのメディアを再度アップロードするように電話に要求することができます。電話はオンラインである必要があり、ファイルが保存されている必要があります。 携帯電話が30秒以内に応答しない場合、同期はさらに実行されたメッセージの再アップロード要求をスキップし、メッセージをインポートし続けます。 添付ファイルなしでファイルをインポートできないメッセージがインポートされます。

RESTパスは元のタイムスタンプを設定できません。インポートされたメッセージはインポート時間を取得します。セルフホスティングされたChatwootの場合、`CHATWOOT_IMPORT_DB_URI`はChatwootのPostgreSQLに直接書き込んで保存します。

v9.9.0以降のGOWA `main` で `CHATWOOT_REOPEN_CONVERSATION=true` を使用すると、インポートする新しいメッセージが表示された場合にのみ、履歴同期が解決された会話を再開します。 REST 同期は、投稿前に会話を再開し、再開に失敗した場合は次の同期でチャットを再試行します。 直接PostgreSQLインポートは、メッセージが書かれたのと同じトランザクションで再開します。 この設定がオフの場合、REST 同期は新しいメッセージに対して新しい会話を作成し、直接インポートは解決済みの会話を使用し続けます。

## 配信と再試行

一時的なChatwootエラーが発生したライブメッセージ (ネットワークエラー) HTTP 429 または 5xx) はローカルストレージでキューに入れられ、バックグラウンドで再試行されます。 その他の4xxエラーは記録およびドロップされます。

## トラブルシューティング

| 症状 | チェック |
| - | - |
| エージェントの返信が届いていません | ログに記録された`CHATWOOT_DEVICE_ID` とデバイスがログインしました。WebhookのURLが正しいと公開されています。ログの`DEVICE_NOT_AVAILABLE` は使用可能なデバイスを意味しません。 |
| `/chatwoot/webhook` の `401` | 秘密の不一致またはクロックドリフト(上記参照)。 |
| ChatwootからWhatsAppメッセージが抜けています | `CHATWOOT_ENABLED`、ユーザートークン、アカウントと受信トレイID、および`CHATWOOT_URL`への接続をチェックします。新しいビルドでは、効果的なイベントフィルタに`message`が含まれていることを確認します。 |
| `CHATWOOT_NOT_CONFIGURED` | URL、トークン、アカウントID、または受信トレイIDがありません。 |

`APP_DEBUG=true`で実行し、`Chatwoot:`と`Chatwoot Webhook:`で始まるログ行を探します。 上流の[Chatwoot guide](https://github.com/aldinokemal/go-whatsapp-web-multidevice/blob/main/docs/chatwoot.md)は、直接データベースのインポートとフォーマットのルールをより深くカバーしています。


## Related topics

- [サーバーのメタデータを取得する](https://gowa-docs.mintlify.site/ja/api-reference/app/サーバーのメタデータを取得する.md)
- [Chatwoot webhook エンドポイント](https://gowa-docs.mintlify.site/ja/api-reference/chatwoot/chatwoot-webhook-エンドポイント.md)
- [デバイスのChatwoot設定を取得する](https://gowa-docs.mintlify.site/ja/api-reference/chatwoot/デバイスのchatwoot設定を取得する.md)
- [デバイスのChatwoot設定を削除する](https://gowa-docs.mintlify.site/ja/api-reference/chatwoot/デバイスのchatwoot設定を削除する.md)
- [デバイスごとのChatwoot設定の一覧](https://gowa-docs.mintlify.site/ja/api-reference/chatwoot/デバイスごとのchatwoot設定の一覧.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.