バージョン: 0.14.0 (最新)

💬 チャットサービス

チャットサービスは、チャンネル、サブスクリプション、メッセージ、メッセージテンプレート、既読状態、WebSocket ストリーミングを含むリアルタイムコミュニケーション機能の包括的なソリューションを提供します。チャンネル管理とサブスクリプション処理を、単一の一貫した API に統合します。

🚀 クイックスタート

import express from 'express';
import {middlewares, services, drivers} from '@nodeblocks/backend-sdk';

const {nodeBlocksErrorMiddleware} = middlewares;
const {chatService} = services;
const {withMongo, createFileStorageDriver} = drivers;

const connectToDatabase = withMongo('mongodb://localhost:27017/?authSource=admin', 'dev', 'user', 'password');
const fileStorageDriver = createFileStorageDriver('your-project-id', 'your-bucket-name');

express()
  .use(
    chatService(
      {
        identities: client.collection('identities'),
        chatChannels: client.collection('chatChannels'),
        chatMessages: client.collection('chatMessages'),
        subscriptions: client.collection('subscriptions'),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        identity: {
          typeIds: {
            admin: '100',
            guest: '000',
            regular: '001',
          },
        },
      }
    )
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

📋 エンドポイント概要

チャンネル操作

メソッド	パス	説明
`POST`	`/channels`	新しいチャンネルを作成
`GET`	`/channels`	すべてのチャンネルを一覧取得
`GET`	`/channels/:channelId`	特定のチャンネルを取得
`GET`	`/channels/:channelId/icon-upload-url`	チャンネルアイコン用の署名付き URL を生成
`PATCH`	`/channels/:channelId`	チャンネルを更新
`DELETE`	`/channels/:channelId`	チャンネルを削除

サブスクリプション操作

メソッド	パス	説明
`POST`	`/subscriptions`	新しいサブスクリプションを作成
`GET`	`/subscriptions`	すべてのサブスクリプションを一覧取得
`GET`	`/subscriptions/:subscriptionId`	特定のサブスクリプションを取得
`DELETE`	`/subscriptions/:subscriptionId`	サブスクリプションを削除

メッセージ操作

メソッド	パス	説明
`POST`	`/messages`	新しいメッセージを作成
`GET`	`/messages?channelId=:channelId`	チャンネル内のメッセージを一覧取得
`GET`	`/channels/:channelId/messages`	特定チャンネルの全メッセージを取得
`GET`	`/messages/:messageId`	特定のメッセージを取得
`GET`	`/messages/:messageId/attachment-upload-url`	メッセージ添付用の署名付き URL を生成
`POST`	`/messages/:messageId/attachments`	既存メッセージに添付ファイルを作成
`DELETE`	`/messages/:messageId/attachments/:attachmentId`	メッセージから添付ファイルを削除
`PATCH`	`/messages/:messageId`	メッセージを更新
`DELETE`	`/messages/:messageId`	メッセージを削除

メッセージテンプレート操作

メソッド	パス	説明
`POST`	`/message-templates`	新しいメッセージテンプレートを作成
`GET`	`/message-templates`	すべてのメッセージテンプレートを一覧取得（管理者のみ）
`GET`	`/organizations/:organizationId/message-templates`	組織のメッセージテンプレートを一覧取得（組織 owner/admin のみ）
`GET`	`/message-templates/:messageTemplateId`	特定のメッセージテンプレートを取得
`PATCH`	`/message-templates/:messageTemplateId`	既存のメッセージテンプレートを更新
`DELETE`	`/message-templates/:messageTemplateId`	既存のメッセージテンプレートを削除

チャンネル既読状態の操作

メソッド	パス	説明
`PUT`	`/channels/:channelId/read-state`	チャンネルの既読状態を upsert（作成または更新）

リアルタイムストリーミング

メソッド	パス	説明
`WS`	`/messages/listen`	メッセージをリアルタイムにストリーミング（`webSocketServer` オプションが必要）

WS /messages/listen を有効にするには、chatService の第 3 引数として { webSocketServer } を渡してください。

🗄️ エンティティスキーマ

チャンネルエンティティ

{
  "name": "string",
  "ownerId": "string",
  "icon": {"objectId": "string (UUID)", "type": "string"},
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

フィールド詳細:

フィールド	型	自動生成	必須	説明
`name`	string	❌	✅	チャンネル名/タイトル
`ownerId`	string	❌	✅	このチャンネルの所有者となるアイデンティティのID
`icon`	object \| null	❌	❌	チャンネルアイコン。リクエストは `{ objectId, type }`、`fileStorageDriver` 使用時のレスポンスは `{ type, url }`
`createdAt`	datetime	✅	✅	作成日時
`id`	string	✅	✅	一意識別子（UUID）
`updatedAt`	datetime	✅	✅	最終更新日時

サブスクリプションエンティティ

{
  "approved": "boolean",
  "channelId": "string",
  "permissions": ["string"],
  "subscribedAt": "string (datetime)",
  "subscribedId": "string",
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

フィールド詳細:

フィールド	型	自動生成	必須	説明
`approved`	boolean	❌	❌	サブスクリプションが承認済みかどうか
`channelId`	string	❌	✅	対象チャンネルのID
`permissions`	array	❌	❌	権限文字列の配列（例: ["read", "write"])
`subscribedAt`	datetime	❌	❌	サブスクリプション作成日時
`subscribedId`	string	❌	❌	購読するアイデンティティのID
`createdAt`	datetime	✅	✅	作成日時
`id`	string	✅	✅	一意識別子（UUID）
`updatedAt`	datetime	✅	✅	最終更新日時

メッセージエンティティ

{
  "channelId": "string",
  "content": "string",
  "senderId": "string",
  "title": "string",
  "attachments": [{"url": "string", "type": "string"}],
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

フィールド詳細:

フィールド	型	自動生成	必須	説明
`channelId`	string	❌	✅	メッセージが送信されるチャンネルのID
`content`	string	❌	✅	メッセージ本文
`senderId`	string	❌	✅	メッセージ送信者のアイデンティティID
`title`	string	❌	❌	任意のメッセージタイトル
`attachments`	array	❌	❌	メッセージのファイル添付（添付エンドポイントで追加するまで空）
`attachments[].url`	string	✅	✅	正規化済みのダウンロード／閲覧 URL（`fileStorageDriver` が必要）
`attachments[].type`	string	❌	✅	MIME タイプまたはファイルカテゴリ
`createdAt`	datetime	✅	✅	作成日時
`id`	string	✅	✅	一意識別子（UUID）
`updatedAt`	datetime	✅	✅	最終更新日時

📝 注意: 自動生成フィールドはサービス側で設定され、作成/更新リクエストに含めないでください。スキーマは additionalProperties: false を強制し、定義されたフィールドのみを許可します。

チャンネル既読状態エンティティ

{
  "channelId": "string",
  "identityId": "string",
  "lastReadMessageId": "string",
  "lastReadMessageCreatedAt": "string (datetime)",
  "createdAt": "string (datetime)",
  "id": "string",
  "updatedAt": "string (datetime)"
}

フィールド詳細:

フィールド	型	自動生成	必須	説明
`channelId`	string	❌	✅	記録対象チャンネルの ID
`identityId`	string	❌	✅	既読状態を記録するアイデンティティの ID
`lastReadMessageId`	string	❌	✅	最後に読んだメッセージの ID
`lastReadMessageCreatedAt`	datetime	❌	✅	最後に読んだメッセージの作成日時
`createdAt`	datetime	✅	✅	作成日時
`id`	string	✅	✅	一意識別子（UUID）
`updatedAt`	datetime	✅	✅	最終更新日時

📝 注意: 自動生成フィールドはサービスが設定するため、upsert リクエストに含めないでください。スキーマでは additionalProperties: false を強制し、定義済みフィールドだけを許可します。

🔐 認証ヘッダー

保護されたエンドポイントでは、次のヘッダーを含めてください：

Authorization: Bearer <access_token>
x-nb-fingerprint: <device_fingerprint>

⚠️ 重要: 認可時にフィンガープリントを指定した場合、認証済みのすべてのリクエストで x-nb-fingerprint ヘッダーが必須です。欠如している場合は 401 Unauthorized が返ります。

🔧 APIエンドポイント

📺 チャンネル操作

1. チャンネル作成

指定された情報で新しいチャットチャンネルを作成します。

リクエスト:

Method: POST
Path: /channels
ヘッダー:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: 自動適用（name と ownerId が必須、追加プロパティなし）
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者ロールまたは本人（ownerId が認証ユーザーと一致）

リクエストボディ:

フィールド	型	必須	説明
`name`	string	✅	チャンネル名/タイトル
`ownerId`	string	✅	このチャンネルを所有するユーザーのID

レスポンスボディ:

フィールド	型	説明
`name`	string	チャンネル名/タイトル
`ownerId`	string	このチャンネルを所有するユーザーのID
`createdAt`	string	作成日時
`id`	string	チャンネル一意ID
`updatedAt`	string	最終更新日時

リクエスト例:

curl -X POST http://localhost:8089/channels \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Updates",
    "ownerId": "user-456"
  }'

成功レスポンス:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "name": "Project Updates",
  "ownerId": "user-456",
  "createdAt": "2025-06-24T08:33:40.146Z",
  "id": "af62eac3-06aa-481a-8c44-a029e96de2ed",
  "updatedAt": "2025-06-24T08:33:40.146Z"
}

バリデーションエラー例:

必須フィールド不足:

{
  "error": {
    "message": "must have ownerId when creating a new channel"
  }
}

スキーマ検証エラー:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'ownerId'"
    ]
  }
}

