跳到內容
Imbrace SDK

工作流程

client.workflows 同時公開頻道自動化（v2/backend 路由）和流程引擎（CRUD 流程、執行、資料夾、連線、元件、MCP 伺服器、表格、邀請）。

請先初始化客戶端（請參閱安裝或快速入門）。如需將工作流程連接至 AI agent 的端到端逐步說明，請參閱完整流程指南 §2。

頻道自動化 — client.workflows

const { data: automations }    = await client.workflows.listChannelAutomation();
const { data: whatsappFlows }  = await client.workflows.listChannelAutomation({ channelType: "whatsapp" });

流程

CRUD

const { data: flows } = await client.workflows.listFlows();


const flow = await client.workflows.getFlow("flow_id");


const newFlow = await client.workflows.createFlow({
  displayName: "New Lead Notification",
  projectId: "project_id",
});


await client.workflows.deleteFlow("flow_id");

Flow Builder — buildFlow / addSteps

TypeScript SDK v1.4.0+。Python SDK 尚未提供 — 請使用 apply_flow_operation（見下文）。

buildFlow 透過一份宣告式 spec，一次呼叫即可建立完整流程 — 觸發條件加（可巢狀的）步驟。它會自動補上原始 flow-operation API 要求且容易遺漏的兩件事：為每個 piece 輸入補一條 propertySettings，以及為迴圈之後新增的 action 補 stepLocationRelativeToParent（缺少它，後續步驟會被靜默孤立）。步驟名稱自動遞增（step_1、step_2、…），除非步驟自行設定 name。

const flow = await client.workflows.buildFlow({
  displayName: "Qualify new leads",
  trigger: {
    kind: "piece",
    pieceName: "@activepieces/piece-webhook",
    pieceVersion: "0.1.24",
    triggerName: "catch_webhook",
    displayName: "Webhook",
  },
  steps: [
    {
      kind: "code",
      displayName: "Score lead",
      code: "export const code = async (inputs) => inputs;",
    },
    {
      kind: "loop",
      displayName: "For each lead",
      items: "{{trigger.leads}}",
      steps: [
        {
          kind: "piece",
          displayName: "Notify sales",
          pieceName: "@activepieces/piece-slack",
          pieceVersion: "0.5.1",
          actionName: "send_channel_message",
          input: { channel: "#sales" },
        },
      ],
    },
  ],
});

步驟類型：code（行內 TypeScript）、piece（piece 的 action）、loop（遍歷 items，可巢狀 steps）。觸發條件可以是 piece 觸發器或 { kind: "empty" }；省略則保留流程預設的空觸發器。

addSteps 以同樣的自動補全把步驟附加到既有流程。預設接在觸發器之後；傳入 parentStep / location 可接到其他位置（例如迴圈內部）。startIndex 延續步驟名稱計數器，確保名稱不重複：

await client.workflows.addSteps(
  flow.id,
  [{ kind: "code", displayName: "Log result", code: "export const code = async () => 'done';" }],
  { parentStep: "step_2", location: "INSIDE_LOOP", startIndex: 3 },
);

套用操作

await client.workflows.applyFlowOperation("flow_id", {
  type: "UPDATE_TRIGGER",
  request: {
    name: "trigger",
    type: "PIECE_TRIGGER",
    valid: true,
    displayName: "Webhook",
    settings: {
      pieceName: "@activepieces/piece-webhook",
      pieceVersion: "0.1.24",
      triggerName: "catch_webhook",
      input: {},
      propertySettings: {},
    },
  },
});

觸發流程

// 觸發後即忘
await client.workflows.triggerFlow("flow_id", {
  contactId: "contact_xxx",
  event: "lead_qualified",
});


// 等待結果
const result = await client.workflows.triggerFlowSync("flow_id", {
  contactId: "contact_xxx",
  event: "lead_qualified",
});

流程執行

const { data: runs } = await client.workflows.listRuns({ flowId: "flow_id", limit: 20 });
const run            = await client.workflows.getRun("run_id");

資料夾

const { data: folders }  = await client.workflows.listFolders();
const folder             = await client.workflows.getFolder("folder_id");
const newFolder          = await client.workflows.createFolder({ displayName: "CRM Automations", projectId: "project_id" });
const updated            = await client.workflows.updateFolder("folder_id", { displayName: "Updated Name" });
await client.workflows.deleteFolder("folder_id");

應用程式連線

const { data: connections } = await client.workflows.listConnections();
const connection            = await client.workflows.getConnection("connection_id");
await client.workflows.upsertConnection({
  name: "slack-integration",
  type: "OAUTH2",
  value: { access_token: "xoxb-xxx" },
});
await client.workflows.deleteConnection("connection_id");

元件

const pieces = await client.workflows.listPieces({ limit: 20 });

觸發條件

const status = await client.workflows.getTriggerRunStatus();
await client.workflows.testTrigger({ pieceName: "@activepieces/piece-webhook", flowId: "flow_id" });

表格與記錄

const { data: tables }  = await client.workflows.listTables();
const table             = await client.workflows.getTable("table_id");
const { data: records } = await client.workflows.listRecords({ tableId: "table_id" });

MCP 伺服器

const { data: servers } = await client.workflows.listMcpServers("project_id");
const server            = await client.workflows.getMcpServer("mcp_server_id");
const newServer         = await client.workflows.createMcpServer({ projectId: "project_id", name: "My MCP" });
await client.workflows.deleteMcpServer("mcp_server_id");
await client.workflows.rotateMcpToken("mcp_server_id");

使用者邀請

const { data: invitations } = await client.workflows.listInvitations({ type: "PROJECT" });
await client.workflows.deleteInvitation("invitation_id");