集成、自动化流程与会议

连接第三方应用，构建自动化流程，接收会议预约，并按需同步 Google Sheets 中的潜在客户。

这些端点覆盖 Warmbly 的集成层：服务商目录和连接生命周期、每个连接的事件订阅与字段映射、可视化自动化流程构建器、已预约会议列表，以及按需 Google Sheets 潜在客户同步。多数读取操作可供集成功能使用者访问（use_integrations / INTEGRATIONS），而连接和配置属于设置操作，需要 manage_settings。

集成是付费套餐功能。浏览目录和列出连接对所有组织开放，未付费组织可看到升级提示；但组织没有付费套餐时，任何修改调用，包括连接、授权、配置、推送、测试和自动化流程写入，都会返回 403，消息为“集成功能仅适用于付费套餐”。

本组列表多数采用各自的封装，例如 {"connections": [...]}、{"automations": [...]}，而非其他位置使用的游标分页 data + pagination 结构。会议搜索和潜在客户同步来源列表为例外，具体见各处说明。错误采用标准 {error, message, code, request_id} 封装，参阅错误码。

列出集成目录

GET /integrations/catalog

返回 Warmbly 支持的每个服务商的静态元数据，并标明各 OAuth 服务商是否已配置服务端凭据（configured）。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

响应

catalog 数组，包含服务商条目。

{
  "catalog": [
    {
      "provider": "hubspot",
      "name": "HubSpot",
      "tagline": "Sync contacts and deals to your CRM",
      "category": "crm",
      "auth_method": "oauth",
      "beta": false,
      "highlights": ["Push contacts on demand", "Auto-sync on positive reply"],
      "scopes": ["crm.objects.contacts.write"],
      "events": ["email.replied", "meeting.booked"],
      "action_types": ["hubspot.upsert_contact"],
      "supports_push": true,
      "configured": true,
      "rank": 1
    }
    // ... one entry per provider
  ]
}

rank 表示服务商在本实例的使用排名，1 为使用最多。排名依据具有有效连接的工作区数量；并列时按预设顺序决定，因此新实例也有排名。数组本身保持目录顺序；按 rank 排序可将使用最多的放在前面。

列出社区应用

GET /integrations/community

返回发现页面显示的社区目录条目：精选应用优先，其后是已在发布者以外至少 25 个工作区安装、且这些工作区各自已创建至少两周的已发布应用，按安装数从多到少排序。仅可通过链接访问的应用不会在此返回。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

参数	位置	类型	说明
`limit`	query	integer	范围 1 至 200，默认 100。超出范围返回 `400`。
`cursor`	query	string	来自 `pagination.next_cursor` 的不透明游标。不是由本 API 签发的游标返回 `400`。

响应

{
  "data": [
    {
      "application_id": "5a8f0c1e-2b3d-4e5f-8a9b-0c1d2e3f4a5b",
      "slug": "acme-sync",
      "name": "Acme Sync",
      "tagline": "Push positive replies into Acme as deals",
      "description": "",
      "category": "crm",
      "logo_url": "",
      "website_url": "https://acme.com",
      "install_url": "https://acme.com/warmbly/install",
      "support_url": "https://acme.com/support",
      "privacy_url": "",
      "developer": "Acme Inc",
      "scopes": 1,
      "permissions": [
        { "name": "READ_EMAILS", "value": 1, "description": "View email accounts and settings", "category": "read" }
      ],
      "status": "featured",
      "listed": true,
      "installs": 12,
      "installed": false,
      "published_at": "2026-10-03T09:00:00Z"
    }
  ],
  "pagination": { "total": 1, "next_cursor": null, "has_more": false }
}

status 为 featured 或 published，listed 表示是否在发现页面展示。developer 是发布工作区的名称。installs 统计本实例中持有有效授权的工作区数，installed 表示调用者工作区是否有任何人持有有效授权。绝不包含凭据、重定向 URI 或 Webhook 设置。

获取社区应用

GET /integrations/community/{slug}

按短标识返回单个条目，包括目录公开条目和仅链接可访问条目，结构与列表项相同。共享链接通过此接口解析。条目已隐藏、未发布，或所属应用已停用时，返回 404。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

列出连接

GET /integrations/connections

返回本组织的连接记录。机密值，包括访问令牌、刷新令牌和粘贴的 API 密钥，永远不会序列化输出。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

响应

connections 数组，包含 IntegrationConnection 对象。

{
  "connections": [
    {
      "id": "9b2c1f7e-4d6a-4f2b-bb11-9d0e2a7c5f33",
      "organization_id": "1a2b3c4d-0000-0000-0000-000000000001",
      "provider": "hubspot",
      "label": "HubSpot (Sales)",
      "status": "connected",
      "auth_method": "oauth",
      "display_fields": {},
      "sync_direction": "push",
      "external_account_name": "Acme Inc",
      "granted_scopes": ["crm.objects.contacts.write"],
      "health": "healthy",
      "last_synced_at": "2026-06-10T14:03:00Z",
      "created_at": "2026-05-01T09:00:00Z",
      "updated_at": "2026-06-10T14:03:00Z"
    }
  ]
}

