Usuarios virtuales en la Public API de Chatfuel

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. Un bot puede tener hasta 20 usuarios virtuales.

Cómo crear un usuario virtual

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

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

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

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

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

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

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

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

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

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

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

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

"VirtualUserRoleNotAllowed"

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

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