チームAPI #

チームとは、あなた以外のアカウント内で作業するすべての人（管理者、エージェント、閲覧専用ユーザー）に加え、あなたが送信した招待、およびそれらを整理する部門を指します。チームAPIは、設定 → チームのプログラム版であり、メンバーの追加や削除、各メンバーの権限設定、招待の送信や催促、部門の管理を行うことができます。

以下のすべてのエンドポイントは、ベースURL https://api.youraiconnector.com/v1 に対する相対パスです。このページで説明するすべての機能のダッシュボード版については、チーム管理を参照してください。

認証：これらのエンドポイントにはサインインしたユーザーが必要です #

これはAPIキーを使用できないAPIの一部です。 部門関連のエンドポイントを除くすべての /team エンドポイントは、サインインしたセッションから取得した Firebase IDトークンを使用して呼び出す必要があります。

Authorization: Bearer <Firebase ID token>

代わりにAPIキーを送信すると、リクエストは 401 で拒否されます。

{
  "success": false,
  "error_code": 401,
  "error": "This endpoint requires a Firebase ID token (Authorization: Bearer <token>)."
}

その理由は、これらのエンドポイントが誰がサインインしているか（あなたのロール、他者に付与できる権限の上限、現在別のアカウント内で作業中かどうか）に基づいて処理を決定するためです。APIキーは統合ツールであり、個人ではないため、これらのルールを適用する対象が存在しません。

実際には、チームAPIはログインした Your AI Connector ユーザーを持つファーストパーティアプリ向けであることを意味します（認証 → Firebase IDトークンを参照）。サーバー間統合ではチームメンバーを管理できません。アプリの外部からこれらのトークンを作成する方法はないためです。

例外： 4つの部門エンドポイントは通常のAPIエンドポイントです。これらは、APIの他の部分と同様にAPIキーを受け入れるほか、サインインしたセッションでも利用可能です。

このページのすべてのレスポンスは、通常のエンベロープに従います。トップレベルに success: true とエンドポイントのフィールドが含まれるか、エラーが発生した場合は success: false に error と error_code が含まれます。

ロールと権限 #

すべてのチームメンバーには1つのロールがあり、アプリ内の12の領域に対するデフォルトのアクセス権が設定されます。その後、個別の領域ごとに権限を上書きできます。

各領域は、none（非表示）、view（読み取り専用）、edit（作成および変更）、full（削除を含む）の4つのレベルのいずれかに設定されます。

ロールのデフォルトから変更するには、permission_overrides（{ "area": ..., "level": ... }オブジェクトの配列）を送信します。各エントリはその領域のロールのデフォルトを置き換えます。リストに含まれていないものはすべて、ロールのデフォルトが維持されます。

"permission_overrides": [
  { "area": "analytics", "level": "full" },
  { "area": "billing", "level": "none" }
]

これらのエンドポイントを呼び出せるユーザー

• アカウント所有者は常にすべての操作を行えます。
• チームメンバーが名簿や招待リストを読み取るにはviewのteam_managementが必要であり、追加、変更、一時停止、削除、招待、キャンセル、再送を行うにはeditの権限が必要です。管理者はデフォルトでeditを持っています。編集者と閲覧者はnoneを持っているため、デフォルトでは管理者のみがチームを管理できます。
• 自分より高い権限を付与することはできません。 自分自身が保持していないレベルを誰かに付与しようとしたり、自分よりも広いアクセス権を持つユーザーを編集、一時停止、削除しようとしたりすると、リクエストは403と対象領域を示すメッセージとともに拒否されます。

チームメンバーオブジェクト #

GET /team/membersは、メンバーごとに以下のいずれかを返します。

削除されたメンバーは返されません。リストにはアクティブなメンバーと一時停止中のメンバーのみが含まれます。

可視性の制限は、ここでは書き込み専用です。 contact_scope、contact_scope_axes、およびsub_account_access（メンバーの表示範囲の制限を参照）は、作成、更新、招待時に設定できますが、このエンドポイントでは返されません。

