Bitrix24 任务小部件安装与运行时处理器 - n8n 工作流

需要可靠的后端来处理安装和令牌管理的 Bitrix24 应用开发者。
寻求用于复杂 Webhook 交互的稳定 n8n 模板的用户。
在 CRM 环境中部署自定义小部件的自动化专家。
正在寻找用于自托管 Bitrix24 API 处理方案的工程师。

为 Bitrix24 等平台开发自定义应用，需要对 OAuth 令牌、安装回调和动态内容交付进行复杂的处理。这个强大的 n8n 工作流通过充当与您的自定义小部件应用相关的所有 Bitrix24 事件的中央处理器，解决了这些挑战。此 n8n 模板的主要价值在于它能够无缝管理安装握手——将关键访问令牌保存到磁盘——然后在运行时利用这些存储的凭据，在 Bitrix24 任务视图标签页内获取并显示特定于上下文的信息（如任务详情）。

每次 Bitrix24 发送请求（无论是安装还是小部件显示），这个特定的 n8n 节点设置都能确保安全的身份验证并立即提供定制的响应，展示了精心设计的 n8n 工作流的效率。

整个过程始于指定的 n8n 触发器，即 Webhook 节点，它侦听来自 Bitrix24 的 POST 请求。

1. 触发与初始化： Bitrix24 Handler n8n 触发器接收事件。Extract Credentials n8n 节点立即解析传入的 JSON 负载，以检索域、访问令牌和刷新令牌。


2. 事件判断： Check Event Type 代码节点分析请求，以区分应用安装事件 (ONAPPINSTALL) 和运行时放置请求（例如，查看任务）。


3. 安装路径： 如果是安装事件，工作流将分流。如果安装尚未完成，系统使用 Set Settings Data n8n 节点格式化令牌，将其转换为 JSON 文件（Create Settings File），并使用 Save Installation Settings n8n 节点（读/写文件）保存配置。然后，它会注册小部件的放置位置（Register Placement HTTP 请求节点），并通过 Installation Response webhook 响应完成该过程。


4. 运行时路径（小部件显示）： 如果事件是运行时请求，系统会使用 Read Installation Settings 和 Extract Installation Settings n8n 节点检索先前保存的身份验证数据。Merge request data with installation settings 节点准备必要的数据上下文。


5. 数据处理与检索： Process Settings 函数节点提取特定于上下文的信息，例如 taskId。Has Valid Settings? If 节点验证凭据。如果有效，Get Task Data HTTP 请求 n8n 节点使用已保存的 Bitrix24 访问令牌向 Bitrix24 API 查询详细的任务信息。


6. 响应生成： Format Task Data 函数节点将原始任务数据转换为结构化的 HTML。最后，Task View Response n8n 节点将此 HTML 发送回 Bitrix24，Bitrix24 会在自定义任务小部件中渲染它。如果设置无效，则改而返回 Error Response。这个复杂的逻辑展示了 n8n 工作流的强大应用。

要部署这个完善的 n8n 工作流，请遵循以下步骤：

1. 导入 n8n 工作流： 复制提供的 JSON 数据。在您的 n8n 实例中，导航到“工作流”(Workflows)，然后点击“新建”(New)。选择“从 JSON 导入”(Import from JSON) 并粘贴代码。


2. 配置 Webhook 触发器： 找到 Bitrix24 Handler n8n 触发器节点。路径设置为 bitrix24/widgethandler.php。激活工作流以生成完整的 Webhook URL。此 URL 必须在您的 Bitrix24 应用设置中注册为安装和放置事件的处理程序 URL。


3. 设置占位符凭据： Extract Credentials n8n 节点包含硬编码的占位符值（例如 local.67b8a796e92127.82791242）。这些通常在安装 Webhook 期间被 Bitrix24 发送的实时数据覆盖，但如果您的应用使用不同的静态客户端 ID/密钥，您可能需要调整它们。确保您的 Bitrix24 应用已正确配置以发送这些初始令牌。


4. 文件系统访问： 该工作流使用 ReadWriteFile n8n 节点来保存和读取 Bitrix24 身份验证令牌。请确保您的 n8n 托管环境有权访问路径 /data/files/hotline_files/（或在 Extract Credentials 节点中将 settingsFilePath 变量调整为您 n8n 实例可访问的位置）。


5. 激活： 保存并激活 n8n 工作流。自动化现在将开始侦听 Bitrix24 事件。

Bitrix24 Handler (Webhook n8n 触发器): n8n 工作流的入口点。它被配置为侦听特定路径上的 POST 请求，从而为安装和任务视图请求启动一系列操作。
Extract Credentials (Set n8n 节点): 对安全性至关重要，此节点会解析 Bitrix24 发送的动态身份验证参数（如 accesstoken 和 refreshtoken），为它们在后续 HTTP 请求中的使用以及保存到存储中做好准备。
Check Event Type (Code n8n 节点): 一个自定义脚本节点，用于解析传入的请求主体，区分应用安装回调和小部件放置事件，为 n8n 工作流提供关键的流程控制逻辑。
Is Installation? (If n8n 节点): 一个核心逻辑 n8n 节点，根据当前请求是否属于应用安装过程（isInstallation: true）来引导流程走向。
Set Settings Data & Save Installation Settings (Set & ReadWriteFile n8n 节点): 在 n8n 模板中，这些节点协同工作，将新收到的 Bitrix24 令牌（包括过期时间和域）序列化，并将其安全地写入本地文件系统的 JSON 文件中，保证了持久性以供后续运行时使用。
Register Placement (HTTP Request n8n 节点): 执行 Bitrix24 API 调用，将自定义小部件处理程序 URL 绑定到所需的位置，特别是 TASKVIEWTAB，确保 n8n Webhook URL 正确集成到 Bitrix24 界面中。
Read Installation Settings & Process Settings (ReadWriteFile & Function n8n 节点): 在运行时访问时，这些节点会检索和处理存储的令牌，确保 n8n 工作流拥有必要的凭据和上下文（如特定的 taskId）以继续进行 API 查询。
Get Task Data (HTTP Request n8n 节点): 利用已验证的访问令牌对 Bitrix24 API (tasks.task.get) 执行经过身份验证的调用，获取小部件显示所需的详细信息。这是此 n8n 工作流运行时阶段的关键步骤。

• Task View Response (RespondToWebhook n8n 节点): 运行时请求的最后操作。它会打包由前一个函数节点生成的 HTML，并立即将其发送回 Bitrix24，从而在自定义任务小部件中显示内容。