创建连接

POST /integrations/connections

为采用 api_key / webhook 的服务商，例如 Close 或 Discord，创建基于凭据的连接。OAuth 服务商在此会被拒绝，并提示改为启动授权流程（POST /integrations/oauth/start，仅限会话）。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings。

请求体

字段	类型	必填	说明
`provider`	string	是	有效的服务商 ID，例如 `close`、`discord`。
`label`	string	否	显示在连接卡片上的友好名称。
`config`	object	否	服务商专用配置，例如粘贴的 API 密钥或 Webhook URL。

{
  "provider": "close",
  "label": "Close (Outbound)",
  "config": { "api_key": "api_xxx" }
}

响应

201 Created，直接返回创建的 IntegrationConnection 对象，无额外封装。对于入站服务商 Calendly 和 Cal.com，响应会包含仅显示一次的 inbound_webhook_url。

{
  "id": "c0ffee00-0000-4000-8000-000000000abc",
  "provider": "close",
  "label": "Close (Outbound)",
  "status": "connected",
  "auth_method": "api_key",
  "sync_direction": "push",
  "health": "unknown",
  "created_at": "2026-06-11T10:00:00Z",
  "updated_at": "2026-06-11T10:00:00Z"
}

获取连接

GET /integrations/connections/:id

返回一个连接、其事件订阅和最多 20 次近期同步运行，用于详情抽屉。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

参数	位置	类型	说明
`id`	path	uuid	连接 ID。

响应

{
  "connection": {
    "id": "9b2c1f7e-4d6a-4f2b-bb11-9d0e2a7c5f33",
    "provider": "hubspot",
    "label": "HubSpot (Sales)",
    "status": "connected",
    "auth_method": "oauth",
    "sync_direction": "push",
    "health": "healthy",
    "created_at": "2026-05-01T09:00:00Z",
    "updated_at": "2026-06-10T14:03:00Z"
  },
  "events": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "connection_id": "9b2c1f7e-4d6a-4f2b-bb11-9d0e2a7c5f33",
      "event_type": "email.replied",
      "action": "hubspot.upsert_contact",
      "config": {},
      "enabled": true,
      "use_case": "crm_sync",
      "created_at": "2026-05-01T09:05:00Z",
      "updated_at": "2026-05-01T09:05:00Z"
    }
  ],
  "runs": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "connection_id": "9b2c1f7e-4d6a-4f2b-bb11-9d0e2a7c5f33",
      "kind": "push",
      "status": "success",
      "detail": "pushed 12 contacts",
      "records_processed": 12,
      "started_at": "2026-06-10T14:02:00Z",
      "finished_at": "2026-06-10T14:03:00Z"
    }
  ]
}

更新连接配置

PATCH /integrations/connections/:id/config

保存连接的初始配置及能力快照，包括所选对象、已启用用途，以及同步方向。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings。

参数	位置	类型	说明
`id`	path	uuid	连接 ID。

请求体

字段	类型	必填	说明
`config_capabilities`	object	否	各连接的能力快照，包括选择器选项和已启用用途。
`sync_direction`	string	否	数据流向：`push`、`pull` 或 `both`。

{
  "config_capabilities": { "objects": ["contact"], "use_cases": ["crm_sync"] },
  "sync_direction": "push"
}

响应

{
  "connection": {
    "id": "9b2c1f7e-4d6a-4f2b-bb11-9d0e2a7c5f33",
    "provider": "hubspot",
    "sync_direction": "push",
    "status": "connected",
    "health": "healthy",
    "updated_at": "2026-06-11T11:00:00Z"
  }
}

列出事件订阅

GET /integrations/connections/:id/events

返回连接配置的事件订阅，即事件到操作的路由。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

参数	位置	类型	说明
`id`	path	uuid	连接 ID。

响应

{
  "events": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "connection_id": "9b2c1f7e-4d6a-4f2b-bb11-9d0e2a7c5f33",
      "event_type": "email.replied",
      "action": "hubspot.upsert_contact",
      "config": {},
      "enabled": true,
      "use_case": "crm_sync",
      "automation_id": null,
      "created_at": "2026-05-01T09:05:00Z",
      "updated_at": "2026-05-01T09:05:00Z"
    }
  ]
}

创建事件订阅

POST /integrations/connections/:id/events

将 Warmbly 事件路由到此连接上的服务商操作。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings。

参数	位置	类型	说明
`id`	path	uuid	连接 ID。

请求体

字段	类型	必填	说明
`event_type`	string	是	要响应的 Warmbly 事件，例如 `email.replied`。
`action`	string	是	服务商操作 ID，例如 `slack.notify`、`hubspot.upsert_contact`。
`config`	object	否	操作配置，例如 Slack 频道或消息模板。
`enabled`	boolean	否	省略时默认 `true`。

