diff --git a/en/usage/platforms/wecom/wecomcs.mdx b/en/usage/platforms/wecom/wecomcs.mdx index 3f93414a4..f625d699a 100644 --- a/en/usage/platforms/wecom/wecomcs.mdx +++ b/en/usage/platforms/wecom/wecomcs.mdx @@ -33,4 +33,53 @@ Click Submit on the LangBot configuration page to enable the robot, copy the Web Copy the Secret from the page, then open the newly created LangBot WeCom Customer Service robot, fill in the new Secret, and restart. -Go back to the WeCom Customer Service configuration page, click on Customer Service Accounts, create a customer service account, and you can start using it. +## Get the customer service link and QR code + +After configuring the callback, obtain an entry point that WeChat users can use to start a conversation. + +1. Return to the [WeChat Customer Service console](https://kf.weixin.qq.com/kf), open **Customer Service Accounts** (`客服帐号`), and create or select the account you want to connect to LangBot. +2. Open its integration page, scroll to **Integrate into apps or websites outside WeChat** (`在微信外App/网页中接入`), and click **Integrate** (`去接入`). + +![Find the integration entry for apps and websites outside WeChat](/images/zh/deploy/bots/wecom/wecomcs/customer-service-entry.png) + +3. Find the account at the top of the integration page. Click **Copy Link** (`复制链接`) to obtain its customer service link, or **Generate QR Code** (`生成二维码`) to display its QR code. + +![Copy the customer service link or generate a QR code](/images/zh/deploy/bots/wecom/wecomcs/customer-service-link.png) + + +The link in the screenshot is an example. Use the link or QR code generated for your own account. The Webhook callback URL delivers events to LangBot; the customer service link and QR code let users start a conversation. + + +## Test with WeChat + +1. Enable the bot in LangBot and configure **Event Routing** to send **Message Received** events to the processor you want to use. +2. Scan the generated QR code with regular WeChat, enter the customer service conversation, and send a message. +3. Check the bot logs, session monitor, and the processor's execution logs in LangBot to confirm receipt and processing, then check for a reply in WeChat. + +For a QR-code test, you do not need to configure the app association shown further down the integration page. + +## Routable events + +Select a processor for each event in the bot's **Event Routing** settings. Regular messages can use a Pipeline or Agent; other events require an Agent or plugin processor that supports them. + +| Event | Event type | +| --- | --- | +| Message received | `message.received` | +| Customer or representative recalled a message | `message.deleted` | +| Customer entered through a service link | `wecomcs.enter_session` | +| Outgoing message failed | `wecomcs.msg_send_fail` | +| Representative availability changed | `wecomcs.servicer_status_change` | +| Conversation accepted, transferred, closed or reopened | `wecomcs.session_status_change` | +| Customer message rejection changed | `wecomcs.reject_customer_msg_switch_change` | + +Recall events include the original message ID, operator and chat ID. Customer-service events retain account, customer and event-specific fields such as `welcome_code`, `fail_type` and `change_type`. Unknown events preserve their payload through `platform.specific`. + +Entering through a service link triggers the entry event; reopening an existing chat from the chat list does not. Configure the processor's handling logic to send a welcome message; receiving the event alone does not send one. + +### Reply windows and welcome messages + +- Ordinary replies require the customer to send a message first and must be sent within 48 hours. Entering a session alone does not open this window. Error `95002` indicates that the sending time restriction was not met. +- For entry events, the Agent's `event_reply` uses the dedicated event response API with `welcome_code`. WeChat only supplies this credential when welcome-message conditions are met. It permits one message and expires after 20 seconds. Prefer a fast, fixed welcome message instead of waiting for a long model response. +- For session-status changes, `event_reply` uses `msg_code`, subject to its expiration and the current session state. Event replies currently support text. Missing, expired or used credentials cannot be reused; rerunning an old event does not extend their validity. + +See the official [send message](https://developer.work.weixin.qq.com/document/path/94677) and [send event response](https://developer.work.weixin.qq.com/document/path/95122) documentation. diff --git a/images/zh/deploy/bots/wecom/wecomcs/customer-service-entry.png b/images/zh/deploy/bots/wecom/wecomcs/customer-service-entry.png new file mode 100644 index 000000000..950be088e Binary files /dev/null and b/images/zh/deploy/bots/wecom/wecomcs/customer-service-entry.png differ diff --git a/images/zh/deploy/bots/wecom/wecomcs/customer-service-link.png b/images/zh/deploy/bots/wecom/wecomcs/customer-service-link.png new file mode 100644 index 000000000..f4c9fc178 Binary files /dev/null and b/images/zh/deploy/bots/wecom/wecomcs/customer-service-link.png differ diff --git a/ja/usage/platforms/wecom/wecomcs.mdx b/ja/usage/platforms/wecom/wecomcs.mdx index 99e33a3c7..7b1a0357c 100644 --- a/ja/usage/platforms/wecom/wecomcs.mdx +++ b/ja/usage/platforms/wecom/wecomcs.mdx @@ -33,4 +33,53 @@ LangBot 設定ページの提交をクリックして 로봇を有効化し、We ページの Secret をコピーし、新しく作成した LangBot 企業微信カスタマーサービス 로봇を開き、新しい Secret を入力して再起動します。 -企業微信カスタマーサービス設定画面に戻り、カスタマーサービスアカウントをクリックしてカスタマーサービスアカウントを作成すれば、使用できます。 +## 問い合わせリンクと QR コードを取得する + +コールバックの設定後、WeChat ユーザーが問い合わせを開始するためのリンクまたは QR コードを取得します。 + +1. [WeChat カスタマーサービス管理画面](https://kf.weixin.qq.com/kf)に戻り、`客服帐号`（カスタマーサービスアカウント）から、LangBot に接続するアカウントを作成または選択します。 +2. アカウントの接続ページを開き、`在微信外App/网页中接入`（WeChat 外のアプリ・Web ページに接続）までスクロールして、`去接入` をクリックします。 + +![WeChat 外のアプリ・Web ページへの接続入口](/images/zh/deploy/bots/wecom/wecomcs/customer-service-entry.png) + +3. 接続ページ上部の対象アカウントで、`复制链接` をクリックすると問い合わせリンクをコピーでき、`生成二维码` をクリックすると QR コードを表示できます。 + +![問い合わせリンクのコピーと QR コードの生成](/images/zh/deploy/bots/wecom/wecomcs/customer-service-link.png) + + +スクリーンショットのリンクは例です。自分のアカウントで生成したリンクまたは QR コードを使用してください。Webhook コールバック URL は LangBot へのイベント通知用で、問い合わせリンクと QR コードはユーザーが会話を開始するためのものです。 + + +## QR コードで動作を確認する + +1. LangBot のボットを有効にし、イベントルーティングで「メッセージ受信」イベントを使用するプロセッサーに割り当てます。 +2. 通常の WeChat で生成した QR コードを読み取り、カスタマーサービスの会話を開いてメッセージを送信します。 +3. LangBot のボットログ、セッション監視、対象プロセッサーの実行ログで受信と処理を確認し、WeChat に返信が届くことを確認します。 + +QR コードで動作を確認するだけなら、接続ページ下部のアプリ連携を設定する必要はありません。 + +## ルーティングできるイベント + +ボットのイベントルーティングで、イベントごとにプロセッサーを選択できます。通常のメッセージにはパイプラインまたは Agent、それ以外には対象イベントに対応した Agent またはプラグインプロセッサーを使用します。 + +| イベント | イベントタイプ | +| --- | --- | +| メッセージ受信 | `message.received` | +| 顧客または担当者によるメッセージ撤回 | `message.deleted` | +| 顧客がリンクから会話に参加 | `wecomcs.enter_session` | +| メッセージ送信失敗 | `wecomcs.msg_send_fail` | +| 担当者の受付状態変更 | `wecomcs.servicer_status_change` | +| 会話の受付、転送、終了、再開 | `wecomcs.session_status_change` | +| 顧客メッセージの受信拒否設定変更 | `wecomcs.reject_customer_msg_switch_change` | + +撤回イベントには元のメッセージ ID、操作者、チャット ID が含まれます。カスタマーサービス固有のイベントにはアカウント、顧客、`welcome_code`、`fail_type`、`change_type` などの関連フィールドが含まれます。未知のイベントは `platform.specific` として元のデータを保持します。 + +会話への参加イベントはリンクから入った場合に発生し、既存のチャット一覧から開いても発生しません。歓迎メッセージを送るにはプロセッサーの処理を設定してください。イベントの受信だけでは送信されません。 + +### 返信期限と歓迎メッセージ + +- 通常の返信には顧客からのメッセージが必要で、48 時間以内に送信する必要があります。会話への参加だけではこの条件を満たしません。エラー `95002` は送信期限の条件を満たしていないことを示します。 +- 参加イベントでの Agent の `event_reply` は、専用のイベント応答 API と `welcome_code` を使います。このコードは歓迎メッセージの条件を満たす場合のみ提供され、送信できるのは 1 件、有効期限は 20 秒です。時間のかかるモデル生成より、すぐに送信できる固定文面を推奨します。 +- 会話状態変更イベントの `event_reply` は `msg_code` を使用し、有効期限と現在の会話状態による制限を受けます。現在のイベント返信はテキストに対応しています。コードがない場合、期限切れの場合、使用済みの場合は再送できません。古いイベントを再実行しても有効期限は延長されません。 + +詳細は公式の[メッセージ送信](https://developer.work.weixin.qq.com/document/path/94677)と[イベント応答送信](https://developer.work.weixin.qq.com/document/path/95122)を参照してください。 diff --git a/zh/usage/platforms/wecom/wecomcs.mdx b/zh/usage/platforms/wecom/wecomcs.mdx index cd0f21eeb..466194935 100644 --- a/zh/usage/platforms/wecom/wecomcs.mdx +++ b/zh/usage/platforms/wecom/wecomcs.mdx @@ -33,5 +33,54 @@ description: "用 LangBot 配置企业微信客服，提供 AI 驱动的客服 复制页面中的 Secret，然后打开新建好的 LangBot 企业微信客服机器人，填写入新的 Secret，重新启动。 -回到企业微信客服配置页面，点击客服账号，创建客服账号，即可使用。 +## 获取客服链接和二维码 + +完成回调配置后，还需要获取供微信用户发起咨询的入口。 + +1. 回到[微信客服后台](https://kf.weixin.qq.com/kf)，进入`客服帐号`，创建或选择需要接入 LangBot 的客服帐号。 +2. 打开该帐号的接入页面，向下找到`在微信外App/网页中接入`，点击`去接入`。 + +![在微信外 App 或网页中接入微信客服](/images/zh/deploy/bots/wecom/wecomcs/customer-service-entry.png) + +3. 在接入页面顶部找到对应的客服帐号。点击`复制链接`可获取客服咨询链接，点击`生成二维码`可查看该帐号的咨询二维码。 + +![复制客服链接或生成二维码](/images/zh/deploy/bots/wecom/wecomcs/customer-service-link.png) + + +截图中的客服链接仅作示例，请使用自己帐号生成的链接或二维码。Webhook 回调地址用于微信向 LangBot 推送消息，客服链接和二维码用于用户发起咨询。 + + +## 扫码测试 + +1. 确认 LangBot 中的机器人已启用，并在`事件路由`中将`收到消息`交给需要使用的处理器。 +2. 使用普通微信扫描刚生成的二维码，进入客服会话后发送一条消息。 +3. 在 LangBot 中查看机器人的日志、会话监控及对应处理器的运行日志，确认消息已接收并处理，再检查微信中是否收到回复。 + +如果只是扫码测试，获取二维码后即可发起咨询，无需继续配置页面下方的 App 关联。 + +## 可路由的事件 + +在机器人的「事件路由」中，可以分别为以下事件选择处理器。普通消息可交给流水线或 Agent；其他事件可交给支持相应事件的 Agent 或插件处理器。 + +| 事件 | 事件类型 | +| --- | --- | +| 收到消息 | `message.received` | +| 客户或接待人员撤回消息 | `message.deleted` | +| 客户通过链接进入会话 | `wecomcs.enter_session` | +| 客服消息发送失败 | `wecomcs.msg_send_fail` | +| 接待人员状态变更 | `wecomcs.servicer_status_change` | +| 客服会话接入、转接、结束或重新接入 | `wecomcs.session_status_change` | +| 拒收客户消息设置变更 | `wecomcs.reject_customer_msg_switch_change` | + +撤回事件包含原消息 ID、操作者和会话 ID。客服专属事件保留客服帐号、客户及事件相关字段，例如 `welcome_code`、`fail_type` 和 `change_type`；处理器可按字段决定后续操作。未知事件仍通过 `platform.specific` 保留原始数据。 + +进入会话事件只在客户通过客服链接进入时触发，从已有聊天列表打开会话不会触发。接入事件不等于自动发送欢迎语，仍需配置相应处理逻辑。 + +### 回复窗口与欢迎语 + +- 普通消息回复要求客户先主动发消息，且在 48 小时内回复；仅进入会话不会开启此窗口。错误码 `95002` 表示不满足发送时间限制。 +- Agent 的 `event_reply` 在进入会话事件中使用专用事件回复接口和 `welcome_code`，不会当作普通消息发送。微信只在符合欢迎语条件时提供此凭据，每个凭据只能发送一条消息，有效期仅 20 秒。建议使用快速固定文案，避免等待耗时较长的模型生成。 +- 会话状态变化事件的 `event_reply` 使用 `msg_code`，仍受凭据有效期和当前会话状态限制。当前事件回复支持文本；凭据缺失、过期或已使用时无法补发，重新执行旧事件不能延长有效期。 + +详见微信官方的[发送消息](https://developer.work.weixin.qq.com/document/path/94677)和[发送事件响应消息](https://developer.work.weixin.qq.com/document/path/95122)。