Botpress Attio 集成实战指南：从 API Token 配置到记录读写全流程

本指南以 Botpress 开源仓库中 Attio CRM 集成的官方文档（hub.md）为主线，完整讲解如何将 Botpress 机器人接入 Attio 工作区数据，实现对象（Objects）与记录（Records）的列出、查询、创建和更新。读完本文，你将掌握 Attio API Token 的创建与作用域配置、集成安装步骤、7 个核心 Action 的输入输出参数，以及该集成在源码层的请求封装与数据处理原理，可直接在 Botpress 工作台中落地使用。

一、集成概述：机器人如何操作 Attio 工作区数据

Attio 集成（包名 @botpresshub/attio，版本 1.0.3，定义见 integration.definition.ts）允许 Botpress 机器人直接访问 Attio 工作区中的对象定义与业务记录。其核心能力是围绕 Attio API v2 封装了一套 CRUD 操作：

• 对象（Object）：Attio 中的业务实体，如 people、company，集成可列出全部对象、按 slug 或 UUID 查询单个对象；
• 记录（Record）：对象下的具体数据行，支持按过滤条件列出、按 ID 查询、创建新记录和更新已有记录；
• 属性（Attribute）：对象的字段定义，集成可列出某对象的全部属性及其选项，用于辅助解析记录值。

从实现上看，所有能力都由一个自建的 AttioApiClient（src/attio-api.ts）完成，它以 https://api.attio.com/v2 为基准地址，通过 Bearer Token 鉴权向 Attio 发起 HTTP 请求。集成将 API 错误统一包装为 RuntimeError 抛出，方便在 Botpress 工作流中捕获与处理。

二、配置：创建 Token 并完成接入

为确保工作区数据安全，本集成不使用 OAuth 而是使用 API Token 鉴权。你需要在 Attio 侧创建一个 Token，粘贴到 Botpress 的集成配置中。官方文档给出的步骤如下：

1. 在 Attio 中创建一个 API Token，并授予以下三个作用域（Scope）：
   • object_configuration:read —— 用于列出和读取对象定义；
   • record:read —— 用于列出和读取记录；
   • record:write —— 用于创建和更新记录。
2. 在 Botpress 中为你的机器人添加 Attio 集成。
3. 将 API Token 粘贴到集成配置的 Access Token 字段并保存。

完成以上三步后，集成会调用 Attio 的 /v2/self 端点验证 Token 的有效性与访问权限（对应源码中的 testConnection() 方法，见 attio-api.ts）。

从源码角度补充说明配置项：集成仅有一个配置字段，即 integration.definition.ts 中定义的 accessToken（字符串类型，标题为 "Access Token"）。所有 Action 在执行时都从 ctx.configuration.accessToken 读取该值并实例化 API 客户端，因此 Token 保存后无需在流程中重复传入。

三、七个核心 Action 详解

集成共暴露 7 个可被 Botpress 流程调用的 Action，其输入输出 Schema 定义在 definitions/actions.ts，实现位于 src/actions/record.ts 与 src/actions/objects.ts。下文按数据维度分组说明。

3.1 记录操作：List / Get / Create / Update

List Records（列出记录）

• 输入：
  • object（必填，字符串）：对象 slug 或 UUID，例如 people；
  • filter（可选，对象数组）：[{ attribute, value }]，按属性过滤，语法遵循 Attio 官方的 Shorthand Filtering 指南；
  • sorts（可选，对象数组）：[{ direction: 'asc' | 'desc', attribute, field }]，排序指令，遵循 Attio sorting 指南；
  • limit（可选，数字）：最大返回记录数，默认 500；
  • offset（可选，数字）：跳过的记录数，默认 0，用于分页。
• 输出：data 为记录数组，每条记录含 id、created_at（RFC3339 时间戳）、web_url（Attio UI 中的记录 URL）和 values（属性 slug 或 ID 到值的映射，值可为单值或数组）。

从源码看，该 Action 在调用 listRecords 前会把 filter 数组通过 _mapValues 折叠为 { attribute: value } 映射对象（见 record.ts），再以 POST 请求发往 /objects/{object}/records/query 端点（见 attio-api.ts）。

Get Record（获取单条记录）

• 输入：object（必填）与 id（必填，含 record_id 记录 UUID）；
• 输出：单条记录数据（id、web_url、values、created_at）。

对应 HTTP 调用为 GET /objects/{object}/records/{recordId}。

Create Record（创建记录）

• 输入：
  • object（必填）：目标对象 slug 或 UUID；
  • data.values（必填，对象数组）：[{ attribute, value }]，其中 attribute 为 Attio 接受的属性 slug 或 ID，value 为要设置的值。
• 输出：创建成功的完整记录。

实现上会先把 values 数组转为映射对象，然后 POST /objects/{object}/records。

Update Record（更新记录）

