Team and Roles API Reference
List bot members and invites, and create, rotate, re-role or remove virtual users. Changing the team always needs a bot Admin's personal API token.
Last updated on
The team of a Chatfuel bot is its list of members, human teammates and virtual users, each with a role: Admin, Editor, Agent or Custom. Any member can read the team; changing it, including everything to do with virtual users, needs the personal API token of a bot Admin. This page lists the team operations; virtual users walks through the virtual user lifecycle step by step.
How to read members, roles and invites
Any virtual user of the bot can read the team (Agent):
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!) returns one member. currentUser.botRole(botID:) returns the role of the token's owner in a bot.
How roles and permissions work
A role is a roleTypeV2 plus a list of botPermissions, each an object with an action of None, View or Edit. The objects are Ai, Configure, Roles, Pro, Inbox, Broadcasting, People, Analyze, Home, Bot, Workspaces, Flows, ContactsAssignedToOthers and ContactsUnassigned.
Admin, Editor and Agent have fixed permission sets; only a Custom role uses the permissions you send. Virtual users can only be Editor or Agent. The bot's rolesConfig applies on top: when allowOnlyAssignedToMeContacts is on for a role, members with that role, virtual users included, see and change only contacts assigned to them. Keep this in mind when an Agent virtual user can't find contacts it expects.
Virtual user operations
All of these are Personal token only and need the Admin role in the bot:
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
}Teammate and invite operations
These operations change the team, so they are Personal token only:
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 returns botInviteToken, which a person opens in the dashboard to join the bot. Virtual users can't accept invites; create them with createVirtualUser instead.
Subscription
type Subscription {
# Fires when the role of the token's owner changes in any bot. role is null after removal.
currentUserAccountRoleInBotUpdated: CurrentUserAccountRoleInBotUpdate!
}An integration can listen to this subscription with its virtual user token to notice when an Admin changes its role or removes it.
Common issues
An Agent virtual user gets "NotEnoughPermissions" or empty lists for some contacts
Check bot.rolesConfig.agentRoleSettings. When allowOnlyAssignedToMeContacts is on, an Agent only works with contacts assigned to it; when allowContactsWithEmptyAssignee is off, unassigned contacts are hidden.
"CustomRoleNotSupported"
Invites and role changes accept Admin, Editor and Agent. Custom roles can't be assigned through these mutations.
The removal warning "FuelySwitchToHumanAssignee"
The member is set as the person Fuely AI hands conversations to. After removal, choose another person in the automation's Switch to human setting so chats are not left without an assignee.