追加プロパティエラー:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must NOT have additional properties"
    ]
  }
}

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must NOT have additional properties",
      "request body must NOT have additional properties"
    ]
  }
}

2. チャンネル一覧

フィルタやページングを指定して全チャンネルを取得します。

リクエスト:

Method: GET
Path: /channels
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: name, ownerId とページング（page, limit）のクエリ検証
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者ロール、または本人（自分のチャンネルを取得する場合）

クエリパラメータ:

パラメータ	型	必須	説明
`name`	string	❌	チャンネル名でフィルタ
`ownerId`	string	❌	所有者IDでフィルタ
`page`	number	❌	ページ番号
`limit`	number	❌	1ページあたりの件数

レスポンスボディ:

フィールド	型	説明
`name`	string	チャンネル名/タイトル
`ownerId`	string	このチャンネルを所有するユーザーのID
`createdAt`	string	作成日時
`id`	string	チャンネル一意ID
`updatedAt`	string	最終更新日時

リクエスト例:

curl http://localhost:8089/channels

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "name": "Project Updates",
    "ownerId": "user-456",
    "createdAt": "2025-06-24T08:33:40.146Z",
    "id": "af62eac3-06aa-481a-8c44-a029e96de2ed",
    "updatedAt": "2025-06-24T08:33:40.146Z"
  }
]

3. チャンネル取得

ID で特定のチャンネルを取得します。

リクエスト:

Method: GET
Path: /channels/:channelId
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: チャンネルIDのパスパラメータ検証
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者ロール、チャンネル所有者、または当該チャンネルの有効なサブスクリプション

リクエスト例:

curl http://localhost:8089/channels/af62eac3-06aa-481a-8c44-a029e96de2ed

4. チャンネルアイコンのアップロード URL を取得

チャンネルアイコン画像を安全にアップロードするための署名付き URL を生成します。オブジェクト ID と一時的な署名付き URL を返します。

リクエスト:

Method: GET
Path: /channels/:channelId/icon-upload-url
ヘッダー: Authorization: Bearer <token>、x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

URL パラメータ:

パラメータ	型	必須	説明
`channelId`	string	✅	対象チャンネルの ID

クエリパラメータ:

パラメータ	型	必須	説明
`contentType`	string	✅	画像の MIME タイプ（例: `image/png`、`image/jpeg`）
`contentLength`	number	✅	ファイルサイズ（バイト、最大 10MB）

レスポンスボディ:

フィールド	型	説明
`objectId`	string	アイコン用に生成されたストレージオブジェクト ID
`url`	string	ファイルアップロード用の署名付き URL

バリデーション: 画像アップロードスキーマ（コンテンツタイプとサイズの制約）を使用します。認証済みであり、管理者またはチャンネル所有者である必要があります。

リクエスト例:

