Virtual Users in the Chatfuel Public API

A virtual user is an API-only member of one Chatfuel bot. It has a name, the Editor or Agent role and its own Public API token, but no login: it can't sign in to the dashboard and can't see other bots, workspaces or billing. Virtual users are how integrations should call the Public API, because each one is limited to a single bot and a single role and can be revoked without touching your own account.

Only a bot Admin can create, rotate, re-role or remove virtual users, and only with a personal API token. A bot can have up to 20 virtual users.

How to create a virtual user

Personal token only. Call createVirtualUser with the bot ID, a name and a role:

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

• name is required, 1 to 100 characters after trimming spaces. It is what your teammates see in the dashboard, so name the virtual user after the integration or customer it serves.
• role.roleType must be Editor or Agent. The permissions in botPermissions are ignored: a virtual user always gets the standard permission set of its role, adjusted by the bot's role settings. Pass an empty list.
• authToken in the response is the virtual user's token. It is returned only here. Store it together with member.id, the member ID you need for every later change.

What Editor and Agent virtual users can do

A virtual user's permissions come only from its role in the bot. The two allowed roles match the Editor and Agent roles of human teammates.

An Editor virtual user can:

• read and edit contacts, attributes, notes, assignees and sales stages, import and export contacts
• read conversations and send messages on every channel
• build and change flows, keyword rules, Fuely AI settings, automations and broadcasts
• manage bookings, specialists, products and services
• change website widget settings and publish to the connected Instagram account

An Agent virtual user can:

• read contacts and export them, but not edit their names, attributes or notes
• read conversations, send messages and WhatsApp templates
• assign contacts, set the Fuely AI assignee and move contacts between sales stages
• view flows and automations and run test chats, but not change them

Neither role can rename or delete the bot, change its timezone or country, manage teammates, connect or disconnect channels, or touch workspaces and billing. Those operations need a personal API token, as listed in authentication. Each operation in the reference pages states the lowest role that can run it.

How to regenerate a virtual user token

Personal token only. Rotate a token when it may be exposed or when someone with access leaves:

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

The old token stops working immediately, and the mutation returns the new token as a string. If memberID belongs to a human teammate, the call fails with NotVirtualUser.

How to change a virtual user's role

Personal token only. Switch a virtual user between Editor and Agent with changeBotMemberRoleV2:

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

The same change is available in the dashboard: Settings → Teammates, select the virtual user, then Manage teammate. Only Editor and Agent are offered for virtual users.

How to remove a virtual user

Personal token only. Removing a virtual user deletes the account and its token permanently:

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

In the dashboard, open Settings → Teammates, select the virtual user and choose Delete API user. The dashboard warns: "This deletes the account and its API token permanently. Anything calling the API with that token will stop working. Delete anyway?"

Deleting a bot also deletes all of its virtual users.

How virtual users appear in the dashboard and the API

In the dashboard, a virtual user is listed in Settings → Teammates with the API label after its name. The same label appears in the contact assignee list and in the Fuely AI human handoff settings, so you can assign contacts to an integration just like to a teammate.

In the API, a virtual user's account has accountType: Virtual. When a virtual user reads its own account with currentUser, it gets itself, not the person who created it, and currentUser.botsV2 returns only its own bot. Your account and your other bots never appear in its responses.

Common issues

"VirtualUsersLimitReached"

The bot already has 20 virtual users. Remove ones you no longer use with removeMemberFromBot, or reuse an existing virtual user for the integration.

"VirtualUserNameInvalid"

The name is empty or longer than 100 characters after trimming spaces.

"VirtualUserRoleNotAllowed"

The role is Admin or Custom. Virtual users can only be Editor or Agent.

"NotVirtualUser"

regenerateVirtualUserToken was called with the member ID of a human teammate. Use the member ID returned by createVirtualUser, or find it in bot(id:) { members { id user { name accountType } } }.