> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usereplier.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Replier API

> 在帳戶設定建立 API 金鑰，從自己的程式呼叫 Replier REST API，並處理錯誤、重試與請求次數限制。

Replier API 讓你自己的程式或自動化工具做到在 Replier 裡能做的事：列出工作區、社群帳號與貼文，建立和修改自動化，讀取成效與聯絡人，傳送補回覆或單次自動化的回覆。若要在 ChatGPT、Claude 或其他 AI 工具使用 Replier，請改用 [AI 連線](https://docs.usereplier.com/zh-TW/guides/ai-connections.md)。

[API 參考文件](https://docs.usereplier.com/api-reference/workspaces/list-workspaces.md)（英文）列出每個端點的參數與回應。

## 建立 API 金鑰

1. 在 Replier 開啟帳戶選單，選擇「**帳戶設定 → 整合**」。
2. 在「**API 金鑰**」選擇「**建立 API 金鑰**」。
3. 輸入之後認得出來的名稱，選擇權限，再按「**建立金鑰**」。
4. 複製金鑰。Replier 只會顯示這一次。

拿到金鑰的人都能以你的身分使用 Replier，所以別把它放進會分享的程式碼或瀏覽器裡。金鑰外洩時，刪除它並建立新的。

只能查看資料的金鑰，嘗試修改時會被拒絕。也能修改的金鑰可以建立、修改、開啟或關閉、刪除自動化，儲存預設訊息文字，調整下一篇貼文佇列的順序，上傳回覆照片，以及傳送補回覆與單次自動化的回覆。無論哪一種，金鑰都以你在各工作區的角色運作，權限不會超過你本人。

## 送出請求

把金鑰當作 bearer token，送到 `https://api.usereplier.com/v1`：

```bash theme={null}
curl https://api.usereplier.com/v1/workspaces \
  -H "Authorization: Bearer $REPLIER_API_KEY"
```

其他請求都在某個工作區內進行。使用上面清單裡的工作區 `id`：

```bash theme={null}
curl https://api.usereplier.com/v1/workspaces/$WORKSPACE_ID/accounts \
  -H "Authorization: Bearer $REPLIER_API_KEY"
```

會修改資料的請求以 JSON 傳送：

```bash theme={null}
curl -X PATCH https://api.usereplier.com/v1/workspaces/$WORKSPACE_ID/automations/$AUTOMATION_ID \
  -H "Authorization: Bearer $REPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

透過 API 建立或修改的自動化，限制和在 Replier 裡相同：最多 24 個目標、三個按鈕、一張選用照片，訊息流程限 Studio 工作區。

## 錯誤

被拒絕的請求會回傳 HTTP 狀態碼和這樣的內容：

```json theme={null}
{
  "error": {
    "code": "AUTOMATION_NOT_FOUND",
    "message": "Automation not found in this workspace."
  }
}
```

`code` 不會變；`message` 是英文說明，措辭可能調整。有些錯誤會附上其他欄位，例如已經使用你所選貼文的自動化。

| 狀態碼 | 意思 |
| - | - |
| 400 | 請求內容有誤。`INVALID_REQUEST` 的 message 會指出是哪個欄位。 |
| 401 | `INVALID_API_KEY`：沒有帶金鑰，或金鑰錯誤、已暫停、已刪除。 |
| 403 | 金鑰或你的角色不允許，例如只能查看的金鑰會得到 `WRITE_ACCESS_REQUIRED`。 |
| 404 | 工作區、帳號或自動化不存在，或你無法存取，例如 `WORKSPACE_NOT_FOUND`。 |
| 409 | 和目前狀態衝突，例如讀取後自動化又被修改過，會得到 `VERSION_CONFLICT`。 |
| 429 | `RATE_LIMITED`：同一把金鑰一分鐘內超過 300 次請求。等候 `Retry-After` 標頭的秒數後再試。 |
| 500 | Replier 發生錯誤。用同一個 `Idempotency-Key` 再試一次。 |

## 安全地重試

會修改資料的請求可以帶 `Idempotency-Key` 標頭。每個操作送一個新的隨機值（例如 UUID），重試時送同一個值。用同一個值重試會拿到第一次的結果，不會多建立一個自動化或重複傳送回覆。傳送補回覆、backfill 或單次自動化的回覆，以及建立單次自動化時，一定要帶這個標頭；沒帶會以 `IDEMPOTENCY_KEY_REQUIRED` 被拒絕。

```bash theme={null}
curl -X POST https://api.usereplier.com/v1/workspaces/$WORKSPACE_ID/catch-up \
  -H "Authorization: Bearer $REPLIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9c1d2e-8a7b-4c3d-9e1f-2a6b5c8d7e0f" \
  -d @items.json
```

為了避免蓋掉別人的修改，請帶上你讀到的版本 `expected_version`。如果自動化在那之後被改過，請求會以 `VERSION_CONFLICT` 被拒絕。刪除自動化時必須帶上它。

## API 的變動

在 `/v1` 裡，Replier 只會新增：新的端點、新的選用參數、新的回應欄位，以及狀態或原因欄位的新值。請忽略你不認得的欄位和值。會讓既有程式出錯的變動會以 `/v2` 推出。

## 暫停或刪除金鑰

在「**帳戶設定 → 整合**」，每把金鑰都會顯示權限與最後使用時間。按「**暫停存取**」會拒絕它的請求，直到你按「**恢復存取**」。按「**刪除金鑰**」會永久移除，使用它的程式會立即失去存取權。它建立的自動化會繼續運作。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.