curl "http://localhost:8089/channels/af62eac3-06aa-481a-8c44-a029e96de2ed/icon-upload-url?contentType=image/jpeg&contentLength=524288" \
  -H "Authorization: Bearer <token>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "objectId": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
  "url": "https://storage.googleapis.com/bucket/channels/icons/...&X-Goog-Expires=900&X-Goog-Signature=..."
}

使用手順:

contentType と contentLength を指定してこのエンドポイントを呼び出し、署名付き URL を取得します。
返された url にファイルバイナリを含む PUT リクエストを送り、アイコンをクラウドストレージへ直接アップロードします。
返された objectId を保存し、アップロード済みのアイコンを参照します。

エラーレスポンス: クエリパラメータが不足すると Validation Error、画像以外のコンテンツタイプでは Invalid content type - must be an image、10MB 超過では File size exceeds maximum allowed (10MB) が返ります。チャンネルがない場合は Channel not found、所有者または管理者でない場合は Unauthorized - must be channel owner or admin が返ります。

5. チャンネル更新

既存のチャンネルのプロパティを更新します。

リクエスト:

Method: PATCH
Path: /channels/:channelId
ヘッダー:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: 部分更新スキーマ（全フィールド任意、追加プロパティなし）
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者ロールまたはチャンネル所有者

リクエストボディ:

フィールド	型	必須	説明
`name`	string	❌	新しいチャンネル名/タイトル
`ownerId`	string	❌	新しい所有者ID

レスポンスボディ:

フィールド	型	説明
`name`	string	更新後のチャンネル名/タイトル
`ownerId`	string	更新後の所有者ID
`createdAt`	string	作成日時
`id`	string	チャンネル一意ID
`updatedAt`	string	最終更新日時

リクエスト例:

curl -X PATCH http://localhost:8089/channels/af62eac3-06aa-481a-8c44-a029e96de2ed \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Project Updates"
  }'

5. チャンネル削除

チャンネルと関連データを削除します。

リクエスト:

Method: DELETE
Path: /channels/:channelId
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: チャンネルIDのパスパラメータ検証
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者ロールまたはチャンネル所有者

レスポンスボディ:

フィールド	型	説明
なし	-	成功時はレスポンスボディなし

リクエスト例:

curl -X DELETE http://localhost:8089/channels/af62eac3-06aa-481a-8c44-a029e96de2ed

成功レスポンス:

ステータス: 204 No Content
ボディ: （空）

見つからない場合のエラー例:

{
  "error": {
    "message": "Channel not found"
  }
}

📋 サブスクリプション操作

6. サブスクリプション作成

チャンネルへの新規サブスクリプションを作成します。

リクエスト:

Method: POST
Path: /subscriptions
ヘッダー:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: 自動適用（channelId と subscribedId が必須、追加プロパティなし）
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者ロールまたは本人（購読者が認証ユーザー）

リクエストボディ:

フィールド	型	必須	説明
`channelId`	string	✅	購読対象のチャンネルID
`approved`	boolean	❌	サブスクリプションが承認済みか
`permissions`	array	❌	権限文字列の配列
`subscribedAt`	string	❌	サブスクリプション作成日時
`subscribedId`	string	❌	購読ユーザーのID

レスポンスボディ:

フィールド	型	説明
`channelId`	string	購読対象のチャンネルID
`subscribedId`	string	購読ユーザーのID
`approved`	boolean	サブスクリプションが承認済みか
`permissions`	array	権限文字列の配列
`subscribedAt`	string	サブスクリプション作成日時
`createdAt`	string	作成日時
`id`	string	サブスクリプション一意ID
`updatedAt`	string	最終更新日時

リクエスト例:

curl -X POST http://localhost:8089/subscriptions \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "af62eac3-06aa-481a-8c44-a029e96de2ed",
    "subscribedId": "user-456",
    "approved": true,
    "permissions": ["read", "write"]
  }'

成功レスポンス:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "channelId": "af62eac3-06aa-481a-8c44-a029e96de2ed",
  "subscribedId": "user-456",
  "approved": true,
  "permissions": ["read", "write"],
  "createdAt": "2025-06-27T02:16:07.916Z",
  "id": "b17501d6-2576-4a18-86f5-3545da75e678",
  "updatedAt": "2025-06-27T02:16:07.916Z"
}

バリデーションエラー例:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'channelId'",
      "request body must have required property 'subscribedId'",
    ]
  }
}

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must NOT have additional properties",
    ]
  }
}

7. サブスクリプション一覧

フィルタやページングを指定してサブスクリプションを取得します。

リクエスト:

Method: GET
Path: /subscriptions
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: approved, channelId, subscribedAt, subscribedId とページング（page, limit）のクエリ検証
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者、当該チャンネルの有効なサブスクリプション、チャンネル所有者、または本人（購読者）

クエリパラメータ:

パラメータ	型	必須	説明
`approved`	boolean	❌	承認状態でフィルタ
`channelId`	string	❌	チャンネルIDでフィルタ
`subscribedId`	string	❌	購読者IDでフィルタ
`subscribedAt`	string	❌	購読日時でフィルタ
`page`	number	❌	ページ番号
`limit`	number	❌	1ページあたりの件数

レスポンスボディ:

フィールド	型	説明
`channelId`	string	購読対象のチャンネルID
`subscribedId`	string	購読ユーザーのID
`approved`	boolean	サブスクリプションが承認済みか
`permissions`	array	権限文字列の配列
`subscribedAt`	string	サブスクリプション作成日時
`createdAt`	string	作成日時
`id`	string	サブスクリプション一意ID
`updatedAt`	string	最終更新日時

リクエスト例:

curl http://localhost:8089/subscriptions

8. サブスクリプション取得

ID で特定のサブスクリプションを取得します。

リクエスト:

Method: GET
Path: /subscriptions/:subscriptionId
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: サブスクリプションIDのパスパラメータ検証
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者ロールまたはサブスクリプション所有者

リクエスト例:

curl http://localhost:8089/subscriptions/b17501d6-2576-4a18-86f5-3545da75e678

9. サブスクリプション削除

サブスクリプションを削除（チャンネルの購読解除）します。

リクエスト:

