Bots og interaktive meldinger

En bot-konto er en bruker laget for et program. Den har sitt eget navn, bilde og tokens, og viser en BOT-etikett ved siden av navnet. Denne siden dekker også de interaktive delene av meldinger: knapper, menyer og dialoger, som enhver integrasjon kan bruke.

Hvorfor en bot-konto

• Meldingene kommer fra en tydelig identitet, med en BOT-etikett, i stedet for fra en kollegas konto.
• Tokensene fortsetter å fungere når personen som opprettet den endrer rolle eller forlater organisasjonen (med mindre serveren deaktiverer bots med deaktiverte eiere, se nedenfor).
• Bots kan ikke logge inn med passord, og de ser aldri webapplikasjonen.

Apper oppretter sine egne bots, for eksempel Todo- eller Playbooks-bots, via plugin-API-et (EnsureBotUser).

Slå på bot-kontoer

En systemadministrator aktiverer Aktiver opprettelse av bot-kontoer i Systemkonsoll › Integrasjoner › Botkontoer (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Det er deaktivert som standard. Bare systemadministratorer kan opprette bots, med mindre de gir rettigheten til andre roller i tillatelsesinnstillingene.

På samme side deaktiveres en bot når eierens konto deaktiveres, hvis Deaktiver bot-kontoer når eieren deaktiveres (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, aktivt som standard) er slått på.

Opprett en bot

1. Åpne avataren din øverst til høyre, deretter Integrasjoner › Botkontoer, og deretter Legg til bot-konto.
2. Skriv inn et Brukernavn (små bokstaver, tall, prikker, bindestrek og understrek), og eventuelt et Bot-ikon, et Visningsnavn og en Beskrivelse.
3. Velg Rolle: Medlem, eller Systemadministrator for en bot som administrerer serveren. Gi en bot bare de rettighetene den absolutt trenger.
4. Avkryss post:channels for å la den poste i alle offentlige kanaler, eller post:all for alle kanaler, inkludert private kanaler og direktemeldinger, uten å være medlem.
5. Angi når standardtokenet utløper, og velg deretter Opprett bot-konto.
6. Kopier tilgangstokenen som vises. Den vises ikke igjen.

Senere kan du legge til et token ved å velge Opprett nytt token i raden for boten. Hvert token kan deaktiveres eller slettes. Bot-tokens fungerer selv om personlige tilgangstokens er deaktivert for brukere.

Med API-et:

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

Fra kommandolinjen, pålogget som administrator (ikke i lokal modus): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Andre endepunkter: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable og /enable, samt POST /api/v4/bots/{bot_user_id}/assign/{user_id} for å endre eier.

Legg boten til i samfunn og kanaler

En ny bot er ikke medlem av noe samfunn. Legg den til som en person, enten via medlemsforvaltningen i samfunnet eller via API-et:

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

En bot med post:channels eller post:all kan poste uten å være medlem, men den mottar bare WebSocket-hendelser for kanaler den er medlem av.

Post som boten

Bruk botens token i alle API-oppkall; POST /api/v4/posts er det vanligste (se Hovedressurser). For å skrive direkte til noen, må du først åpne direktemeldingskanalen:

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

For å reagere på det folk sier, må du følge WebSocket-strømmen med botens token og svare på posted-hendelsene du er interessert i. Ignorer botens egne meldinger for å unngå løkker.

En melding som bare én person kan se (en ephemeral-melding) sendes med POST /api/v4/posts/ephemeral og {"user_id", "post": {"channel_id", "message"}}. Den krever rettigheten create_post_ephemeral, som bare systemadministratorer har som standard. Integrasjoner sender vanligvis ephemeral-meldinger som svar på skråstrek-kommandoer og knapper.

Interaktive meldinger: knapper og menyer

Enhver melding med vedlegg kan inneholde handlinger: knapper og menyer å velge fra. De fungerer i meldinger postet via API-et, webhooks og svar på skråstrek-kommandoer. Når noen bruker en av dem, ringer Antimatter URL-en til integrasjonen din.

{
  "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 eller select.
• id: bokstaver, tall, bindestrek og understrek, unike for hver handling i meldingen. Den genereres hvis du utelater den.
• style (knapper): default, primary, success, good, warning, danger, eller en hex-farge.
• options (menyer), eller data_source: users eller channels for å velge en person eller en kanal. default_option forutvelger en verdi.
• integration.url: hvor klikket sendes. En app (plugin) kan bruke sin egen rute, for eksempel /plugins/com.example.deploy/actions. integration.context er din: den kommer tilbake med klikket, og klienter ser den aldri.

Forespørselen integrasjonen mottar

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

For en meny er type select, og context.selected_option inneholder den valgte verdien.

Svaret ditt

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

• update: erstatter meldingens tekst og egenskaper, for eksempel for å fjerne knappene når de er brukt (en tom props).
• ephemeral_text: en melding som bare personen som klikket ser.
• goto_location: en URL som skal åpnes.
• En tom kropp endrer ingenting.

Serveren venter så lenge som Tidsavbrudd for integrasjonsforespørsler tillater (30 sekunder som standard). Integrasjons-URLer på private nettverksadresser må tillates av en systemadministrator, slik det er tilfelle for webhooks.

Dialoger

En dialog er et skjema som åpnes over chatten. Du kan bare åpne den som svar på noe personen nettopp gjorde, en skråstrek-kommando eller en knapp, fordi den trenger trigger_id fra den forespørselen. trigger_id er gyldig i hele integrasjonens forespørsels tidsavbrudd.

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

Hvert element tar display_name, name, help_text, placeholder, default og optional.

Når personen sender inn, POST-er Antimatter til dialogens url:

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

Svar med en tom kropp for å lukke dialogen, eller hold den åpen og vis hva som er galt:

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

{"error": "…"} viser en melding for hele skjemaet. Med notify_on_cancel sender lukking av dialogen "cancelled": true. Dialoger fungerer på samme måte i apper: plugin-API-et OpenInteractiveDialog tar den samme forespørselen.