{
  "event_type": "email.replied",
  "action": "slack.notify",
  "config": { "channel": "#sales" },
  "enabled": true
}

响应

201 Created，直接返回创建的 IntegrationEventSubscription 对象。

{
  "id": "33333333-3333-4333-8333-333333333333",
  "connection_id": "9b2c1f7e-4d6a-4f2b-bb11-9d0e2a7c5f33",
  "event_type": "email.replied",
  "action": "slack.notify",
  "config": { "channel": "#sales" },
  "enabled": true,
  "use_case": "notify",
  "created_at": "2026-06-11T12:00:00Z",
  "updated_at": "2026-06-11T12:00:00Z"
}

列出字段映射

GET /integrations/connections/:id/field-mappings

返回连接配置的 Warmbly 字段到服务商字段的映射。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

参数	位置	类型	说明
`id`	path	uuid	连接 ID。

响应

{
  "mappings": [
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "connection_id": "9b2c1f7e-4d6a-4f2b-bb11-9d0e2a7c5f33",
      "direction": "push",
      "object_name": "contact",
      "warmbly_field": "email",
      "external_field": "email",
      "transform": "",
      "static_value": "",
      "is_default": true,
      "created_at": "2026-05-01T09:06:00Z"
    }
  ]
}

替换字段映射

PUT /integrations/connections/:id/field-mappings

整体替换某个对象在连接中的默认字段映射。完整替换本身具有幂等性，因此无需 Idempotency-Key 也可安全重试。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings。

参数	位置	类型	说明
`id`	path	uuid	连接 ID。

请求体

字段	类型	必填	说明
`object`	string	否	映射适用的服务商对象，例如 `contact`。
`mappings`	array	是	要保存的完整映射集合，替换所有现有映射。
`mappings[].external_field`	string	是	服务商侧目标字段，每条映射必填。
`mappings[].warmbly_field`	string	有条件必填	来源 Warmbly 字段。除非 `transform` 为 `static`，否则必填。
`mappings[].transform`	string	否	取值为 ``（无）、`none`、`static`、`uppercase`、`lowercase`、`trim` 之一。
`mappings[].static_value`	string	有条件必填	`transform` 为 `static` 时必填。

{
  "object": "contact",
  "mappings": [
    { "warmbly_field": "email", "external_field": "email", "transform": "" },
    { "warmbly_field": "first_name", "external_field": "firstname", "transform": "trim" },
    { "external_field": "lifecyclestage", "transform": "static", "static_value": "lead" }
  ]
}

响应

替换后的完整映射集合，结构与列表端点相同。

{
  "mappings": [
    {
      "id": "44444444-4444-4444-8444-444444444444",
      "connection_id": "9b2c1f7e-4d6a-4f2b-bb11-9d0e2a7c5f33",
      "object_name": "contact",
      "warmbly_field": "email",
      "external_field": "email",
      "transform": "",
      "is_default": true,
      "created_at": "2026-06-11T12:30:00Z"
    }
  ]
}

列出同步执行记录

GET /integrations/connections/:id/runs

返回某个连接最多 50 条近期可观测记录，包括连接、令牌刷新、事件分发和手动推送。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

参数	位置	类型	说明
`id`	path	uuid	连接 ID。

响应

{
  "runs": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "connection_id": "9b2c1f7e-4d6a-4f2b-bb11-9d0e2a7c5f33",
      "kind": "push",
      "status": "success",
      "detail": "pushed 12 contacts",
      "records_processed": 12,
      "started_at": "2026-06-10T14:02:00Z",
      "finished_at": "2026-06-10T14:03:00Z"
    }
  ]
}

获取连接的 Webhook 密钥

GET /integrations/connections/:id/webhook-secret

返回自动化连接的 HMAC 签名密钥，首次调用时生成，用于验证 Warmbly 对外 Webhook 的签名。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings。

参数	位置	类型	说明
`id`	path	uuid	连接 ID。

响应

{
  "signing_secret": "whsec_live_...",
  "signature_header": "X-Warmbly-Signature",
  "scheme": "HMAC-SHA256 of \"{t}.{body}\", sent as t=<unix>,v1=<hex>"
}

测试连接

POST /integrations/connections/:id/test

通过连接的通知或 Webhook 自动化发送一个模拟事件，便于确认 Zap、场景或频道已经连通。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings。

参数	位置	类型	说明
`id`	path	uuid	连接 ID。

响应

{ "sent": true }

将联系人推送到 CRM

POST /integrations/connections/:id/push

将指定的组织联系人同步插入或更新到已连接的 CRM，包括 HubSpot、Pipedrive、Salesforce、Close。重试本身安全：各服务商的插入或更新均以邮件地址为键，重复推送会收敛到相同结果，不会产生重复记录，无需 Idempotency-Key。响应返回逐条结果。对于 Salesforce，每个联系人会匹配对应的 Lead 或 Contact；不存在时按连接的 Create as（创建类型） 设置创建，并通过其字段规则更新。