Method: DELETE
Path: /subscriptions/:subscriptionId
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: サブスクリプションIDのパスパラメータ検証
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者ロールまたはサブスクリプション所有者

レスポンスボディ:

フィールド	型	説明
なし	-	成功時はレスポンスボディなし

リクエスト例:

curl -X DELETE http://localhost:8089/subscriptions/b17501d6-2576-4a18-86f5-3545da75e678

成功レスポンス:

ステータス: 204 No Content
ボディ: （空）

見つからない場合のエラー例:

{
  "error": {
    "message": "Subscription not found"
  }
}

💬 メッセージ操作

10. メッセージ作成

チャンネルに新しいメッセージを送信します。

リクエスト:

Method: POST
Path: /messages
ヘッダー:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: 自動適用（content, senderId, channelId が必須、追加プロパティなし）
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 送信者本人であること
- 当該チャンネルの有効なサブスクリプションがあること

リクエストボディ:

フィールド	型	必須	説明
`channelId`	string	✅	メッセージが送信されるチャンネルのID
`content`	string	✅	メッセージ本文
`senderId`	string	✅	メッセージ送信者のユーザーID
`title`	string	❌	任意のメッセージタイトル

レスポンスボディ:

フィールド	型	説明
`channelId`	string	メッセージが送信されるチャンネルのID
`content`	string	メッセージ本文
`senderId`	string	メッセージ送信者のユーザーID
`title`	string	任意のメッセージタイトル
`createdAt`	string	作成日時
`id`	string	メッセージ一意ID
`updatedAt`	string	最終更新日時

リクエスト例:

curl -X POST http://localhost:8089/messages \
  -H "Content-Type: application/json" \
  -d '{"channelId": "test-channel-123", "content": "Hello world!", "senderId": "user-456"}'

成功レスポンス:

{
  "channelId": "test-channel-123",
  "content": "Hello world!",
  "senderId": "user-456",
  "createdAt": "2025-07-01T03:22:06.178Z",
  "id": "2b43d66c-9cab-434b-9cb7-18de8d3ec9c9",
  "updatedAt": "2025-07-01T03:22:06.178Z"
}

バリデーションエラー例:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'senderId'",
      "request body must have required property 'channelId'"
    ]
  }
}

11. メッセージ一覧

特定のチャンネルのメッセージを取得します。

リクエスト:

Method: GET
Path: /messages?channelId=:channelId
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: channelId（必須）、任意の content, senderId, title、およびページング（page, limit）のクエリ検証
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者、当該チャンネルの有効なサブスクリプション、または送信者本人

クエリパラメータ:

パラメータ	型	必須	説明
`channelId`	string	✅	取得対象のチャンネルID
`content`	string	❌	メッセージ本文でフィルタ
`senderId`	string	❌	送信者IDでフィルタ
`title`	string	❌	メッセージタイトルでフィルタ
`page`	number	❌	ページ番号
`limit`	number	❌	1ページあたりの件数

レスポンスボディ:

フィールド	型	説明
`channelId`	string	メッセージが送信されるチャンネルのID
`content`	string	メッセージ本文
`senderId`	string	メッセージ送信者のユーザーID
`title`	string	任意のメッセージタイトル
`createdAt`	string	作成日時
`id`	string	メッセージ一意ID
`updatedAt`	string	最終更新日時

リクエスト例:

curl "http://localhost:8089/messages?channelId=test-channel-123"

成功レスポンス:

[
  {
    "channelId": "test-channel-123",
    "content": "Updated message content",
    "senderId": "user-456",
    "createdAt": "2025-07-01T03:22:06.178Z",
    "id": "2b43d66c-9cab-434b-9cb7-18de8d3ec9c9",
    "updatedAt": "2025-07-01T03:22:34.413Z"
  }
]

バリデーションエラー例:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "query parameter 'channelId' is required"
    ]
  }
}

12. メッセージ取得（ID指定）

ID で特定のメッセージを取得します。

リクエスト:

Method: GET
Path: /messages/:messageId
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: メッセージIDのパスパラメータ検証
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者ロールまたはメッセージ所有者

リクエスト例:

curl http://localhost:8089/messages/2b43d66c-9cab-434b-9cb7-18de8d3ec9c9

成功レスポンス:

{
  "channelId": "test-channel-123",
  "content": "Updated message content",
  "senderId": "user-456",
  "createdAt": "2025-07-01T03:22:06.178Z",
  "id": "2b43d66c-9cab-434b-9cb7-18de8d3ec9c9",
  "updatedAt": "2025-07-01T03:22:34.413Z"
}

Not Found エラー例:

{
  "error": {
    "message": "Message not found"
  }
}

13. メッセージ更新

既存のメッセージ内容を更新します。

リクエスト:

Method: PATCH
Path: /messages/:messageId
ヘッダー:
- Content-Type: application/json
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: 部分更新スキーマ（全フィールド任意、メッセージIDのパス検証、追加プロパティなし）
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者ロールまたはメッセージ所有者

リクエストボディ:

フィールド	型	必須	説明
`content`	string	❌	更新後のメッセージ本文
`title`	string	❌	更新後のメッセージタイトル

レスポンスボディ:

フィールド	型	説明
`channelId`	string	メッセージが送信されるチャンネルのID
`content`	string	更新後のメッセージ本文
`senderId`	string	メッセージ送信者のユーザーID
`title`	string	更新後のメッセージタイトル
`createdAt`	string	作成日時
`id`	string	メッセージ一意ID
`updatedAt`	string	最終更新日時

リクエスト例:

curl -X PATCH http://localhost:8089/messages/2b43d66c-9cab-434b-9cb7-18de8d3ec9c9 \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated message content"}'

成功レスポンス:

{
  "channelId": "test-channel-123",
  "content": "Updated message content",
  "senderId": "user-456",
  "createdAt": "2025-07-01T03:22:06.178Z",
  "id": "2b43d66c-9cab-434b-9cb7-18de8d3ec9c9",
  "updatedAt": "2025-07-01T03:22:34.413Z"
}

Not Found エラー例:

{
  "error": {
    "message": "Chat message not found"
  }
}

14. メッセージ削除

チャンネルからメッセージを削除します。

リクエスト:

