Relay
主控台
所有系統正常正常運行 99.99%
RELAY API 參考

概覽

Relay 是為即時通訊打造的 API。用一組端點串接訊息、頻道與 Webhooks，把通知、聊天與工作流事件送達任何裝置。所有請求皆走 HTTPS，回應一律為 JSON，並以標準 HTTP 狀態碼表示結果。

基礎網址
https://api.relay.dev
目前版本
v3.2 · 2026-06
驗證方式
Bearer 金鑰
預設速率
1,000 req / 分鐘
版本控管
所有請求都會鎖定你建立金鑰時的 API 版本。要升級時，於主控台切換版本並以測試金鑰驗證後再上線，破壞性變更絕不會在未告知的情況下套用。
安全性

驗證

以金鑰驗證每個請求。將金鑰放入 Authorization 標頭，格式為Bearer <金鑰>。金鑰分為 rl_live_（正式）與rl_test_（測試）兩種前綴，測試金鑰不會產生實際送達或計費。

驗證請求
1curl https://api.relay.dev/v1/channels \
2  -H "Authorization: Bearer rl_live_8fK2pQ9xR4mZ" \
3  -H "Relay-Version: 2026-06-01"
切勿外洩金鑰
正式金鑰擁有帳號完整權限，請只在伺服器端使用，切勿寫入前端程式碼、版本控管或行動裝置。若疑似外洩，立即於主控台輪替。
三分鐘上手

快速開始

安裝 SDK、設定金鑰、送出訊息。以下範例使用 Node.js，Python、Go 與 Ruby 亦有對應官方套件。

quickstart.ts
1# 安裝官方 Node.js SDK
2npm install @relay/node
3
4// 送出第一則訊息
5import Relay from "@relay/node";
6
7const relay = new Relay(process.env.RELAY_KEY);
8
9await relay.messages.send({
10  channel: "ch_9f2a",
11  text: "部署完成 ✓",
12});

回傳指定頻道的訊息，依建立時間新到舊排序。以游標分頁遍歷歷史紀錄，單次最多 100 筆。

GEThttps://api.relay.dev/v1/messages

查詢參數

參數型別必填說明
channelstring必填要查詢的頻道 ID，例如 ch_9f2a。
limitinteger選填單頁回傳筆數，1–100，預設 20。
beforestring選填游標分頁：回傳此訊息 ID 之前的資料。
statusenum選填以狀態篩選：queued、sent、delivered、failed。
請求
cURL
1curl -G https://api.relay.dev/v1/messages \
2  --data-urlencode "channel=ch_9f2a" \
3  --data-urlencode "limit=2" \
4  -H "Authorization: Bearer rl_live_***"
200 OK 回應
回應 · application/json
1{
2  "object": "list",
3  "has_more": true,
4  "data": [
5    {
6      "id": "msg_3kP9xQ",
7      "text": "部署完成 ✓",
8      "status": "delivered",
9      "created": 1720900000
10    }
11  ]
12}

建立並排入一則新訊息。回應立即返回 queued 狀態，實際送達進度可透過 Webhooks 或輪詢單筆訊息取得。

POSThttps://api.relay.dev/v1/messages

請求主體

參數型別必填說明
channelstring必填目標頻道 ID。
textstring必填訊息內容，最長 4,000 字元，支援 Markdown。
attachmentsarray選填附件物件陣列，每則訊息最多 10 個。
idempotency_keystring選填冪等鍵，24 小時內重送相同鍵不會重複建立。
用冪等鍵安全重試
網路逾時後直接以相同 idempotency_key 重送即可，Relay 會回傳原本那筆訊息而非重複建立，非常適合部署腳本與佇列工作。
cURL · 請求
1curl -X POST https://api.relay.dev/v1/messages \
2  -H "Authorization: Bearer rl_live_***" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "channel": "ch_9f2a",
6    "text": "部署完成 ✓ 版本 3.2.1",
7    "idempotency_key": "deploy-3f9a2"
8  }'
201 Created · 回應
1{
2  "id": "msg_7Rk2mB",
3  "object": "message",
4  "channel": "ch_9f2a",
5  "status": "queued",
6  "created": 1720986412
7}

建立一個新頻道作為訊息容器。頻道 ID 以 ch_ 為前綴，之後即可對其傳送訊息與訂閱事件。

POSThttps://api.relay.dev/v1/channels

請求主體

參數型別必填說明
namestring必填頻道顯示名稱，例如 deploys。
typeenum選填public 或 private，預設 private。
membersarray選填初始成員的 user ID 陣列。
201 Created · 回應
1{
2  "id": "ch_a12bK9",
3  "name": "deploys",
4  "type": "private",
5  "member_count": 3
6}
事件推送

事件與簽章

Webhooks 會將事件即時 POST 到你設定的端點。每個請求都帶有Relay-Signature 標頭，請務必驗證後再處理，以確保來源可信。

message.delivered訊息成功送達收件端。
message.failed送達失敗，payload 內含 error 物件。
channel.created有新頻道被建立。
member.joined使用者加入頻道。
verify-signature.ts
1// 驗證 Relay 簽章（Node.js）
2import { createHmac } from "crypto";
3
4const expected = createHmac("sha256", secret)
5  .update(rawBody)
6  .digest("hex");
7
8if (expected !== req.headers["relay-signature"]) throw Error("簽章不符");
端點需在 5 秒內回應
請先回傳 200 再處理事件。逾時或非 2xx 回應會觸發指數退避重試，最長重試 72 小時。

Relay 使用標準 HTTP 狀態碼。2xx 表示成功，4xx 表示請求端問題，5xx 表示 Relay 端問題。錯誤回應主體一律包含結構化的 error 物件。

400invalid_request請求參數格式錯誤或缺少必填欄位。
401unauthorized金鑰缺失、無效或已被撤銷。
403forbidden金鑰有效但無權存取此資源。
404not_found找不到指定 ID 的資源。
429rate_limited超出速率限制，請參考 Retry-After。
500server_errorRelay 端發生錯誤，可安全重試。

錯誤物件結構

400 Bad Request
1{
2  "error": {
3    "type": "invalid_request",
4    "param": "channel",
5    "message": "找不到頻道 ch_9f2a"
6  }
7}

預設限制為每分鐘 1,000 次請求，以滑動視窗計算。每個回應都會附上速率標頭，超限時回傳429 並帶有 Retry-After。企業方案可申請更高額度。

X-RateLimit-Limit當前視窗允許的請求上限。
X-RateLimit-Remaining當前視窗剩餘可用次數。
X-RateLimit-Reset視窗重置的 Unix 時間戳。
Retry-After遭限流時，建議等待的秒數。
遵循退避策略
收到 429 時請等待 Retry-After 指定的秒數再重試，並加入抖動（jitter）以避免多個工作同時湧入造成尖峰。