身份验证：权限范围 INTEGRATIONS · 组织权限 use_integrations。

参数	位置	类型	说明
`id`	path	uuid	连接 ID。

请求体

字段	类型	必填	说明
`contact_ids`	string[]	必填，除非使用 `all`	要推送的联系人 ID。服务端去重，至少 1 个，最多 500 个。
`all`, `filters`, `exclude`	—	否	使用筛选选择替代 ID 列表。最终仍必须解析为不超过 500 个联系人，因为此次请求会为每个联系人调用一次 CRM。

{
  "contact_ids": [
    "aaaaaaaa-0000-4000-8000-000000000001",
    "aaaaaaaa-0000-4000-8000-000000000002"
  ]
}

响应

{
  "provider": "hubspot",
  "pushed": 1,
  "failed": 1,
  "results": [
    { "contact_id": "aaaaaaaa-0000-4000-8000-000000000001", "email": "[email protected]", "ok": true },
    { "contact_id": "aaaaaaaa-0000-4000-8000-000000000002", "email": "bad", "ok": false, "error": "invalid email" }
  ]
}

连接令牌无法继续刷新时，返回 409 Conflict，并提示“需要重新连接”。

Salesforce 同步

以下所有路由均使用 Salesforce 连接 ID 作为 :id，并限定在调用者组织范围内。各设置的作用见 Salesforce 指南。

方法	路径	组织权限	用途
GET	`/integrations/salesforce/:id/overview`	读取	健康状况、API 用量和额度、发件队列计数、上次拉取。`?checks=1` 还会探测连接用户可创建和编辑的内容
GET	`/integrations/salesforce/:id/settings`	读取	`{ settings, warmbly_fields, defaults }`
PUT	`/integrations/salesforce/:id/settings`	`manage_settings`	替换设置。整体写入文档，因此重试会收敛到相同状态
GET	`/integrations/salesforce/:id/metadata`	读取	Lead 和 Contact 字段、Lead Status 和 Lead Source 选项列表
GET	`/integrations/salesforce/:id/users?q=`	读取	有效 Salesforce 用户，用于负责人选择器
GET	`/integrations/salesforce/:id/list-views?object=Lead\|Contact`	读取	连接用户可见的列表视图
GET	`/integrations/salesforce/:id/campaigns?q=`	读取	Salesforce Campaigns（营销活动）
POST	`/integrations/salesforce/:id/import/preview`	`use_integrations`	输入 `{ source_kind, object, source_id }`，返回 `{ total, sample }`，不写入任何内容
GET	`/integrations/salesforce/:id/import-sources`	读取	已保存的导入及其最近结果
POST	`/integrations/salesforce/:id/import-sources`	`manage_settings`	保存导入，并启动首次运行
PATCH	`/integrations/salesforce/:id/import-sources/:sourceId`	`manage_settings`	编辑名称、`campaign_id`（`null` 可清除）、`category_ids`、`recurring`、`enabled`
POST	`/integrations/salesforce/:id/import-sources/:sourceId/run`	`use_integrations`	立即运行。已有运行时返回 `409 import_running`
DELETE	`/integrations/salesforce/:id/import-sources/:sourceId`	`manage_settings`	移除导入。已导入的联系人保留
GET	`/integrations/salesforce/:id/activity?status=&contact_id=&cursor=&limit=`	读取	活动日志，最新优先，结构为 `{ data, pagination }`
POST	`/integrations/salesforce/:id/activity/retry`	`manage_settings`	`{ ids }` 将指定的失败或跳过记录重新入队；不提供 ID 则将全部失败记录重新入队
POST	`/integrations/salesforce/:id/sync-now`	`use_integrations`	立即记录待处理活动，并拉取变更
GET	`/contacts/:id/salesforce`	`view_contacts`	联系人的 Salesforce 卡片：关联记录、负责人、状态、商机、近期 Tasks、同步状态
POST	`/contacts/:id/salesforce/sync`	`use_integrations`	`{ connection_id?, create_as? }`：匹配记录，或按 `lead` / `contact` 创建，并推送映射字段；返回卡片
DELETE	`/contacts/:id/salesforce/links/:linkId`	`use_integrations`	解除联系人与记录的关联。不修改 Salesforce 中的任何内容

“读取”权限可为 manage_settings 或 use_integrations。API 密钥需要 INTEGRATIONS 权限，但 GET /contacts/:id/salesforce 例外：它显示商机，需要 READ_CRM。

创建导入不会按请求去重：重试创建会保存第二个导入，但由于按邮件地址匹配联系人，其运行不会新增重复联系人。

列出会议预约（集成视图）

GET /integrations/bookings

返回最多 50 条近期预约会议。要获取会议页面的完整列表、筛选和分页，请使用 GET /meetings。