Method: DELETE
Path: /messages/:messageId
ヘッダー:
- Authorization: Bearer <token>
- x-nb-fingerprint: <device-fingerprint>
認可: ベアラートークン必須

バリデーション:

スキーマ検証: メッセージIDのパスパラメータ検証
ルートバリデーション:
- 認証済みリクエスト（ベアラー）必須
- 管理者ロールまたはメッセージ所有者

レスポンスボディ:

フィールド	型	説明
なし	-	成功時はレスポンスボディなし

リクエスト例:

curl -X DELETE http://localhost:8089/messages/81950444-5223-47c8-8a8c-0604c2955f15

成功レスポンス:

ステータス: 204 No Content
ボディ: （空）

見つからない場合のエラー例:

{
  "error": {
    "message": "Chat message not found"
  }
}

📝 メッセージテンプレート操作

メッセージテンプレートは再利用可能なメッセージ内容です。すべてのテンプレート操作にはベアラートークンが必要で、組織に属するテンプレートでは管理者、またはその組織の owner／admin 権限が必要です。

16. メッセージテンプレートを作成

リクエスト:

Method: POST
Path: /message-templates
ヘッダー: Content-Type: application/json

フィールド	型	必須	説明
`content`	string	✅	テンプレートのメッセージ本文
`title`	string	✅	テンプレートのタイトルまたは説明
`organizationId`	string	❌	テンプレートの対象組織

content と title は必須です。認証済みであり、管理者、または本文の organizationId に対する組織 owner／admin である必要があります。

curl -X POST {{host}}/message-templates \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>" \
  -d '{"content":"Welcome to our community! Please follow our guidelines.","title":"Welcome Message","organizationId":"org-123"}'

成功レスポンス:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "content": "Welcome to our community! Please follow our guidelines.",
  "createdAt": "2025-01-20T10:30:00.000Z",
  "id": "template-uuid-here",
  "organizationId": "org-123",
  "title": "Welcome Message",
  "updatedAt": "2025-01-20T10:30:00.000Z"
}

必須項目がない場合は Validation Error を返します。

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'content'",
      "request body must have required property 'title'"
    ]
  }
}

17. ID でメッセージテンプレートを取得

リクエスト:

Method: GET
Path: /message-templates/:messageTemplateId

messageTemplateId は必須のテンプレート一意識別子です。認証済みであり、管理者、またはテンプレートにアクセスできる組織 owner／admin である必要があります。成功時は 200 OK とテンプレートを返し、存在しない場合は Chat message template not found を返します。

curl -X GET {{host}}/message-templates/template-123 \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

HTTP/1.1 200 OK
Content-Type: application/json

{
  "content": "Welcome to our community! Please follow our guidelines.",
  "createdAt": "2025-01-20T10:30:00.000Z",
  "id": "template-123",
  "organizationId": "org-123",
  "title": "Welcome Message",
  "updatedAt": "2025-01-20T10:30:00.000Z"
}

{
  "error": { "message": "Chat message template not found" }
}

18. メッセージテンプレートを更新

リクエスト:

Method: PATCH
Path: /message-templates/:messageTemplateId

本文では任意の content と title を部分更新できます。パスパラメータと部分本文を検証し、管理者またはテンプレートの組織 owner／admin を要求します。

curl -X PATCH {{host}}/message-templates/template-123 \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>" \
  -H "Content-Type: application/json" \
  -d '{"content":"Updated welcome message content","title":"Updated Welcome Message"}'

成功時は 200 OK。該当しない場合は Chat message template not found、無効なトークンでは token could not be verified、権限不足では Identity is not allowed access to this resource を返します。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "content": "Updated welcome message content",
  "createdAt": "2025-01-20T10:30:00.000Z",
  "id": "template-123",
  "organizationId": "org-123",
  "title": "Updated Welcome Message",
  "updatedAt": "2025-01-25T14:20:00.000Z"
}

{ "error": { "message": "Identity is not allowed access to this resource" } }

{ "error": { "message": "token could not be verified" } }

19. メッセージテンプレートを削除

リクエスト:

Method: DELETE
Path: /message-templates/:messageTemplateId

管理者または組織 owner／admin が削除できます。成功時は 204 No Content、削除に失敗した場合は Failed to delete message template を返します。

curl -X DELETE {{host}}/message-templates/template-123 \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

HTTP/1.1 204 No Content

{ "error": { "message": "Failed to delete message template" } }

{ "error": { "message": "Chat message template not found" } }

{ "error": { "message": "token could not be verified" } }

20. メッセージテンプレート一覧

リクエスト:

Method: GET
Path: /message-templates

管理者専用で、page（1～1000）と limit（1～50）によるページネーションを受け取ります。レスポンスはテンプレート配列を data、ページ情報を metadata.pagination に格納します。checkIdentityType(['admin']) を使用して認可します。

curl "http://localhost:8089/message-templates?page=1&limit=10" \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

認証に失敗すると token could not be verified、権限不足では Identity is not authorized to access this resource、取得失敗では Failed to find message templates を返します。

