API 參考

所有 API 請求使用 X-Api-Key 標頭中的 API 金鑰進行認證。

取得您的 API 金鑰

1. 前往管理面板中的設定 → API 金鑰
2. 點擊建立 API 金鑰並為其命名
3. 立即複製金鑰 — 它只會顯示一次
4. 安全儲存（環境變數、密鑰管理器）

發送請求

在每個請求中包含金鑰：

curl -H "X-Api-Key: tak_your_key_here" \
     https://api.enuchat.com/api/v1/tenant-api/widgets

所有回應均為 JSON。成功回應包含 data 欄位。錯誤包含 error 欄位，其中有 code 和 message。

安全性：API 金鑰在資料庫中以 SHA-256 雜湊儲存。我們絕不儲存原始金鑰。像對待密碼一樣對待您的金鑰 — 不要提交到程式碼或公開分享。

GET /widgets

列出您帳號的所有小工具。

回應

{'{'}
  "data": [
{'{'}
      "id": "019d19c6-7e0b-...",
      "name": "Main Website Chat",
      "isActive": true,
      "aiEnabled": true,
      "translationEnabled": true,
      "primaryColor": "#2563eb",
      "position": "bottom-right"
    }
  ]
}

GET /conversations

列出對話，按最新訊息排序。

查詢參數

範例

curl -H "X-Api-Key: tak_..." \
     "https://api.enuchat.com/api/v1/tenant-api/conversations?status=open&limit=10"

回應

{'{'}
  "data": [
{'{'}
      "id": "019d6724-000e-...",
      "widgetId": "019d19c6-7e0b-...",
      "visitorId": "v-abc123",
      "visitorName": "John",
      "visitorEmail": "john{'@'}example.com",
      "visitorLanguage": "en",
      "status": "open",
      "assignedTo": null,
      "lastMessageAt": "2026-04-11T14:30:00+00:00",
      "startedAt": "2026-04-11T14:25:00+00:00"
    }
  ]
}

GET /conversations/{'{'}id}

取得對話及所有訊息。

查詢參數

回應

{'{'}
  "data": {'{'}
    "id": "019d6724-000e-...",
    "visitorLanguage": "en",
    "status": "open",
    "messages": [
{'{'}
        "id": "019d6724-1234-...",
        "role": "visitor",
        "content": "Hello, how much does it cost?",
        "contentLanguage": "en",
        "translatedContent": "Cześć, ile to kosztuje?",
        "translatedLanguage": "pl",
        "isAutoReply": false,
        "createdAt": "2026-04-11T14:25:30+00:00"
      },
{'{'}
        "id": "019d6724-5678-...",
        "role": "ai",
        "content": "Our plans start at €19/month...",
        "isAutoReply": true,
        "createdAt": "2026-04-11T14:25:32+00:00"
      }
    ]
  }
}

POST /conversations/{'{'}id}/messages

向對話發送訊息。訊息會透過聊天小工具即時傳送給訪客。

請求主體

{'{'}
  "content": "Thanks for reaching out! We'll process your request.",
  "role": "system"
}

回應（201 Created）

{'{'}
  "data": {'{'}
    "id": "019d6725-abcd-...",
    "role": "system",
    "content": "Thanks for reaching out!",
    "createdAt": "2026-04-11T14:35:00+00:00"
  }
}

PATCH /conversations/{'{'}id}

更新對話的狀態或分配。

請求主體

{'{'}
  "status": "closed"
}

GET /billing/balance

取得您目前的方案和額度餘額。

回應

{'{'}
  "data": {'{'}
    "plan": "pro",
    "creditBalance": 4500000,
    "totalCreditsAdded": 10000000
  }
}

CRM 整合

輪詢新對話並將訪客資料（姓名、電子郵件、語言）同步到您的 CRM。使用對話 ID 作為外部參考。

自動化後續跟進

對話關閉後，透過 API 發送後續訊息：「感謝您的聊天！還有什麼我們可以幫助的嗎？」

webhook 替代方案

在外發 webhook 可用之前，定期輪詢對話 endpoint 以偵測新訊息或狀態變更。

批次操作

關閉超過 7 天的所有對話、根據外部邏輯將對話分配給客服，或匯出對話歷史用於分析。