Usuários virtuais na Public API do Chatfuel

Um usuário virtual é um membro de um bot do Chatfuel que usa apenas a API. Ele tem um nome, a função Editor ou Agent e o próprio token da Public API, mas não tem login: não pode entrar no painel nem ver outros bots, workspaces ou a cobrança. Os usuários virtuais são a forma como as integrações devem chamar a Public API, porque cada um fica limitado a um único bot e a uma única função e pode ser revogado sem afetar a sua própria conta.

Somente um Admin do bot pode criar, rotacionar, mudar a função ou remover usuários virtuais, e somente com um token de API pessoal. Um bot pode ter até 20 usuários virtuais.

Como criar um usuário virtual

Somente token pessoal. Chame createVirtualUser com o ID do bot, um nome e uma função:

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

• name é obrigatório, com 1 a 100 caracteres depois de remover os espaços das pontas. É o que os membros da sua equipe veem no painel, então dê ao usuário virtual o nome da integração ou do cliente que ele atende.
• role.roleType deve ser Editor ou Agent. As permissões em botPermissions são ignoradas: um usuário virtual sempre recebe o conjunto padrão de permissões da sua função, ajustado pelas configurações de funções do bot. Passe uma lista vazia.
• authToken na resposta é o token do usuário virtual. Ele só é retornado aqui. Guarde-o junto com member.id, o ID de membro de que você precisa para qualquer alteração posterior.

O que usuários virtuais Editor e Agent podem fazer

As permissões de um usuário virtual vêm apenas da função dele no bot. As duas funções permitidas correspondem às funções Editor e Agent dos membros humanos da equipe.

Um usuário virtual Editor pode:

• ler e editar contatos, atributos, notas, responsáveis e etapas de venda, além de importar e exportar contatos
• ler conversas e enviar mensagens em todos os canais
• criar e alterar fluxos, regras de palavras-chave, configurações do Fuely AI, automações e transmissões
• gerenciar agendamentos, especialistas, produtos e serviços
• alterar as configurações do widget do site e publicar na conta do Instagram conectada

Um usuário virtual Agent pode:

• ler contatos e exportá-los, mas não editar nomes, atributos ou notas
• ler conversas, enviar mensagens e templates do WhatsApp
• atribuir contatos, definir o responsável do Fuely AI e mover contatos entre etapas de venda
• ver fluxos e automações e executar chats de teste, mas não alterá-los

Nenhuma das duas funções pode renomear ou excluir o bot, alterar o fuso horário ou o país dele, gerenciar membros da equipe, conectar ou desconectar canais nem mexer em workspaces e cobrança. Essas operações precisam de um token de API pessoal, como listado em autenticação. Cada operação nas páginas de referência informa a função mínima que pode executá-la.

Como regenerar o token de um usuário virtual

Somente token pessoal. Rotacione um token quando ele puder estar exposto ou quando alguém com acesso sair:

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

O token antigo para de funcionar imediatamente, e a mutação retorna o novo token como string. Se memberID pertencer a um membro humano da equipe, a chamada falha com NotVirtualUser.

Como alterar a função de um usuário virtual

Somente token pessoal. Alterne um usuário virtual entre Editor e Agent com changeBotMemberRoleV2:

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

A mesma alteração está disponível no painel: Settings → Teammates, selecione o usuário virtual e depois Manage teammate. Para usuários virtuais, só Editor e Agent são oferecidos.

Como remover um usuário virtual

Somente token pessoal. Remover um usuário virtual exclui a conta e o token dela permanentemente:

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

No painel, abra Settings → Teammates, selecione o usuário virtual e escolha Delete API user. O painel exibe este aviso: "This deletes the account and its API token permanently. Anything calling the API with that token will stop working. Delete anyway?" (Isso exclui a conta e o token de API dela permanentemente. Tudo o que chamar a API com esse token vai parar de funcionar. Excluir mesmo assim?)

Excluir um bot também exclui todos os usuários virtuais dele.

Como os usuários virtuais aparecem no painel e na API

No painel, um usuário virtual aparece em Settings → Teammates com o rótulo API depois do nome. O mesmo rótulo aparece na lista de responsáveis dos contatos e nas configurações de transferência para humano do Fuely AI, então você pode atribuir contatos a uma integração como faria com um membro da equipe.

Na API, a conta de um usuário virtual tem accountType: Virtual. Quando um usuário virtual lê a própria conta com currentUser, ele recebe a si mesmo, não a pessoa que o criou, e currentUser.botsV2 retorna apenas o próprio bot. A sua conta e os seus outros bots nunca aparecem nas respostas dele.

Problemas comuns

"VirtualUsersLimitReached"

O bot já tem 20 usuários virtuais. Remova os que você não usa mais com removeMemberFromBot ou reutilize um usuário virtual existente para a integração.

"VirtualUserNameInvalid"

O nome está vazio ou tem mais de 100 caracteres depois de remover os espaços das pontas.

"VirtualUserRoleNotAllowed"

A função é Admin ou Custom. Usuários virtuais só podem ser Editor ou Agent.

"NotVirtualUser"

regenerateVirtualUserToken foi chamado com o ID de membro de um membro humano da equipe. Use o ID de membro retornado por createVirtualUser ou encontre-o em bot(id:) { members { id user { name accountType } } }.