跳到內容
Imbrace SDK

資源參考

本頁列出 SDK 公開的每個資源命名空間以及每個命名空間中最常用的呼叫。首先初始化 client（參閱安裝或快速入門）。以下所有程式碼片段均假設 client 是已初始化的實例。

端到端演練請參閱完整流程指南。

助手 — chatAi / chat_ai

管理 AI 助手（CRUD）、執行 OpenAI 相容的 completions，以及處理 document/file。該命名空間也涵蓋 Knowledge Hub 資料夾和 knowledge bases。

助手 CRUD

// 列出帳戶中的所有助手
const assistants = await client.chatAi.listAssistants();


// 取得單一助手
const assistant = await client.chatAi.getAssistant("9f77692f-33d0-436a-8138-2efb268838e6");


// 建立 — provider_id 和 model_id 為必填
const created = await client.chatAi.createAssistant({
  name: "Support Bot",
  workflow_name: "support_bot_v1",
  provider_id: "system",
  model_id: "gpt-4o",
  description: "處理一級支援問題",
});


// 更新 — 更新時 workflow_name 也是必填
const updated = await client.chatAi.updateAssistant(created.id, {
  name: "Support Bot v2",
  workflow_name: "support_bot_v1",
});


// 僅更新系統指令
await client.chatAi.updateAssistantInstructions(
  created.id,
  "您是一位樂於助人的支援代理。",
);


await client.chatAi.deleteAssistant(created.id);

Completions

const response = await client.chatAi.chat({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "您是 CRM 助手。" },
    { role: "user", content: "摘要這位客戶的備註：..." },
  ],
});
console.log(response.choices[0].message.content);

模型

const models = await client.chatAi.listModels();

檔案處理

// 從 PDF 或圖片中擷取結構化資料
const result = await client.chatAi.extractFile({
  modelName: "gpt-4o",
  url: "https://example.com/invoice.pdf",
  organizationId: "org_xxx",
});

持久化聊天工作階段（Python）

chat    = client.chat_ai.create_chat({"title": "Support Chat"})
history = client.chat_ai.list_chats()
client.chat_ai.delete_chat(chat["id"])

Knowledge Hub — 資料夾和 Knowledge Bases

資料夾組織 knowledge bases。建立助手時在 folder_ids 中傳入資料夾 ID — 參閱完整流程指南 §3。

// 資料夾
const folders = await client.chatAi.listFolders();
const folder  = await client.chatAi.createFolder({ name: "Q1 報告" });
await client.chatAi.updateFolder(folder.id, { name: "Q1 2025 報告" });
await client.chatAi.deleteFolder(folder.id);


// Knowledge bases
const all = await client.chatAi.listKnowledge();
const kb  = await client.chatAi.getKnowledge("kb_id");
const created = await client.chatAi.createKnowledge({
  name: "支援文件",
  folderId: folder.id,
});
await client.chatAi.deleteKnowledge(created.id);

OpenAI 相容 AI 服務 — client.ai（Python）

原始 OpenAI 風格的 completions、streaming 和 embeddings。TypeScript SDK 目前不公開此命名空間 — 請改用助手 → Completions。

# 單次 completion
response = client.ai.complete(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "您是 CRM 助手。"},
        {"role": "user",   "content": "摘要這位客戶的備註：..."},
    ],
    temperature=0.7,
)
print(response["choices"][0]["message"]["content"])


# 串流傳輸
for chunk in client.ai.stream(
    model="gpt-4o",
    messages=[{"role": "user", "content": "為這個 lead 起草跟進郵件。"}],
):
    print(chunk["choices"][0]["delta"].get("content", ""), end="", flush=True)


# Embeddings
result = client.ai.embed(
    model="text-embedding-ada-002",
    input=["客戶投訴計費問題", "計費問題升級"],
)

AI Agent — aiAgent / ai_agent

與助手的串流聊天、knowledge base embedding 管理、parquet 資料和終端用戶聊天工作階段。參閱 AI Agent 取得完整的方法參考。最常用的入口是 streamChat。

串流聊天（SSE）

const sessionId = crypto.randomUUID();


const response = await client.aiAgent.streamChat({
  id: sessionId,
  assistant_id: "asst_xxx",
  organization_id: "org_xxx",
  messages: [{ role: "user", content: "本季度哪些交易已成交？" }],
});


const reader = response.body!.getReader();
const decoder = new TextDecoder();


while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  for (const line of text.split("\n")) {
    if (!line.startsWith("data: ")) continue;
    const raw = line.slice(6).trim();
    if (raw === "[DONE]") break;
    try {
      const event = JSON.parse(raw);
      if (event.type === "text-delta") process.stdout.write(event.textDelta);
    } catch {}
  }
}

提示建議

const suggestions = await client.aiAgent.getAgentPromptSuggestion("asst_xxx");

Embedding 檔案（Knowledge Base）

const files = await client.aiAgent.listEmbeddingFiles();
const file  = await client.aiAgent.getEmbeddingFile("file_id");


const classified = await client.aiAgent.classifyFile({
  url: "https://example.com/product-catalog.pdf",
  mime_type: "application/pdf",
});


await client.aiAgent.updateEmbeddingFileStatus("file_id", { status: "active" });
await client.aiAgent.deleteEmbeddingFile("file_id");

Parquet 資料

const job = await client.aiAgent.generateParquet({
  assistant_id: "asst_xxx",
  data: [{ id: "1", name: "Acme Corp", revenue: 120000 }],
});


const parquetFiles = await client.aiAgent.listParquetFiles();
await client.aiAgent.deleteParquetFile("file_id");

終端用戶聊天客戶端

