mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-10-28 19:35:27 +08:00
docs(wecomcs): explain entry links events and reply windows
This commit is contained in:
Hyu
@@ -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** (`去接入`).
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## 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.
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 195 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 49 KiB |
@@ -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 ページに接続）までスクロールして、`去接入` をクリックします。
|
||||
|
||||
|
||||
|
||||
3. 接続ページ上部の対象アカウントで、`复制链接` をクリックすると問い合わせリンクをコピーでき、`生成二维码` をクリックすると QR コードを表示できます。
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
スクリーンショットのリンクは例です。自分のアカウントで生成したリンクまたは QR コードを使用してください。Webhook コールバック URL は LangBot へのイベント通知用で、問い合わせリンクと QR コードはユーザーが会話を開始するためのものです。
|
||||
</Note>
|
||||
|
||||
## 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)を参照してください。
|
||||
|
||||
@@ -33,5 +33,54 @@ description: "用 LangBot 配置企业微信客服，提供 AI 驱动的客服
|
||||
|
||||
复制页面中的 Secret，然后打开新建好的 LangBot 企业微信客服机器人，填写入新的 Secret，重新启动。
|
||||
|
||||
回到企业微信客服配置页面，点击客服账号，创建客服账号，即可使用。
|
||||
## 获取客服链接和二维码
|
||||
|
||||
完成回调配置后，还需要获取供微信用户发起咨询的入口。
|
||||
|
||||
1. 回到[微信客服后台](https://kf.weixin.qq.com/kf)，进入`客服帐号`，创建或选择需要接入 LangBot 的客服帐号。
|
||||
2. 打开该帐号的接入页面，向下找到`在微信外App/网页中接入`，点击`去接入`。
|
||||
|
||||
|
||||
|
||||
3. 在接入页面顶部找到对应的客服帐号。点击`复制链接`可获取客服咨询链接，点击`生成二维码`可查看该帐号的咨询二维码。
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
截图中的客服链接仅作示例，请使用自己帐号生成的链接或二维码。Webhook 回调地址用于微信向 LangBot 推送消息，客服链接和二维码用于用户发起咨询。
|
||||
</Note>
|
||||
|
||||
## 扫码测试
|
||||
|
||||
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)。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user