身份验证：权限范围 READ_CONTACTS · 组织权限 view_contacts。

响应

{
  "bookings": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "source": "calendly",
      "status": "booked",
      "invitee_email": "[email protected]",
      "invitee_name": "Lead Person",
      "event_name": "Intro call",
      "scheduled_for": "2026-06-15T16:00:00Z",
      "join_url": "https://meet.example/abc",
      "contact_id": "aaaaaaaa-0000-4000-8000-000000000001",
      "created_at": "2026-06-11T08:00:00Z",
      "updated_at": "2026-06-11T08:00:00Z"
    }
  ]
}

列出自动化流程

GET /automations

返回本组织的自动化流程，即可视化流程构建器中的流程。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

响应

{
  "automations": [
    {
      "id": "66666666-6666-4666-8666-666666666666",
      "organization_id": "1a2b3c4d-0000-0000-0000-000000000001",
      "name": "Notify on positive reply",
      "enabled": true,
      "trigger_event": "email.replied",
      "graph": { "nodes": [], "edges": [] },
      "created_at": "2026-06-01T09:00:00Z",
      "updated_at": "2026-06-01T09:00:00Z"
    }
  ]
}

创建自动化流程

POST /automations

创建新的自动化流程，包括触发事件，以及由条件和操作节点构成的图。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings。

请求体

字段	类型	必填	说明
`name`	string	是	显示名称。
`enabled`	boolean	否	是否在匹配事件发生时运行自动化流程。
`trigger_event`	string	是	触发流程的事件，例如 `email.replied`。
`filter`	object	否	可选的流程整体条件，例如意图或 `min_confidence`，应用于每个操作。
`graph`	object	是	流程图：`nodes` 和 `edges`。
`graph.nodes[]`	object	是	一个节点。`type` 为 `trigger`（恰好一个，ID 为 `trigger`）、`condition` 或 `action`。操作节点包含 `action`、可选的 `connection_id` 及 `config`；条件节点包含 `condition`。每个节点具有 `x` / `y` 画布坐标。
`graph.edges[]`	object	是	一条边：`source`、`target` 和 `when`；普通边为 `""`，条件节点的两条出边分别为 `true` / `false`。

{
  "name": "Notify on positive reply",
  "enabled": true,
  "trigger_event": "email.replied",
  "graph": {
    "nodes": [
      { "id": "trigger", "type": "trigger", "x": 0, "y": 0 },
      {
        "id": "a1",
        "type": "action",
        "action": "slack.notify",
        "connection_id": "9b2c1f7e-4d6a-4f2b-bb11-9d0e2a7c5f33",
        "config": { "channel": "#sales" },
        "x": 240,
        "y": 0
      }
    ],
    "edges": [
      { "id": "e1", "source": "trigger", "target": "a1", "when": "" }
    ]
  }
}

响应

201 Created，在 automation 键下返回创建的自动化流程。

{
  "automation": {
    "id": "66666666-6666-4666-8666-666666666666",
    "name": "Notify on positive reply",
    "enabled": true,
    "trigger_event": "email.replied",
    "graph": { "nodes": [ /* ... */ ], "edges": [ /* ... */ ] },
    "created_at": "2026-06-11T13:00:00Z",
    "updated_at": "2026-06-11T13:00:00Z"
  }
}

获取自动化流程

GET /automations/:id

返回单个自动化流程及其完整流程图。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

参数	位置	类型	说明
`id`	path	uuid	自动化流程 ID。

响应

{
  "automation": {
    "id": "66666666-6666-4666-8666-666666666666",
    "name": "Notify on positive reply",
    "enabled": true,
    "trigger_event": "email.replied",
    "graph": { "nodes": [ /* ... */ ], "edges": [ /* ... */ ] },
    "created_at": "2026-06-01T09:00:00Z",
    "updated_at": "2026-06-01T09:00:00Z"
  }
}

更新自动化流程

PATCH /automations/:id

替换自动化流程的名称、启用状态、触发器、筛选条件和流程图。请求体结构与创建载荷一致。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings。

参数	位置	类型	说明
`id`	path	uuid	自动化流程 ID。

请求体

字段与创建自动化流程相同。

{
  "name": "Notify on positive reply",
  "enabled": false,
  "trigger_event": "email.replied",
  "graph": { "nodes": [ /* ... */ ], "edges": [ /* ... */ ] }
}

响应

{
  "automation": {
    "id": "66666666-6666-4666-8666-666666666666",
    "name": "Notify on positive reply",
    "enabled": false,
    "trigger_event": "email.replied",
    "graph": { "nodes": [ /* ... */ ], "edges": [ /* ... */ ] },
    "updated_at": "2026-06-11T13:30:00Z"
  }
}

删除自动化流程

DELETE /automations/:id

移除自动化流程。如果仍被营销活动步骤引用，返回 409 Conflict。

