团队 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 令牌）。服务器到服务器的集成无法管理团队成员——无法在应用程序外部生成这些令牌。

例外情况： 四个部门端点是普通的 API 端点。它们像 API 的其余部分一样接受您的 API 密钥，同时也接受已登录的会话。

本页面上的每个响应都遵循通常的信封格式：success: true 以及顶层的端点字段，或者在出错时返回带有 error 和 error_code 的 success: false。

角色和权限

每个团队成员都有一个角色，该角色设定了他们在应用程序 12 个区域中的默认访问权限。随后，您可以覆盖各个区域的权限。

角色	值	摘要
管理员	`admin`	除所有者级别的计费操作外，拥有所有权限。
编辑者	`editor`	可以创建和更改内容。在应用程序中显示为坐席。
查看者	`viewer`	只读。

每个区域被设置为四个级别之一：none（隐藏）、view（只读）、edit（创建和更改）、full（包括删除）。

区域	管理员	编辑者	查看者
`campaigns`	full	edit	view
`contacts`	full	edit	view
`messages`	full	edit	view
`appointments`	full	edit	view
`settings`	edit	view	none
`billing`	edit	none	none
`team_management`	edit	none	none
`analytics`	full	view	view
`phone_numbers`	edit	none	none
`integrations`	edit	none	none
`faqs`	full	edit	view
`daily_summaries`	full	view	view

若要偏离角色的默认设置，请发送 permission_overrides（一个 { "area": ..., "level": ... } 对象数组）。每个条目都会替换该角色在特定区域的默认设置；未列出的所有内容都将保持角色默认值。

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

谁可以调用这些端点

账户所有者始终拥有所有权限。
团队成员需要 view 处的 team_management 权限才能读取花名册和邀请列表，并需要 edit 处的权限才能进行添加、更改、暂停、移除、邀请、取消或重新发送操作。管理员默认拥有 edit 权限；编辑者和查看者拥有 none 权限，因此默认情况下只有管理员可以管理团队。
任何人不得授予高于自身权限的访问权限。 如果您尝试授予某人您自己都不具备的权限级别，或者尝试编辑、暂停或移除权限范围已超过您的人员，请求将被拒绝，并返回 403 以及说明相关区域的消息。

团队成员对象

GET /team/members 会为每位成员返回以下对象之一：

字段	类型	描述
`member_uid`	string	成员自己的用户 ID。这是下方路径中的 `{memberUid}`。
`account_owner_uid`	string	他们所属的账户。
`member_email`	string	他们的电子邮件地址。
`member_display_name`	string	他们在应用程序中显示的名称。
`role`	string	`admin`、`editor` 或 `viewer`。
`permission_overrides`	array	他们在各区域的例外设置。`[]` 表示他们完全遵循角色默认设置。
`status`	string	`active` 或 `suspended`。
`auto_assign_enabled`	boolean \| null	是否可以将新联系人自动分配给他们。`null` 表示从未更改，其行为与 `true` 相同。
`created_by`	string	添加他们的人。
`created_at`	string \| null	ISO 8601 时间戳。
`updated_at`	string \| null	ISO 8601 时间戳。

已移除的成员不会被返回——该列表仅包含活跃成员和已暂停成员。

可见性限制在此处仅为写入权限。 contact_scope、contact_scope_axes 和 sub_account_access（请参阅限制成员可见范围）可以在创建、更新和邀请时设置，但此端点不会返回它们。

列出团队成员

GET /team/members

返回花名册以及您套餐的席位统计信息，以便您可以显示“已用 3 个，共 5 个席位”，并了解何时即将无法发送邀请。

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 登录账号，为他们创建的账户将没有密码，因此在重置密码之前他们无法登录。除非你有自己的方式通知对方并让他们登录，否则请使用发送邀请。

请求字段

字段	必填	说明
`email`	是	团队成员的电子邮件地址。
`display_name`	是	在应用中显示的成员姓名。
`role`	是	`admin`、`editor` 或 `viewer`。
`permission_overrides`	否	针对角色默认设置的各区域例外情况。
`contact_scope`	否	`all` 或 `assigned` — 请参阅限制成员可见范围。
`contact_scope_unassigned`	否	使用 `assigned` 时，允许他们查看尚未归属任何人的联系人。
`contact_scope_axes`	否	将其限制为指定的座席、渠道或部门。
`sub_account_access`	否	仅限代理机构 — 他们可以打开哪些客户子账户。

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."
}

