Boti a interaktivní zprávy

Účet bota je uživatel vytvořený pro program. Má vlastní název, obrázek a tokeny a vedle svého názvu zobrazuje štítek BOT. Tato stránka se také věnuje agentům AI, které provozujete sami, a interaktivním částem zpráv: tlačítkům, nabídkám a dialogům, které může používat jakákoli integrace.

Proč botový účet

• Jeho zprávy pocházejí z jasně identifikovatelné identity se štítkem BOT, nikoli z účtu kolegy.
• Jeho tokeny fungují i v případě, že osoba, která je nastavila, změní roli nebo odejde (pokud to server nevyžaduje, viz níže).
• Boti se nemohou přihlásit heslem a nikdy nevidí webovou aplikaci.

Aplikace si vytvářejí vlastní boty, například boty pro Úkoly nebo Playbooky, prostřednictvím plugin API (EnsureBotUser). Agenti AI jsou také účty botů, ale vlastního druhu, označené štítkem AGENT: viz Agenti.

Zapnutí botových účtů

Systémový administrátor zapne Povolit vytváření účtů botů v Systémová konzole › Integrace › Účty botů (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Výchozí stav je vypnuto. Boty mohou vytvářet pouze systémoví administrátoři, pokud jim v nastavení oprávnění neudělíte toto právo i jiným rolím.

Na stejné stránce je možnost Zakázat účty botů, když je vlastník deaktivován (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, výchozí stav je zapnuto), která vypne bota, když je účet jeho vlastníka deaktivován.

Vytvoření bota

1. Otevřete nabídku týmu, pak Nastavení týmu, klikněte na Integrace na konci jejích karet, pak na Účty botů a Přidat účet bota.
2. Zadejte Uživatelské jméno (malá písmena, číslice, tečky, pomlčky a podtržítka) a volitelně Ikona bota, Zobrazovaný název a Popis.
3. Vyberte Role: Člen nebo Systémový administrátor pro bota, který spravuje server. Bota nadělejte pouze těch oprávnění, která skutečně potřebuje.
4. Zaškrtněte post:channels, aby mohl odesílat zprávy do všech veřejných kanálů, nebo post:all pro všechny kanály, včetně soukromých a přímých zpráv, aniž by musel být členem.
5. Nastavte, kdy vyprší platnost výchozího tokenu, a poté zvolte Vytvořit účet bota.
6. Zkopírujte zobrazený přístupový token. Znovu se nezobrazí.

Později můžete na řádku bota použít Vytvořit nový token pro přidání tokenu. Každý token lze vypnout nebo smazat. Tokeny botů fungují i v případě, že jsou osobní přístupové tokeny pro uživatele vypnuté.

Bot může nést atributy serveru (nastavené v Systémová konzole › Systémové atributy), které se nastavují ve formuláři pro přidání nebo úpravu bota nebo prostřednictvím Upravit atributy… v nabídce ⋯ daného bota. Nastavuje je ten, kdo bota spravuje: jeho vlastník s oprávněním spravovat boty, nebo kdokoli s oprávněním spravovat boty ostatních. Atributy spravované administrátorem stále vyžadují systémového administrátora. Bot AI agenta nepatří nikomu, takže jeho atributy mohou nastavit pouze osoby s oprávněním spravovat boty ostatních nebo systémoví administrátoři.

Přes 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"}'

Z příkazového řádku, přihlášený jako administrátor (ne v lokálním režimu): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Další koncové body: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable a /enable, POST /api/v4/bots/{bot_user_id}/assign/{user_id} pro změnu vlastníka.

Přidejte bota do komunit a kanálů

Nový bot není v žádné komunitě. Přidejte ho jako osobu, buď přes správu členů komunity, nebo pomocí 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'"}'

Bot s oprávněním post:channels nebo post:all může publikovat bez toho, aby byl členem, ale přijímá WebSocket události pouze pro kanály, ve kterých se nachází.

Publikujte jménem bota

Použijte token bota pro jakýkoli API volání; POST /api/v4/posts je nejběžnější (viz Hlavní zdroje). Pro přímé psaní někomu nejdřív otevřete kanál přímé zprávy:

# 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'"]'

Pokud chcete reagovat na to, co lidé říkají, sledujte WebSocket s tokenem bota a reagujte na události posted, které vás zajímají. Ignorujte vlastní zprávy bota, abyste předešli smyčkám.

Zprávu, kterou vidí jen jedna osoba (efemerní zprávu), odešlete pomocí POST /api/v4/posts/ephemeral a {"user_id", "post": {"channel_id", "message"}}. Vyžaduje oprávnění create_post_ephemeral, které mají ve výchozím nastavení pouze systémoví administrátoři. Integrace obvykle efemerní zprávy odesílají jako odpovědi na příkazy s lomítkem a tlačítka.

Agenti

Agent je účet bota typu agent: uživatelé mají "is_agent": true, boti "kind": "agent" a rozhraní místo štítku BOT zobrazuje štítek AGENT. Agenty vytvářejí pouze systémoví administrátoři (agenti pro celý server) v Systémová konzole › AI › Připojení k modelům a administrátoři komunity (pro svou komunitu) na kartě AI v nastavení komunity, nebo pomocí /api/v4/ai/agents (viz API). Bot vytvořený pomocí POST /bots nebo aplikací je vždy běžný bot.

Na vestavěného agenta odpovídá server pomocí připojení k modelu. Externí agent je na vás: program běžící jinde (například kódovací agent v projektu), který se přihlásí jako agent a odpovídá jako člověk. Antimatter za něj neodpovídá.

Stav vestavěného agenta nastavuje server: Online, když jeho připojení k modelu odpovídá, Pryč, když neodpovídá (výpadek, vypršení časového limitu, zamítnutý klíč), a Offline, když je vypnutý nebo nemá žádné použitelné připojení či model. Stav se kontroluje při změně agenta nebo jeho připojení, při testování připojení, při každém volání modelu agenta a každých 10 minut. Nikdo nemůže nastavit stav vestavěného agenta: PUT /users/{id}/status a koncové body pro vlastní stav odpovídají 403 (api.status.agent.app_error), a to i pro systémové administrátory. Plugin API metody UpdateUserStatus, SetUserStatusTimedDND, UpdateUserCustomStatus a RemoveUserCustomStatus to odmítají stejným způsobem. Stav externího agenta se řídí jeho vlastním připojením a změnit ho může pouze jeho vlastní token.

Provoz externího agenta

1. Administrátor přidá agenta v Systémová konzole › AI › Připojení k modelům (nebo na kartě AI komunity), s typem Externí agent, a zvolí, kdo s ním může komunikovat. Stránka pak zobrazí návod na připojení.
2. Přiřaďte mu token: administrátor systému otevře Integrace › Účty botů, najde účet agenta a zvolí Vytvořit nový token, nebo zavolá API pro tokeny s ID uživatele agenta:

   curl -X POST https://chat.example.com/api/v4/users/$AGENT_USER_ID/tokens \
     -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
     -d '{"description": "agent"}'

3. Program volá API a otevírá WebSocket s Authorization: Bearer <token>, čte své zmínky a přímé zprávy z událostí posted a odpovídá pomocí POST /posts ve vláknu zprávy.
4. Lidem ukazuje, co dělá, nastavením své aktivity:

   curl -X PUT https://chat.example.com/api/v4/ai/agents/$AGENT_USER_ID/activity \
     -H "Authorization: Bearer $AGENT_TOKEN" -H 'Content-Type: application/json' \
     -d '{"state": "working", "text": "Running the tests", "thread_post_id": "'$ROOT_ID'"}'

ID agenta v těchto cestách je jeho ID uživatele. Token udržujte v tajnosti: kdokoli, kdo ho má, může odesílat zprávy jako agent.

Aktivita

• state: idle, thinking, working, waiting (na někoho), blocked nebo offline. Zaneprázdněné stavy (thinking, working, waiting, blocked) se po uplynutí hodnoty expires_in_seconds vrátí do stavu idle: výchozí hodnota je 10 minut, maximálně 24 hodin.
• text: stručný popis úkolu, jeden řádek s maximálně 200 znaky. Rozhraní jej zobrazuje v seznamu členů a na kartě profilu.
• thread_post_id: identifikátor vlákna, ve kterém agent pracuje. Program musí mít k tomuto vláknu přístup pro čtení. Tento údaj je poskytován pouze uživatelům, kteří mají oprávnění vlákno číst.

Uživatelé, kteří vidí agenta, mohou číst jeho aktivitu (GET /ai/agents/{agent_id}/activity nebo POST /ai/agents/activity/ids s seznamem ID) a přijímají událost WebSocketu agent_activity_changed, a to bez obsahu vlákna. Vestavění agenti nastavují svou aktivitu automaticky.

Během psaní odpovědi vestavěným agentem server posílá postupně se rozšiřující text v událostech agent_post_stream do kanálu: post_id, channel_id, root_id, user_id, message (dosud napsaný text) a control (start, text, end, error nebo cancel). Událost post_edited obsahuje finální zprávu. Klienti, kteří stream ignorují, uvidí odpověď až po jejím uložení.

Interaktivní zprávy: tlačítka a nabídky

Jakákoli zpráva s přílohami může nést akce: tlačítka a nabídky pro výběr. Fungují ve zprávách publikovaných přes API, webhooks a odpovědi na příkazy s lomítkem. Když je někdo použije, Antimatter zavolá URL vaší integrace.

{
  "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 nebo select.
• id: písmena, číslice, pomlčky a podtržítka, odlišná pro každou akci v zprávě. Pokud ji neuvédete, vygeneruje se automaticky.
• style (tlačítka): default, primary, success, good, warning, danger nebo barva v hexadecimálním zápisu.
• options (nabídky) nebo data_source: users nebo channels pro výběr osoby nebo kanálu. default_option předem vybere hodnotu.
• integration.url: adresa, na kterou se odesílá kliknutí. Aplikace (plugin) může použít vlastní trasu, například /plugins/com.example.deploy/actions. integration.context je vaše: vrací se s kliknutím a klienti ho nikdy nevidí.

Požadavek, který vaše integrace přijme

{
  "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"}
}

Pro menu je type rovné select a context.selected_option obsahuje vybranou hodnotu.

Vaše odpověď

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

• update: nahrazí text a vlastnosti zprávy, například aby se po použití odstranily tlačítka (prázdné props).
• ephemeral_text: zpráva, kterou uvidí pouze osoba, která klikla.
• goto_location: URL k otevření.
• Prázdné tělo nic nezmění.

Server čeká tak dlouho, jak to dovoluje Časový limit požadavků integrací (výchozí hodnota je 30 sekund). URL adresy integrací na soukromých síťových adresách musí povolit systémový administrátor, stejně jako u webhooků.

Dialogy

Dialog je formulář, který se otevře nad chatem. Otevřít ho můžete pouze jako odpověď na něco, co osoba právě udělala, na příkaz s lomítkem nebo na tlačítko, protože je potřeba trigger_id z toho požadavku. trigger_id je platný po dobu časového limitu požadavku integrace.

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"}
      ]
    }
  }'

Každý prvek přijímá display_name, name, help_text, placeholder, default a optional.

submit_buttons v definici dialogu určuje statický prvek select: jeho možnosti se stanou tlačítky pro odeslání dialogu (jedno tlačítko pro každou možnost) místo jednoho tlačítka Odeslat a samotný prvek select se nezobrazí. Atribut size ("small", "medium" nebo "large"; výchozí je "small") určuje širší dialog. Atribut refresh_on_return (vyžaduje source_url) zajistí, že se dialog znovu načte z source_url po uzavření dialogu, který byl otevřen nad ním, aby se zobrazily aktuální změny. Nerozpoznaná hodnota size nebo sub_type nezabrání otevření dialogu: použije se výchozí hodnota a server tuto skutečnost pouze zaznamená do logu.

Když osoba odešle, Antimatter pošle požadavek POST na url dialogu:

{
  "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
}

Odpovězte prázdným tělem, abyste dialog zavřeli, nebo ho nechte otevřený a zobrazte, co je špatně:

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

{"error": "…"} zobrazí zprávu pro celý formulář. S notify_on_cancel odesílá zavření dialogu "cancelled": true. Dialogy fungují stejně i v aplikacích: OpenInteractiveDialog z plugin API přijímá stejný požadavek.