Referência da API de equipe e funções

A equipe de um bot do Chatfuel é a sua lista de membros, pessoas da equipe e usuários virtuais, cada um com uma função: Admin, Editor, Agent ou Custom. Qualquer membro pode ler a equipe; para alterá-la, incluindo tudo o que envolve usuários virtuais, você precisa do token de API pessoal de um Admin do bot. Esta página lista as operações da equipe; usuários virtuais mostra passo a passo o ciclo de vida de um usuário virtual.

Como ler membros, funções e convites

Qualquer usuário virtual do bot pode ler a equipe (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!) retorna um membro. currentUser.botRole(botID:) retorna a função do dono do token em um bot.

Como funcionam as funções e as permissões

Uma função é um roleTypeV2 mais uma lista de botPermissions, cada uma um object com uma action de None, View ou Edit. Os objetos são Ai, Configure, Roles, Pro, Inbox, Broadcasting, People, Analyze, Home, Bot, Workspaces, Flows, ContactsAssignedToOthers e ContactsUnassigned.

Admin, Editor e Agent têm conjuntos de permissões fixos; só uma função Custom usa as permissões que você envia. Usuários virtuais só podem ser Editor ou Agent. O rolesConfig do bot se aplica por cima: quando allowOnlyAssignedToMeContacts está ativado para uma função, os membros com essa função, incluindo usuários virtuais, só veem e alteram os contatos atribuídos a eles. Lembre-se disso quando um usuário virtual Agent não encontrar contatos que deveria ver.

Operações de usuários virtuais

Todas são Somente token pessoal e exigem a função Admin no 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
}

Operações de membros da equipe e convites

Estas operações alteram a equipe, por isso são Somente token pessoal:

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 retorna botInviteToken, que uma pessoa abre no painel para entrar no bot. Usuários virtuais não podem aceitar convites; crie-os com createVirtualUser.

Assinatura

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

Uma integração pode escutar esta assinatura com o token do seu usuário virtual para saber quando um Admin muda a função dele ou o remove do bot.

Problemas comuns

Um usuário virtual Agent recebe "NotEnoughPermissions" ou listas vazias para alguns contatos

Verifique bot.rolesConfig.agentRoleSettings. Quando allowOnlyAssignedToMeContacts está ativado, um Agent só trabalha com os contatos atribuídos a ele; quando allowContactsWithEmptyAssignee está desativado, os contatos sem responsável ficam ocultos.

"CustomRoleNotSupported"

Convites e mudanças de função aceitam Admin, Editor e Agent. Funções Custom não podem ser atribuídas por meio dessas mutações.

O aviso de remoção "FuelySwitchToHumanAssignee"

O membro está definido como a pessoa para quem o Fuely AI transfere as conversas. Depois da remoção, escolha outra pessoa na configuração Switch to human da automação para que os chats não fiquem sem responsável.