Corsair Intercom 插件接入指南：在 Agent 中集成客户支持、会话与知识库能力

Corsair Intercom 插件接入指南在 Agent 中集成客户支持、会话与知识库能力【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair导读corsair-dev/intercom是 Corsair 生态中用于连接 Intercom客户沟通平台的官方插件。通过它你的 AI Agent 可以在获得终端用户授权后直接代表用户操作其 Intercom 工作区中的联系人、会话、公司、文章、合集与管理员资源并在联系人创建、会话关闭等关键事件发生时实时接收 Webhook 通知。阅读本文后你将掌握该插件的安装方式、66 个端点操作的完整清单与风险分级、API Key 认证与密钥构建逻辑、7 类 Webhook 事件的签名校验与多租户路由原理以及如何利用内置错误处理器实现自动重试与故障排查。插件概览Intercom 插件是 Corsair 的官方插件之一位于仓库的 packages/intercom 目录。它对外暴露为一个标准的 Corsair 插件工厂函数intercom()返回一个实现了CorsairPlugin接口的插件实例包含端点Endpoints围绕 Intercom REST API 封装的操作集合覆盖 contacts、conversations、companies、articles、collections、admins、helpCenters 七个资源域Webhook处理 Intercom 推送的 7 类事件Schema基于 Zod 定义的本地数据库实体模型contacts、conversations、companies、articles、admins错误处理器针对限流、认证失败、权限不足、资源不存在等场景的匹配与重试策略。插件通过corsair/http模块中的request发送请求基础地址为https://api.intercom.io详见 client.ts。请求头中固定携带Authorization: Bearer apiKey、Content-Type: application/json以及Intercom-Version: 2.11Intercom API 版本头并指定 JSON 作为响应格式。从这里可以看出插件的所有端点操作都基于 Intercom 的稳定 API 版本约定调用方无需自行处理版本协商。安装与 Corsair 的其他插件一致Intercom 插件以独立的 npm 包形式发布通过 pnpm 安装pnpm add corsair-dev/intercom从 package.json 可以看到它声明了两个必需的 peerDependencies依赖版本要求作用corsair0.1.0Corsair 核心运行时提供插件框架、HTTP 客户端与类型系统zod^4.1.13输入输出校验与数据库实体 Schema 定义安装完成后将intercom()注册进你的 Corsair 应用中即可启用。插件注册与配置选项在 Corsair 中注册 Intercom 插件的方式是调用工厂函数intercom()其接受IntercomPluginOptions配置对象。根据 index.ts 的类型定义支持以下选项选项类型默认值说明authTypePickAuthapi_keyapi_key认证方式当前仅支持 API Keykeystring无静态 API Key可直接在代码中指定适用于服务端场景webhookSecretstring无静态 Webhook 签名密钥用于校验 Intercom 推送的请求hooksInternalIntercomPlugin[hooks]无插件生命周期钩子webhookHooksInternalIntercomPlugin[webhookHooks]无Webhook 事件处理钩子errorHandlersCorsairErrorHandler内置处理器自定义错误处理会与默认处理器合并permissionsPluginPermissionsConfig无端点级权限配置可对单个操作做精细化授权一个典型的注册示例import { intercom } from corsair-dev/intercom; const intercomPlugin intercom({ authType: api_key, // 静态 Key适用于你自己的服务端应用 key: process.env.INTERCOM_API_KEY, // Webhook 签名密钥注册 Webhook URL 时由 Intercom 提供 webhookSecret: process.env.INTERCOM_WEBHOOK_SECRET, // 自定义错误处理会与内置处理器合并 errorHandlers: { // 例如为特定错误追加日志或告警 }, permissions: { contacts.delete: deny, // 示例禁止删除联系人 }, });intercom()内部会将传入选项与默认值合并authType缺省时取api_key并组装出完整的插件对象包含id: intercom、认证配置、Schema、端点、Webhook、元数据与密钥构建器等见 index.ts。permissions配置中的操作键名对应下文端点表中的 Operation ID如contacts.delete风险分级是权限控制的重要依据。端点操作完整清单与风险分级插件共封装 66 个端点操作按资源域分为 7 组。每个操作都带有全局唯一的 Operation ID形如intercom.api.xxx以及风险分级read/write/destructive其中destructive表示不可逆的删除操作。下表完整列出所有操作OperationOperation IDRiskDescriptionadmins.getintercom.api.admins.getreadRetrieve a single adminadmins.identifyintercom.api.admins.identifyreadIdentify the currently authorised adminadmins.listintercom.api.admins.listreadList all admins in the workspaceadmins.listActivityLogsintercom.api.admins.listActivityLogsreadList all admin activity logsadmins.setAwayintercom.api.admins.setAwaywriteSet an admin as awayarticles.createintercom.api.articles.createwriteCreate a new articlearticles.deleteintercom.api.articles.deletedestructiveDelete an article [DESTRUCTIVE]articles.getintercom.api.articles.getreadRetrieve a single articlearticles.listintercom.api.articles.listreadList all articlesarticles.searchintercom.api.articles.searchreadSearch for articlesarticles.updateintercom.api.articles.updatewriteUpdate an existing articlecollections.createintercom.api.collections.createwriteCreate a new collectioncollections.deleteintercom.api.collections.deletedestructiveDelete a collection [DESTRUCTIVE]collections.getintercom.api.collections.getreadRetrieve a single collectioncollections.listintercom.api.collections.listreadList all collectionscollections.updateintercom.api.collections.updatewriteUpdate a collectioncompanies.createOrUpdateintercom.api.companies.createOrUpdatewriteCreate or update a companycompanies.deleteintercom.api.companies.deletedestructiveDelete a company [DESTRUCTIVE]companies.getintercom.api.companies.getreadRetrieve a company by Intercom IDcompanies.listintercom.api.companies.listreadList all companiescompanies.listAttachedContactsintercom.api.companies.listAttachedContactsreadList contacts attached to a companycompanies.listAttachedSegmentsintercom.api.companies.listAttachedSegmentsreadList segments attached to a companycompanies.retrieveintercom.api.companies.retrievereadRetrieve a company by company_id or namecompanies.scrollintercom.api.companies.scrollreadScroll over all companies for large datasetscontacts.addSubscriptionintercom.api.contacts.addSubscriptionwriteAdd a subscription to a contactcontacts.addTagintercom.api.contacts.addTagwriteAdd a tag to a contactcontacts.attachToCompanyintercom.api.contacts.attachToCompanywriteAttach a contact to a companycontacts.createNoteintercom.api.contacts.createNotewriteCreate a note for a contactcontacts.deleteintercom.api.contacts.deletedestructiveDelete a contact [DESTRUCTIVE]contacts.detachFromCompanyintercom.api.contacts.detachFromCompanywriteDetach a contact from a companycontacts.getintercom.api.contacts.getreadGet a single contact by IDcontacts.listintercom.api.contacts.listreadList all contactscontacts.listAttachedCompaniesintercom.api.contacts.listAttachedCompaniesreadList companies attached to a contactcontacts.listAttachedSegmentsintercom.api.contacts.listAttachedSegmentsreadList segments attached to a contactcontacts.listNotesintercom.api.contacts.listNotesreadList all notes for a contactcontacts.listSubscriptionsintercom.api.contacts.listSubscriptionsreadList subscription types for a contactcontacts.listTagsintercom.api.contacts.listTagsreadList all tags attached to a contactcontacts.mergeintercom.api.contacts.mergewriteMerge a lead into a user contactcontacts.removeSubscriptionintercom.api.contacts.removeSubscriptionwriteRemove a subscription from a contactcontacts.removeTagintercom.api.contacts.removeTagwriteRemove a tag from a contactcontacts.updateintercom.api.contacts.updatewriteUpdate an existing contactconversations.assignintercom.api.conversations.assignwriteAssign a conversation to an admin or teamconversations.closeintercom.api.conversations.closewriteClose a conversationconversations.createintercom.api.conversations.createwriteCreate a new conversationconversations.getintercom.api.conversations.getreadGet a conversation by ID with all messages and detailsconversations.listintercom.api.conversations.listreadList conversations with filtering and paginationconversations.reopenintercom.api.conversations.reopenwriteReopen a closed conversationconversations.replyintercom.api.conversations.replywriteSend a reply to a conversationconversations.searchintercom.api.conversations.searchreadSearch conversations using query stringhelpCenters.getintercom.api.helpCenters.getreadRetrieve a single help centerhelpCenters.listintercom.api.helpCenters.listreadList all help centers端点实现与本地缓存逻辑每个端点操作的实现都遵循统一的模式从输入中提取路径参数与查询参数 → 调用makeIntercomRequest发起请求 → 可选将结果写入本地数据库 → 记录事件日志。以 contacts.ts 为例查询类操作如contacts.get、contacts.list会解析出id作为路径参数其余字段作为 query 传递写入类操作如contacts.update使用PUT方法并把剩余字段作为请求体删除类操作如contacts.delete使用DELETE方法读取或更新成功后只要本地数据库实体ctx.db.contacts已配置就会调用upsertByEntityId(result.id, result)将远端数据同步到本地实现远端 API 本地缓存的双写模型见 contacts.ts每个操作结束时通过logEventFromContext记录intercom.contacts.get等格式的事件便于审计与追踪见 contacts.ts。类型安全输入输出 Schema插件为全部 66 个操作提供了 Zod 输入/输出 Schema集中定义在 endpoints/types.ts并在 index.ts 的intercomEndpointSchemas中按contacts.get这样的点分键名注册。同时导出了全部输入/输出类型如ContactsGetInput、ContactsGetResponse供调用方在编译期获得完整的类型提示这也是 Corsair 插件体系类型即文档的体现。认证方式API Key本插件使用API Key认证。Corsair 会在终端用户首次使用相关端点时向其提示并提供录入凭据的入口凭据录入后由 Corsair 运行时安全托管开发者无需接触用户的原始密钥。认证配置与密钥构建器认证配置定义在 index.tsexport const intercomAuthConfig { api_key: { account: [app_id] as const, }, } as const satisfies PluginAuthConfig;其中account: [app_id]表示与用户账号关联的标识字段是 Intercom 工作区的app_id。这意味着即使同一用户的多个 Intercom 工作区多个app_id同时接入Corsair 也能将它们作为不同的租户区分对待。密钥的解析逻辑在keyBuilder中实现见 index.ts优先级如下Webhook 场景且配置了webhookSecret直接返回该静态密钥用于验签Webhook 场景从ctx.keys.get_webhook_signature()获取已托管的 Webhook 签名密钥若缺失则抛出[auth-missing:intercom:webhook_signature]错误端点场景且配置了key返回静态 API Key端点场景从ctx.keys.get_api_key()获取已托管的 API Key若缺失则抛出AuthMissingError(intercom, api_key)。这种静态 Key 优先、托管 Key 兜底的设计让插件既能服务于你自己的后端直接配置key也能服务于多租户 SaaS 场景由 Corsair 管理每个租户的凭据。Webhook7 类事件与签名校验插件处理 7 类 Webhook 事件定义在 webhooks/index.ts分组事件Intercom topic触发场景contactscontactCreatedcontact.user.created新联系人创建contactscontactDeletedcontact.user.deleted联系人被删除contactscontactTagCreatedcontact.user.tag.created联系人被打上标签conversationsconversationCreatedconversation.admin.created新会话创建conversationsconversationAssignedconversation.admin.assigned会话被分配给管理员或团队conversationsconversationClosedconversation.admin.closed会话关闭-pingping首次注册 Webhook URL 时 Intercom 发送的验证请求请求识别与多租户匹配在插件层面通过pluginWebhookMatcher判断请求是否属于 Intercom Webhook要求请求头同时包含x-hub-signature与intercom-webhook-subscription-id两个字段见 index.ts。多租户匹配则由 tenant-matcher.ts 实现Intercom 的通知载荷中携带app_id字段即工作区标识matchIntercomTenantWebhook从请求体解析出app_id返回{ linkType: app_id, externalId: appId }Corsair 据此将事件路由到对应的租户连接。事件结构与签名验签所有事件的公共载荷结构定义在 webhooks/types.tsinterface IntercomWebhookPayload { type: string; topic: string; // 事件主题如 contact.user.created id: string | null; // ping 事件中为 null app_id: string; // 工作区标识用于租户匹配 created_at: number; first_sent_at: number; data: { type: string; item: Recordstring, unknown; // 随 topic 变化的动态数据 }; }每个事件的match函数通过createIntercomMatch(topic)生成仅比较请求体中的topic字段见 webhooks/types.ts。签名校验是 Webhook 处理的第一道关卡。verifyIntercomWebhookSignature见 webhooks/types.ts的实现要点读取请求头x-hub-signature兼容字符串或字符串数组使用HMAC-SHA1以 Webhook 密钥对原始请求体计算sha1hex签名通过crypto.timingSafeEqual进行常数时间比较防止时序攻击校验失败返回{ valid: false, error }成功返回{ valid: true }。在每个 Webhook handler 中签名校验失败会直接返回401状态码。例如contactCreated见 webhooks/contacts.ts在验签通过后还会将事件中的联系人数据id、email、name、role、created_at通过upsertByEntityId同步进本地数据库并把created_at秒级时间戳转换为Date类型写入createdAt字段。本地数据模型Schema插件定义了一个版本化的数据库 Schemaversion: 1.0.0包含 5 类实体见 schema/index.ts实体Zod 模型关键字段节选contactsIntercomContactid、external_id、email、name、phone、role、created_at、last_seen_at、location、owner_idconversationsIntercomConversationid、state、priority、admin_assignee_id、team_assignee_id、contact_id、source_typecompaniesIntercomCompanyid、company_id、name、monthly_spend、session_count、user_count、planarticlesIntercomArticleid、title、description、body、author_id、state、url、default_localeadminsIntercomAdminid、name、email、away_mode_enabled、has_inbox_seat、team_ids模型定义详见 schema/database.ts。其中时间字段统一采用 Unix 秒级时间戳optionalUnixSeconds/nullableUnixSeconds同时提供createdAt作为z.coerce.date()的派生字段便于在本地数据库中直接按Date类型查询与排序。由于本地 Schema 与 Intercom API/Webhook 的返回结构一一对应接入方可以直接使用 Corsair 的数据库能力持久化同步数据实现远端工作区 本地副本的混合查询模式。错误处理与自动重试插件内置了一组默认错误处理器定义在 error-handlers.ts并通过errorHandlers选项与用户自定义处理器合并。每个处理器由match判定与handler响应两部分组成处理器匹配条件行为RATE_LIMIT_ERRORHTTP 429或错误信息含rate_limited/ratelimited/429返回maxRetries: 5并透传retry-after头作为重试等待时间AUTH_ERRORHTTP 401或信息含invalid_auth/unauthorized/authentication failed/access_token_not_found打印告警提示检查 API KeymaxRetries: 0不重试PERMISSION_ERRORHTTP 403或信息含permission_denied/forbidden/access_denied/admin_not_found打印告警maxRetries: 0NOT_FOUND_ERRORHTTP 404或信息含not_found/resource_not_found打印告警maxRetries: 0DEFAULT兜底匹配所有错误打印Unhandled errormaxRetries: 0告警日志统一使用[INTERCOM:operation]前缀便于在日志系统中快速过滤定位。内置的限流重试策略最多 5 次对 Intercom 这类有严格 API 配额的平台尤为重要可以有效降低 Agent 调用被 429 中断的概率。另外client.ts 还定义了IntercomAPIError错误类将底层 HTTP 错误包装为携带可选错误码的统一异常便于上层 Agent 进行结构化处理。在 Corsair 应用中的使用建议综合以上实现将 Intercom 插件接入你的 Corsair 应用时推荐按以下路径落地安装依赖pnpm add corsair-dev/intercom并确保corsair与zod版本满足 peerDependencies 要求注册插件调用intercom()并传入authType: api_key若为自有服务端场景直接配置key与webhookSecret配置权限通过permissions对destructive级别的操作如contacts.delete、companies.delete、articles.delete、collections.delete进行显式管控避免 Agent 误操作接入 Webhook在 Intercom 后台注册回调 URL 并配置订阅事件插件通过x-hub-signature与intercom-webhook-subscription-id识别请求通过app_id路由租户通过 HMAC-SHA1 验签后进入各事件 handler利用本地缓存配置数据库实体后查询与更新操作会自动upsertByEntityId配合createdAt派生字段实现高效的本地检索观察错误日志依据[INTERCOM:operation]前缀日志与内置重试策略持续观测限流与鉴权状态。扩展阅读插件入口与完整类型导出packages/intercom/index.ts端点实现示例packages/intercom/endpoints/contacts.ts全部端点输入/输出类型与 Zod Schemapackages/intercom/endpoints/types.tsWebhook 事件类型与验签实现packages/intercom/webhooks/types.ts本地数据库实体模型packages/intercom/schema/database.ts错误处理器packages/intercom/error-handlers.ts插件文档与示例仓库内镜像docs/plugins/intercom该插件遵循 Apache-2.0 协议开源见 packages/intercom/package.json你可以在自己的项目中自由使用并基于源码深入理解其实现细节。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考