チームメンバーの一覧表示 #

GET /team/members

名簿とプランのシート数（座席数）を返します。これにより、「5席中3席使用」といった表示が可能になり、招待が拒否されるタイミングを把握できます。

cURL

curl "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  headers: { Authorization: `Bearer ${idToken}` },
});
const { members, seat_limit, seats_used } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/team/members",
    headers={"Authorization": f"Bearer {id_token}"},
)
data = res.json()

レスポンス

{
  "success": true,
  "members": [
    {
      "account_owner_uid": "owner_uid_123",
      "member_uid": "uid_alice",
      "member_email": "alice@example.com",
      "member_display_name": "Alice Chen",
      "role": "admin",
      "permission_overrides": [],
      "status": "active",
      "auto_assign_enabled": true,
      "created_by": "owner_uid_123",
      "created_at": "2026-05-01T10:00:00.000Z",
      "updated_at": "2026-06-02T09:15:00.000Z"
    }
  ],
  "seat_limit": 5,
  "seats_used": 3
}

プランにシート数の上限がない場合、seat_limitはnullになります。seats_usedはアクティブなメンバーのみをカウントします。メンバーを一時停止または削除すると、そのシートは即座に解放されます。

チームメンバーを直接追加する #

POST /team/members

招待なしで、チームに直接メンバーを追加します。

この操作ではメールは送信されません。 追加されたことは本人に通知されません。また、すでに Your AI Connector のログイン情報を持っていない場合、作成されたアカウントには パスワードが設定されていない ため、パスワードをリセットするまでサインインできません。本人に連絡してサインインしてもらう独自の方法がない限り、招待を送信 を使用してください。

リクエストフィールド

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "role": "editor"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "sam@example.com",
    display_name: "Sam Rivera",
    role: "editor",
  }),
});
const { member_uid } = await res.json();

レスポンス — 201 Created

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "member_uid": "uid_sam",
  "message": "Team member created successfully."
}

以前に 停止または削除された メンバーを追加すると、失敗するのではなく、そのメンバーが復帰します。

チームメンバーを更新する #

PATCH /team/members/{memberUid}

メンバーのロール、権限、表示範囲、クライアントアクセス、または自動連絡先割り当てへの参加の有無を変更します。変更したいフィールドのみを送信してください。省略したフィールドは現在の値が保持されます。

リクエストフィールド

このエンドポイントでのみ、null は「クリア」を意味します。 "contact_scope": null、"contact_scope_axes": null、または "sub_account_access": null を送信すると、その制限が完全に解除され、メンバーはすべてを表示できる状態に戻ります。作成および招待時、null は単に「未指定」を意味します。

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "permission_overrides": [{ "area": "billing", "level": "none" }]
  }'

レスポンス

{
  "success": true,
  "message": "Team member updated successfully."
}

チームメンバーを停止する #

POST /team/members/{memberUid}/suspend

メンバーを停止します。チーム内での場所は保持されますが、アクセス権が失われます。一時的な停止の場合は削除の代わりに使用してください。復帰させるには PATCH /team/members/{memberUid} と {"status": "active"} を使用します。

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members/uid_sam/suspend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

レスポンス

{
  "success": true,
  "message": "Team member suspended successfully."
}

停止されたメンバーは シートを解放する ため、代わりに他のメンバーを招待できます。アクセス権は現在のセッションのトークンが次に更新されるときに終了します（最大1時間かかる場合があります）。即座にアクセスを終了させる必要がある場合は、削除を行ってください。

チームメンバーを削除する #

DELETE /team/members/{memberUid}

チームからメンバーを削除し、その席を解放します。削除されたメンバーはサインアウトされ、アカウントへのアクセス権を失いますが、そのメンバー自身のログインアカウントには影響しません。

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

レスポンス

{
  "success": true,
  "message": "Team member removed successfully."
}

