WeChat OA（公众号）

WeChat OA（微信公众号）のカスタマーサポートメッセージング。48 時間返信ウィンドウ内で動作し、WeCom と同じ暗号化エンベロープを使用します。

🟡 送信対応済み・受信対応済み・48 時間ウィンドウあり。 アウトバウンドのカスタマーサポートメッセージには制約があります。ユーザーが過去 48 時間以内に OA へアクセスしていない場合、プラットフォームは errcode 45015 を返し、メッセージは破棄されます。コールドプッシュが必要な本番環境では、テンプレートメッセージ（事前承認済みテンプレート）の使用を検討してください。テンプレートメッセージのサポートは今後追加予定です。

利用できる機能

アウトバウンドテキスト送信（POST /cgi-bin/message/custom/send?access_token=...）過去 48 時間以内に OA へメッセージを送ったユーザーの openid 宛てに送信できます。
インバウンドメッセージイベント（/webhooks/wechat-oa） WeCom と同じ SHA1 ソート + AES-256-CBC エンベロープを使用します（共有ヘルパー wxcrypt が両方をカバーします）。GET ハンドシェイクに小さな違いがあり、WeChat OA は 4 タプルではなく 3 タプル [token, timestamp, nonce] で署名します。
アプリごとの access_token を 2 時間キャッシュ。
テキストのみ対応。 画像 / ニュース / テンプレートメッセージは今後対応予定です。
テキストの上限は 2,048 文字。

セットアップ

1. 公式アカウントを作成 / 取得する

WeChat Public Platform にサインインします（カスタマーサービス API にはサービスアカウントが必要です。サブスクリプションアカウントは使用できません）
「設定」→「基本情報」から AppID と AppSecret を確認します
「設定」→「サーバー設定」を開き、以下を入力します。
- URL: https://<your-host>/webhooks/wecom
- Token: 任意の不透明な文字列（WECHAT_OA_TOKEN になります）
- EncodingAESKey: 「ランダム生成」をクリック（43 文字、WECHAT_OA_AES_KEY になります）
- 暗号化モード: 「安全モード」（暗号化あり）を推奨します
「送信」をクリックします。WeChat が GET ハンドシェイクで URL にアクセスし、Minara が復号したプレーンテキストをエコーバックします。

2. デフォルト openid を取得する

カスタマーサービス API には openid（不透明なユーザー識別子）が必要です。テストユーザーに何らかの操作（OA のフォロー、メッセージ送信、メニュー項目のタップなど）を行ってもらいます。インバウンド Webhook の FromUserName フィールドに openid が表示されます。その値を WECHAT_OA_DEFAULT_OPENID として保存してください。

3. Minara を設定する

minara auth messaging add
# リストから `wechat_oa` を選択します。

または環境変数を直接設定します。

WECHAT_OA_APP_ID=wx<...>
WECHAT_OA_APP_SECRET=<opaque secret>
WECHAT_OA_TOKEN=<server config Token>
WECHAT_OA_AES_KEY=<43-char EncodingAESKey>
WECHAT_OA_DEFAULT_OPENID=<o...........>

4. テストする

minara auth messaging test wechat_oa

デフォルト openid のユーザーが過去 48 時間以内に OA と通信していない場合、テストは errcode 45015 で失敗します。

インバウンド Webhook

WeChat OA のサーバー設定 GET ハンドシェイクは WeCom と少し異なります。4 タプル [token, ts, nonce, encrypt] の代わりに、3 タプル [token, timestamp, nonce] を使用します。

expected = sha1(sort([token, timestamp, nonce]).join(""))

POST の署名は WeCom と同じです。URL クエリの msg_signature、4 タプルのソート、ボディ内の AES エンベロープを使用します。

復号後のインナー XML ペイロードは Tencent の標準的な形式に従います。

<xml>
  <ToUserName>...</ToUserName>
  <FromUserName>...</FromUserName>
  <CreateTime>...</CreateTime>
  <MsgType>text</MsgType>
  <Content>...</Content>
  <MsgId>...</MsgId>
</xml>

MsgType=text のイベントのみ Agent に転送されます。

制限事項と注意点

48 時間カスタマーサービスウィンドウ。 ウィンドウ外へのアウトバウンドはすべて errcode 45015 を返します。ユーザーが起点となる操作から 48 時間以内の受動返信と、長期プッシュ用の事前承認済みテンプレートメッセージを組み合わせた UX 設計を検討してください。
サービスアカウントとサブスクリプションアカウントの違い。 カスタマーサービス API はサービスアカウントのみ利用できます。サブスクリプションアカウントではこのプロバイダーを使用できません。
EncodingAESKey は正確に 43 文字でなければなりません。 文字数が異なると、起動時のデコードに失敗します。

トラブルシューティング

「errcode 45015」

openid のユーザーが過去 48 時間以内に OA と通信していません。これは仕様上の動作です。コールドプッシュにはテンプレートメッセージを使用してください（Minara への組み込みは未対応です）。

「errcode 40001 / Token invalid」

access_token のリフレッシュに失敗しています。OA コンソールで WECHAT_OA_APP_ID と WECHAT_OA_APP_SECRET を確認してください。

「インバウンド Webhook がハンドシェイクで 401 を返す」

3 タプルの SHA1 チェックに失敗しています。最も多い原因は WECHAT_OA_TOKEN の入力ミスです。OA のサーバー設定ページの「Token」と値が一致しているか確認してください。

リファレンス

環境変数: WECHAT_OA_*
アウトバウンド: apps/agent/src/messaging/wechat_oa.ts
インバウンド仕様: apps/agent/src/messaging/inbound/specs/wechat_oa.ts
カスタマーサービス API: developers.weixin.qq.com / 客服消息

WeChat OA（公众号）

目次