身份验证：权限范围 INTEGRATIONS · 组织权限 manage_settings。

参数	位置	类型	说明
`id`	path	uuid	自动化流程 ID。

响应

{ "deleted": true }

测试自动化流程

POST /automations/:id/test

使用示例或提供的数据运行自动化流程，不产生副作用，并返回执行轨迹及每个操作的预览，用于构建器的“测试”按钮。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

参数	位置	类型	说明
`id`	path	uuid	自动化流程 ID。

请求体

请求体可选。省略时，服务器根据触发器构建示例事件。

字段	类型	必填	说明
`data`	object	否	用于评估流程的示例事件载荷。

{
  "data": { "email": "[email protected]", "intent": "positive" }
}

响应

试运行轨迹，以及解析后的事件数据。

{
  "trace": [
    { "node_id": "trigger", "type": "trigger", "status": "success" },
    {
      "node_id": "a1",
      "type": "action",
      "action": "slack.notify",
      "label": "Slack · #sales",
      "status": "success",
      "preview": { "channel": "#sales", "text": "Lead replied: [email protected]" }
    }
  ],
  "data": { "email": "[email protected]", "intent": "positive" }
}

列出自动化流程执行记录

GET /automations/:id/runs

返回自动化流程最近的运行历史，每次触发事件或手动启动对应一次运行，并包含各节点结果。

身份验证：权限范围 INTEGRATIONS，或具有组织权限 manage_settings 或 use_integrations 的会话。

参数	位置	类型	说明
`id`	path	uuid	自动化流程 ID。
`limit`	query	int	最多返回的运行数，默认 50。

响应

{
  "runs": [
    {
      "id": "77777777-7777-4777-8777-777777777777",
      "automation_id": "66666666-6666-4666-8666-666666666666",
      "trigger_event": "email.replied",
      "status": "success",
      "node_results": [
        { "node_id": "a1", "type": "action", "action": "slack.notify", "status": "success" }
      ],
      "started_at": "2026-06-10T15:00:00Z",
      "finished_at": "2026-06-10T15:00:01Z"
    }
  ]
}

搜索会议

GET /meetings

会议页面列表：包括已连接预约服务商 Calendly、Cal.com 的预约通话，以及手动记录的会议，支持按时间范围、状态和文本筛选，并使用偏移量分页。

身份验证：权限范围 READ_CONTACTS · 组织权限 view_contacts。

参数	位置	类型	说明
`timeframe`	query	string	取值为 `upcoming`、`past`，或留空表示全部。其他值返回 `400`。
`status`	query	string	精确状态筛选（`booked`、`rescheduled`、`canceled`、`completed`、`no_show`），留空表示任意状态。
`q`	query	string	匹配受邀人姓名、邮件地址或事件名称。
`limit`	query	int	每页数量，服务端限制在 1 至 200。
`cursor`	query	string	上一页 `pagination.next_cursor` 中的不透明游标。第一页省略。

响应

data 数组，加上标准 pagination 封装，包含不透明的 next_cursor 和准确的 total。内部使用偏移量分页，外部结构与其他列表一致。

{
  "data": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "source": "calendly",
      "status": "booked",
      "invitee_email": "[email protected]",
      "invitee_name": "Lead Person",
      "event_name": "Intro call",
      "scheduled_for": "2026-06-15T16:00:00Z",
      "join_url": "https://meet.example/abc",
      "contact_id": "aaaaaaaa-0000-4000-8000-000000000001",
      "contact_name": "Lead Person",
      "created_at": "2026-06-11T08:00:00Z",
      "updated_at": "2026-06-11T08:00:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "next_cursor": null,
    "has_more": false
  }
}

会议摘要

GET /meetings/summary

返回会议页面顶部和侧边栏显示的计数。

身份验证：权限范围 READ_CONTACTS · 组织权限 view_contacts。

响应

{
  "upcoming": 7,
  "today": 2,
  "total": 42,
  "canceled": 3
}

创建会议

POST /meetings

手动记录会议，来源为 manual。会议会与自动获取的 Calendly / Cal.com 预约一起出现在会议页面和联系人时间线中。通过明确提供且经过验证的 ID，或组织范围内的邮件地址匹配，确定关联联系人。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts。

请求体

字段	类型	必填	说明
`title`	string	否	会议标题。为空时默认 `Call`。
`invitee_name`	string	有条件必填	姓名或邮件地址至少提供一个。
`invitee_email`	string	有条件必填	姓名或邮件地址至少提供一个。服务端转为小写。
`scheduled_for`	string	是	RFC 3339 日期时间。必填，并进行验证。
`duration_minutes`	int	否	大于 0 时，用于设置结束时间。
`location`	string	否	自由文本地点。
`join_url`	string	否	视频会议或加入链接。
`contact_id`	string	否	明确指定要关联的联系人 ID，会验证其属于该组织。

