Team and access

すべてのパスは Public API base URL に追加します。各リクエストに X-Api-Key を付け、表で JSON ボディを指定している場合は Content-Type: application/json も付けてください。AI-client の DELETE もボディを使います。対象ストアはキーで決まり、ボディにストア ID を入れても切り替わりません。

操作権限と上限

操作主体の admin は、呼び出し用キーの作成時に記録されたメンバーです。API はそのメンバーを再取得し、同じストアに属して active: true と role: "admin" を満たすことを確認します。作成者が不明、削除・無効化済み、または role が変わっている場合は 403 KEY_OWNER_NOT_ADMIN を返します。保存値が active: null の場合も通りません。管理用スコープを持っているだけでは不十分です。

この確認は POST /members、メンバーの PATCH・状態変更・削除・再招待・通知設定の書き込み、4 つの /api-keys 操作、両方の /ai-clients 操作に適用されます。GET /members、GET /members/{id}、GET /members/{id}/notifications には適用されません。

毎時上限は追加の固定期間カウンターです。Public API 共通の、キーごとに毎分 120 リクエスト、送信元 IP ごとに毎分 300 リクエストの制限も適用されます。POST /members/{id}/resend-invite は共通制限を使い、毎時 20 回の招待カウンターは共有しません。招待や再送の成功は送信処理の完了を意味し、受信者が開封・承諾したことを意味しません。

メンバーを読み取る

3 つともボディは不要で、成功時は 200 を返します。Pro / Plus で作成したキーに、表のスコープを付けてください。members:write は members:read を含みますが、一覧に必要な conversations:read は含みません。

メンバーの例は抜粋です。読み取りでは、保存されている id、email、firstName、lastName、fullName、avatarUrl、role、active、enableAwayMode、createdAt を返します。招待中は active: null の場合があります。パスワード、認証 ID、デバイストークン、完全な権限マップは返しません。メンバーが存在しないか別のストアに属する場合は 404 NOT_FOUND です。

通知設定の読み取りでは、保存されている pushTopics、emailTopics、forwardTopicEmails、enabledSoundOpt、topicEmail、verifiedTopicEmail を返します。デバイスの push token は返しません。

招待と再送

両方とも members:write、Pro / Plus で作成したキー、および操作主体の admin の確認が必要です。招待には、現在のチーム利用資格または購入済み追加シートと、空きシートが必要です。

email は有効なアドレスが必要で、検証後に小文字へ変換します。前後の空白は送信前に除去してください。firstName と lastName は任意の文字列、permissions は任意で後述のカタログを使います。新規レコードは常に role: "staff"、有効化待ちの active: null です。role、active、認証 ID を送信しても設定できません。

招待時のシート数には、招待中と有効な人間のメンバーを含みます。上限はプランのシート数と購入済み追加シートの合計です。招待リンクは 24 時間で失効するため、新しいリンクが必要なら再送してください。既存メールアドレスを POST で招待すると、招待中であっても 409 MEMBER_EXISTS を返します。再送ルートを使ってください。有効なメンバーへの再送は 409 ALREADY_ACTIVE、メンバーが存在しないか別のストアに属する場合は 404 NOT_FOUND です。

不正なメール、名前の型、権限は 400 INVALID_PARAMS、チームの利用資格不足は 403 PLAN_REQUIRED、シート上限超過は 409 MEMBER_LIMIT_EXCEEDED を返します。メールの失敗はサーバーエラーで、招待中のメンバーを保存した後に起こる場合があります。作成を再試行する前にメンバー一覧を確認してください。

curl -X POST 'https://app.chatty.net/v1/members' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","firstName":"Example","lastName":"Teammate"}'

staff の編集、有効化、削除

これらのルートには members:write、Pro / Plus で作成したキー、および操作主体の admin の確認が必要です。最後の admin だけでなく、すべての admin を対象とする操作を 403 ADMIN_TARGET_FORBIDDEN で拒否します。そのため、操作主体の admin が自分を編集、無効化、削除することもできません。role の変更や所有権の移転には対応しません。

PATCH で指定できる項目は次のとおりです。

プロフィールの PATCH は、email、avatarUrl、role、active を含む未対応の項目を無視します。許可された項目が 1 つも残らなければ 400 INVALID_PARAMS を返します。許可された項目でも値が不正なら 400 INVALID_PARAMS です。名前の変更で他の名前項目がすべて再計算されるわけではないため、変更したい項目を明示的に送信してください。

状態変更のボディには真偽値の active が必須です。有効化時は有効なメンバー数の上限を再確認し、409 MEMBER_LIMIT_EXCEEDED を返す場合があります。無効化すると、そのメンバーの OAuth 接続と Firebase セッションを失効させ、push 配信を止めます。メンバーや会話は削除しません。

削除はセッションを失効させてから staff レコードを削除します。その後、過去 30 日以内に活動があった未解決の会話を最大 500 件まで再割り当てし、担当可能な人がいなければ割り当て待ちにします。再割り当ては可能な範囲で行い、失敗しても削除後にログを記録するだけで、削除を取り消したり失敗レスポンスに変えたりしません。過去の全割り当てが移行したとは仮定しないでください。対象が存在しないか別のストアに属する場合は 404 NOT_FOUND です。

メンバー権限のカタログ

これらの UI 権限は API キーのスコープとは別です。権限を変更できるのは admin だけです。公開の staff 編集ルートは呼び出し元を含む全 admin を 403 ADMIN_TARGET_FORBIDDEN で拒否し、admin は全権限を保持します。permissions オブジェクトは保存済みマップを置き換えるため、意図したマップ全体を送信してください。省略項目はカタログの既定値やフォールバックに従うので、省略が none を意味するわけではありません。

