---
title: "Usuários virtuais na Public API do Chatfuel"
description: "Um usuário virtual é um Editor ou Agent exclusivo da API em um bot, com token próprio. Crie, rotacione, mude a função e remova-o com seu token de API pessoal."
canonical_url: https://chatfuel.com/pt/docs/public-api/virtual-users
markdown_url: https://chatfuel.com/pt/docs/public-api/virtual-users.md
last_updated: 2026-10-06
lang: pt
site: https://chatfuel.com/docs
llms_txt: https://chatfuel.com/llms.txt
---

# Usuários virtuais na Public API do Chatfuel

Um usuário virtual é um Editor ou Agent exclusivo da API em um bot, com token próprio. Crie, rotacione, mude a função e remova-o com seu token de API pessoal.

Um usuário virtual é um membro de um bot do Chatfuel que usa apenas a API. Ele tem um nome, a função Editor ou Agent e o próprio token da Public API, mas não tem login: não pode entrar no painel nem ver outros bots, workspaces ou a cobrança. Os usuários virtuais são a forma como as integrações devem chamar a Public API, porque cada um fica limitado a um único bot e a uma única função e pode ser revogado sem afetar a sua própria conta.

Somente um **Admin** do bot pode criar, rotacionar, mudar a função ou remover usuários virtuais, e somente com um [token de API pessoal](https://chatfuel.com/pt/docs/public-api/authentication). Um bot pode ter até 20 usuários virtuais.

## Como criar um usuário virtual [#como-criar-um-usuário-virtual]

**Somente token pessoal.** Chame `createVirtualUser` com o ID do bot, um nome e uma função:

```graphql
mutation CreateVirtualUser($botID: BotID!) {
  createVirtualUser(
    botID: $botID
    name: "HubSpot sync"
    role: { roleType: Agent, botPermissions: [] }
  ) {
    member {
      id
      role { roleTypeV2 }
      user { id name accountType }
    }
    authToken
  }
}
```

* `name` é obrigatório, com 1 a 100 caracteres depois de remover os espaços das pontas. É o que os membros da sua equipe veem no painel, então dê ao usuário virtual o nome da integração ou do cliente que ele atende.
* `role.roleType` deve ser `Editor` ou `Agent`. As permissões em `botPermissions` são ignoradas: um usuário virtual sempre recebe o conjunto padrão de permissões da sua função, ajustado pelas configurações de funções do bot. Passe uma lista vazia.
* `authToken` na resposta é o token do usuário virtual. Ele só é retornado aqui. Guarde-o junto com `member.id`, o ID de membro de que você precisa para qualquer alteração posterior.

## O que usuários virtuais Editor e Agent podem fazer [#o-que-usuários-virtuais-editor-e-agent-podem-fazer]

As permissões de um usuário virtual vêm apenas da função dele no bot. As duas funções permitidas correspondem às funções Editor e Agent dos membros humanos da equipe.

Um usuário virtual **Editor** pode:

* ler e editar contatos, atributos, notas, responsáveis e etapas de venda, além de importar e exportar contatos
* ler conversas e enviar mensagens em todos os canais
* criar e alterar fluxos, regras de palavras-chave, configurações do Fuely AI, automações e transmissões
* gerenciar agendamentos, especialistas, produtos e serviços
* alterar as configurações do widget do site e publicar na conta do Instagram conectada

Um usuário virtual **Agent** pode:

* ler contatos e exportá-los, mas não editar nomes, atributos ou notas
* ler conversas, enviar mensagens e templates do WhatsApp
* atribuir contatos, definir o responsável do Fuely AI e mover contatos entre etapas de venda
* ver fluxos e automações e executar chats de teste, mas não alterá-los

Nenhuma das duas funções pode renomear ou excluir o bot, alterar o fuso horário ou o país dele, gerenciar membros da equipe, conectar ou desconectar canais nem mexer em workspaces e cobrança. Essas operações precisam de um token de API pessoal, como listado em [autenticação](https://chatfuel.com/pt/docs/public-api/authentication). Cada operação nas páginas de referência informa a função mínima que pode executá-la.

## Como regenerar o token de um usuário virtual [#como-regenerar-o-token-de-um-usuário-virtual]

**Somente token pessoal.** Rotacione um token quando ele puder estar exposto ou quando alguém com acesso sair:

```graphql
mutation RotateToken($memberID: BotTeamMemberID!) {
  regenerateVirtualUserToken(memberID: $memberID)
}
```

O token antigo para de funcionar imediatamente, e a mutação retorna o novo token como string. Se `memberID` pertencer a um membro humano da equipe, a chamada falha com `NotVirtualUser`.

## Como alterar a função de um usuário virtual [#como-alterar-a-função-de-um-usuário-virtual]

**Somente token pessoal.** Alterne um usuário virtual entre Editor e Agent com `changeBotMemberRoleV2`:

```graphql
mutation MakeEditor($memberID: BotTeamMemberID!) {
  changeBotMemberRoleV2(memberID: $memberID, newRole: { roleType: Editor, botPermissions: [] }) {
    id
    role { roleTypeV2 }
  }
}
```

A mesma alteração está disponível no painel: **Settings → Teammates**, selecione o usuário virtual e depois **Manage teammate**. Para usuários virtuais, só Editor e Agent são oferecidos.

## Como remover um usuário virtual [#como-remover-um-usuário-virtual]

**Somente token pessoal.** Remover um usuário virtual exclui a conta e o token dela permanentemente:

```graphql
mutation RemoveVirtualUser($memberID: BotTeamMemberID!) {
  removeMemberFromBot(memberID: $memberID) { id }
}
```

No painel, abra **Settings → Teammates**, selecione o usuário virtual e escolha **Delete API user**. O painel exibe este aviso: "This deletes the account and its API token permanently. Anything calling the API with that token will stop working. Delete anyway?" (Isso exclui a conta e o token de API dela permanentemente. Tudo o que chamar a API com esse token vai parar de funcionar. Excluir mesmo assim?)

Excluir um bot também exclui todos os usuários virtuais dele.

## Como os usuários virtuais aparecem no painel e na API [#como-os-usuários-virtuais-aparecem-no-painel-e-na-api]

No painel, um usuário virtual aparece em **Settings → Teammates** com o rótulo **API** depois do nome. O mesmo rótulo aparece na lista de responsáveis dos contatos e nas configurações de transferência para humano do Fuely AI, então você pode atribuir contatos a uma integração como faria com um membro da equipe.

Na API, a conta de um usuário virtual tem `accountType: Virtual`. Quando um usuário virtual lê a própria conta com `currentUser`, ele recebe a si mesmo, não a pessoa que o criou, e `currentUser.botsV2` retorna apenas o próprio bot. A sua conta e os seus outros bots nunca aparecem nas respostas dele.

## Problemas comuns [#problemas-comuns]

### "VirtualUsersLimitReached" [#virtualuserslimitreached]

O bot já tem 20 usuários virtuais. Remova os que você não usa mais com `removeMemberFromBot` ou reutilize um usuário virtual existente para a integração.

### "VirtualUserNameInvalid" [#virtualusernameinvalid]

O nome está vazio ou tem mais de 100 caracteres depois de remover os espaços das pontas.

### "VirtualUserRoleNotAllowed" [#virtualuserrolenotallowed]

A função é `Admin` ou `Custom`. Usuários virtuais só podem ser `Editor` ou `Agent`.

### "NotVirtualUser" [#notvirtualuser]

`regenerateVirtualUserToken` foi chamado com o ID de membro de um membro humano da equipe. Use o ID de membro retornado por `createVirtualUser` ou encontre-o em `bot(id:) { members { id user { name accountType } } }`.