{
  "title": "Intro call",
  "invitee_name": "Lead Person",
  "invitee_email": "[email protected]",
  "scheduled_for": "2026-06-15T16:00:00Z",
  "duration_minutes": 30,
  "join_url": "https://meet.example/abc"
}

响应

201 Created，在 meeting 键下返回创建的预约。

{
  "meeting": {
    "id": "55555555-5555-4555-8555-555555555555",
    "source": "manual",
    "status": "booked",
    "invitee_email": "[email protected]",
    "invitee_name": "Lead Person",
    "event_name": "Intro call",
    "scheduled_for": "2026-06-15T16:00:00Z",
    "end_time": "2026-06-15T16:30:00Z",
    "contact_id": "aaaaaaaa-0000-4000-8000-000000000001",
    "created_at": "2026-06-11T14:00:00Z",
    "updated_at": "2026-06-11T14:00:00Z"
  }
}

删除会议

DELETE /meetings/:id

移除会议预约，用于手动创建的会议。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts。

参数	位置	类型	说明
`id`	path	uuid	会议预约 ID。

响应

{ "deleted": true }

获取潜在客户同步所用的 Google 连接

GET /lead-sync/google/connection

报告组织是否已连接可用于潜在客户同步的 Google 账户，即隐藏的 google_sheets OAuth 连接。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts。

响应

{
  "connected": true,
  "connection": {
    "id": "88888888-8888-4888-8888-888888888888",
    "external_account_name": "[email protected]",
    "status": "connected"
  }
}

没有连接 Google 账户时，connected 为 false，connection 为 null。

获取电子表格元数据

POST /lead-sync/google/spreadsheet

返回电子表格标题和工作表标签，便于界面在列映射前显示工作表选择器。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts。

请求体

字段	类型	必填	说明
`connection_id`	string	是	`google_sheets` 连接 ID。
`sheet_id`	string	是	Google 电子表格 ID。

{
  "connection_id": "88888888-8888-4888-8888-888888888888",
  "sheet_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz"
}

响应

{
  "sheet_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "title": "Q2 Leads",
  "tabs": [
    { "title": "Inbound", "index": 0 },
    { "title": "Outbound", "index": 1 }
  ]
}

预览潜在客户同步

POST /lead-sync/google/preview

返回与导入预览相同结构的载荷，包括列、示例行、总行数、表头检测和建议映射，使前端可以直接复用联系人导入的列映射器。映射建议与文件导入预览完全一致，包括将表头匹配到工作区已有自定义字段。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts。

请求体

字段	类型	必填	说明
`connection_id`	string	是	`google_sheets` 连接 ID。
`sheet_id`	string	是	Google 电子表格 ID。
`tab_title`	string	否	要读取的工作表标签。默认第一个。

{
  "connection_id": "88888888-8888-4888-8888-888888888888",
  "sheet_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "tab_title": "Inbound"
}

响应

{
  "filename": "Q2 Leads / Inbound",
  "format": "google_sheets",
  "total_rows": 124,
  "columns": ["Email", "First name", "Company"],
  "has_header": true,
  "sample_rows": [
    ["[email protected]", "Jane", "Acme"]
  ],
  "suggested_mapping": [
    { "index": 0, "target": "email" },
    { "index": 1, "target": "first_name" },
    { "index": 2, "target": "company" }
  ]
}

列出潜在客户同步来源

GET /lead-sync/sources

列出本组织已保存的同步来源，可按营销活动或分群筛选。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts。

参数	位置	类型	说明
`campaign_id`	query	uuid	可选。仅返回以该营销活动为目标的来源。无效 ID 返回 `400`。
`segment_id`	query	uuid	可选。仅返回会将记录固定纳入该分群的来源。无效 ID 返回 `400`。可与 `campaign_id` 组合。

响应

data 数组，此列表不使用分页封装。

{
  "data": [
    {
      "id": "99999999-9999-4999-8999-999999999999",
      "provider": "google_sheets",
      "connection_id": "88888888-8888-4888-8888-888888888888",
      "sheet_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
      "sheet_title": "Q2 Leads",
      "tab_title": "Inbound",
      "has_header": true,
      "column_mapping": [
        { "index": 0, "target": "email" },
        { "index": 1, "target": "first_name" }
      ],
      "dedup": "update",
      "category_ids": [],
      "segment_ids": [],
      "subscribed_default": true,
      "status": "idle",
      "last_synced_at": "2026-06-10T12:00:00Z",
      "created_at": "2026-06-01T09:00:00Z",
      "updated_at": "2026-06-10T12:00:00Z"
    }
  ]
}

创建潜在客户同步来源

POST /lead-sync/sources

保存新的按需同步来源，将某个 Google Sheets 工作表绑定到 Warmbly 联系人导入器。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts。

请求体

