Chuyển đến nội dung
Imbrace SDK

Workflows

client.workflows hiển thị cả tự động hóa kênh (route v2/backend) và công cụ flow (CRUD flows, runs, folders, connections, pieces, MCP servers, tables, invitations).

Khởi tạo client trước (xem Cài đặt hoặc Quick Start). Để biết hướng dẫn từ đầu đến cuối kết nối workflow với AI agent, xem Hướng dẫn toàn diện §2.

Tự động hóa Kênh — client.workflows

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

Flows

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+. Chưa có trong Python SDK — dùng apply_flow_operation (bên dưới).

buildFlow tạo trọn một flow — trigger cùng các step (có thể lồng nhau) — trong một lệnh gọi duy nhất, từ một spec khai báo. Nó tự điền hai thứ mà flow-operation API gốc yêu cầu và rất dễ bỏ sót: một mục propertySettings cho mỗi input của piece, và stepLocationRelativeToParent cho action thêm sau một loop (thiếu nó, các step phía sau sẽ bị bỏ rơi một cách âm thầm). Tên step tự tăng (step_1, step_2, …) trừ khi step tự đặt 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" },
        },
      ],
    },
  ],
});

Các loại step: code (TypeScript inline), piece (một action của piece), và loop (lặp qua items, có thể lồng steps). Trigger là một piece trigger hoặc { kind: "empty" }; bỏ qua để giữ trigger rỗng mặc định của flow.

addSteps nối thêm step vào flow có sẵn với cùng cơ chế tự điền. Mặc định step gắn sau trigger; truyền parentStep / location để gắn vào chỗ khác (ví dụ bên trong loop). startIndex tiếp tục bộ đếm tên step để tên không bị trùng:

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 },
);

Áp dụng thao tác

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: {},
    },
  },
});

Kích hoạt flow

// Fire and forget
await client.workflows.triggerFlow("flow_id", {
  contactId: "contact_xxx",
  event: "lead_qualified",
});


// Chờ kết quả
const result = await client.workflows.triggerFlowSync("flow_id", {
  contactId: "contact_xxx",
  event: "lead_qualified",
});

Lượt chạy Flow

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

Thư mục

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");

Kết nối Ứng dụng

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");

Pieces

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

Triggers

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

Bảng & Bản ghi

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 Servers

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");

Lời mời Người dùng

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