状态	情况
`400`	缺少 `email`、`display_name` 或 `role`，角色不是这三种之一，或者你尝试添加自己。
`403`	你没有管理团队的权限，或者你尝试授予高于你自身权限的访问权。
`409`	该人员已经是你团队中的活跃成员。
`429`	你套餐中的团队席位已满。

添加之前被暂停或移除的人员会恢复其状态，而不是报错。

更新团队成员

PATCH /team/members/{memberUid}

更改成员的角色、权限、可见性、客户访问权限，或他们是否参与自动联系人分配。仅发送你想要更改的字段；任何你省略的字段将保持其当前值。

请求字段

字段	说明
`role`	`admin`、`editor` 或 `viewer`。
`permission_overrides`	替换其整个覆盖列表。发送 `[]` 以使其恢复为纯角色默认设置。
`status`	仅接受 `active`，用于恢复已暂停的成员。要暂停某人，请使用暂停端点。
`auto_assign_enabled`	`true` 或 `false`。
`contact_scope`	`all` 或 `assigned`。
`contact_scope_unassigned`	`true` 或 `false`。
`contact_scope_axes`	请参阅限制成员可见范围。
`sub_account_access`	仅限代理机构。

这是唯一一个 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."
}

状态	情况
`400`	`status` 或 `auto_assign_enabled` 值无效，或者你尝试重新激活已被移除的成员（被移除的成员必须重新邀请）。
`403`	你没有权限，或者更改后的访问权限范围超出了你自身的权限。
`404`	无此团队成员。

暂停团队成员

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."
}

被暂停的成员会释放其席位，因此你可以邀请其他人代替他们。他们的访问权限会在其当前会话令牌下次刷新时终止，这可能需要长达一小时的时间 — 如果你需要立即生效，请改为移除他们。

状态	情况
`400`	你尝试暂停账户所有者，或尝试暂停已处于暂停或移除状态的成员。
`403`	他们的访问权限范围超出了你的权限。
`404`	无此团队成员。

移除团队成员

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."
}

从您的角度来看，移除操作是永久性的：被移除的成员无法通过更新端点重新激活——如果您改变主意，请再次邀请他们。他们的电子邮件地址也会从您账户的通知列表中移除。

状态	原因
`400`	您尝试移除账户所有者。
`403`	他们的访问权限比您更广泛。
`404`	无此团队成员。

限制成员的可见范围

在添加、更新和邀请时可接受三个可选字段，用于决定成员可以看到账户的多少内容。它们是叠加生效的：如果成员受到多项限制，则受所有这些限制的共同约束。

contact_scope — all（默认值：所有联系人和对话）或 assigned（仅限分配给他们的内容）。使用 assigned 时，添加 "contact_scope_unassigned": true 还可以让他们看到尚未分配给任何人的联系人。

contact_scope_axes — 将他们限制在指定的坐席、渠道或部门：

字段	类型	描述
`agents`	string[]	坐席 ID。他们只能看到路由给这些坐席的聊天记录。最多 200 个。
`channels`	string[]	渠道名称 — `whatsapp`, `whatsapp_web`, `sms`, `instagram`, `instagram_private`, `messenger`, `facebook`, `chat_widget`, `telegram`, `line`, `viber`, `tiktok`, `imessage`, `email`, `linkedin`, `skool`, `custom`, `custom_channel`。最多 200 个。
`departments`	string[]	部门 ID（参见部门）。他们只能看到归入这些部门下的线索。最多 200 个。
`include_unrouted`	boolean	设置为 `agents` 时，同时显示没有坐席处理的聊天记录。默认关闭。当 `agents` 为空时忽略此项。
`include_undepartmented`	boolean	设置为 `departments` 时，同时显示不属于任何部门的聊天记录。默认关闭。当 `departments` 为空时忽略此项。

保存时不会检查坐席和部门 ID——不存在的 ID 只是匹配不到任何内容，这会表现为空收件箱而不是错误。渠道名称会被检查：无法识别的名称会被 400 拒绝。

这三个字段均不能设置在账户所有者身上——该请求会被 400 拒绝。

列出邀请

GET /team/invites

按时间倒序排列您已发送的邀请，以便查看谁尚未接受邀请。

查询参数