{
  "data": [{
    "id": "template-123",
    "title": "Welcome Message",
    "content": "Hello, welcome to our chat!",
    "organizationId": "org-456",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }],
  "metadata": { "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1, "hasNext": false, "hasPrev": false } }
}

{ "error": { "message": "Identity is not authorized to access this resource" } }

{ "error": { "message": "Failed to find message templates" } }

21. 組織のメッセージテンプレート一覧

リクエスト:

Method: GET
Path: /organizations/:organizationId/message-templates

必須の organizationId と、任意の page（既定値 1）および limit（既定値 10）を受け取ります。組織の owner または admin であるメンバーだけがアクセスできます。成功時は data と metadata.pagination を含む 200 OK を返します。

curl "http://localhost:8089/organizations/org-123/message-templates?page=1&limit=10" \
  -H "Authorization: Bearer <token>" \
  -H "x-nb-fingerprint: <device-fingerprint>"

認証失敗時は token could not be verified、組織メンバーでない場合は Identity is not a member of the organization、取得失敗時は Failed to find message templates を返します。

{
  "data": [{
    "id": "template-456",
    "title": "Organization Welcome",
    "content": "Welcome to our organization chat!",
    "organizationId": "org-123",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }],
  "metadata": { "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1, "hasNext": false, "hasPrev": false } }
}

{ "error": { "message": "Identity is not a member of the organization" } }

22. チャンネル ID でメッセージを取得

チャンネルスコープのパスから、チャンネルのメッセージをページネーション付きで取得します。

リクエスト:

Method: GET
Path: /channels/:channelId/messages
認可: ベアラートークン必須（チャンネルを購読している必要があります）

URL パラメータ:

パラメータ	型	必須	説明
`channelId`	string	✅	チャンネル識別子

クエリパラメータ:

パラメータ	型	必須	説明
`page`	number	❌	ページ番号（1～1000）
`limit`	number	❌	1 ページあたりの件数（1～50）

バリデーション: isAuthenticated、channelExists、hasSubscription を使用します。

成功レスポンス: メッセージ一覧と同じ、{ data, metadata.pagination } のページネーション形式です。添付ファイル項目は { url, type } に正規化されます。

23. メッセージ添付ファイルのアップロード URL を取得

既存メッセージにファイルを添付するための署名付きアップロード URL を生成します。fileStorageDriver が必要です。

エンドポイント表記は GET /messages/:messageId/attachment-upload-url です。

リクエスト:

Method: GET
Path: /messages/:messageId/attachment-upload-url
認可: ベアラートークン必須（メッセージ所有者）

URL パラメータ:

パラメータ	型	必須	説明
`messageId`	string	✅	メッセージ識別子

クエリパラメータ:

パラメータ	型	必須	説明
`contentType`	string	✅	アップロードするファイルの MIME タイプ
`contentLength`	number	✅	ファイルサイズ（バイト）

リクエスト例:

curl "{{host}}/messages/<messageId>/attachment-upload-url?contentType=image/png&contentLength=1048576" \
  -H "Authorization: Bearer <access-token>"

成功レスポンス（200）: { objectId, url }、またはファイルストレージドライバーが返す同等のアップロード URL ペイロードです。

24. メッセージ添付ファイルを作成

事前にアップロードしたファイルをメッセージに添付します。メッセージ作成時には添付されません。

エンドポイント表記は POST /messages/:messageId/attachments です。

リクエスト:

Method: POST
Path: /messages/:messageId/attachments
ヘッダー: Content-Type: application/json、Authorization: Bearer <access-token>
認可: ベアラートークン必須（メッセージ所有者）

リクエストボディ:

フィールド	型	必須	説明
`objectId`	string (UUID)	✅	アップロード URL 取得時に返されたストレージオブジェクト ID
`type`	string	✅	MIME タイプまたはファイルカテゴリ

リクエスト例:

curl -X POST {{host}}/messages/<messageId>/attachments \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"objectId": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2", "type": "image/png"}'

成功レスポンス: 正規化された添付ファイル { url, type } を含む 201 Created です。

25. メッセージ添付ファイルを削除

リクエスト:

Method: DELETE
Path: /messages/:messageId/attachments/:attachmentId
認可: ベアラートークン必須（管理者またはメッセージ所有者）

成功レスポンス: 204 No Content。

26. チャンネル既読状態を upsert

チャンネル内で ID に対応する、最後に読んだメッセージを記録します。

リクエスト:

Method: PUT
Path: /channels/:channelId/read-state
ヘッダー: Content-Type: application/json、Authorization: Bearer <access-token>
認可: ベアラートークン必須（購読済みであり、identityId は本人である必要があります）

リクエストボディ:

フィールド	型	必須	説明
`identityId`	string	✅	既読状態を更新する ID（トークンと一致する必要があります）
`lastReadMessageId`	string	✅	最後に読んだメッセージの ID

成功レスポンス: 204 No Content。

27. メッセージをストリーミング（WebSocket）

チャンネルのメッセージをリアルタイムでストリーミングします。chatService の第 3 引数に { webSocketServer } が必要です。

リクエスト:

プロトコル: WebSocket
Path: /messages/listen

クエリパラメータ:

パラメータ	型	必須	説明
`channelId`	string	✅	ストリーミングを購読するチャンネル

注記: このルートの認証・購読バリデーターは現在 SDK でコメントアウトされています。ゲートウェイで保護するか、カスタム機能を合成するときにバリデーターを有効にしてください。

⚙️ 設定オプション

サービスデータストア

チャットサービスには identities、chatChannels、subscriptions、chatMessages、chatChannelReadStates のコレクションが必要です。organizations と chatMessageTemplates は任意です。

interface ChatServiceDataStore {
  identities: Collection; // 必須: ユーザーアイデンティティコレクション
  chatChannels: Collection; // 必須: チャットチャンネルコレクション
  organizations?: Collection; // 任意: 組織コレクション
  subscriptions: Collection; // 必須: チャンネル購読コレクション
  chatMessages: Collection; // 必須: チャットメッセージコレクション
  chatMessageTemplates?: Collection; // 任意: メッセージテンプレートコレクション
  chatChannelReadStates: Collection; // 必須: チャンネル既読状態コレクション
}

サービス設定

interface ChatServiceConfiguration {
  authSecrets: {
    authEncSecret: string;    // JWT encryption secret
    authSignSecret: string;   // JWT signing secret
  };
  authMode?: 'bearer' | 'cookie'; // 未指定時は bearer
  identity?: {
    typeIds?: {
      admin: string;          // Admin user type identifier
      guest: string;          // Guest user type identifier
      regular: string;        // Regular user type identifier
    };
  };
  organization?: {
    roles?: {
      admin: string; // 組織管理者ロールの識別子
      member: string; // 組織メンバーロールの識別子
      owner: string; // 組織所有者ロールの識別子
    };
  };
}

設定詳細

チャットサービスの設定は、セキュリティとユーザー種別管理の論理グループに整理されています。

🔐 セキュリティ設定

authSecrets - JWT トークンのセキュリティシークレット

型: { authEncSecret: string; authSignSecret: string }
説明: JWT の暗号化および署名に使用する秘密鍵（トークン検証に使用）
必須: 本番環境では必須
子プロパティ:
- authEncSecret: JWT ペイロード暗号化の秘密鍵
- authSignSecret: JWT 署名検証の秘密鍵

👥 ユーザー種別設定

identity.typeIds - ユーザー種別識別子の設定

型: { admin?: string; guest?: string; regular?: string }
説明: ロールベースアクセス制御のためのカスタムユーザー種別識別子
デフォルト: undefined（デフォルトの種別検証を使用）
子プロパティ:
- admin: 管理者ユーザー種別の識別子
  - 型: string
  - 説明: 管理者ユーザーのカスタム識別子
  - 利用例: 管理操作のロールベースアクセス制御
  - 例: "admin", "administrator", "superuser"
- guest: ゲストユーザー種別の識別子
  - 型: string
  - 説明: ゲストユーザーのカスタム識別子
  - 利用例: 未認証/一時ユーザーの限定的アクセス
  - 例: "guest", "visitor", "anonymous"
- regular: 一般ユーザー種別の識別子
  - 型: string
  - 説明: 一般ユーザーのカスタム識別子
  - 利用例: 標準的なユーザー権限
  - 例: "user", "member", "customer"

🏢 組織設定

organization.roles は組織ロールの識別子を設定します。owner、admin、member のキーをルートバリデーターで使用し、それぞれの設定済み文字列 ID を組織メンバーのレコードに保存します。

型: { admin?: string; member?: string; owner?: string }
デフォルト: undefined（既定のロール検証を使用）
admin: 組織管理操作用の識別子
member: 標準の組織メンバー権限用の識別子
owner: 組織の完全な所有権限用の識別子

設定例

const chatConfig = {
  authSecrets: {
    authEncSecret: process.env.AUTH_ENC_SECRET || 'your-enc-secret',
    authSignSecret: process.env.AUTH_SIGN_SECRET || 'your-sign-secret'
  },
  identity: {
    typeIds: {
      admin: 'administrator',
      guest: 'visitor',
      regular: 'member'
    }
  }
};

🚨 エラーハンドリング

チャットサービスのエラーは、適切なHTTPステータスコードとJSON形式で返されます。

代表的なエラーコード

ステータス	エラーメッセージ	説明
400	Validation Error	リクエストボディの形式不正または必須項目不足
400	must have ownerId when creating a new channel	リクエストボディに ownerId が存在しない
400	request body must have required property 'name'	リクエストボディに name が存在しない
400	request body must have required property 'ownerId'	リクエストボディに ownerId が存在しない
400	request body must have required property 'channelId'	リクエストボディに channelId が存在しない
400	request body must have required property 'subscribedId'	リクエストボディに subscribedId が存在しない
400	request body must have required property 'content'	リクエストボディに content が存在しない
400	request body must have required property 'senderId'	リクエストボディに senderId が存在しない
400	request body must NOT have additional properties	サポートされないフィールドが含まれている
400	query parameter 'channelId' is required	必須のクエリパラメータが不足
400	Failed to create channel	追加IDが返らず作成に失敗
400	Failed to update channel	変更が検出されず更新に失敗
400	Failed to delete channel	削除処理に失敗
400	Failed to create subscription	追加IDが返らず作成に失敗
400	Failed to delete subscription	削除処理に失敗
400	Failed to create message	追加IDが返らず作成に失敗
400	Failed to update message	変更が検出されず更新に失敗
400	Failed to delete message	削除処理に失敗
401	token could not be verified	認可トークンがない/無効
401	Authentication failed	認証トークンがない/無効
401	Token fails security check	トークンのセキュリティ検証に失敗
403	User is not authorized to access this resource	権限不足（管理者アクセスが必要）
404	Channel not found	対象のチャンネルが存在しない
404	Subscription not found	対象のサブスクリプションが存在しない
404	Message not found	対象のメッセージが存在しない
404	Chat message not found	対象のチャットメッセージが存在しない
500	Failed to create channel	作成中のDB接続問題/予期せぬ失敗
500	Failed to get channel	取得中のDB接続問題/予期せぬ失敗
500	Failed to find channels	一覧取得中のDB接続問題/フィルタ不正/予期せぬ失敗
500	Failed to update channel	更新中のDB接続問題/予期せぬ失敗
500	Failed to delete channel	削除中のDB接続問題/予期せぬ失敗
500	Failed to create subscription	作成中のDB接続問題/予期せぬ失敗
500	Failed to get subscription	取得中のDB接続問題/予期せぬ失敗
500	Failed to find subscriptions	一覧取得中のDB接続問題/フィルタ不正/予期せぬ失敗
500	Failed to delete subscription	削除中のDB接続問題/予期せぬ失敗
500	Failed to create message	作成中のDB接続問題/予期せぬ失敗
500	Failed to get message	取得中のDB接続問題/予期せぬ失敗
500	Failed to find messages	一覧取得中のDB接続問題/フィルタ不正/予期せぬ失敗
500	Failed to update message	更新中のDB接続問題/予期せぬ失敗
500	Failed to delete message	削除中のDB接続問題/予期せぬ失敗

エラーレスポンス形式

主要なエンドポイントで返るエラーの形式は次のとおりです。サーバーが返す message の値は技術リテラルのため変更しません。

エラーを処理するクライアントは HTTP ステータスコードと error.message の両方を確認してください。 400 は通常、必須フィールドの不足、形式の不正、または追加プロパティを示します。 401 は認証トークンがない、無効、またはセキュリティ検証に失敗したことを示します。 403 は認証済みであっても、要求されたリソースに対するロールまたは所有権が不足していることを示します。 404 はチャンネル、購読、メッセージ、またはテンプレートが存在しないことを示します。 500 はストレージ接続、データベース操作、または予期しないサービス側の失敗を示します。バリデーションエラーでは、error.data に不正なフィールドや不足している値の詳細が含まれます。添付ファイルのアップロードでは、コンテンツタイプとファイルサイズの検証エラーも返されます。クライアントはサーバーから返されたエラーメッセージをそのまま利用できるよう、必要に応じて表示用の文言と分離してください。再試行可能な失敗かどうかは、ステータスコードと操作の種類に基づいて判断します。削除操作が成功した場合はレスポンスボディがないため、204 No Content を成功として扱います。一覧取得のレスポンスでは、metadata.pagination を使って次ページや前ページの有無を判定できます。権限エラーを受け取った場合は、組織ロール、チャンネル所有者、または購読状態を確認してください。チャンネルとメッセージの ID はパスパラメータとして渡し、URL エンコードが必要な値は適切に処理してください。署名付き URL は一時的なものなので、取得後は期限内にアップロードを完了してください。エラー内容をログへ記録する際は、アクセストークンやファイル URL に含まれる署名情報を出力しないでください。本番環境では、クライアントに返す表示文言と診断用の詳細情報を分けて管理することを推奨します。 WebSocket 接続の切断時は、必要に応じてチャンネル購読を再確立してください。メッセージテンプレートは、組織のコミュニケーション方針に合わせて定期的に見直してください。ファイル添付の MIME タイプは、クライアント側でも事前に確認すると利用者に分かりやすいエラーを示せます。管理者操作は監査可能なログと組み合わせ、誤った更新や削除を追跡できるようにしてください。必要に応じて、組織ロールを変更した直後にクライアントの認可状態を更新してください。ページネーションを利用する画面では、空の結果と最後のページを区別して扱います。サービス設定のシークレットは安全な環境変数またはシークレットストアから読み込んでください。

{ "error": { "message": "Channel not found" } }

{ "error": { "message": "Subscription not found" } }

{ "error": { "message": "Message not found" } }

{ "error": { "message": "Chat message not found" } }

{ "error": { "message": "Channel does not exist" } }

{ "error": { "message": "token could not be verified" } }

{ "error": { "message": "Token missing authentication" } }

{ "error": { "message": "Token fails security check" } }

{ "error": { "message": "Identity is not authorized to access this resource" } }

{ "error": { "message": "Failed to create channel" } }

{ "error": { "message": "Failed to update channel" } }

{ "error": { "message": "Failed to delete channel" } }

{ "error": { "message": "Failed to create subscription" } }

{ "error": { "message": "Failed to delete subscription" } }

{ "error": { "message": "Failed to create chat message" } }

{ "error": { "message": "Failed to update chat message" } }

{ "error": { "message": "Failed to delete chat message" } }

{
  "error": {
    "message": "Error message description",
    "data": ["Additional error details"]
  }
}

Validation Errors には追加情報が含まれます：

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'name'",
      "request body must have required property 'ownerId'"
    ]
  }
}