字段	类型	必填	说明
`connection_id`	uuid	是	组织的 `google_sheets` OAuth 连接。
`sheet_id`	string	是	Google 电子表格 ID。
`sheet_title`	string	否	电子表格标题，用于显示。
`tab_title`	string	否	要读取的工作表标签。
`has_header`	boolean	否	第一行是否为表头。
`column_mapping`	array	是	列到目标的映射（与联系人导入结构相同）。保存时即验证，不等到下次同步；映射没有 `email` 列，或自定义字段名称不符合 Warmbly 要求时，此处返回 `400`。
`dedup`	string	否	冲突策略：`skip`、`update` 或 `create_duplicate`。
`target_campaign_id`	uuid	否	每次同步时，将新增或更新的潜在客户加入此营销活动。
`category_ids`	string[]	否	添加到已同步潜在客户的标签 ID。
`segment_ids`	string[]	否	每次运行时，每条同步记录都以手动纳入覆盖规则固定加入的分群。每个 ID 都必须属于组织内的分群，否则保存返回 `400`；若分群之后被删除，则运行时忽略该分群，不使整次运行失败。
`subscribed_default`	boolean	否	新联系人默认订阅状态。
`label`	string	否	友好名称。

{
  "connection_id": "88888888-8888-4888-8888-888888888888",
  "sheet_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "sheet_title": "Q2 Leads",
  "tab_title": "Inbound",
  "has_header": true,
  "column_mapping": [
    { "index": 0, "target": "email" },
    { "index": 1, "target": "first_name" }
  ],
  "dedup": "update",
  "target_campaign_id": null,
  "category_ids": [],
  "segment_ids": [],
  "subscribed_default": true,
  "label": "Q2 inbound leads"
}

响应

201 Created，直接返回创建的 LeadSyncSource 对象，结构与列表项相同。

{
  "id": "99999999-9999-4999-8999-999999999999",
  "provider": "google_sheets",
  "connection_id": "88888888-8888-4888-8888-888888888888",
  "sheet_id": "1AbCdEfGhIjKlMnOpQrStUvWxYz",
  "sheet_title": "Q2 Leads",
  "tab_title": "Inbound",
  "has_header": true,
  "column_mapping": [
    { "index": 0, "target": "email" },
    { "index": 1, "target": "first_name" }
  ],
  "dedup": "update",
  "category_ids": [],
  "segment_ids": [],
  "subscribed_default": true,
  "status": "idle",
  "created_at": "2026-06-11T15:00:00Z",
  "updated_at": "2026-06-11T15:00:00Z"
}

获取潜在客户同步来源

GET /lead-sync/sources/:id

返回单个已保存来源。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts。

参数	位置	类型	说明
`id`	path	uuid	来源 ID。

响应

直接返回 LeadSyncSource 对象，结构与列表项相同。

更新潜在客户同步来源

PATCH /lead-sync/sources/:id

编辑已保存来源。所有字段均可选，省略字段保留已存值。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts。

参数	位置	类型	说明
`id`	path	uuid	来源 ID。

请求体

字段	类型	必填	说明
`sheet_id`	string	否	新的电子表格 ID。
`sheet_title`	string	否	新标题。
`tab_title`	string	否	新的工作表标签。
`has_header`	boolean	否	是否有表头的开关。
`column_mapping`	array	否	替换现有映射。
`dedup`	string	否	冲突策略。
`target_campaign_id`	uuid	否	新的目标营销活动。
`clear_campaign`	boolean	否	为 `true` 时，取消目标营销活动。
`category_ids`	string[]	否	替换现有标签 ID 集合。
`segment_ids`	string[]	否	替换目标分群集合。未知 ID 返回 `400`；空数组清除全部目标。
`subscribed_default`	boolean	否	默认订阅状态。
`label`	string	否	新标签。

{
  "label": "Q2 inbound (paused)",
  "dedup": "skip",
  "clear_campaign": true
}

响应

更新后的 LeadSyncSource，直接返回对象。

删除潜在客户同步来源

DELETE /lead-sync/sources/:id

移除已保存来源。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts。

参数	位置	类型	说明
`id`	path	uuid	来源 ID。

响应

204 No Content.

立即运行指定来源的潜在客户同步

POST /lead-sync/sources/:id/sync

按需运行来源：读取电子表格，并通过联系人导入器插入或更新联系人。新行创建联系人，按邮件地址匹配已有联系人的行则更新。按邮件地址插入或更新本身具有幂等性，因此无需 Idempotency-Key 也可安全重试。

身份验证：权限范围 WRITE_CONTACTS · 组织权限 manage_contacts。

参数	位置	类型	说明
`id`	path	uuid	来源 ID。

响应

来源 ID，以及底层联系人导入的计数。

{
  "source_id": "99999999-9999-4999-8999-999999999999",
  "result": {
    "total": 124,
    "imported": 18,
    "updated": 100,
    "skipped": 6,
    "failed": 0,
    "started_at": "2026-06-11T16:00:00Z",
    "ended_at": "2026-06-11T16:00:04Z"
  }
}

集成、自动化流程与会议

本页目录