跳转到内容
Imbrace SDK

数据面板

面板是 CRM 管道的核心数据存储 — 线索、交易、任务或任何结构化数据。创建 AI 代理时在 board_ids 中传入面板 ID，以让代理有权访问这些数据 — 参见完整流程指南 §4。

首先初始化客户端（参见安装或快速入门）。

面板增删改查

const { data: boards } = await client.boards.list();
const board = await client.boards.get("board_id");


const newBoard = await client.boards.create({ name: "Enterprise Leads" });
await client.boards.update("board_id", { name: "Enterprise Leads 2025" });
await client.boards.delete("board_id");

重新排序

await client.boards.reorder({ order: ["board_id_1", "board_id_2", "board_id_3"] });

导入 / 导出

// CSV 导入 (multipart/form-data)
const formData = new FormData();
formData.append("file", csvFile);
const result = await client.boards.importCsv("board_id", formData);


// Excel 导入
const excelForm = new FormData();
excelForm.append("file", excelFile);
await client.boards.importExcel("board_id", excelForm);


// 导入进度
const progress = await client.boards.getImportProgress("board_id");


// CSV 导出
const csv = await client.boards.exportCsv("board_id");


// 通过邮件导出 CSV
await client.boards.exportCsvViaMail("board_id", { email: "user@example.com" });

注意：exportCsvViaMail 仅 TypeScript 可用。

条目

const { data: items } = await client.boards.listItems("board_id", { limit: 100 });
const item = await client.boards.getItem("board_id", "item_id");


// createItem 使用 { fields: [{ board_field_id, value }] }
const lead = await client.boards.createItem("board_id", {
  fields: [
    { board_field_id: "name_field_id",   value: "Acme Corp" },
    { board_field_id: "status_field_id", value: "new" },
    { board_field_id: "value_field_id",  value: 50000 },
  ],
});


// updateItem 使用 { data: [{ key, value }] } — 注意是 `key`，不是 `board_field_id`
await client.boards.updateItem("board_id", lead._id, {
  data: [{ key: "status_field_id", value: "qualified" }],
});


await client.boards.deleteItem("board_id", "item_id");
await client.boards.bulkDeleteItems("board_id", { ids: ["item_1", "item_2", "item_3"] });

冲突检测

const { is_conflicted } = await client.boards.checkConflict("board_id", "item_id", { version: 2 });

链接条目（相关面板）

// 从另一个面板获取相关条目
const related = await client.boards.getRelatedItems("board_id", "item_id", "related_board_id");


// 按类型获取链接面板条目 (Opportunities / Tasks)
const linked = await client.boards.getLinkedBoardItems("contact_board_id", "item_id", "Opportunities");


// 链接和取消链接
await client.boards.linkItems("board_id", "item_id", "related_board_id", { related_item_ids: ["other_item_id"] });
await client.boards.unlinkItems("board_id", "item_id", "related_board_id", { related_item_ids: ["other_item_id"] });

搜索

const results = await client.boards.search("board_id", { q: "enterprise" });

字段

const field = await client.boards.createField("board_id", {
  name: "Deal Value",
  type: "Number",
});
await client.boards.updateField("board_id", field._id, { name: "Contract Value" });
await client.boards.deleteField("board_id", field._id);


// 重新排序和批量更新
await client.boards.reorderFields("board_id", { fields: ["field_id_1", "field_id_2"] });
await client.boards.bulkUpdateFields("board_id", { fields: [{ _id: "field_1", name: "Updated" }] });

分段

// listSegments 直接返回 BoardSegment[]（没有 { data } 包装）
const segments = await client.boards.listSegments("board_id");
const segment = await client.boards.createSegment("board_id", {
  name: "High Value Leads",
  filter: {},
});
await client.boards.updateSegment("board_id", segment._id, { name: "VIP Leads" });
await client.boards.deleteSegment("board_id", segment._id);

知识中心 — 文件夹

// 搜索
const folders = await client.boards.searchFolders({ q: "contracts" });


// 增删改查
const folder = await client.boards.getFolder("folder_id", { recursive: true });
const newFolder = await client.boards.createFolder({ name: "Contracts", parent_id: "parent_id" });
await client.boards.updateFolder("folder_id", { name: "Renamed" });
await client.boards.deleteFolders({ ids: ["folder_id_1", "folder_id_2"] });


// 内容（文件夹元数据 + 子文件夹 + 文件）
const contents = await client.boards.getFolderContents("folder_id");

知识中心 — 文件

// 搜索和增删改查
const files = await client.boards.searchFiles({ folderId: "folder_id" });
const file = await client.boards.getFile("file_id");
const newFile = await client.boards.createFile({ name: "report.pdf", folder_id: "folder_id" });
await client.boards.updateFile("file_id", { name: "renamed.pdf" });
await client.boards.deleteFiles({ ids: ["file_id_1", "file_id_2"] });


// 上传和下载
const uploaded = await client.boards.uploadFile(formData);
const response = await client.boards.downloadFile("file_id");

面板文件

上传附加到面板记录的文件（非知识中心）。

const formData = new FormData();
formData.append("file", file);
const { url } = await client.boards.uploadBoardFile(formData);


// 备选端点
const { url: url2 } = await client.boards.uploadBoardFileV2(formData);

AI 功能

// AI 生成的标签
const { tags } = await client.boards.generateAiTags({ text: "Enterprise deal with Acme Corp" });


// 链接预览
const preview = await client.boards.getLinkPreview("https://example.com");

外部驱动器

用于知识中心的 OneDrive / Google Drive 集成。

// 发起 OAuth 流程
const { auth_url } = await client.boards.initiateDriveAuth("onedrive");


// 列出远程文件夹和文件
const folders = await client.boards.listDriveFolders("onedrive");
const files = await client.boards.listDriveFiles("onedrive", { folder_id: "remote_folder_id" });


// 下载远程文件
const response = await client.boards.downloadDriveFile("onedrive", { file_id: "remote_file_id" });


// 会话状态（仅 OneDrive）
const { status } = await client.boards.getOneDriveSessionStatus();