🔗 関連ドキュメント

アイデンティティサービス - チャット参加者のユーザー管理
組織サービス - チームベースのチャット編成
認証サービス - 認証と認可
エラーハンドリング - エラーパターンの理解
スキーマコンポーネント - データ検証の概念
カスタムサービスチュートリアル - チャット機能の拡張

🚀 クイックスタート​

📋 エンドポイント概要​

チャンネル操作​

サブスクリプション操作​

メッセージ操作​

メッセージテンプレート操作​

チャンネル既読状態の操作​

リアルタイムストリーミング​

🗄️ エンティティスキーマ​

チャンネルエンティティ​

サブスクリプションエンティティ​

メッセージエンティティ​

チャンネル既読状態エンティティ​

🔐 認証ヘッダー​

🔧 APIエンドポイント​

📺 チャンネル操作​

1. チャンネル作成​

2. チャンネル一覧​

3. チャンネル取得​

4. チャンネルアイコンのアップロード URL を取得​

5. チャンネル更新​

5. チャンネル削除​

📋 サブスクリプション操作​

6. サブスクリプション作成​

7. サブスクリプション一覧​

8. サブスクリプション取得​

9. サブスクリプション削除​

💬 メッセージ操作​

10. メッセージ作成​

11. メッセージ一覧​

