---
title: "Referencia de la API de equipo y roles"
description: "Lista miembros e invitaciones, y crea, rota, cambia de rol o elimina usuarios virtuales. Cambiar el equipo requiere el token de API personal de un Admin."
canonical_url: https://chatfuel.com/es/docs/public-api/team-and-roles
markdown_url: https://chatfuel.com/es/docs/public-api/team-and-roles.md
last_updated: 2026-10-06
lang: es
site: https://chatfuel.com/docs
llms_txt: https://chatfuel.com/llms.txt
---

# Referencia de la API de equipo y roles

Lista miembros e invitaciones, y crea, rota, cambia de rol o elimina usuarios virtuales. Cambiar el equipo requiere el token de API personal de un Admin.

El equipo de un bot de Chatfuel es su lista de miembros, compañeros de equipo humanos y usuarios virtuales, cada uno con un rol: Admin, Editor, Agent o Custom. Cualquier miembro puede leer el equipo; para cambiarlo, incluido todo lo relacionado con usuarios virtuales, necesitas el [token de API personal](https://chatfuel.com/es/docs/public-api/authentication) de un Admin del bot. Esta página lista las operaciones del equipo; [usuarios virtuales](https://chatfuel.com/es/docs/public-api/virtual-users) explica paso a paso el ciclo de vida de un usuario virtual.

## Cómo leer miembros, roles e invitaciones [#cómo-leer-miembros-roles-e-invitaciones]

Cualquier usuario virtual del bot puede leer el equipo (**Agent**):

```graphql
query Team($botID: BotID!) {
  bot(id: $botID) {
    members {
      id                                   # BotTeamMemberID, used by all team mutations
      role { roleTypeV2 botPermissions { object action } }
      user { id name accountType }         # accountType: Regular or Virtual
      removalWarnings                      # FuelySwitchToHumanAssignee if Fuely AI hands chats to this member
    }
    invites { id role { roleTypeV2 } used }
    rolesConfig {
      editorRoleSettings { allowOnlyAssignedToMeContacts allowContactsWithEmptyAssignee }
      agentRoleSettings { allowOnlyAssignedToMeContacts allowContactsWithEmptyAssignee }
    }
  }
}
```

`bot.member(id: BotTeamMemberID!)` devuelve un miembro. `currentUser.botRole(botID:)` devuelve el rol del dueño del token en un bot.

## Cómo funcionan los roles y los permisos [#cómo-funcionan-los-roles-y-los-permisos]

Un rol es un `roleTypeV2` más una lista de `botPermissions`, cada uno un `object` con una `action` de `None`, `View` o `Edit`. Los objetos son `Ai`, `Configure`, `Roles`, `Pro`, `Inbox`, `Broadcasting`, `People`, `Analyze`, `Home`, `Bot`, `Workspaces`, `Flows`, `ContactsAssignedToOthers` y `ContactsUnassigned`.

Admin, Editor y Agent tienen conjuntos de permisos fijos; solo un rol Custom usa los permisos que envías. Los usuarios virtuales solo pueden ser Editor o Agent. El `rolesConfig` del bot se aplica por encima: cuando `allowOnlyAssignedToMeContacts` está activado para un rol, los miembros con ese rol, incluidos los usuarios virtuales, solo ven y cambian los contactos asignados a ellos. Tenlo en cuenta cuando un usuario virtual Agent no encuentre contactos que espera ver.

## Operaciones de usuarios virtuales [#operaciones-de-usuarios-virtuales]

Todas son **Solo token personal** y requieren el rol Admin en el bot:

```graphql
type Mutation {
  # Creates a virtual user and returns its token once. Role: Editor or Agent.
  # Errors: VirtualUserRoleNotAllowed, VirtualUserNameInvalid, VirtualUsersLimitReached
  createVirtualUser(botID: BotID!, name: String!, role: BotRoleInputV2!): VirtualUserCreateResult!
  # Revokes the current token of a virtual user and returns a new one. Errors: NotVirtualUser
  regenerateVirtualUserToken(memberID: BotTeamMemberID!): AuthToken!
}

type VirtualUserCreateResult {
  member: TeamMember!
  authToken: AuthToken!
}

input BotRoleInputV2 {
  roleType: BotRoleTypeV2!            # Admin, Editor, Agent or Custom
  botPermissions: [PermissionInput!]! # used only for Custom; pass [] otherwise
}
```

## Operaciones de compañeros de equipo e invitaciones [#operaciones-de-compañeros-de-equipo-e-invitaciones]

Estas operaciones cambian el equipo, así que son **Solo token personal**:

```graphql
type Mutation {
  # Changes a member's role. A virtual user can only be switched between Editor and Agent.
  # Errors: CustomRoleNotSupported, VirtualUserRoleNotAllowed
  changeBotMemberRoleV2(memberID: BotTeamMemberID!, newRole: BotRoleInputV2!): TeamMember!
  # Removes a member. For a virtual user this deletes the account and its token.
  removeMemberFromBot(memberID: BotTeamMemberID!): Bot!
  # Creates an invite link for a human teammate. Errors: CustomRoleNotSupported
  createBotInviteV2(botID: BotID!, role: BotRoleInputV2!, wlLogin: String): BotInviteCreateResult
  botInviteDelete(inviteID: BotInviteID!): Bot!
  # Leaves a bot you are a member of. Not available to virtual users (VirtualUserNotAllowed).
  leaveBot(botID: BotID!): CurrentUserAccount!
}
```

`createBotInviteV2` devuelve `botInviteToken`, que una persona abre en el panel para unirse al bot. Los usuarios virtuales no pueden aceptar invitaciones; créalos con `createVirtualUser`.

## Suscripción [#suscripción]

```graphql
type Subscription {
  # Fires when the role of the token's owner changes in any bot. role is null after removal.
  currentUserAccountRoleInBotUpdated: CurrentUserAccountRoleInBotUpdate!
}
```

Una integración puede escuchar esta suscripción con el token de su usuario virtual para detectar cuándo un Admin cambia su rol o la elimina del bot.

## Problemas comunes [#problemas-comunes]

### Un usuario virtual Agent recibe "NotEnoughPermissions" o listas vacías para algunos contactos [#un-usuario-virtual-agent-recibe-notenoughpermissions-o-listas-vacías-para-algunos-contactos]

Revisa `bot.rolesConfig.agentRoleSettings`. Cuando `allowOnlyAssignedToMeContacts` está activado, un Agent solo trabaja con los contactos asignados a él; cuando `allowContactsWithEmptyAssignee` está desactivado, los contactos sin responsable quedan ocultos.

### "CustomRoleNotSupported" [#customrolenotsupported]

Las invitaciones y los cambios de rol aceptan Admin, Editor y Agent. Los roles Custom no se pueden asignar mediante estas mutaciones.

### La advertencia de eliminación "FuelySwitchToHumanAssignee" [#la-advertencia-de-eliminación-fuelyswitchtohumanassignee]

El miembro está configurado como la persona a la que Fuely AI transfiere las conversaciones. Después de eliminarlo, elige a otra persona en la opción **Switch to human** de la automatización para que los chats no queden sin responsable.