Activepieces AskHandle 集成 Piece 深度解析构建、鉴权、动作与 Webhook 触发器【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepiecesAskHandle 是一款面向客户支持与销售场景的聊天与线索管理服务本仓库中的activepieces/piece-ask-handle是 Activepieces 官方社区维护的 AskHandle 集成 Piece用于在自动化工作流中收发聊天室消息、管理销售线索并对新消息、新线索、新聊天室等事件做出实时响应。读完本文你将掌握该 Piece 的构建命令、API Key 鉴权机制、4 个动作与 3 个触发器的完整参数语义以及其基于 Webhook 的实时触发实现原理可以直接在 Activepieces 中搭建线索捕获 → 即时跟进的自动化流程。Piece 概览一个模块化封装的 AskHandle 客户端该 Piece 的入口文件 src/index.ts 通过createPiece组装了完整的集成能力展示名称AskHandle鉴权方式askHandleAuthAPI Key 密文输入最低支持版本minimumSupportedRelease: 0.36.1即需要 Activepieces 0.36.1 及以上版本才能安装使用维护作者onyedikachi-david动作actions创建消息createMessage、创建线索createLead、列出聊天室listRooms、列出线索listLeads触发器triggers新消息newMessageTrigger、新线索newLeadTrigger、新聊天室newRoomTrigger从 package.json 可以看到包名为activepieces/piece-ask-handle版本0.1.8commonjs格式其运行依赖activepieces/pieces-common、activepieces/pieces-framework、activepieces/core-piece-types与activepieces/core-utils这些 workspace 依赖提供了 HTTP 客户端、Piece 属性框架等基础能力。构建该 PieceREADME 中的标准命令该 Piece 的 README.md 给出了标准的构建方式在仓库根目录执行以下命令即可单独构建 AskHandle 集成库turbo run build --filteractivepieces/piece-ask-handle该命令通过 Turborepo 的任务过滤机制只构建activepieces/piece-ask-handle及其上游 workspace 依赖无需构建整个仓库。构建脚本定义在 package.json 的scripts.build中核心是tsc -p tsconfig.lib.json cp package.json dist/即先用 TypeScript 编译器按库模式配置tsconfig.lib.json把src/编译为dist/再把package.json复制到产物目录保证发布后的包元数据完整。除此之外该包还提供了bundle调用 CLI 打包 Piece与lintESLint 检查src/**/*.ts两个脚本。鉴权设计API Key 校验与连接验证AskHandle 使用 API Key 作为连接凭证实现在 src/lib/common/auth.ts。它基于PieceAuth.SecretText定义了一个必填的密文输入项用户需要在 AskHandle 控制台完成以下步骤获取密钥访问 AskHandle 控制台https://dashboard.askhandle.com并登录账号进入 API 设置页面创建或复制 API Token将 Token 粘贴到 Activepieces 的连接配置中。值得注意的是该鉴权定义了一个validate回调当用户在 Activepieces 中保存连接时Piece 会立即向GET https://dashboard.askhandle.com/api/v1/rooms/发起一次真实请求来验证密钥有效性。请求头使用Authorization: Token apiKey的认证格式注意是Token前缀而非Bearer。只有当服务端返回 HTTP 200 时校验才通过否则会给出Invalid API key之类的错误提示。这意味着密钥在保存连接阶段就会被预检能有效避免配置了无效凭证的流程在运行期才报错。统一 API 客户端与错误语义映射所有动作的数据交互都收敛在 src/lib/common/client.ts 的askHandleApiCall函数中。该函数统一以https://dashboard.askhandle.com/api/v1为基址拼接传入的path发起请求头部固定携带Authorization: Token apiKey与Content-Type: application/json。成功2xx时直接返回响应体失败时会将 HTTP 状态码映射为语义明确的中文可读错误信息状态码错误语义400请求参数无效需检查提交的数据401认证失败API Key 无效需核对凭证403访问被拒绝当前凭证无权访问该资源404资源不存在500 / 502 / 503 / 504服务端异常建议稍后重试其他携带具体状态码的通用错误信息此外当请求未返回任何状态码如网络层失败时会抛出包含底层错误信息的 Unexpected error。这种集中式的错误处理让 4 个动作无需各自重复编写异常逻辑也保证了用户在工作流运行日志中能看到统一、可排查的错误文案。四个动作详解从读取到写入的完整能力发送消息到聊天室Create Message定义于 src/lib/actions/create-message.ts分类为WRITE通过POST /messages/向指定聊天室追加一条消息。参数如下参数类型必填说明roomDropdown是目标聊天室从动态加载的聊天室列表中选取值为 room 的 UUIDbodyLongText是消息正文内容nicknameShortText否发送者昵称emailShortText否发送者邮箱phone_numberShortText否发送者电话号码从源码实现看请求体固定包含body与room: { uuid }结构仅当昵称、邮箱、电话被填写时才追加对应字段避免发送空串。该动作非幂等每次调用都会新增一条消息适合作为自动回复或人工客服通知的输出节点。创建线索Create Lead定义于 src/lib/actions/create-lead.ts分类为WRITE通过POST /leads/创建一条新线索记录参数如下参数类型必填说明nicknameShortText否线索昵称emailShortText否线索邮箱phone_numberShortText否线索电话deviceShortText否设备信息from_page_titleShortText否线索来源页面标题referrerShortText否来源页 URL实现上仅将已填写的字段纳入请求体。该动作同样非幂等每次调用都会创建独立线索不会按邮箱或电话去重适合表单提交、落地页捕获等新增潜客场景。列出聊天室List Rooms定义于 src/lib/actions/list-rooms.ts分类为SEARCH无任何输入参数直接GET /rooms/返回账号下所有聊天室。可用于在流程中枚举会话、按需查找 room UUID。按时间窗口查询线索List Leads定义于 src/lib/actions/list-leads.ts分类为SEARCH通过GET /leads/查询线索支持三个可选过滤参数参数类型必填说明start_dateDateTime否线索起始时间过滤源码会将其转换为YYYY-MM-DD日期串end_dateDateTime否线索截止时间过滤limitNumber否返回线索的最大条数源码中会将日期参数先经new Date(...).toISOString()规范化为 ISO 格式再截取日期部分拼入查询串如/leads/?start_date2026-09-01end_date2026-09-12limit50未填任何过滤条件时则请求裸路径/leads/。这是一个只读、幂等的查询动作适合作为周期性的线索同步节点。动态下拉属性聊天室与线索的实时选择src/lib/common/props.ts 定义了两个共享的动态下拉属性供动作与触发器界面复用roomDropdown调用GET /rooms/拉取聊天室列表以room.name || room.label || Room uuid作为显示标签、room.uuid作为提交值leadDropdown调用GET /leads/拉取线索列表以lead.nickname || lead.email || Lead uuid作为标签、lead.uuid作为值。两个下拉在未连接账号时都会进入disabled状态并提示Please connect your account first请求失败时则提示 Error loading rooms/leads。它们兼容分页结构response.results与直接数组两种响应形态从源码结构看这体现了对 AskHandle API 两种返回格式的适配。三个 Webhook 触发器实时事件响应三个触发器分别对应新消息、新线索、新聊天室事件均采用TriggerStrategy.WEBHOOK策略实现在 src/lib/triggers/new-message.ts、src/lib/triggers/new-lead.ts 与 src/lib/triggers/new-room.ts三者的生命周期实现完全对称。事件订阅与生命周期管理每个触发器都实现了onEnable/onDisable/run三段式生命周期onEnable启用时注册订阅向POST /webhooks/注册一个 webhook请求体为{ event: 事件名, target: context.webhookUrl }其中target是 Activepieces 为该触发器动态生成的接收地址。注册成功后HTTP 200 或 201把返回的 webhookuuid存入context.store键名分别为_askhandle_webhook_message、_askhandle_webhook_lead、_askhandle_webhook_room。onDisable停用时注销订阅先从 store 读取之前保存的 webhook uuid再调用DELETE /webhooks/{uuid}/注销订阅并清理 store防止停用后仍收到回调。run事件分发收到回调后从请求体取data字段取不到则回退整个 payload作为事件负载返回给工作流。三个触发器的订阅事件名分别为新消息message.added、新线索lead.added、新聊天室chat.added。示例负载sampleData源码为每个触发器内置了示例数据便于在编辑器中预览数据结构新消息{ uuid, nickname: Mary, email: maryexample.com, body: Hello!, is_support_sender: false, sent_at }——其中is_support_sender可用来判断消息是否来自支持人员新线索{ uuid, nickname, email, phone_number, device, from_page_title, referrer, created_at }——携带完整的联系人与来源上下文新聊天室{ uuid, label, name, rating, is_bot_use, created_at, messages }——包含聊天室评级、是否机器人使用等元信息。典型应用场景线索驱动的实时跟进综合以上能力可以在 Activepieces 中构建如下闭环用New Lead触发器监听新线索产生事件lead.added在流程中解析负载里的nickname、email、from_page_title等字段路由到 CRM、表格或通知节点用Create Message动作向对应聊天室POST /messages/发送即时欢迎或跟进消息结合List Leads / List Rooms动作在流程内动态查询和补全上下文。由于触发器采用 Webhook 推送而非轮询事件在 AskHandle 侧产生后即可实时到达工作流而 store 机制保证了订阅注册与注销的成对管理重复启用/停用触发器不会在 AskHandle 侧累积失效的 webhook 订阅。源码结构一览packages/pieces/community/ask-handle/ ├── README.md # 构建说明 ├── package.json # 包元数据与构建/打包脚本 └── src/ ├── index.ts # createPiece 入口组装动作与触发器 ├── i18n/ # 多语言文案de/es/fr/ja/nl/pt/zh 等 └── lib/ ├── common/ │ ├── auth.ts # API Key 鉴权与连接校验 │ ├── client.ts # 统一 API 客户端与错误映射 │ └── props.ts # room/lead 动态下拉属性 ├── actions/ │ ├── create-message.ts │ ├── create-lead.ts │ ├── list-rooms.ts │ └── list-leads.ts └── triggers/ ├── new-message.ts ├── new-lead.ts └── new-room.ts从源码结构看该 Piece 遵循 Activepieces 社区 Piece 的标准分层common收敛鉴权、客户端与共享属性actions与triggers各自独立成文件入口文件仅做声明式组装整体结构清晰、易于扩展例如新增动作时只需在lib/actions下添加文件并在index.ts注册。如果你需要在本地二次开发直接基于上述目录修改再执行开头的turbo run build --filteractivepieces/piece-ask-handle即可验证构建。【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考