12. メッセージ取得（ID指定）​

13. メッセージ更新​

14. メッセージ削除​

📝 メッセージテンプレート操作​

16. メッセージテンプレートを作成​

17. ID でメッセージテンプレートを取得​

18. メッセージテンプレートを更新​

19. メッセージテンプレートを削除​

20. メッセージテンプレート一覧​

21. 組織のメッセージテンプレート一覧​

22. チャンネル ID でメッセージを取得​

23. メッセージ添付ファイルのアップロード URL を取得​

24. メッセージ添付ファイルを作成​

25. メッセージ添付ファイルを削除​

26. チャンネル既読状態を upsert​

27. メッセージをストリーミング（WebSocket）​

⚙️ 設定オプション​

サービスデータストア​

サービス設定​

設定詳細​

🔐 セキュリティ設定​

👥 ユーザー種別設定​

🏢 組織設定​

設定例​

🚨 エラーハンドリング​

代表的なエラーコード​

エラーレスポンス形式​

🔗 関連ドキュメント​

🚀 クイックスタート

📋 エンドポイント概要

チャンネル操作

サブスクリプション操作

メッセージ操作

メッセージテンプレート操作

チャンネル既読状態の操作

リアルタイムストリーミング

🗄️ エンティティスキーマ

チャンネルエンティティ

サブスクリプションエンティティ

メッセージエンティティ

チャンネル既読状態エンティティ

🔐 認証ヘッダー

🔧 APIエンドポイント

📺 チャンネル操作

1. チャンネル作成

2. チャンネル一覧

3. チャンネル取得

4. チャンネルアイコンのアップロード URL を取得

5. チャンネル更新

5. チャンネル削除

📋 サブスクリプション操作

6. サブスクリプション作成

7. サブスクリプション一覧

8. サブスクリプション取得

9. サブスクリプション削除

💬 メッセージ操作

10. メッセージ作成

11. メッセージ一覧

12. メッセージ取得（ID指定）

13. メッセージ更新

14. メッセージ削除

📝 メッセージテンプレート操作

16. メッセージテンプレートを作成

17. ID でメッセージテンプレートを取得

18. メッセージテンプレートを更新

19. メッセージテンプレートを削除

20. メッセージテンプレート一覧

21. 組織のメッセージテンプレート一覧

22. チャンネル ID でメッセージを取得

23. メッセージ添付ファイルのアップロード URL を取得

24. メッセージ添付ファイルを作成

25. メッセージ添付ファイルを削除

26. チャンネル既読状態を upsert

27. メッセージをストリーミング（WebSocket）

⚙️ 設定オプション

サービスデータストア

サービス設定

設定詳細

🔐 セキュリティ設定

👥 ユーザー種別設定

🏢 組織設定

設定例

🚨 エラーハンドリング

代表的なエラーコード

エラーレスポンス形式

🔗 関連ドキュメント