Botpress Salesforce 集成实战指南：OAuth 授权、对象增删改查与通用 API 代理

AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载本文以 Botpress 官方仓库中的 Salesforce 集成文档 为主体结合 集成定义文件 与底层 TypeScript 实现系统讲解如何在 Botpress Studio 中安装并授权 Salesforce、使用沙箱环境以及通过Make API Request、Search/Create/Update Contacts、Search/Create/Update Leads等卡片完成 CRM 数据操作。读完本文你将能独立完成 Salesforce 集成的接入配置并在 Bot 流程中稳定地读写联系人、线索等对象同时掌握 OAuth 令牌刷新与自定义字段扩展的实现原理。集成能力总览Salesforce 集成允许 Bot 直接操作 Salesforce 中的对象联系人、线索、Case 等并提供通用 API 代理能力。根据 integration.definition.ts该集成当前版本为1.0.3官方描述为“允许创建、搜索、更新和删除多种 Salesforce 对象”。从 动作定义聚合文件 可以看到集成实际暴露了 10 个动作分属四组分组动作说明Contact联系人createContact/searchContacts/updateContact创建、搜索、更新 Salesforce ContactLead线索createLead/searchLeads/updateLead创建、搜索、更新 Salesforce LeadCase工单createCase/searchCases/updateCase创建、搜索、更新 Salesforce CaseAPImakeApiRequest以代理方式直接请求 Salesforce REST API这些动作在 Studio 中会以卡片Card形式出现在流程编辑器中可直接拖入对话流使用。集成安装与 OAuth 授权按照 hub.md 的步骤接入流程只需三步安装集成在 Botpress 集线器Hub中安装 Salesforce 集成。OAuth 授权点击Authorize或Connect with OAuth按钮跳转到 Salesforce 完成授权从而完成安装过程。选择环境如需使用 Salesforce 的 Sandbox沙箱环境在连接前将配置类型切换为Sandbox即可。授权背后的 OAuth Wizard 流程点击授权按钮后真正执行授权的是 handler.ts 中定义的 OAuth 向导Wizard。整个流程分为两步start 步骤handler.ts#L6-L16拼接 Salesforce 授权 URL携带response_typecode、client_id来自密钥CONSUMER_KEY、redirect_uriBotpress 的 oauth-callback 地址以及state当前 webhookId随后将用户重定向到 Salesforce 登录授权页。oauth-callback 步骤handler.ts#L18-L66用户授权后回调到 Botpress使用jsforce的OAuth2与Connection以授权码换取accessToken、instanceUrl和refreshToken然后写入集成级状态credentials并通过configureIntegration({ identifier: ctx.webhookId })完成实例标识配置。集成所需的密钥与状态在创建并配置集成实例前需要在 Botpress 中为集成配置两个密钥integration.definition.ts#L45-L52CONSUMER_KEYSalesforce 连接应用Connected App的 Consumer KeyCONSUMER_SECRETSalesforce 连接应用的 Consumer Secret。授权成功后accessToken、instanceUrl、refreshToken与isSandbox会以 JSON 形式持久化在集成级状态credentials中integration.definition.ts#L27-L44。所有后续 API 调用都会从该状态读取令牌与实例地址。使用 Sandbox 沙箱环境hub.md 明确指出连接前选择Sandbox配置类型即可使用 Salesforce 沙箱环境。这一配置在源码中有明确对应integration.definition.ts#L17-L25 定义了名为sfsandbox的配置项标题为Sandbox描述为“使用 Salesforce 沙箱环境test.salesforce.com”。sf-utils.ts#L114-L116 中的getEnvironmentUrl会根据当前配置类型返回不同登录地址sfsandbox返回https://test.salesforce.com否则返回https://login.salesforce.com。值得注意的一个细节在集成注册register钩子中src/index.ts#L7-L22如果检测到当前配置类型与已保存凭证中的isSandbox不一致会清空credentials状态并提示“Salesforce 环境已变更请重新登录”。也就是说从正式环境切换到沙箱或反向切换后必须重新走一次 OAuth 授权流程不能直接复用旧凭证。Make API Request通用 API 代理当内置卡片无法覆盖需求时Make API Request卡片充当代理允许直接向 Salesforce API 发起请求。hub.md 中的使用方式如下在流程中添加Make API Request卡片传入合法的 HTTP 方法、URL 路径格式为yourinstance.salesforce.com/services/data/v54.0/PATH以及需要的附加请求数据。输入参数详解根据 api-actions.ts该动作的完整输入如下参数类型说明methodstring必填HTTP 方法GET、POST、PATCH、DELETEpathstring必填相对路径如sobjects/Contact、query?qSELECTIdFROMContactheadersstring可选附加请求头JSON 格式paramsstring可选URL 查询参数JSON 格式requestBodystring可选请求体JSON 格式支持多行编辑与动态变量注意path中不需要包含域名部分。从 src/actions/api.ts#L13 的实现可以看到最终请求 URL 由代码拼装为${instanceUrl}/services/data/v54.0/${input.path}其中instanceUrl来自授权时保存的凭证形如https://yourorg.salesforce.comAPI 版本v54.0由集成内置。hub.md 中“yourinstance.salesforce.com/services/data/v54.0/PATH”的写法即是对该路径格式的示意。输出与错误处理动作输出api-actions.ts#L28-L35包含successboolean请求是否成功statusnumber可选HTTP 状态码bodyany可选API 返回体errorstring可选失败时的错误信息。在 src/actions/api.ts#L23-L61 中还内置了令牌自动刷新逻辑当请求返回 HTTP 401访问令牌过期时集成会调用refreshSfToken刷新令牌并自动重试一次请求全程对流程无感知非 401 错误则直接记录告警并返回错误信息。Contact联系人操作hub.md 为 Contact 提供了三种操作卡片下面逐一展开并补充源码层面的字段细节。Search Contacts搜索联系人操作步骤hub.md在 Studio 中向流程添加Search Contacts卡片在卡片输入中至少传入一个搜索条件可将动作结果存入变量供后续使用。搜索条件定义于 contact-actions.ts#L54-L72均为可选字段Id联系人 ID、Name名字如 John、Email邮箱。三个字段中至少填写一个集成会基于传入的条件查询 Salesforce 并返回匹配的记录数组。Create Contact创建联系人操作步骤hub.md在流程中添加Create Contact卡片在卡片输入中传入联系人信息其中First Name、Last Name、Email为必填可通过 JSON 格式传入自定义字段可将创建出的联系人Id存入变量。字段定义见 contact-actions.ts#L4-L27字段必填说明FirstName是名字如 JohnLastName是姓氏如 DoeEmail是邮箱需符合 email 格式校验Phone否电话如 1-555-1234customFields否自定义字段JSON 格式多行文本编辑Update Contact更新联系人操作步骤hub.md在流程中添加Update Contact卡片传入要更新的联系人Id以及需要更新的字段可通过 JSON 格式传入自定义字段可将更新后的联系人Id存入变量。源码实现上contact-actions.ts#L40-L52updateContact的输入是“Id 创建卡片全部字段的可选版本”即除Id外所有字段均可选只更新实际传入的字段。Lead线索操作Lead 与 Contact 的操作模式完全一致区别在于必填字段与可用字段。Search Leads搜索线索步骤hub.md添加Search Leads卡片 → 至少传入一个搜索条件 → 将结果存入变量。可选搜索条件为Id、Name、Emaillead-actions.ts#L53-L71。Create Lead创建线索步骤hub.md添加Create Leads卡片 → 传入线索信息其中First Name、Last Name、Email、Company为必填 → 可选 JSON 自定义字段 → 将生成的Id存入变量。完整字段见 lead-actions.ts#L4-L26字段必填说明FirstName是名字LastName是姓氏Email是邮箱Company是公司如 Acme Inc.Phone否电话Title否职位Description否描述customFields否自定义字段JSON 格式Update Lead更新线索步骤hub.md添加Update Leads卡片 → 传入Id与待更新字段 → 可选 JSON 自定义字段 → 将Id存入变量。同样地源码中updateLead为“Id 创建字段全可选”的结构lead-actions.ts#L39-L51。补充Case工单操作hub.md 未单独列出 Case 操作但集成源码中同样提供了createCase、searchCases、updateCase三个动作case-actions.ts并在集成定义中统一导出definitions/index.ts#L7-L13。其中createCase的必填字段为Subject与DescriptionStatus可选同样支持customFieldsJSON 扩展。若你的场景需要处理客服工单可直接使用这三个卡片操作方式与 Contact/Lead 完全一致。自定义字段Custom Fields的底层处理Contact、Lead、Case 的创建与更新动作都支持customFields参数它接受一段 JSON 字符串用于传入 Salesforce 对象上的自定义字段如自定义的My_Field__c。其底层实现在 sf-utils.ts#L102-L112解析customFieldsJSON将展开后的键值对合并进请求负载合并完成后删除customFields键本身避免把原始 JSON 字符串误当作字段名提交。例如在Create Contact卡片中传入{ FirstName: John, LastName: Doe, Email: john.doeexample.com, customFields: {\Industry__c\: \Software\, \LeadSource\: \Bot\} }最终提交给 Salesforce 的负载等价于{ FirstName: John, LastName: Doe, Email: john.doeexample.com, Industry__c: Software, LeadSource: Bot }注意customFields必须是合法 JSON 字符串若解析失败动作会直接报错。Studio 中该输入框支持多行编辑与动态变量displayAs配置见 contact-actions.ts#L13-L26方便在流程中拼接动态内容。动作的统一输出结构所有对象操作都遵循统一的输出约定common-schemas.ts创建 / 更新recordResultSchema字段类型说明idstring可选创建或更新的记录 IDsuccessboolean操作是否成功errorstring可选失败时的错误信息搜索searchOutputSchema字段类型说明successboolean搜索是否成功recordsarray可选搜索返回的记录数组errorstring可选失败时的错误信息因此在流程中你可以直接用“{{action_result.success}}”判断成败用“{{action_result.id}}”或“{{action_result.records}}”承接后续逻辑。从实现上看这些动作最终复用了 generic 目录 下的createSalesforceRecord、fetchSalesforceRecords、updateSalesforceRecord三个通用函数见 contacts.ts#L7-L17对不同对象传入对应的SalesforceObject枚举即可复用同一套 CRUD 逻辑。令牌生命周期与自动刷新Salesforce 的访问令牌accessToken默认有有效期过期后返回 HTTP 401。该集成在两层做了自动处理API 代理层src/actions/api.ts#L34-L51makeApiRequest收到 401 后调用refreshSfToken刷新令牌并用新令牌重试一次。jsforce 连接层sf-utils.ts#L36-L54创建Connection时注册refresh事件监听一旦 jsforce 内部发现令牌过期会自动用refreshToken换取新令牌并将新令牌回写进credentials状态持久化。refreshSfToken的具体实现sf-utils.ts#L59-L100是向${环境地址}/services/oauth2/token发起grant_typerefresh_token的 OAuth 令牌交换请求。需要留意的是若凭证中不存在refreshToken刷新会直接失败并提示“请重新授权”这通常发生在 Salesforce 连接应用未勾选refresh_tokenscope 或用户撤销授权的情况下。常见问题与排查建议授权后报错“No refresh token provided”说明 Salesforce 连接应用未授予refresh_tokenscope或该用户已授权过但 scope 变更需要在 Salesforce Connected App 中检查 OAuth 配置并重新授权。切换正式/沙箱环境后接口报未授权这是设计行为——register 钩子 检测到环境切换后会清空旧凭证必须重新点击 Authorize。Make API Request 返回 401 后仍失败令牌刷新重试只有一次若刷新本身失败如 refresh token 失效请重新走授权流程。自定义字段 JSON 解析失败请确认传入的是合法的 JSON 字符串而不是花括号内直接写字段名的裸文本。搜索条件全部留空searchContacts、searchLeads、searchCases都要求至少传入一个条件否则查询没有依据。关联文件索引集成使用文档本篇文章的骨架来源integrations/salesforce/hub.md集成定义版本、配置、密钥、状态与动作清单integrations/salesforce/integration.definition.ts动作定义Contact / Lead / Case / API 分组定义见 integrations/salesforce/definitionsOAuth 授权向导 integrations/salesforce/src/handler.ts令牌刷新与环境地址工具 integrations/salesforce/src/misc/utils/sf-utils.ts通用 CRUD 实现 integrations/salesforce/src/actions/generic赞分享AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载相关推荐Instant Platform OAuth 2.0 集成指南授权码流程与 Superadmin API 实战Instant Platform OAuth 2.0 集成指南授权码流程与 Superadmin API 实战 Instant 支持标准的 OAuth 2.0后端数据库Argilla 用户管理实战角色体系、SDK 增删改查与工作区授权完整指南Argilla 用户管理实战角色体系、SDK 增删改查与工作区授权完整指南 Argilla 的 用户管理User management 是构建高质量标注数数据标注人工智能NLPMLOpsRAGDataHub Tags API 实战指南通过 GraphQL 与 Python SDK 完成标签的增删改查DataHub Tags API 实战指南通过 GraphQL 与 Python SDK 完成标签的增删改查 Tags 是 DataHub 中一类非正式、松散数据目录数据治理数据血缘后端前端数据工程数据集成上一篇baidupankey 使用指南几秒钟查到百度网盘分享链接的提取码下一篇XUnity自动翻译器实战不等汉化组十分钟让你的Unity游戏变成中文创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考