---
title: "Referência da API de equipe e funções"
description: "Liste membros e convites, e crie, renove, mude a função ou remova usuários virtuais. Alterar a equipe exige o token de API pessoal de um Admin."
canonical_url: https://chatfuel.com/pt/docs/public-api/team-and-roles
markdown_url: https://chatfuel.com/pt/docs/public-api/team-and-roles.md
last_updated: 2026-10-06
lang: pt
site: https://chatfuel.com/docs
llms_txt: https://chatfuel.com/llms.txt
---

# Referência da API de equipe e funções

Liste membros e convites, e crie, renove, mude a função ou remova usuários virtuais. Alterar a equipe exige o token de API pessoal de um Admin.

A equipe de um bot do Chatfuel é a sua lista de membros, pessoas da equipe e usuários virtuais, cada um com uma função: Admin, Editor, Agent ou Custom. Qualquer membro pode ler a equipe; para alterá-la, incluindo tudo o que envolve usuários virtuais, você precisa do [token de API pessoal](https://chatfuel.com/pt/docs/public-api/authentication) de um Admin do bot. Esta página lista as operações da equipe; [usuários virtuais](https://chatfuel.com/pt/docs/public-api/virtual-users) mostra passo a passo o ciclo de vida de um usuário virtual.

## Como ler membros, funções e convites [#como-ler-membros-funções-e-convites]

Qualquer usuário virtual do bot pode ler a equipe (**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!)` retorna um membro. `currentUser.botRole(botID:)` retorna a função do dono do token em um bot.

## Como funcionam as funções e as permissões [#como-funcionam-as-funções-e-as-permissões]

Uma função é um `roleTypeV2` mais uma lista de `botPermissions`, cada uma um `object` com uma `action` de `None`, `View` ou `Edit`. Os objetos são `Ai`, `Configure`, `Roles`, `Pro`, `Inbox`, `Broadcasting`, `People`, `Analyze`, `Home`, `Bot`, `Workspaces`, `Flows`, `ContactsAssignedToOthers` e `ContactsUnassigned`.

Admin, Editor e Agent têm conjuntos de permissões fixos; só uma função Custom usa as permissões que você envia. Usuários virtuais só podem ser Editor ou Agent. O `rolesConfig` do bot se aplica por cima: quando `allowOnlyAssignedToMeContacts` está ativado para uma função, os membros com essa função, incluindo usuários virtuais, só veem e alteram os contatos atribuídos a eles. Lembre-se disso quando um usuário virtual Agent não encontrar contatos que deveria ver.

## Operações de usuários virtuais [#operações-de-usuários-virtuais]

Todas são **Somente token pessoal** e exigem a função Admin no 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
}
```

## Operações de membros da equipe e convites [#operações-de-membros-da-equipe-e-convites]

Estas operações alteram a equipe, por isso são **Somente token pessoal**:

```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` retorna `botInviteToken`, que uma pessoa abre no painel para entrar no bot. Usuários virtuais não podem aceitar convites; crie-os com `createVirtualUser`.

## Assinatura [#assinatura]

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

Uma integração pode escutar esta assinatura com o token do seu usuário virtual para saber quando um Admin muda a função dele ou o remove do bot.

## Problemas comuns [#problemas-comuns]

### Um usuário virtual Agent recebe "NotEnoughPermissions" ou listas vazias para alguns contatos [#um-usuário-virtual-agent-recebe-notenoughpermissions-ou-listas-vazias-para-alguns-contatos]

Verifique `bot.rolesConfig.agentRoleSettings`. Quando `allowOnlyAssignedToMeContacts` está ativado, um Agent só trabalha com os contatos atribuídos a ele; quando `allowContactsWithEmptyAssignee` está desativado, os contatos sem responsável ficam ocultos.

### "CustomRoleNotSupported" [#customrolenotsupported]

Convites e mudanças de função aceitam Admin, Editor e Agent. Funções Custom não podem ser atribuídas por meio dessas mutações.

### O aviso de remoção "FuelySwitchToHumanAssignee" [#o-aviso-de-remoção-fuelyswitchtohumanassignee]

O membro está definido como a pessoa para quem o Fuely AI transfere as conversas. Depois da remoção, escolha outra pessoa na configuração **Switch to human** da automação para que os chats não fiquem sem responsável.