Bot e messaggi interattivi

Un account bot è un utente creato per un programma. Ha un proprio nome, immagine e token, e mostra un tag BOT accanto al nome. Questa pagina copre anche le parti interattive dei messaggi: pulsanti, menu e dialoghi, che qualsiasi integrazione può utilizzare.

Perché un account bot

• I suoi messaggi provengono da un'identità chiara, con un tag BOT, anziché dall'account di un collega.
• I suoi token continuano a funzionare quando la persona che li ha configurati cambia ruolo o lascia l'organizzazione (a meno che il server non disabiliti i bot dei proprietari disattivati, come descritto di seguito).
• I bot non possono accedere con una password e non visualizzano mai l'app web.

Le app creano i propri bot, come i bot Todo o Playbooks, tramite l'API dei plugin (EnsureBotUser).

Attiva gli account bot

Un amministratore di sistema attiva Abilita creazione account bot in Console di Sistema › Integrazioni › Account bot (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). È disattivato per impostazione predefinita. Solo gli amministratori di sistema possono creare bot, a meno che non concedano questo diritto ad altri ruoli nelle impostazioni dei permessi.

Nella stessa pagina, Disabilita gli account bot se il proprietario è disattivato (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, attivo per impostazione predefinita) disattiva un bot quando l'account del suo proprietario viene disattivato.

Crea un bot

1. Apri il tuo avatar in alto a destra, poi Integrazioni › Account bot, quindi Aggiungi Account Bot.
2. Inserisci un Nome utente (lettere minuscole, numeri, punti, trattini e underscore) e, facoltativamente, un'Icona Bot, un Nome visibile e una Descrizione.
3. Scegli il Ruolo: Membro, oppure Amministratore di sistema per un bot che gestisce il server. Concedi al bot solo le autorizzazioni strettamente necessarie.
4. Seleziona post:channels per consentirgli di pubblicare in tutti i canali pubblici, oppure post:all per tutti i canali, inclusi quelli privati e i messaggi diretti, senza che sia un membro.
5. Imposta quando scade il token predefinito, quindi scegli Crea Account Bot.
6. Copia il token di accesso visualizzato. Non verrà mostrato di nuovo.

In seguito, Crea nuovo token nella riga del bot aggiunge un token, e ciascun token può essere disabilitato o eliminato. I token dei bot funzionano anche quando i token di accesso personale sono disattivati per gli utenti.

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

Dalla riga di comando, autenticati come amministratore (non in modalità locale): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Altri endpoint: 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} per cambiarne il proprietario.

Aggiungi il bot alle community e ai canali

Un nuovo bot non appartiene a nessuna community. Aggiungilo come se fosse una persona, dalla gestione dei membri della community o tramite l'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 con post:channels o post:all può pubblicare senza essere un membro, ma riceve eventi WebSocket solo per i canali in cui è presente.

Pubblica come bot

Usa il token del bot con qualsiasi chiamata API; POST /api/v4/posts è la più comune (vedi Risorse principali). Per scrivere direttamente a qualcuno, apri prima il canale di messaggio diretto:

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

Per reagire a ciò che le persone dicono, segui il WebSocket con il token del bot e rispondi agli eventi posted che ti interessano. Ignora i messaggi del bot stesso per evitare loop.

Un messaggio visibile solo a una persona (un messaggio effimero) viene inviato con POST /api/v4/posts/ephemeral e {"user_id", "post": {"channel_id", "message"}}. Richiede il permesso create_post_ephemeral, che di default è disponibile solo agli amministratori di sistema. Le integrazioni inviano di solito messaggi effimeri come risposta ai comandi con barra e ai pulsanti.

Messaggi interattivi: pulsanti e menu

Qualsiasi messaggio con allegati può includere azioni: pulsanti e menu per la selezione. Funzionano nei messaggi pubblicati tramite API, webhook e risposte ai comandi con barra. Quando qualcuno li usa, Antimatter chiama l'URL della tua integrazione.

{
  "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 o select.
• id: lettere, numeri, trattini e underscore, diverso per ciascuna azione del messaggio. Viene generato automaticamente se lasciato vuoto.
• style (pulsanti): default, primary, success, good, warning, danger o un colore in esadecimale.
• options (menu) o data_source: users o channels per selezionare una persona o un canale. default_option preimpostato un valore.
• integration.url: il punto in cui viene inviata la richiesta. Un'app (plugin) può usare il proprio percorso, ad esempio /plugins/com.example.deploy/actions. integration.context è a tua disposizione: viene restituito con la richiesta e i client non lo visualizzano mai.

La richiesta ricevuta dalla tua integrazione

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

Per un menu, type è select e context.selected_option contiene il valore selezionato.

La tua risposta

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

• update: sostituisce il testo e le proprietà del messaggio, ad esempio per rimuovere i pulsanti una volta utilizzati (con props vuoto).
• ephemeral_text: un messaggio visibile solo alla persona che ha fatto clic.
• goto_location: un URL da aprire.
• Un corpo vuoto non modifica nulla.

Il server attende per il tempo consentito dal Timeout richiesta integrazione (30 secondi di default). Gli URL delle integrazioni su indirizzi di rete privata devono essere autorizzati da un amministratore di sistema, come per i webhook.

Dialoghi

Un dialogo è un modulo che si apre sopra la chat. Puoi aprirlo solo in risposta a un'azione appena eseguita dalla persona, come un comando con barra o un pulsante, perché richiede il trigger_id di quella richiesta. Il trigger_id è valido per la durata del timeout della richiesta di integrazione.

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

Ogni elemento accetta display_name, name, help_text, placeholder, default e optional.

Quando la persona invia, Antimatter invia una richiesta POST all'url del dialogo:

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

Rispondi con un corpo vuoto per chiudere il dialogo, oppure tienilo aperto e mostra cosa non va:

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

{"error": "…"} mostra un messaggio per l'intero modulo. Con notify_on_cancel, la chiusura del dialogo invia "cancelled": true. I dialoghi funzionano allo stesso modo nelle app: OpenInteractiveDialog dell'API dei plugin accetta la stessa richiesta.