Botok és interaktív üzenetek

A bot-fiók egy program számára létrehozott felhasználó. Saját neve, képe és tokenjei vannak, a neve mellett pedig BOT címkét jelenít meg. Ez az oldal a bejegyzések interaktív elemeit is leírja: gombok, menük és párbeszédablakok, amelyeket bármilyen integráció használhat.

Miért érdemes botfiókot használni

• Az üzenetei egyértelmű identitástól származnak, BOT jelzéssel, nem pedig egy kolléga fiókja által.
• A tokenjei akkor is működnek, ha a beállító személy szerepköre megváltozik, vagy kilép (kivéve, ha a szerver letiltja a deaktivált tulajdonosok botjait, lásd alább).
• A botok nem jelentkezhetnek be jelszóval, és soha nem látják a webböngészős alkalmazást.

Az alkalmazások saját botokat hoznak létre, például a Teendők vagy a Playbook botokat, a bővítmény-API (EnsureBotUser) segítségével.

Botfiókok engedélyezése

A rendszeradmin a Rendszerkonzol › Integrációk › Botfiókok menüben engedélyezi a Bot fiók létrehozás engedélyezése beállítást (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Alapértelmezetten letiltva van. Csak a rendszeradminok hozhatnak létre botokat, hacsak nem adják meg ezt a jogosultságot más szerepköröknek a jogosultsági beállításokban.

Ugyanezen az oldalon a Bot fiókok letiltása a tulajdonos letiltásakor beállítás (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, alapértelmezetten engedélyezve) letiltja a botot, ha a tulajdonos fiókja deaktiválva lett.

Bot létrehozása

1. Nyissa meg az avatárját a jobb felső sarokban, majd válassza a Integrációk › Botfiókok, és utána az Bot fiók hozzáadása lehetőséget.
2. Adja meg a Felhasználónevet (kisbetűk, számok, pontok, kötőjelek és alulvonások), valamint opcionálisan a Bot ikont, a Megjelenítési nevet és a Leírást.
3. Válassza ki a Szerepkört: Tag, vagy Rendszeradmin egy olyan bot számára, amely kezeli a szervert. Adjon a botnak csak annyi jogosultságot, amennyire szüksége van.
4. Jelölje be a bejegyzés:csatornák lehetőséget, hogy minden nyílt csatornában posztálhasson, vagy a bejegyzés:mind lehetőséget, hogy minden csatornában, privát csatornákban és közvetlen üzenetekben is posztálhasson, tagként nem.
5. Állítsa be, hogy a alapértelmezett token mikor jár le, majd válassza a Bot fiók létrehozása lehetőséget.
6. Másolja ki a megjelenített hozzáférési tokent. Ez nem jelenik meg újra.

Később a bot sorában az Új token létrehozása gombbal adhat hozzá tokent, és minden tokent letilthat vagy törölhet. A bot tokenek akkor is működnek, ha a személyes hozzáférési tokenek letiltva vannak a felhasználók számára.

Az API-val:

# 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 parancssorból, adminisztrátorként bejelentkezve (nem helyi módban): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Egyéb végpontok: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable és /enable, valamint POST /api/v4/bots/{bot_user_id}/assign/{user_id} a tulajdonosának megváltoztatásához.

A bot hozzáadása közösségekhez és csatornákhoz

Egy új bot eleinte egyetlen közösséghez sem tartozik. Hozzáadható olyan módon, mint egy ember: a közösség tagkezelésén keresztül, vagy az API-val:

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

Egy bejegyzés:csatornák vagy bejegyzés:mind jogosultsággal rendelkező bot tagként nem is kell, hogy csatlakozzon a csatornákhoz, hogy bejegyezzen, de csak azokon a csatornákon kap WebSocket-eseményeket, ahol tag.

Bejegyzés a bot nevében

A bot tokenjét bármilyen API-híváshoz használhatod; a leggyakoribb a POST /api/v4/posts (lásd: Fő erőforrások). Ha közvetlenül valakinek szeretnél írni, először nyisd meg a közvetlen üzenet csatornáját:

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

Ha reagálni szeretnél az emberek által mondottakra, kövesd a WebSocket csatornát a bot tokenjével, és válaszolj a posted eseményekre, amelyek érdekelnek. A bot saját üzeneteit hagyd ki, hogy elkerüld a végtelen ciklusokat.

Egy olyan üzenet, amelyet csak egy személy láthat (ideiglenes üzenet), a POST /api/v4/posts/ephemeral végponttal és a {"user_id", "post": {"channel_id", "message"}} testtel küldhető. Ehhez a create_post_ephemeral jogosultság szükséges, amelyre alapértelmezés szerint csak a rendszeradminisztrátorok jogosultak. Az integrációk általában ideiglenes üzeneteket küldenek válaszként perjeles parancsokra és gombokra.

Interaktív üzenetek: gombok és menük

Bármely csatolmánnyal rendelkező üzenet viselhet műveleteket: gombokat és menüket. Ezek működnek az API-val, webhookokkal és perjeles parancsokkal küldött üzenetekben is. Amikor valaki használja az egyiket, az Antimatter meghívja az integráció URL-jét.

{
  "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 vagy select.
• id: betűk, számok, kötőjelek és alvonalak; minden üzeneti műveletnek egyedi azonosítója. Ha ki hagyod, a rendszer generál egyet.
• style (gombok): default, primary, success, good, warning, danger, vagy egy hex színkód.
• options (menük), vagy data_source: users vagy channels egy személy vagy csatorna kiválasztásához. A default_option előre kiválaszt egy értéket.
• integration.url: ide küldi a kattintást. Egy alkalmazás (bővítmény) használhatja a saját útvonalát, például /plugins/com.example.deploy/actions. A integration.context a sajátod: a kattintással együtt visszaküldi, és a kliensek soha nem látják.

A kérés, amelyet az integrációd kap

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

Menü esetén a type értéke select, és a context.selected_option tartalmazza a kiválasztott értéket.

A válaszod

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

• update: lecseréli az üzenet szövegét és tulajdonságait, például a gombok eltávolításához használat után (üres props).
• ephemeral_text: olyan üzenet, amelyet csak a kattintó személy lát.
• goto_location: egy megnyitandó URL.
• Egy üres test nem változtat semmit.

A szerver addig vár, amíg az Integrációs kérés időtúllépési határa engedi (alapértelmezés szerint 30 másodperc). A privát hálózati címeken lévő integrációs URL-eket a rendszeradminisztrátornak engedélyeznie kell, ahogy a webhookoknál is.

Párbeszédablakok

A párbeszédablak egy űrlap, amely a csevegés felett nyílik meg. Csak akkor nyitható meg, ha valaki éppen most végzett valamit, például perjeles parancsot vagy gombot használt, mert ehhez a kérés trigger_id-je szükséges. A trigger_id addig érvényes, amíg az integrációs kérés időtúllépési határa meg nem telik.

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

Minden elem elfogadja a display_name, name, help_text, placeholder, default és optional mezőket.

Amikor a felhasználó beküldi, az Antimatter POST-kéri a párbeszédablak url-jét:

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

Válassz üres testtel, hogy bezárd a párbeszédablakot, vagy tartsd nyitva, és jelezd, mi a hiba:

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

{"error": "…"} az egész űrlapra vonatkozó üzenetet jelenít meg. A notify_on_cancel beállításával a párbeszédablak bezárása "cancelled": true értékű kérést küld. Az alkalmazásokban a párbeszédablakok ugyanígy működnek: a bővítmény-API OpenInteractiveDialog függvénye ugyanazt a kérést fogadja.