Referencia de la API de equipo y roles

El equipo de un bot de Chatfuel es su lista de miembros, compañeros de equipo humanos y usuarios virtuales, cada uno con un rol: Admin, Editor, Agent o Custom. Cualquier miembro puede leer el equipo; para cambiarlo, incluido todo lo relacionado con usuarios virtuales, necesitas el token de API personal de un Admin del bot. Esta página lista las operaciones del equipo; usuarios virtuales explica paso a paso el ciclo de vida de un usuario virtual.

Cómo leer miembros, roles e invitaciones

Cualquier usuario virtual del bot puede leer el equipo (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!) devuelve un miembro. currentUser.botRole(botID:) devuelve el rol del dueño del token en un bot.

Cómo funcionan los roles y los permisos

Un rol es un roleTypeV2 más una lista de botPermissions, cada uno un object con una action de None, View o Edit. Los objetos son Ai, Configure, Roles, Pro, Inbox, Broadcasting, People, Analyze, Home, Bot, Workspaces, Flows, ContactsAssignedToOthers y ContactsUnassigned.

Admin, Editor y Agent tienen conjuntos de permisos fijos; solo un rol Custom usa los permisos que envías. Los usuarios virtuales solo pueden ser Editor o Agent. El rolesConfig del bot se aplica por encima: cuando allowOnlyAssignedToMeContacts está activado para un rol, los miembros con ese rol, incluidos los usuarios virtuales, solo ven y cambian los contactos asignados a ellos. Tenlo en cuenta cuando un usuario virtual Agent no encuentre contactos que espera ver.

Operaciones de usuarios virtuales

Todas son Solo token personal y requieren el rol Admin en el 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
}

Operaciones de compañeros de equipo e invitaciones

Estas operaciones cambian el equipo, así que son Solo token personal:

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 devuelve botInviteToken, que una persona abre en el panel para unirse al bot. Los usuarios virtuales no pueden aceptar invitaciones; créalos con createVirtualUser.

Suscripción

type Subscription {
  # Fires when the role of the token's owner changes in any bot. role is null after removal.
  currentUserAccountRoleInBotUpdated: CurrentUserAccountRoleInBotUpdate!
}

Una integración puede escuchar esta suscripción con el token de su usuario virtual para detectar cuándo un Admin cambia su rol o la elimina del bot.

Problemas comunes

Un usuario virtual Agent recibe "NotEnoughPermissions" o listas vacías para algunos contactos

Revisa bot.rolesConfig.agentRoleSettings. Cuando allowOnlyAssignedToMeContacts está activado, un Agent solo trabaja con los contactos asignados a él; cuando allowContactsWithEmptyAssignee está desactivado, los contactos sin responsable quedan ocultos.

"CustomRoleNotSupported"

Las invitaciones y los cambios de rol aceptan Admin, Editor y Agent. Los roles Custom no se pueden asignar mediante estas mutaciones.

La advertencia de eliminación "FuelySwitchToHumanAssignee"

El miembro está configurado como la persona a la que Fuely AI transfiere las conversaciones. Después de eliminarlo, elige a otra persona en la opción Switch to human de la automatización para que los chats no queden sin responsable.