即時API參考

概述

即時有兩個接口：

REST API用於通道管理、訊息歷程記錄、交付統計、權限和保留設定。
Socket.IO用於即時訂閱、發佈、呈現和交付事件。

REST API不會串流訊息。使用Socket.IO連線或TypeScript SDK取得即時事件。

驗証

管理員REST端點需要專案管理員權杖或API金鑰。

Authorization: Bearer <project-admin-jwt-or-ik_api_key>
Content-Type: application/json

您也可以使用以下方式傳遞API金鑰：

X-API-Key: <ik_api_key>

Socket.IO連線透過Socket.IOauth物件進行驗証：

const socket = io('https://your-app.insforge.app', {
  auth: {
    token: '<user-jwt-or-anon-token>'
  }
});

伺服器/管理員用戶端可以傳遞API金鑰：

const socket = io('https://your-app.insforge.app', {
  auth: {
    apiKey: '<ik_api_key>'
  }
});

Socket.IO發佈/訂閱

在不使用InsForge SDK時安裝Socket.IO用戶端：

npm install socket.io-client

連線和訂閱

import { io } from 'socket.io-client';

const socket = io('https://your-app.insforge.app', {
  auth: {
    token: '<user-jwt-or-anon-token>'
  }
});

socket.emit('realtime:subscribe', { channel: 'order:123' }, (response) => {
  if (response.ok) {
    console.log('Subscribed:', response.channel);
    console.log('Presence:', response.presence.members);
  } else {
    console.error(response.error.code, response.error.message);
  }
});

聆聽事件

socket.on('status_changed', (message) => {
  console.log(message.status);
  console.log(message.meta.messageId);
  console.log(message.meta.senderType);
});

socket.on('presence:join', (message) => {
  console.log('Joined:', message.member);
});

socket.on('presence:leave', (message) => {
  console.log('Left:', message.member);
});

socket.on('realtime:error', (error) => {
  console.error(error.channel, error.code, error.message);
});

發佈

socket.emit('realtime:publish', {
  channel: 'order:123',
  event: 'customer_viewed',
  payload: {
    viewedAt: new Date().toISOString()
  }
});

通訊端必須成功訂閱通道，才能發佈至該通道。

取消訂閱

socket.emit('realtime:unsubscribe', { channel: 'order:123' });
socket.disconnect();

通訊端事件

事件	方向	說明
`realtime:subscribe`	用戶端至伺服器	訂閱通道。確認傳回成功/錯誤和呈現快照。
`realtime:unsubscribe`	用戶端至伺服器	離開通道。
`realtime:publish`	用戶端至伺服器	將使用者訊息插入即時管道。
Custom event name	伺服器至用戶端	已交付的訊息，在訊息`eventName`下發出。
`presence:join`	伺服器至用戶端	邏輯成員在通道中出現。
`presence:leave`	伺服器至用戶端	邏輯成員不再在通道中。
`realtime:error`	伺服器至用戶端	訂閱或發佈失敗。

通道模式

在用戶端訂閱之前建立通道定義。

模式	相符
`orders`	`orders`
`order:%`	`order:123`, `order:456`
`chat:%:messages`	`chat:room-1:messages`

模式相符使用SQLLIKE，因此%是萬用字元。_在通道模式中不被接受，因為它也是SQL萬用字元。

通道

列出通道

GET /api/realtime/channels

curl "https://your-app.insforge.app/api/realtime/channels" \
  -H "Authorization: Bearer <project-admin-jwt-or-ik_api_key>"

回應：

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "pattern": "order:%",
    "description": "Order updates",
    "webhookUrls": ["https://example.com/webhook"],
    "enabled": true,
    "createdAt": "2026-04-25T17:00:00.000Z",
    "updatedAt": "2026-04-25T17:00:00.000Z"
  }
]

建立通道

POST /api/realtime/channels

請求本文：

欄位	類型	必需	說明
`pattern`	`string`	是	通道模式。
`description`	`string`	否	人類可讀的說明。
`webhookUrls`	`string[]`	否	每筆已交付訊息的Webhook URL。
`enabled`	`boolean`	否	預設為`true`。已停用的通道無法加入或交付至。

curl -X POST "https://your-app.insforge.app/api/realtime/channels" \
  -H "Authorization: Bearer <project-admin-jwt-or-ik_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "chat:%",
    "description": "Chat rooms",
    "webhookUrls": ["https://example.com/realtime-webhook"],
    "enabled": true
  }'