参数	必需	描述
`status`	否	仅返回处于此状态的邀请 — `pending`、`accepted`、`declined`、`cancelled` 或 `expired`。

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 账户，系统会为他们创建一个，并引导他们通过电子邮件设置密码。

请求字段

字段	必需	描述
`email`	是	发送邀请的地址。
`role`	是	`admin`、`editor` 或 `viewer`。
`permission_overrides`	否	各区域的例外权限，在他们接受邀请时立即应用。
`contact_scope`	否	在他们接受邀请时应用。
`contact_scope_unassigned`	否	在他们接受邀请时应用。
`contact_scope_axes`	否	在他们接受邀请时应用。
`sub_account_access`	否	仅限代理机构。在他们接受邀请时应用。

预先设置权限意味着您无需事后编辑成员信息 — 当他们接受邀请时，所有设置都会复制到他们的成员资格中。

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 天有效期。
待处理的邀请会占用席位。 与直接添加成员不同，此处的席位检查会计算活跃成员加上待处理的邀请，因此如果账户的所有席位已满，在发送电子邮件之前就会被拒绝。
每天 20 个邀请限制，按账户计算，包含发送和重新发送。

状态	时间
`400`	`email` 缺失或角色无效。
`403`	您没有管理团队的权限，或者您尝试授予高于您自身权限的访问权限。
`409`	该电子邮件的待处理邀请已存在，或者该人员已在您的团队中。
`429`	您套餐的团队席位已满，或者您已达到每天 20 个邀请的限制。`error` 消息会说明具体原因。

取消邀请

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."
}

新邮件包含一个新链接，且旧链接依然有效，因此如果用户稍后找到第一封邮件，也不会受阻。重新发送计入与发送相同的每日 20 次限制，并且重新激活已过期的邀请会重新检查您的席位——如果套餐已满，将返回 429。

接受邀请

POST /team/invites/accept

使用邀请邮件中的令牌接受邀请，将已登录的用户加入到该账户的团队中。

这是您个人身份的操作。 请以您自己的身份登录——当您在他人账户内工作时，此操作会被明确拒绝，并返回 403。

请求字段

字段	必填	描述
`invite_token`	是	来自邀请邮件链接的令牌。

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."
}

状态	情况
`400`	`invite_token` 缺失，或邀请是发给您自己的账户的。
`403`	会话正在另一个账户内工作，或者邀请发送到的邮箱地址与您当前登录的邮箱地址不符。
`404`	邀请不存在或已被使用。
`429`	在邀请发出到您接受期间，账户席位已满。
`504`	邀请已过期。请要求发送者重新发送。

拒绝邀请

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."
}

部门

部门是您团队中的一个命名组，例如：销售、客户支持、人力资源。它为潜在客户指定了一个所属团队，可以独立认领新的对话，并可用于限制成员的可见范围。

这四个端点需要 API 密钥。 与本页面的其余部分不同，它们像 API 中的所有其他端点一样进行身份验证（请参阅身份验证）。已登录的会话也适用：读取需要 contacts 位于 view，创建、更改或删除需要 team_management 位于 edit。

部门对象

字段	类型	描述
`id`	string	部门的 ID。在 `contact_scope_axes.departments` 和下方的路径中使用它。
`name`	string	团队名称。最多 60 个字符，在账户内唯一。
`color`	string \| null	强调色，格式为 `#rrggbb` 或 `null`。
`member_uids`	string[]	该部门的团队成员。可能包含账户所有者。
`auto_assign_enabled`	boolean	归入此部门的潜在客户是否也会分配给其中的某个人。`false` 表示该部门通过共享队列工作。
`routing_agents`	string[]	由这些 AI 代理处理的新对话会自动归入此部门。为空表示没有代理规则。
`routing_channels`	string[]	这些渠道上的新对话会自动归入此处。为空表示没有渠道规则。
`created_by`	string \| null	创建者。

当同时设置了 routing_agents 和 routing_channels 时，对话必须同时满足这两个条件才能归入此处——这就是如何实现“支持代理，但仅限 WhatsApp”这种特定团队分配的方法。

一个账户最多可以拥有 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

请求字段

