Bots and interactive messages

Un cont de bot este un cont de utilizator creat pentru un program. Are propriul nume, imagine și tokenuri, iar lângă nume apare eticheta BOT. Această pagină acoperă și părțile interactive ale mesajelor: butoane, meniuri și dialoguri, pe care orice integrare le poate utiliza.

De ce un cont de bot

• Mesajele sale provin de la o identitate clară, cu eticheta BOT, în loc să vină de la contul unui coleg.
• Tokenurile sale rămân funcționale chiar și atunci când persoana care l-a configurat își schimbă rolul sau părăsește organizația (cu excepția cazului în care serverul dezactivează boturile ale căror proprietari sunt dezactivați, vezi mai jos).
• Boturile nu se pot autentifica cu o parolă și nu văd niciodată aplicația web.

Aplicațiile își creează propriile boturi, cum ar fi boturile Todo sau Playbooks, prin API-ul de pluginuri (EnsureBotUser).

Activarea conturilor de bot

Un administrator de sistem activează Activează crearea de cont Bot în Consola de sistem › Integrări › Conturi de bot (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Opțiunea este dezactivată implicit. Doar administratorii de sistem pot crea boturi, cu excepția cazului în care acordă acest drept altor roluri în setările de permisiuni.

Pe aceeași pagină, Dezactivați conturile botului atunci când proprietarul este dezactivat (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, activat implicit) dezactivează un bot atunci când contul proprietarului este dezactivat.

Crearea unui bot

1. Deschideți avatarul din colțul din dreapta sus, apoi Integrări › Conturi de bot, apoi Adaugă Cont Bot.
2. Introduceți un Utilizator (litere mici, cifre, puncte, cratime și liniuțe de subliniere) și, opțional, o Icoana Bot, un Nume afișat și o Descriere.
3. Alegeți Rol: Membru, sau Administrator de sistem pentru un bot care gestionează serverul. Acordați unui bot doar permisiunile de care are nevoie.
4. Bifați poștale: canale pentru a-i permite să posteze în fiecare canal public, sau articol:toate pentru fiecare canal, inclusiv cele private și mesajele directe, fără a fi membru.
5. Setați când expiră tokenul implicit, apoi alegeți Creează cont Bot.
6. Copiază tokenul de acces afișat. Acesta nu va mai fi afișat niciodată.

Mai târziu, Creați un token nou pe rândul botului adaugă un token, iar fiecare token poate fi dezactivat sau șters. Tokenurile boturilor funcționează chiar și atunci când tokenurile de acces personale sunt dezactivate pentru utilizatori.

Cu API-ul:

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

Din linia de comandă, autentificat ca administrator (nu în modul local): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Alte puncte de acces: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable și /enable, POST /api/v4/bots/{bot_user_id}/assign/{user_id} pentru a-i schimba proprietarul.

Adăugați botul în comunități și canale

Un bot nou nu face parte din nicio comunitate. Adăugați-l ca pe o persoană, din gestionarea membrilor comunității sau prin 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'"}'

Un bot cu poștale: canale sau articol:toate poate posta fără a fi membru, dar primește evenimente WebSocket doar pentru canalele în care se află.

Postați în numele botului

Folosiți tokenul botului pentru orice apel API; POST /api/v4/posts este cel mai frecvent (a se vedea Resurse principale). Pentru a scriu direct cuiva, deschideți mai întâi canalul de mesaj direct:

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

Pentru a reacționa la ce spun oamenii, urmați WebSocket cu tokenul botului și răspundeți la evenimentele posted care vă interesează. Ignorați mesajele proprii ale botului pentru a evita buclele.

Un mesaj vizibil doar de o singură persoană (un mesaj efemer) este trimis cu POST /api/v4/posts/ephemeral și {"user_id", "post": {"channel_id", "message"}}. Necesită permisiunea create_post_ephemeral, pe care, implicit, o au doar administratorii de sistem. Integrările trimit de obicei mesaje efemere ca răspuns la comenzi cu slash și butoane.

Mesaje interactive: butoane și meniuri

Orice mesaj cu atașamente poate include acțiuni: butoane și meniuri pentru selecție. Acestea funcționează în mesajele postate prin API, webhooks și răspunsurile la comenzi cu slash. Când cineva folosește una dintre ele, Antimatter apelează URL-ul integrării dvs.

{
  "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 sau select.
• id: litere, cifre, cratime și liniuțe de subliniere, diferite pentru fiecare acțiune a mesajului. Este generat dacă lăsați câmpul gol.
• style (butoane): default, primary, success, good, warning, danger sau o culoare în hex.
• options (meniuri) sau data_source: users sau channels pentru a alege o persoană sau un canal. default_option preselectează o valoare.
• integration.url: unde este trimis clicul. O aplicație (plugin) poate folosi propria sa rută, de exemplu /plugins/com.example.deploy/actions. integration.context este al dumneavoastră: revine împreună cu clicul, iar clienții nu îl văd niciodată.

Cererea primită de integrarea dumneavoastră

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

Pentru un meniu, type este select, iar context.selected_option conține valoarea aleasă.

Răspunsul dumneavoastră

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

• update: înlocuiește textul și proprietățile mesajului, de exemplu pentru a elimina butoanele după ce au fost folosite (un props gol).
• ephemeral_text: un mesaj vizibil doar pentru persoana care a făcut clic.
• goto_location: o adresă URL care va fi deschisă.
• Un corp gol nu modifică nimic.

Serverul așteaptă atât timp cât permite Timp de așteptare pentru cererile de integrare (30 de secunde implicit). Adresele de rețea privată pentru URL-urile de integrare trebuie să fie permise de un administrator de sistem, la fel ca în cazul webhook-urilor.

Dialoguri

Un dialog este un formular care se deschide peste chat. Puteți deschide unul doar ca răspuns la ceva ce a făcut tocmai persoana, o comandă cu slash sau un buton, deoarece este necesar trigger_id al acelei cereri. trigger_id este valid pentru toată durata timeout-ului cererii de integrare.

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

Fiecare element primește display_name, name, help_text, placeholder, default și optional.

Când persoana trimite formularul, Antimatter trimite o cerere POST către url dialogului:

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

Răspundeți cu un corp gol pentru a închide dialogul, sau lăsați-l deschis și arătați ce este greșit:

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

{"error": "…"} afișează un mesaj pentru întregul formular. Cu notify_on_cancel, închiderea dialogului trimite "cancelled": true. Dialogurile funcționează la fel în aplicații: OpenInteractiveDialog din API-ul plugin-urilor primește aceeași cerere.