削除はあなた側から見て永続的なものです。削除されたメンバーは、更新エンドポイントを使用して再有効化することはできません。気が変わった場合は、再度招待してください。また、そのメールアドレスはアカウントの通知リストからも削除されます。

メンバーの閲覧範囲を制限する #

追加、更新、招待の各操作で受け入れられる3つのオプションフィールドにより、その人物がアカウントのどの範囲まで閲覧できるかを決定します。これらは累積されます。複数の制限が適用されているメンバーは、そのすべてによって制限されます。

contact_scope — all（デフォルト：すべての連絡先と会話）または assigned（自分に割り当てられたもののみ）。assigned を使用する場合、"contact_scope_unassigned": true を追加すると、まだ誰も所有していない連絡先も閲覧できるようになります。

contact_scope_axes — 指定したエージェント、チャネル、または部門のみに制限します：

エージェントIDと部門IDは保存時にチェックされません。存在しないIDは単に何も一致しないだけとなり、エラーではなく空の受信トレイとして表示されます。チャネル名はチェックされます。認識されないチャネル名は 400 で拒否されます。

これら3つの設定はいずれもアカウント所有者には適用できません。そのリクエストは 400 で拒否されます。

招待リスト #

GET /team/invites

送信済みの招待を新しい順に表示します。誰がまだ承諾していないかを確認できます。

クエリパラメータ

cURL

curl "https://api.youraiconnector.com/v1/team/invites?status=pending" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

レスポンス

{
  "success": true,
  "invites": [
    {
      "id": "inv_abc123",
      "account_owner_uid": "owner_uid_123",
      "account_owner_display_name": "Acme Ltd",
      "invitee_email": "sam@example.com",
      "invitee_uid": null,
      "role": "editor",
      "permission_overrides": [],
      "status": "pending",
      "created_by": "owner_uid_123",
      "created_at": "2026-06-10T12:00:00.000Z",
      "expires_at": "2026-06-17T12:00:00.000Z",
      "responded_at": null
    }
  ]
}

招待トークンは返されません。送信されたメール内にのみ存在します。

招待を送信する #

POST /team/invites

チームへの参加招待をメールで送信します。これがチームメンバーを追加する一般的な方法です。相手がリンクをクリックして自身のアカウントでサインインし、承諾することで完了します。相手がまだ Your AI Connector アカウントを持っていない場合は、その人のためにアカウントが作成され、メールでパスワードの設定手順が案内されます。

リクエストフィールド

事前に権限を設定しておけば、後でメンバーを編集する必要はありません。承諾時にすべてがメンバーシップにコピーされます。

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "sam@example.com", "role": "editor" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/invites", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "sam@example.com", role: "editor" }),
});
const { invite_id } = await res.json();

レスポンス — 201 Created

{
  "success": true,
  "invite_id": "inv_abc123",
  "message": "Team invite sent successfully."
}

計画しておくべきこと

• 招待の有効期限は7日間です。 期限切れの招待は再送でき、その時点で新たに7日間の有効期限が始まります。
• 保留中の招待はシートを占有します。 メンバーを直接追加する場合とは異なり、ここでのシートチェックは、アクティブなメンバー数に保留中の招待数を加算してカウントされます。そのため、すべてのシートが埋まっているアカウントでは、メールが送信される前に拒否されます。
• 1日あたり20件の招待制限があります。 これはアカウントごとに、送信と再送を合計してカウントされます。

招待を取り消す #

DELETE /team/invites/{inviteId}

招待が承認される前に取り消します。メール内のリンクは無効になります。

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/invites/inv_abc123" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

レスポンス

{
  "success": true,
  "message": "Team invite cancelled."
}

pending および expired の招待はどちらもキャンセル可能です。すでに承認、拒否、またはキャンセルされた招待は 400 を返します。自分のものではない招待は 403 を返し、不明なIDは 404 を返します。

招待を再送する #

POST /team/invites/{inviteId}/resend