字段	必填	说明
`name`	是	最多 60 个字符。不得与现有部门重复。
`color`	否	`#rrggbb` 十六进制，或 `null`。
`member_uids`	否	谁在其中。每个 UID 必须是账户所有者或活跃团队成员。
`auto_assign_enabled`	否	默认为 `true`。
`routing_agents`	否	新聊天会分配到的坐席 ID。
`routing_channels`	否	新聊天会分配到的渠道名称 — 与 `contact_scope_axes.channels` 使用相同的词汇。

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"
  }
}

状态	情况
`400`	`name` 缺失或过长，`color` 不是 `#rrggbb`，渠道名称无法识别，列出的 UID 不是此团队的活跃成员，或者您已经拥有 50 个部门。
`409`	同名部门已存在。

更新部门

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（当他们的成员资格包含这些权限时）。

会话令牌

五个端点会生成用于在账户之间切换的一次性登录令牌。它们的响应方式相同：

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

该令牌用于与 Firebase 客户端 SDK 交换会话。它不是 API 密钥，不能作为 API 密钥发送，这就是为什么这些端点仅在第一方应用程序内有用。

端点	功能	正文
`POST /team/tokens/team-member`	允许团队成员开始在他们所属的账户内工作。	`account_owner_uid` (必需)
`POST /team/tokens/return-from-team`	将他们带回他们自己的账户。	—
`POST /team/tokens/assist`	允许 Your AI Connector 员工打开客户账户以提供帮助。仅限员工。	`customerUid`
`POST /team/tokens/return-to-admin`	结束协助会话并将员工返回到他们自己的账户。	—
`POST /team/tokens/agency-assist`	允许代理机构打开其客户子账户之一——或者在不带参数调用时，返回到代理机构账户。	`subAccountUid` (可选)

当会话无权执行此操作时，每个接口都会返回 403：例如不是该账户的成员、不是员工、该子账户不属于您的代理机构或未授权给您，或者会话当前所处的模式与端点要求的模式不符。

分配平台角色

POST /team/users/{targetUid}/role

设置用户的平台角色 — User、Dev、Support 或 Agency。这并非团队成员身份：它决定了某人拥有何种类型的 Your AI Connector 账户。

此端点仅限 Your AI Connector 员工使用，且最后一名 Dev 不能被降级。此处列出仅为完整性考虑；它不属于管理您自己团队的范畴。

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

状态	情况
`400`	`role` 缺失或不是这四种角色之一，或者此操作会移除最后一名 `Dev`。
`403`	您不是员工，或者会话正在另一个账户内工作。
`404`	无此用户。

团队 API 错误

团队端点返回标准的错误封装，并始终在 HTTP 状态码之外包含 error_code：

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

状态	在团队端点上发生时
`400`	必填字段缺失或无效，或者当前状态下不允许执行此操作（例如重新激活已移除的成员、暂停所有者、删除某人受限的部门）。
`401`	您向需要登录用户的端点发送了 API 密钥 — 请参阅身份验证。
`403`	您没有 `team_management` 权限，更改超出了您的访问范围，或者在另一个账户内工作时拒绝执行此操作。
`404`	无此成员、邀请、部门或用户。
`409`	已是团队成员、已存在待处理的邀请，或已存在同名部门。
`429`	团队席位已满、达到每日 20 次邀请的限制，或您触及了 API 速率限制。
`504`	您尝试接受的邀请已过期。

每个端点都可能返回的共享代码 — 429（速率限制）和 500 — 及其重试指南列在错误与分页中。

团队 API #

身份验证：这些端点需要已登录的用户 #

角色和权限 #

团队成员对象 #

列出团队成员 #

直接添加团队成员 #

更新团队成员 #

暂停团队成员 #

移除团队成员 #

限制成员的可见范围 #

列出邀请 #

发送邀请 #

取消邀请 #

重新发送邀请 #

接受邀请 #

拒绝邀请 #

部门 #

列出部门 #

创建部门 #

更新部门 #

删除部门 #

检查您自己的权限 #

会话令牌 #

分配平台角色 #

团队 API 错误 #

相关内容 #

团队 API

身份验证：这些端点需要已登录的用户

角色和权限

团队成员对象

列出团队成员

直接添加团队成员

更新团队成员

暂停团队成员

移除团队成员

限制成员的可见范围

列出邀请

发送邀请

取消邀请

重新发送邀请

接受邀请

拒绝邀请

部门

列出部门

创建部门

更新部门

删除部门

检查您自己的权限

会话令牌

分配平台角色

团队 API 错误

相关内容