未知の権限キーや未対応のレベルは 400 INVALID_PARAMS を返します。ただし、対象メンバーにすでに保存されている廃止済みの未知キーは、検証時に除外される場合があります。メンバー権限を付与しても、それに対応する Public API のエンドポイントや API キースコープが新しく利用可能になるわけではありません。

通知設定を更新する

PATCH /members/{id}/notifications には members:write、Pro / Plus で作成したキー、および操作主体の admin の確認が必要です。staff のプロフィール・状態変更・削除とは異なり、通知設定は操作主体を含む admin も対象にできます。

両方の配列に指定できるトピック名：

conversation-assigned
new-message-assigned
conversation-mentioned
conversation-assigned-others
new-message-assigned-others
conversation-assigned-chatbot
new-message-unassigned
new-unassigned-from-ai
agent-unassigned
no-replies

未知のトピック文字列は除外しますが、文字列でない配列要素は拒否します。pushTokens、トークンのプラットフォーム情報、verifiedTopicEmail はここでは書き込めません。未対応の項目は無視し、通知項目が 1 つも残らなければ 400 INVALID_PARAMS を返します。メール、サウンド設定、配列の型が不正な場合も 400 INVALID_PARAMS です。

curl -X PATCH 'https://app.chatty.net/v1/members/member_123/notifications' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"emailTopics":["conversation-assigned"],"enabledSoundOpt":"first","topicEmail":"[email protected]"}'

成功時は 200 {"success":true} です。topicEmail の更新だけでは認証されず、認証完了までは以前の認証済みアドレスを配信に使います。この書き込みにより認証メールの送信や会話の通知設定の同期が行われる場合があります。メンバーが存在しないか別のストアに属する場合は 404 NOT_FOUND です。

API キーを管理する

4 つのルートすべてに api_keys:write、操作主体の admin の確認、現在の Pro / Plus プランが必要です。呼び出し用キーへの api_keys:write は Settings → General → Manage keys で付与してください。これらのエンドポイントから別のキーへ委譲することはできません。

GET は有効なキーだけを返します。メタデータは、保存されている id、maskedKey、title、scopes、apiVersion、createdAt です。旧キーが含まれる場合もありますが、公開ルートでの変更・失効はできません。ダッシュボードを使ってください。

POST の title は空白以外を含む文字列で、トリミング前に最大 50 文字です。scopes を指定する場合は既知のスコープ文字列の配列にします。省略時は []、重複は除去されます。新しいキーは呼び出し用キーの作成者を引き継ぎ、現在の API バージョンで作成します。シークレットは作成時に一度だけ返し、そのレスポンスに createdAt は含まれません。すぐに保存してください。GET、PATCH、DELETE では復元できません。

要求するスコープは、呼び出し元が実際に持つ権限の範囲内である必要があります。例えば customers:write を持つキーから customers:read のキーを作成できますが、無関係な権限は付与できません。api_keys:write を要求に含めると、呼び出し元自身が持っていても 400 INVALID_PARAMS を返します。

PATCH は scopes が必須で、スコープを置き換えます。タイトル、シークレット、固定バージョンは変更しません。PATCH または DELETE の前に、対象の現在のスコープも呼び出し元の権限内であることを確認します。変更後に狭める予定でも、現在の対象が広い権限を持っていれば 403 FORBIDDEN です。対象が存在しない、別のストアに属する、または失効済みなら 404 NOT_FOUND、旧キーなら 403 FORBIDDEN になります。

キーに自動の有効期限はなく、これらのリクエストで期限を指定する項目もありません。失効後は新たな認証リクエストを拒否し、監査記録用のキー ID は保持します。入れ替えは、有効キー 5 個の上限内で、作成 → 連携先の切り替え → 古いキーの失効の順に行ってください。現在のキー管理プランを満たさなければ 403 PLAN_REQUIRED、有効キーの上限超過は 409 KEY_LIMIT_REACHED です。

AI client の一覧と切断

両方のルートに members:write、Pro / Plus で作成したキー、および操作主体の admin の確認が必要です。管理するのは既存の merchant OAuth 接続で、API キーや新規 OAuth 登録ではありません。

GET は未失効の許可を、クライアントと接続したメンバーの正確な組ごとにまとめます。各グループには、取得可能な clientId、clientName、clientHost、connectedByMemberId、connectedByName、createdAt、lastUsedAt、scopes が含まれます。scopes は文字列ではなく、value、label、description を持つ説明オブジェクトです。スコープの重複を除き、最も古い作成日時と最新の利用日時を返します。アクセストークン、更新トークン、内部接続 ID は返しません。

切断するには、1 つのグループの clientId と connectedByMemberId をコピーし、後者をボディの memberId として送信してください。両方とも空白以外を含む文字列が必要です。識別子の内部形式は解釈せず、URL 正規化、トリミング、自作をせずに値をそのまま保持してください。connectedByName や内部接続 ID は指定しません。

DELETE は、呼び出し元のストア内で、その client/member の組に一致するすべての有効な許可を失効させます。有効な形式の組でも一致する許可がなければ 200 {"success":true} を返し、404 にはなりません。識別子が未指定または不正な場合は 400 INVALID_PARAMS です。同じ切断を繰り返しても問題ありません。再接続には通常の OAuth 同意手順が必要です。

共通エラー

検証や権限確認のエラーは次の形式です。

{"error":{"code":"KEY_OWNER_NOT_ADMIN","message":"The API key owner must be an active shop admin"}}

予期しないサービスやメールの失敗では、このコード付き形式ではなくサーバーエラーになる場合があります。後続のメールや監査処理で失敗する前に、すでに保存済みの場合があるため、再試行前に現在の状態を確認してください。書き込みには認証済みキーと操作主体の admin が記録されますが、汎用の冪等性キーはありません。