Bottit ja interaktiiviset viestit

Bottitili on ohjelmalle tarkoitettu käyttäjä. Sillä on oma nimi, kuva ja tunnukset, ja sen nimen vieressä näkyy BOT-tunniste. Tämä sivu käsittelee myös itse hallinnoimiasi tekoälyagenteja sekä viestien interaktiivisia osia: painikkeita, valikoita ja dialogeja, joita mikä tahansa integraatio voi käyttää.

Miksi bottitili

• Sen viestit tulevat selvästä identiteetistä, jossa on BOTTI-merkki, eikä kollegan tililtä.
• Sen tunnukset toimivat edelleen, vaikka asettaja vaihtaisi roolia tai poistuisi (ellei palvelin poista poistettujen omistajien bottitilejä käytöstä, ks. alla).
• Bottit eivät voi kirjautua salasanan avulla, eikä ne koskaan näe verkkosovellusta.

Sovellukset luovat omat bottinsa, kuten Tehtävälista- tai Ohjekirja-botit, lisäosarajapinnan kautta (EnsureBotUser). Tekoälyagentit ovat myös bottitilejä, mutta omaa tyyppiään, ja ne näkyvät AGENT-tunnisteella: katso Agentit.

Ota bottitilit käyttöön

Järjestelmän ylläpitäjä ottaa Ota bottitilien luominen käyttöön -asetuksen käyttöön kohdassa Järjestelmäkonsoli › Integraatiot › Bottitilit (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Asetus on oletusarvona pois käytöstä. Vain järjestelmän ylläpitäjät voivat luoda bottitilejä, ellei he anna oikeutta muihin rooleihin oikeusasetuksissa.

Samalla sivulla Poista bottitili käytöstä, kun omistaja poistetaan käytöstä (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, oletusarvona käytössä) poistaa bottitilin käytöstä, kun sen omistajan tili poistetaan käytöstä.

Luo bottitili

1. Avaa tiimivalikko, valitse Tiimin asetukset, klikkaa välilehtien lopussa Integraatiot, sitten Bottitilit ja Lisää bottitili.
2. Syötä Käyttäjätunnus (piisää kirjaimia, numeroita, pisteitä, väliviivoja ja alaviivoja) sekä valinnaisesti Bottin kuvake, Näyttönimi ja Kuvaus.
3. Valitse Rooli: Jäsen tai Järjestelmän ylläpitäjä, jos botti hallinnoi palvelinta. Anna bottille vain se, mitä se todella tarvitsee.
4. Valitse post:channels, jotta botti voi lähettää viestejä kaikkiin julkisiin kanaviin, tai post:all, jotta se voi lähettää viestejä kaikkiin kanaviin, myös yksityisiin kanaviin ja suoriin viesteihin, ilman että se on kanavan jäsen.
5. Aseta, milloin sen oletustunnus vanhenee, ja valitse Luo bottitili.
6. Kopioi näytetty pääsytunnus. Sitä ei näytetä uudelleen.

Myöhemmin Luo uusi tunnus bottitilin rivillä lisää uuden tunnuksen, ja jokainen tunnus voidaan poistaa käytöstä tai poistaa. Bottitunnukset toimivat, vaikka henkilökohtaiset pääsytunnukset olisivat poistettu käytöstä käyttäjiä varten.

Botti voi sisältää palvelinmääritteitä (ne, jotka on määritetty Järjestelmäkonsoli › Järjestelmän ominaisuudet -kohdassa). Ne asetetaan Lisää/Muokkaa bottia -lomakkeella tai bottin ⋯-valikon Muokkaa ominaisuuksia…-kohdasta. Ne asettaa se, joka hallinnoi bottia: sen omistaja, jolla on bottien hallintaoikeus, tai kuka tahansa, jolla on muiden bottien hallintaoikeus. Järjestelmänvalvojan hallinnoima määrite vaatii edelleen järjestelmänvalvojan oikeudet. Tekoälyagentin botti ei kuulu kenellekään, joten vain henkilö, jolla on muiden bottien hallintaoikeus, tai järjestelmänvalvoja voi asettaa sen määritteet.

API:n avulla:

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

Komentoriviltä, kirjautuneena ylläpitäjänä (ei paikallisessa tilassa): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Muut rajapinnat: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable ja /enable sekä POST /api/v4/bots/{bot_user_id}/assign/{user_id} omistajan vaihtamiseksi.

Lisää botti yhteisöihin ja kanaviin

Uusi botti ei ole missään yhteisössä. Lisää se kuten henkilö, yhteisön jäsenhallinnasta tai API:n kautta:

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

Botti, jolla on post:channels- tai post:all-oikeus, voi kirjoittaa ilman jäsenyyttä, mutta se saa WebSocket-tapahtumat vain sille kanaville, joihin se on liitetty.

Kirjoita bottin nimellä

Käytä bottin tokenia minkä tahansa API-kutsun yhteydessä; POST /api/v4/posts on yleisin (katso Pääresurssit). Suoraan jollekulle kirjoittamiseksi avaa ensin suora viestikanava:

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

Reaktioita ihmisten kommentteihin varten seuraa WebSocket-yhteyttä bottin tokenilla ja vastaa posted-tapahtumiin, jotka kiinnostavat. Ohita bottin omat viestit, jotta vältät silmukat.

Viesti, jonka vain yksi henkilö näkee (ephemeral-viesti), lähetetään POST /api/v4/posts/ephemeral-kutsulla ja {"user_id", "post": {"channel_id", "message"}}-kuormalla. Se vaatii create_post_ephemeral-oikeuden, joka on oletuksena vain järjestelmäylläpitäjillä. Integraatiot lähettävät ephemeral-viestit yleensä kauttaviivakomentojen ja painikkeiden vastauksina.

Agentit

Agentti on tyyppiä agent oleva bottitili: käyttäjillä on "is_agent": true, boteilla "kind": "agent", ja käyttöliittymässä näkyy BOT-tunnisteen sijaan AGENT-tunniste. Agentteja voivat luoda vain järjestelmänvalvojat (palvelinkohtaiset agentit) kohdassa Järjestelmäkonsoli › Tekoäly › Malliyhteydet ja tiiminvalvojat (oman tiiminsä agentit) tiimin asetuksien Tekoäly-välilehdellä tai käyttämällä /api/v4/ai/agents (katso API-dokumentointi). POST /bots:lla tai sovelluksen luoma botti on aina tavallinen botti.

Sisäiseen agenttiin vastaa palvelin malliyhteyden avulla. Ulkoinen agentti on sinun hallinnoimasi: muualla oleva ohjelma (esimerkiksi koodausagentti projektissa), joka kirjautuu sisään agenttina ja vastaa kuten ihminen. Antimatter ei vastaa sen puolesta.

Palvelin määrittää sisäänrakennetun agentin tilan: Paikalla kun sen malliyhteys vastaa, Poissa kun se ei vastaa (yhteys on alhaalla, aikakatkaisu tai avain hylätty) ja Ei verkossa kun agentti on pois päältä tai sillä ei ole käyttökelpoista yhteyttä tai mallia. Tila tarkistetaan, kun agentti tai sen yhteys muuttuu, kun yhteys testataan, jokaisen agentin mallikutsun yhteydessä sekä kymmenen minuutin välein. Kukaan ei voi asettaa sisäänrakennetun agentin tilaa: PUT /users/{id}/status ja mukautetun tilan päätepisteet palauttavat 403 (api.status.agent.app_error) myös järjestelmän ylläpitäjille, ja laajennosrajapinnan UpdateUserStatus, SetUserStatusTimedDND, UpdateUserCustomStatus ja RemoveUserCustomStatus hylkäävät pyynnön samalla tavalla. Ulkoisen agentin tila seuraa sen omaa yhteyttä, ja vain sen oma tunnus voi muuttaa sitä.

Ulkoisen agentin käyttäminen

1. Ylläpitäjä lisää agentin kohdassa Järjestelmäkonsoli › Tekoäly › Malliyhteydet (tai yhteisön Tekoäly-välilehdellä), valitsee tyypiksi Ulkoinen agentti ja määrittää, ketkä voivat keskustella sen kanssa. Sivulla näytetään, miten agentti yhdistetään.
2. Anna agentille tunnus: järjestelmän ylläpitäjä avaa kohdan Integraatiot › Bottitilit, etsii agentin tilin ja valitsee Luo uusi tunnus, tai kutsuu tunnusrajapintaa käyttäen agentin käyttäjätunnusta:

   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. Ohjelma kutsuu API:a ja avaa WebSocket-yhteyden käyttäen otsaketta Authorization: Bearer <token>, lukee maininnat ja suorat viestit posted-tapahtumista ja vastaa käyttäen POST /posts viestin ketjussa.
4. Agentti näyttää ihmisille, mitä se tekee asettamalla aktiivisuutensa:

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

Agentin ID näissä poluissa on sen käyttäjätunnus. Pidä tunnus salassa: kuka tahansa, jolla se on, voi lähettää viestejä agentin nimissä.

Aktiivisuus

• state: idle, thinking, working, waiting (odottaa jotakuta), blocked tai offline. Varatut tilat (thinking, working, waiting, blocked) palautuvat tilaan idle ajan expires_in_seconds jälkeen: oletuksena 10 minuuttia, enintään 24 tuntia.
• text: muutama sana tehtävästä, enintään 200 merkin pituinen rivi. Käyttöliittymä näyttää tämän tekstiin jäsenlistassa ja profiilikortissa.
• thread_post_id: ketju, jossa agentti työskentelee. Ohjelman on voitava lukea ketju. Tieto annetaan vain niille, joilla on oikeus lukea se.

Kuka voi nähdä, että agentti voi lukea sen toimintaa (GET /ai/agents/{agent_id}/activity tai POST /ai/agents/activity/ids ID-luettelolla) ja vastaanottaa agent_activity_changed-WebSocket-tapahtuman ilman ketjua. Sisäänrakennetut agentit asettavat toimintansa itse.

Kun sisäänrakennettu agentti kirjoittaa vastauksensa, palvelin lähettää kasvavan tekstin agent_post_stream-tapahtumissa kanavalle: post_id, channel_id, root_id, user_id, message (toistaiseksi oleva teksti) ja control (start, text, end, error tai cancel). post_edited-tapahtuma tuo lopullisen viestin. Asiakkaat, jotka jättävät huomiotta suoratoiston, näkevät vastauksen, kun se on tallennettu.

Interaktiiviset viestit: painikkeet ja valikot

Mikään liitteitä sisältävä viesti voi kantaa toimintoja: painikkeita ja valikoita, joista voi valita. Ne toimivat API:n, webhookkien ja kauttaviivakomentojen vastauksien kautta lähetetyissä viesteissä. Kun joku käyttää toimintoa, Antimatter kutsuu integraation URL:ää.

{
  "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 tai select.
• id: kirjaimet, numerot, väliviivat ja alaviivat, erilainen jokaiselle viestin toiminnolle. Se generoidaan, jos jätät sen pois.
• style (painikkeet): default, primary, success, good, warning, danger tai heksadesimaalinen väri.
• options (valikot) tai data_source: users tai channels henkilön tai kanavan valintaan. default_option esivalitsee arvon.
• integration.url: kohtaus, johon napsautus lähetetään. Sovellus (liitännäinen) voi käyttää omaa reittiään, kuten /plugins/com.example.deploy/actions. integration.context on sinun käytössäsi: se palautuu napsautuksen mukana, eikä asiakkaat koskaan näe sitä.

Integraation vastaanottama pyyntö

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

Valikon tapauksessa type on select ja context.selected_option sisältää valitun arvon.

Vastauksesi

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

• update: korvaa viestin tekstin ja ominaisuudet, esimerkiksi poistaaksesi painikkeet käytön jälkeen (tyhjä props).
• ephemeral_text: viesti, jonka näkee vain napsauttanut henkilö.
• goto_location: avattava URL-osoite.
• Tyhjä ruumis ei muuta mitään.

Palvelin odottaa niin kauan kuin Integraatiopyyntöjen aikakatkaisu sallii (oletus 30 sekuntia). Integraatioiden URL-osoitteet, jotka osoittavat yksityisen verkon osoitteisiin, on ylläpitäjän hyväksyttävä, kuten webhooken kohdalla.

Dialogit

Dialogi on lomake, joka avautuu chatin päälle. Sen voi avata vain vastauksena siihen, mitä henkilö juuri teki, kuten kauttaviivakomennon tai painikkeen, koska se vaatii kyseisen pyynnön trigger_id:n. trigger_id on voimassa integraatiopyyntöjen aikakatkaisun ajan.

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

Jokainen alue ottaa vastaan display_name, name, help_text, placeholder, default ja optional.

submit_buttons valintaikkunassa nimeää staattisen select-elementin: sen vaihtoehdoista tulee valintaikkunan lähetyspainikkeet, yksi per vaihtoehto, yksittäisen Lähetä-painikkeen sijaan, eikä itse select-elementtiä näytetä. size ("small", "medium" tai "large"; oletuksena "small", jos sitä ei määritetä) pyytää leveämpää valintaikkunaa. refresh_on_return (vaatii source_url:n) hakee valintaikkunan uudelleen source_url:sta, kun sen päälle avattu valintaikkuna suljetaan, jotta se voi näyttää tehdyt muutokset. Tunnistamaton size tai sub_type ei estä valintaikkunan avaamista: se palautuu oletusarvoon, ja palvelin vain kirjaa sen.

Kun henkilö lähettää, Antimatter POSTtaa dialogin url:iin:

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

Vastaa tyhjällä ruumilla sulkeaksesi dialogin, tai pidä se auki ja näytä, mikä on vialla:

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

{"error": "…"} näyttää viestin koko lomakkeelle. notify_on_cancel:n kanssa dialogin sulkeminen lähettää "cancelled": true. Dialogit toimivat samalla tavalla sovelluksissa: liitännäis-API:n OpenInteractiveDialog ottaa saman pyynnön.