const chat = await client.aiAgent.createClientChat({
  id: crypto.randomUUID(),
  assistantId: "asst_xxx",
  organizationId: "org_xxx",
  userId: "user_xxx",
  selectedVisibilityType: "private",
  message: {
    id: crypto.randomUUID(),
    role: "user",
    content: "您好，我需要協助。",
    createdAt: new Date().toISOString(),
    parts: [{ type: "text", text: "您好，我需要協助。" }],
  },
});


const clientChats = await client.aiAgent.listClientChats();
const messages    = await client.aiAgent.listClientMessages(chat.id);
await client.aiAgent.deleteClientChat(chat.id);

工作流程 — Activepieces (client.activepieces，TypeScript)

完整 lifecycle（create → publish → trigger），參閱完整流程指南 §2。

Flows

const { data: flows } = await client.activepieces.listFlows();
const flow = await client.activepieces.getFlow("flow_id");
const newFlow = await client.activepieces.createFlow({
  displayName: "新 Lead 通知",
  folderId: "folder_id",
});
await client.activepieces.deleteFlow("flow_id");

觸發 Flow

// 非同步觸發
await client.activepieces.triggerFlow("flow_id", {
  contactId: "contact_xxx",
  event: "lead_qualified",
});


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

Runs、資料夾、連線、表

const { data: runs }     = await client.activepieces.listRuns({ flowId: "flow_id", limit: 20 });
const run                = await client.activepieces.getRun("run_id");
const { data: folders }  = await client.activepieces.listFolders();
const folder             = await client.activepieces.createFolder({ displayName: "CRM 自動化" });
const { data: connections } = await client.activepieces.listConnections();
const { data: tables }   = await client.activepieces.listTables();
const { data: records }  = await client.activepieces.listRecords({ tableId: "table_id" });

看板 & 項目 — client.boards

看板是 CRM pipeline 的核心資料儲存。參閱完整流程指南 §4。

看板 CRUD

const { data: boards } = await client.boards.list();
const board = await client.boards.get("board_id");
const newBoard = await client.boards.create({ name: "企業 Leads" });
await client.boards.update("board_id", { name: "企業 Leads 2025" });
await client.boards.delete("board_id");

項目

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


const lead = await client.boards.createItem("board_id", {
  fields: { name: "Acme Corp", status: "new", value: 50000 },
});


await client.boards.updateItem("board_id", lead.id, {
  fields: { status: "qualified" },
});


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

搜尋

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

欄位、區段和匯出

// 欄位
const field = await client.boards.createField("board_id", {
  name: "交易價值",
  type: "number",
});
await client.boards.updateField("board_id", field.id, { name: "合約價值" });
await client.boards.deleteField("board_id", field.id);


// 區段
const { data: segments } = await client.boards.listSegments("board_id");
const segment = await client.boards.createSegment("board_id", {
  name: "高價值 Leads",
  filters: [{ field: "value", op: "gt", value: 10000 }],
});


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

聯絡人 — client.contacts

const { data: contacts } = await client.contacts.list({ limit: 50 });
const contact = await client.contacts.get("contact_id");


await client.contacts.update("contact_id", {
  name: "Alice B.",
  email: "alice@example.com",
  phone: "+84901234567",
});


const activity = await client.contacts.getActivity("contact_id");
const comments = await client.contacts.getComments("contact_id");
const files    = await client.contacts.getFiles("contact_id");

對話 — client.conversations

// 搜尋
const { data: convs } = await client.conversations.search({
  businessUnitId: "bu_xxx",
  q: "support",
  limit: 20,
});


// 未處理的對話
const { data: open } = await client.conversations.getOutstanding({
  businessUnitId: "bu_xxx",
  limit: 50,
});


// 指派
await client.conversations.assignTeamMember({
  conversation_id: "conv_xxx",
  user_id: "user_xxx",
});


// 更新狀態
await client.conversations.updateStatus({
  conversation_id: "conv_xxx",
  status: "resolved",
});

訊息 — client.channel、client.messages

const channels = await client.channel.list();


await client.messages.send("conversation_id", {
  parts: [{ type: "text", text: "您好，有什麼可以幫您？" }],
});


const msgs = await client.messages.list("conversation_id");
await client.channel.markRead("conversation_id");

頻道自動化工作流程 — client.workflows（Python）

automations    = client.workflows.list_channel_automation().get("data", [])
whatsapp_flows = client.workflows.list_channel_automation(channel_type="whatsapp")

行銷活動 & 觸點 — client.campaign（Python）

# Campaign CRUD
campaigns = client.campaign.list().get("data", [])
campaign  = client.campaign.get("campaign_id")
new_camp  = client.campaign.create({"name": "Q2 推廣", "type": "email"})
client.campaign.delete("campaign_id")


# 觸點
touchpoints = client.campaign.list_touchpoints().get("data", [])
tp = client.campaign.get_touchpoint("touchpoint_id")


client.campaign.create_touchpoint({
    "campaign_id": "campaign_id",
    "type":        "email",
    "delay_days":  3,
})
client.campaign.update_touchpoint("touchpoint_id", {"delay_days": 5})
client.campaign.delete_touchpoint("touchpoint_id")


# 儲存前驗證觸點設定
result = client.campaign.validate_touchpoint({"type": "email", "template_id": "tpl_xxx"})

訊息建議 — client.message_suggestion（Python）

suggestions = client.message_suggestion.get_suggestions({
    "conversation_id": "conv_xxx",
    "limit": 3,
})

預測 — client.predict（Python）

result = client.predict.predict({
    "model": "lead_score_v1",
    "input": {"company_size": 200, "industry": "saas", "mrr": 5000},
})
print(result["score"])   # 0.87