Bots e mensagens interativas

Uma conta de bot é um usuário criado para um programa. Ela possui seu próprio nome, imagem e tokens, e exibe a tag BOT ao lado do nome. Esta página também aborda as partes interativas das mensagens: botões, menus e diálogos, que qualquer integração pode usar.

Por que usar uma conta de bot

• Suas mensagens vêm de uma identidade clara, com a tag BOT, em vez de virem da conta de um colega.
• Seus tokens continuam funcionando quando a pessoa que o configurou muda de função ou sai (a menos que o servidor desative os bots de proprietários desativados, veja abaixo).
• Bots não podem fazer login com senha e nunca veem o aplicativo web.

Aplicativos criam seus próprios bots, como os bots de Tarefas ou Playbooks, por meio da API de plugins (EnsureBotUser).

Ativar contas de bot

Um administrador do sistema ativa Ativar Criação de Conta Bot em Console do Sistema › Integrações › Contas de bot (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Essa opção está desativada por padrão. Somente administradores do sistema podem criar bots, a menos que concedam esse direito a outras funções nas configurações de permissões.

Na mesma página, Desativar contas bot quando o dono é desativado (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, ativado por padrão) desativa um bot quando a conta do seu proprietário é desativada.

Criar um bot

1. Abra seu avatar no canto superior direito, depois Integrações › Contas de bot, e depois Adicionar Conta de Bot.
2. Insira um Usuário (letras minúsculas, números, pontos, traços e sublinhados) e, opcionalmente, um Ícone do Bot, um Nome de Exibição e uma Descrição.
3. Escolha a Função: Membro, ou Administrador do Sistema para um bot que gerencia o servidor. Dê ao bot apenas o mínimo necessário.
4. Marque publicar:canais para permitir que ele publique em todos os canais públicos, ou publicar:todos para todos os canais, incluindo canais privados e mensagens diretas, sem ser membro.
5. Defina quando o token padrão expira e, em seguida, escolha Criar Conta de Bot.
6. Copie o token de acesso exibido. Ele não será exibido novamente.

Mais tarde, Criar Novo Token na linha do bot adiciona um token, e cada token pode ser desativado ou excluído. Os tokens de bot funcionam mesmo quando os tokens de acesso pessoal estão desativados para pessoas.

Com a API:

# create the bot (you become its owner)
curl -X POST https://chat.example.com/api/v4/bots \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"username": "deploy-bot", "display_name": "Deploy", "description": "Posts deployments"}'

# give it a token
curl -X POST https://chat.example.com/api/v4/users/$BOT_USER_ID/tokens \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"description": "deploy pipeline"}'

A partir da linha de comando, conectado como administrador (não no modo local): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Outros endpoints: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable e /enable, POST /api/v4/bots/{bot_user_id}/assign/{user_id} para alterar o proprietário.

Adicione o bot a comunidades e canais

Um novo bot não pertence a nenhuma comunidade. Adicione-o como uma pessoa, pela gestão de membros da comunidade ou pela API:

curl -X POST https://chat.example.com/api/v4/teams/$TEAM_ID/members \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"team_id": "'$TEAM_ID'", "user_id": "'$BOT_USER_ID'"}'

curl -X POST https://chat.example.com/api/v4/channels/$CHANNEL_ID/members \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"user_id": "'$BOT_USER_ID'"}'

Um bot com publicar:canais ou publicar:todos pode publicar sem ser membro, mas ele só recebe eventos WebSocket para os canais nos quais está.

Publique como o bot

Use o token do bot em qualquer chamada de API; POST /api/v4/posts é a mais comum (veja Recursos principais). Para escrever diretamente para alguém, abra primeiro o canal de mensagem direta:

# returns the channel; use its "id" as channel_id
curl -X POST https://chat.example.com/api/v4/channels/direct \
  -H "Authorization: Bearer $BOT_TOKEN" -H 'Content-Type: application/json' \
  -d '["'$BOT_USER_ID'", "'$USER_ID'"]'

Para reagir ao que as pessoas dizem, acompanhe o WebSocket com o token do bot e responda aos eventos posted que lhe interessam. Ignore as próprias mensagens do bot para evitar loops.

Uma mensagem visível apenas para uma pessoa (uma mensagem efêmera) é enviada com POST /api/v4/posts/ephemeral e {"user_id", "post": {"channel_id", "message"}}. Ela requer a permissão create_post_ephemeral, que por padrão só administradores do sistema possuem. As integrações geralmente enviam mensagens efêmeras como respostas a comandos de barra e botões.

Mensagens interativas: botões e menus

Qualquer mensagem com anexos pode carregar ações: botões e menus para seleção. Elas funcionam em mensagens publicadas pela API, webhooks e respostas de comandos de barra. Quando alguém usa uma delas, o Antimatter chama a URL da sua integração.

{
  "channel_id": "…",
  "message": "Deploy **api 2.4.0** to production?",
  "props": {
    "attachments": [{
      "actions": [
        {
          "id": "approve",
          "type": "button",
          "name": "Approve",
          "style": "primary",
          "integration": {"url": "https://deploy.example.com/actions", "context": {"release": "2.4.0", "action": "approve"}}
        },
        {
          "id": "env",
          "type": "select",
          "name": "Pick an environment",
          "options": [{"text": "Staging", "value": "staging"}, {"text": "Production", "value": "production"}],
          "integration": {"url": "https://deploy.example.com/actions", "context": {"release": "2.4.0", "action": "env"}}
        }
      ]
    }]
  }
}

• type: button ou select.
• id: letras, números, traços e sublinhados, diferentes para cada ação da mensagem. É gerado quando você o omite.
• style (botões): default, primary, success, good, warning, danger, ou uma cor em hexadecimal.
• options (menus), ou data_source: users ou channels para selecionar uma pessoa ou um canal. default_option pré-seleciona um valor.
• integration.url: para onde o clique é enviado. Um aplicativo (plugin) pode usar sua própria rota, como /plugins/com.example.deploy/actions. integration.context é seu: ele retorna com o clique, e os clientes nunca o veem.

A solicitação que sua integração recebe

{
  "user_id": "…",
  "user_name": "priya",
  "channel_id": "…",
  "channel_name": "releases",
  "team_id": "…",
  "team_domain": "lumen-labs",
  "post_id": "…",
  "trigger_id": "…",
  "type": "button",
  "context": {"release": "2.4.0", "action": "approve"}
}

Para um menu, type é select e context.selected_option contém o valor escolhido.

Sua resposta

{
  "update": {"message": "Deploy of **api 2.4.0** approved by @priya", "props": {}},
  "ephemeral_text": "Done. The deploy starts in a minute."
}

• update: substitui o texto e as propriedades da mensagem, por exemplo, para remover os botões após o uso (um props vazio).
• ephemeral_text: uma mensagem que apenas a pessoa que clicou vê.
• goto_location: uma URL para abrir.
• Um corpo vazio não altera nada.

O servidor aguarda pelo tempo permitido pelo Tempo limite de solicitação de integração (30 segundos por padrão). As URLs de integração em endereços de rede privada devem ser permitidas por um administrador do sistema, assim como os webhooks.

Diálogos

Um diálogo é um formulário que abre sobre o chat. Você só pode abrir um em resposta a algo que a pessoa acabou de fazer, um comando de barra ou um botão, porque ele precisa do trigger_id dessa solicitação. O trigger_id é válido pelo tempo do tempo limite de solicitação de integração.

curl -X POST https://chat.example.com/api/v4/actions/dialogs/open \
  -H 'Content-Type: application/json' \
  -d '{
    "trigger_id": "'$TRIGGER_ID'",
    "url": "https://deploy.example.com/dialog",
    "dialog": {
      "callback_id": "new-release",
      "title": "New release",
      "introduction_text": "Fill in the release details.",
      "submit_label": "Create",
      "notify_on_cancel": false,
      "state": "anything you want back",
      "elements": [
        {"display_name": "Version", "name": "version", "type": "text", "placeholder": "2.4.0"},
        {"display_name": "Notes", "name": "notes", "type": "textarea", "optional": true},
        {"display_name": "Environment", "name": "env", "type": "select",
         "options": [{"text": "Staging", "value": "staging"}, {"text": "Production", "value": "production"}]},
        {"display_name": "Owner", "name": "owner", "type": "select", "data_source": "users"},
        {"display_name": "Notify the channel", "name": "notify", "type": "bool", "default": "true"}
      ]
    }
  }'

Cada elemento aceita display_name, name, help_text, placeholder, default e optional.

Quando a pessoa envia, o Antimatter faz um POST para a url do diálogo:

{
  "type": "dialog_submission",
  "callback_id": "new-release",
  "state": "anything you want back",
  "user_id": "…",
  "channel_id": "…",
  "team_id": "…",
  "submission": {"version": "2.4.0", "notes": "", "env": "staging", "owner": "…", "notify": true},
  "cancelled": false
}

Responda com um corpo vazio para fechar o diálogo, ou mantenha-o aberto e mostre o que está errado:

{"errors": {"version": "This version already exists."}}

{"error": "…"} exibe uma mensagem para o formulário inteiro. Com notify_on_cancel, fechar o diálogo envia "cancelled": true. Diálogos funcionam da mesma forma em aplicativos: o OpenInteractiveDialog da API de plugins aceita a mesma solicitação.