招待メールを再送信します（見逃した場合や迷惑メールフォルダに入ってしまった場合など）。pending および expired の招待に対して機能し、有効期限を現在から7日間にリセットします。

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/inv_abc123/resend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

レスポンス

{
  "success": true,
  "message": "Team invite resent successfully."
}

新しいメールには新しいリンクが含まれますが、古いリンクも引き続き機能するため、後から最初のメールを見つけたユーザーが困ることはありません。再送も送信と同様に1日20件の制限の対象となり、期限切れの招待を再有効化する際には座席数が再確認されます。プランが満席の場合は 429 で拒否されます。

招待を承認する #

POST /team/invites/accept

招待メール内のトークンを使用して招待を承認し、サインインしているユーザーをそのアカウントのチームに参加させます。

これはあなた自身のアイデンティティによる操作です。 自分自身としてサインインしてください。他人のアカウント内で作業している間は、意図的に 403 で拒否されます。

リクエストフィールド

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/accept" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

レスポンス

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "account_owner_uid": "owner_uid_123",
  "message": "Team invite accepted successfully."
}

招待を拒否する #

POST /team/invites/decline

メール内のトークンを使用して招待を拒否します。承認と同様に、これはあなた自身のアイデンティティによる操作であり、別のアカウント内で作業している間は拒否されます。

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/decline" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

レスポンス

{
  "success": true,
  "message": "Team invite declined."
}

部門 #

部門とは、営業、カスタマーサポート、人事など、チーム内のグループに名前を付けたものです。部門を設定すると、リードに担当チームを割り当てたり、部門単位で新しい会話を取得したりできるほか、メンバーが閲覧できる範囲を制限することも可能です。

これら4つのエンドポイントはAPIキーを使用します。 このページの他のエンドポイントとは異なり、APIの他のすべてのエンドポイントと同様の認証方法（認証を参照）を使用します。サインインしたセッションでも機能します。読み取りには view での contacts が必要であり、作成、変更、削除には edit での team_management が必要です。

部門オブジェクト

routing_agents と routing_channels の両方が設定されている場合、会話は両方に一致しないとここに分類されません。これにより、「サポートエージェントだがWhatsAppのみ」といったチームへの割り当てが可能になります。

1つのアカウントにつき最大 50 個の部門を作成できます。

部門の一覧を取得 #

GET /team/departments

curl "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "departments": [
    {
      "id": "dep_abc123",
      "name": "Sales",
      "color": "#2f6fed",
      "member_uids": ["uid_alice", "uid_bob"],
      "auto_assign_enabled": true,
      "routing_agents": [],
      "routing_channels": ["whatsapp"],
      "created_by": "owner_uid_123"
    }
  ]
}

部門を作成 #

POST /team/departments

リクエストフィールド

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "routing_channels": ["whatsapp"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/departments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Sales",
    color: "#2f6fed",
    member_uids: ["uid_alice", "uid_bob"],
    routing_channels: ["whatsapp"],
  }),
});
const { department } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/team/departments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Sales",
        "color": "#2f6fed",
        "member_uids": ["uid_alice", "uid_bob"],
        "routing_channels": ["whatsapp"],
    },
)
department = res.json()["department"]

レスポンス — 201 Created

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "auto_assign_enabled": true,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

部門を更新 #

PATCH /team/departments/{departmentId}

部門を変更します。送信したフィールドのみが変更されます。

curl -X PATCH "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "member_uids": ["uid_alice"], "auto_assign_enabled": false }'

レスポンス

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice"],
    "auto_assign_enabled": false,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

認識されないフィールドを送信すると 400 が返され、不明な部門を送信すると 404 が返され、他の部門と競合する名前を送信すると 409 が返されます。

部門を削除する #

DELETE /team/departments/{departmentId}

curl -X DELETE "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY"

レスポンス

{
  "success": true,
  "deleted": "dep_abc123"
}

