---
title: "Usuarios virtuales en la Public API de Chatfuel"
description: "Un usuario virtual es un Editor o Agent solo para la API en un bot, con su propio token. Créalo, rótalo, cambia su rol o elimínalo con tu token de API personal."
canonical_url: https://chatfuel.com/es/docs/public-api/virtual-users
markdown_url: https://chatfuel.com/es/docs/public-api/virtual-users.md
last_updated: 2026-10-06
lang: es
site: https://chatfuel.com/docs
llms_txt: https://chatfuel.com/llms.txt
---

# Usuarios virtuales en la Public API de Chatfuel

Un usuario virtual es un Editor o Agent solo para la API en un bot, con su propio token. Créalo, rótalo, cambia su rol o elimínalo con tu token de API personal.

Un usuario virtual es un miembro de un bot de Chatfuel que solo usa la API. Tiene un nombre, el rol Editor o Agent y su propio token de la Public API, pero no tiene inicio de sesión: no puede entrar al panel ni ver otros bots, espacios de trabajo o la facturación. Los usuarios virtuales son la forma en que las integraciones deben llamar a la Public API, porque cada uno está limitado a un solo bot y a un solo rol, y se puede revocar sin tocar tu propia cuenta.

Solo un **Admin** del bot puede crear, rotar, cambiar de rol o eliminar usuarios virtuales, y solo con un [token de API personal](https://chatfuel.com/es/docs/public-api/authentication). Un bot puede tener hasta 20 usuarios virtuales.

## Cómo crear un usuario virtual [#cómo-crear-un-usuario-virtual]

**Solo token personal.** Llama a `createVirtualUser` con el ID del bot, un nombre y un rol:

```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` es obligatorio, de 1 a 100 caracteres después de quitar los espacios de los extremos. Es lo que ven los miembros de tu equipo en el panel, así que ponle al usuario virtual el nombre de la integración o del cliente al que sirve.
* `role.roleType` debe ser `Editor` o `Agent`. Los permisos de `botPermissions` se ignoran: un usuario virtual siempre recibe el conjunto de permisos estándar de su rol, ajustado por la configuración de roles del bot. Pasa una lista vacía.
* `authToken` en la respuesta es el token del usuario virtual. Solo se devuelve aquí. Guárdalo junto con `member.id`, el ID de miembro que necesitas para cualquier cambio posterior.

## Qué pueden hacer los usuarios virtuales Editor y Agent [#qué-pueden-hacer-los-usuarios-virtuales-editor-y-agent]

Los permisos de un usuario virtual provienen solo de su rol en el bot. Los dos roles permitidos equivalen a los roles Editor y Agent de los miembros humanos del equipo.

Un usuario virtual **Editor** puede:

* leer y editar contactos, atributos, notas, responsables y etapas de venta, e importar y exportar contactos
* leer conversaciones y enviar mensajes en todos los canales
* crear y cambiar flujos, reglas de palabras clave, la configuración de Fuely AI, automatizaciones y difusiones
* gestionar reservas, especialistas, productos y servicios
* cambiar la configuración del widget del sitio web y publicar en la cuenta de Instagram conectada

Un usuario virtual **Agent** puede:

* leer contactos y exportarlos, pero no editar sus nombres, atributos ni notas
* leer conversaciones, enviar mensajes y plantillas de WhatsApp
* asignar contactos, definir el responsable de Fuely AI y mover contactos entre etapas de venta
* ver flujos y automatizaciones y ejecutar chats de prueba, pero no cambiarlos

Ninguno de los dos roles puede renombrar ni eliminar el bot, cambiar su zona horaria o su país, gestionar miembros del equipo, conectar o desconectar canales, ni tocar espacios de trabajo y facturación. Esas operaciones necesitan un token de API personal, como se indica en [autenticación](https://chatfuel.com/es/docs/public-api/authentication). Cada operación de las páginas de referencia indica el rol mínimo que puede ejecutarla.

## Cómo regenerar el token de un usuario virtual [#cómo-regenerar-el-token-de-un-usuario-virtual]

**Solo token personal.** Rota un token cuando pueda estar expuesto o cuando alguien con acceso se vaya:

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

El token anterior deja de funcionar de inmediato y la mutación devuelve el nuevo token como una cadena. Si `memberID` pertenece a un miembro humano del equipo, la llamada falla con `NotVirtualUser`.

## Cómo cambiar el rol de un usuario virtual [#cómo-cambiar-el-rol-de-un-usuario-virtual]

**Solo token personal.** Cambia un usuario virtual entre Editor y Agent con `changeBotMemberRoleV2`:

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

El mismo cambio está disponible en el panel: **Settings → Teammates**, selecciona el usuario virtual y luego **Manage teammate**. Para los usuarios virtuales solo se ofrecen Editor y Agent.

## Cómo eliminar un usuario virtual [#cómo-eliminar-un-usuario-virtual]

**Solo token personal.** Eliminar un usuario virtual borra la cuenta y su token de forma permanente:

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

En el panel, abre **Settings → Teammates**, selecciona el usuario virtual y elige **Delete API user**. El panel muestra esta advertencia: "This deletes the account and its API token permanently. Anything calling the API with that token will stop working. Delete anyway?" (Esto elimina la cuenta y su token de API de forma permanente. Todo lo que llame a la API con ese token dejará de funcionar. ¿Eliminar de todos modos?)

Eliminar un bot también elimina todos sus usuarios virtuales.

## Cómo aparecen los usuarios virtuales en el panel y en la API [#cómo-aparecen-los-usuarios-virtuales-en-el-panel-y-en-la-api]

En el panel, un usuario virtual aparece en **Settings → Teammates** con la etiqueta **API** después de su nombre. La misma etiqueta aparece en la lista de responsables de contactos y en la configuración de traspaso a humano de Fuely AI, así que puedes asignar contactos a una integración igual que a un miembro del equipo.

En la API, la cuenta de un usuario virtual tiene `accountType: Virtual`. Cuando un usuario virtual lee su propia cuenta con `currentUser`, obtiene su propia cuenta, no la de la persona que lo creó, y `currentUser.botsV2` devuelve solo su propio bot. Tu cuenta y tus otros bots nunca aparecen en sus respuestas.

## Problemas comunes [#problemas-comunes]

### "VirtualUsersLimitReached" [#virtualuserslimitreached]

El bot ya tiene 20 usuarios virtuales. Elimina los que ya no uses con `removeMemberFromBot` o reutiliza un usuario virtual existente para la integración.

### "VirtualUserNameInvalid" [#virtualusernameinvalid]

El nombre está vacío o tiene más de 100 caracteres después de quitar los espacios de los extremos.

### "VirtualUserRoleNotAllowed" [#virtualuserrolenotallowed]

El rol es `Admin` o `Custom`. Los usuarios virtuales solo pueden ser `Editor` o `Agent`.

### "NotVirtualUser" [#notvirtualuser]

Se llamó a `regenerateVirtualUserToken` con el ID de miembro de un miembro humano del equipo. Usa el ID de miembro que devolvió `createVirtualUser` o búscalo en `bot(id:) { members { id user { name accountType } } }`.