取得通道

GET /api/realtime/channels/{id}

更新通道

PUT /api/realtime/channels/{id}

curl -X PUT "https://your-app.insforge.app/api/realtime/channels/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <project-admin-jwt-or-ik_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Active order updates",
    "enabled": true
  }'

刪除通道

DELETE /api/realtime/channels/{id}

{
  "message": "Channel deleted"
}

訊息歷程記錄會保留。已刪除的通道會將現有訊息channelId值設定為null。

訊息

列出訊息

GET /api/realtime/messages

查詢參數：

參數	類型	說明
`channelId`	`uuid`	按通道ID篩選。
`eventName`	`string`	按事件名稱篩選。
`limit`	`integer`	1至1000。預設為100。
`offset`	`integer`	預設為0。

curl "https://your-app.insforge.app/api/realtime/messages?eventName=status_changed&limit=50" \
  -H "Authorization: Bearer <project-admin-jwt-or-ik_api_key>"

回應：

[
  {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "eventName": "status_changed",
    "channelId": "550e8400-e29b-41d4-a716-446655440000",
    "channelName": "order:123",
    "payload": {
      "id": "123",
      "status": "shipped"
    },
    "senderType": "system",
    "senderId": null,
    "wsAudienceCount": 5,
    "whAudienceCount": 1,
    "whDeliveredCount": 1,
    "createdAt": "2026-04-25T17:00:00.000Z"
  }
]

訊息統計

GET /api/realtime/messages/stats

查詢參數：

參數	類型	說明
`channelId`	`uuid`	按通道ID篩選統計資料。
`since`	`date-time`	僅包含在此時間戳之後建立的訊息。

{
  "totalMessages": 1250,
  "whDeliveryRate": 0.98,
  "topEvents": [
    {
      "eventName": "status_changed",
      "count": 450
    }
  ],
  "retentionDays": null
}

retentionDays: null表示訊息會無限期保留。

權限

GET /api/realtime/permissions

傳回使用者定義的RLS原則，用於：

realtime.channels上的訂閱檢查。
realtime.messages上的發佈檢查。

{
  "subscribe": {
    "policies": [
      {
        "policyName": "users_subscribe_own_orders",
        "tableName": "channels",
        "command": "SELECT",
        "roles": ["authenticated"],
        "using": "pattern = 'order:%'",
        "withCheck": null
      }
    ]
  },
  "publish": {
    "policies": []
  }
}

設定

取得即時設定

GET /api/realtime/config

{
  "retentionDays": null
}

更新即時設定

PATCH /api/realtime/config

curl -X PATCH "https://your-app.insforge.app/api/realtime/config" \
  -H "Authorization: Bearer <project-admin-jwt-or-ik_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "retentionDays": 90
  }'

使用null以無限期保留訊息。正整數表示保留訊息指定的天數。

Webhooks

當通道有webhookUrls時，透過該通道交付的每筆訊息都會發佈至各個URL。請求本文是原始訊息承載。標頭識別交付：

標頭	值
`X-InsForge-Event`	事件名稱
`X-InsForge-Channel`	已解決的通道名稱
`X-InsForge-Message-Id`	訊息UUID

交付嘗試反映在訊息歷程記錄中的whAudienceCount和whDeliveredCount中。

TypeScript

Swift

Kotlin

REST API

範例

概述

驗証

Socket.IO發佈/訂閱

連線和訂閱

聆聽事件

發佈

取消訂閱

通訊端事件

通道模式

通道

列出通道

建立通道

取得通道

更新通道

刪除通道

訊息

列出訊息

訊息統計

權限

設定

取得即時設定

更新即時設定

Webhooks

​概述

​驗証

​Socket.IO發佈/訂閱

​連線和訂閱

​聆聽事件

​發佈

​取消訂閱

​通訊端事件

​通道模式

​通道

​列出通道

​建立通道

​取得通道

​更新通道

​刪除通道

​訊息

​列出訊息

​訊息統計

​權限

​設定

​取得即時設定

​更新即時設定

​Webhooks

概述

驗証

Socket.IO發佈/訂閱

連線和訂閱

聆聽事件

發佈

取消訂閱

通訊端事件

通道模式

通道

列出通道

建立通道

取得通道

更新通道

刪除通道

訊息

列出訊息

訊息統計

權限

設定

取得即時設定

更新即時設定

Webhooks