特定の部門に制限されているメンバーがいる場合、その部門の削除は拒否されます。 400 レスポンスには、その部門に可視性が制限されているメンバーの名前が含まれるため、先にそのメンバーのスコープを再設定できます。これは意図的な仕様です。警告なしに制限を解除してしまうと、そのメンバーに顧客ベース全体が公開されてしまい、その事実を示す痕跡も残らないためです。

削除された部門に登録されていた連絡先は書き換えられません。単に部門が表示されなくなるだけで、次回登録する際に改めて部門が設定されます。

自身の権限を確認する #

GET /team/permissions

現在作業中のアカウントで、サインインしているユーザーに許可されている操作を返します。メンバーが使用できないボタンをエラーで制限を知らせるのではなく、あらかじめ非表示にするために使用してください。

cURL

curl "https://api.youraiconnector.com/v1/team/permissions" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

レスポンス — アカウント所有者の場合

{
  "success": true,
  "role": "owner",
  "is_team_mode": false,
  "permissions": {
    "campaigns": "full",
    "contacts": "full",
    "messages": "full",
    "appointments": "full",
    "settings": "full",
    "billing": "full",
    "team_management": "full",
    "analytics": "full",
    "phone_numbers": "full",
    "integrations": "full",
    "faqs": "full",
    "daily_summaries": "full"
  }
}

レスポンス — アカウント内で作業中のチームメンバーの場合

{
  "success": true,
  "role": "editor",
  "is_team_mode": true,
  "permissions": { "campaigns": "edit", "billing": "none", "…": "…" },
  "member": {
    "uid": "uid_sam",
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "account_owner_uid": "owner_uid_123"
  }
}

サインインしているユーザーがアカウント所有者の場合、role は owner になります。それ以外の場合は、そのユーザーのチームロールになります。member はチームモードでのみ存在し、メンバーシップに contact_scope、contact_scope_unassigned、contact_scope_axes が含まれている場合にそれらを保持します。

セッショントークン #

5つのエンドポイントが、アカウントを切り替えるためのワンタイムサインイントークンを発行します。これらはすべて同じ方法で応答します。

{
  "success": true,
  "customToken": "eyJhbGciOi…"
}

このトークンは、FirebaseクライアントSDKのセッションと交換されます。これはAPIキーではないため、APIキーとして送信することはできません。 そのため、これらのエンドポイントはファーストパーティアプリ内でのみ有効です。

セッションに権限がない場合、403で拒否されます。権限がない理由としては、そのアカウントのメンバーではない、スタッフではない、そのサブアカウントが所属するエージェンシーにない、またはあなたに付与されていない、あるいはセッションが現在エンドポイントが要求するモードではない、などが挙げられます。

プラットフォームロールの割り当て #

POST /team/users/{targetUid}/role

ユーザーのプラットフォームロール（User、Dev、Support、またはAgency）を設定します。これはチームメンバーシップではなく、その人物がどのようなYour AI Connectorアカウントを持っているかを示すものです。

このエンドポイントはYour AI Connectorスタッフに制限されており、最後の1人のDevを降格させることはできません。完全を期すために記載していますが、これは自身のチーム管理の一部ではありません。

{
  "success": true,
  "targetUid": "uid_sam",
  "role": "Agency",
  "claimUpdated": true
}

チームAPIエラー #

チームエンドポイントは標準のエラーエンベロープを返し、常にHTTPステータスとともにerror_codeを含みます：

{
  "success": false,
  "error_code": 403,
  "error": "Cannot grant \"full\" access to \"billing\" — exceeds your own permissions."
}

すべてのエンドポイントが返す可能性のある共通コード（429（レート制限）および500）については、再試行のガイダンスとともにエラーとページネーションに記載されています。

関連情報 #

• チーム管理 — ダッシュボードでの同じ機能（スクリーンショット付き）。
• 認証 — APIキーの代わりにFirebase IDトークンを送信する方法。
• 連絡先API — メンバーの可視性制限が適用される連絡先。