• 输入：object、id.record_id 以及 data.values（[{ attribute, value }]，语义为 upsert）；
• 输出：更新后的记录。

对应 PUT /objects/{object}/records/{recordId}。

3.2 对象与属性操作：List / Get / List Attributes

List Objects（列出工作区全部对象）

• 输入为空；输出 data 为对象数组，每个对象包含 id、api_slug、singular_noun、plural_noun、created_at 等可选字段。对应 GET /objects。

Get Object（查询单个对象）

• 输入：object（slug 或 UUID）；输出该对象的定义信息。对应 GET /objects/{object}。

List Attributes（列出对象属性）

• 输入：object；输出 data 为属性数组，每个属性包含 title、description、api_slug、type、slug 以及可选的 options（下拉选项列表，含 id、label、name、value、title、slug）。对应 GET /objects/{object}/attributes。

属性列表在记录读取流程中承担重要角色（见下文第四节），是理解该集成"人性化输出"设计的关键入口。

四、源码级原理：请求封装与记录值人性化

4.1 统一的请求封装与错误处理

AttioApiClient（src/attio-api.ts）内部维护 _accessToken 与 _baseUrl，所有请求经 _makeRequest 统一处理：自动附加 Authorization: Bearer <token> 与 Content-Type: application/json 请求头；仅对 POST/PUT/PATCH 请求序列化 body；响应非 2xx 时抛出 Attio API Error: <status> <statusText> - <body> 形式的错误。各 Action 捕获异常后包装为 RuntimeError 抛出，Botpress 流程可用标准错误节点处理失败分支。

4.2 记录值的"人性化"转换

这是一个值得注意的实现细节：在 List Records 和 Get Record 的执行路径中，集成并不会直接返回 Attio 原始记录，而是先调用 listAttributes 获取对象的属性元数据，再做两层转换（见 record.ts）：

1. 属性 ID → slug 映射：_buildAttributeMaps 遍历属性列表，建立 idToSlug 映射（兼容新式对象 ID 结构与旧式字符串 ID），把记录 values 中冗长的属性 ID 键替换为可读的 slug；
2. 选项 ID → 标签映射：对带 options 的属性建立 slugToOptionLabelById 映射，_mapValueUsingOptions 会把记录值中的选项 ID（字符串或 { id } 对象）替换为其 label，多选数组则逐个替换。

这样机器人拿到的记录值就是"人类可读"的标签与字段名，而非一串 UUID，便于直接在对话中展示。

4.3 连接验证端点

配置完成后，集成通过 GET /self（testConnection()）验证 Token 可用性，这正是官方文档第 20 行所述"integration will validate access using Attio's /v2/self endpoint"的源码落点。

五、Webhook 事件处理（进阶）

除了主动查询，集成还具备被动接收能力。从 src/setup/handler.ts 与 src/schemas.ts 可看到，集成实现了 Botpress 的 webhook handler：对收到的 payload 先做 JSON 解析，再经 webhookPayloadSchema（包含 webhook_id 与 events 数组）校验，随后按 event_type 分发到 record.created、record.updated、record.deleted 三个事件处理函数；非法 JSON 或校验失败会返回 400 并记录错误日志，未知事件类型则记录 warn 并跳过。这为"Attio 数据变化实时驱动机器人"的场景提供了实现基础，事件定义见 definitions/events.ts。

六、使用注意事项

结合官方文档 Notes 与源码实现，实践中有几点需要留意：

• 过滤语法：List Records 的 filter 参数需按 Attio 官方 Shorthand Filtering 指南构造 { attribute, value } 数组，集成只做透传与映射转换，不校验过滤条件本身的合法性；
• 属性标识：创建/更新记录时，values 中的 attribute 使用 Attio 接受的属性 slug 或 ID，集成不做额外校验，错误会以 RuntimeError 形式返回；
• 默认分页：limit 未指定时默认 500 条，超出部分需用 offset 分页获取；
• 返回值的可读性：记录读取类 Action 返回的 values 键名与选项标签已经过人性化转换，与 Attio API 原始响应存在差异，设计 Bot 流程时需以此为准。

七、从零到一：在机器人流程中使用该集成

典型的使用链路如下：先用 List Objects 让用户选择目标对象（如 people），再用 List Attributes 展示可选字段，随后用 List Records（配合 filter）检索符合条件的记录，最后用 Create Record / Update Record 落库。整个过程无需编写自定义 HTTP 调用代码，直接在 Botpress 可视化流程中拖拽 Action 并映射输入输出即可。

相关文件速查：

• 集成定义与配置 Schema：integration.definition.ts
• Action 输入输出 Schema：definitions/actions.ts
• API 客户端实现：src/attio-api.ts
• Action 业务实现：src/actions/record.ts、src/actions/objects.ts
• Webhook 处理：src/setup/handler.ts
• 官方集成文档：hub.md