Bots en interactieve berichten

Een bot-account is een gebruiker voor een programma. Het heeft een eigen naam, afbeelding en tokens, en er staat een BOT-label naast de naam. Deze pagina behandelt ook de interactieve onderdelen van berichten: knoppen, menu’s en dialoogvensters, die elke integratie kan gebruiken.

Waarom een bot-account

• De berichten komen van een duidelijk identificeerbaar account, met een BOT-label, in plaats van van het account van een collega.
• De tokens blijven werken als de persoon die het heeft ingesteld van rol verandert of vertrekt (tenzij de server de bots van gedeactiveerde eigenaren deactiveert, zie hieronder).
• Bots kunnen zich niet aanmelden met een wachtwoord en zien de webapp nooit.

Apps maken hun eigen bots aan, zoals de bots voor Te doen of Playbooks, via de plugin-API (EnsureBotUser).

Bot-accounts inschakelen

Een systeembeheerder schakelt Bot-account aamaken inschakelen in via Systeem console › Integraties › Botaccounts (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Standaard is dit uit. Alleen systeembeheerders kunnen bots aanmaken, tenzij ze dit recht in de machtigingsinstellingen aan andere rollen toekennen.

Op dezelfde pagina schakelt Bot-accounts uitschakelen als eigenaar gedeactiveerd is (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, standaard aan) een bot uit wanneer het account van de eigenaar wordt gedeactiveerd.

Een bot aanmaken

1. Klik rechtsboven op je avatar, ga daarna naar Integraties › Botaccounts en klik op Bot-Account Toevoegen.
2. Voer een Gebruikersnaam in (kleine letters, cijfers, punten, streepjes en lage streepjes) en, optioneel, een Bot-pictogram, een Weergavenaam en een Omschrijving.
3. Kies de Rol: Lid of Systeembeheerder voor een bot dat de server beheert. Geef een bot alleen de machtigingen die het nodig heeft.
4. Vink post: kanalen aan om berichten in elk publiek kanaal te kunnen plaatsen, of post:allen om in elk kanaal te kunnen plaatsen, inclusief privékanalen en privéberichten, zonder lid te hoeven zijn.
5. Stel in wanneer de standaardtoken verloopt en klik daarna op Maak Bot Account Aan.
6. Kopieer de weergegeven toegangstoken. Deze wordt niet nog een keer getoond.

Klik later op Nieuwe token aanmaken op de rij van de bot om een token toe te voegen. Elke token kan worden gedeactiveerd of verwijderd. Bot-tokens werken ook als persoonlijke toegangstokens voor mensen zijn uitgeschakeld.

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

Vanaf de commandoregel, aangemeld als beheerder (niet in lokale modus): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Andere eindpunten: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable en /enable, POST /api/v4/bots/{bot_user_id}/assign/{user_id} om de eigenaar te wijzigen.

De bot toevoegen aan gemeenschappen en kanalen

Een nieuwe bot is nog geen lid van enige gemeenschap. Voeg deze toe zoals een persoon, via het beheer van leden van de gemeenschap of via de 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'"}'

Een bot met post: kanalen of post:allen kan berichten plaatsen zonder lid te zijn, maar ontvangt alleen WebSocket-events voor de kanalen waar het lid van is.

Berichten plaatsen als de bot

Gebruik het token van de bot voor elke API-aanroep; POST /api/v4/posts is het meest gebruikelijk (zie Hoofdreferenties). Om rechtstreeks met iemand te communiceren, open eerst het privéberichtkanaal:

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

Om te reageren op wat mensen zeggen, volg de WebSocket met het token van de bot en reageer op de posted-events die voor u relevant zijn. Negeer de eigen berichten van de bot om lusjes te voorkomen.

Een bericht dat alleen door één persoon zichtbaar is (een tijdelijk bericht) wordt verzonden met POST /api/v4/posts/ephemeral en {"user_id", "post": {"channel_id", "message"}}. Hiervoor is de create_post_ephemeral-rechten vereist, die standaard alleen systeembeheerders hebben. Integraties sturen tijdelijke berichten meestal als antwoord op slash-opdrachten en knoppen.

Interactieve berichten: knoppen en menu's

Elk bericht met bijlagen kan acties bevatten: knoppen en menu's om uit te kiezen. Ze werken in berichten die via de API, webhooks en antwoorden op slash-opdrachten zijn geplaatst. Wanneer iemand er gebruik van maakt, roept Antimatter de URL van uw integratie aan.

{
  "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 of select.
• id: letters, cijfers, streepjes en underscores, uniek voor elke actie van het bericht. Als u dit veld leeg laat, wordt het gegenereerd.
• style (knoppen): default, primary, success, good, warning, danger, of een hex-kleur.
• options (menu's), of data_source: users of channels om een persoon of kanaal te selecteren. default_option selecteert vooraf een waarde.
• integration.url: de URL waarnaartoe de klik wordt gestuurd. Een app (plug-in) kan een eigen route gebruiken, zoals /plugins/com.example.deploy/actions. integration.context is voor jou: deze wordt teruggezonden bij de klik en is onzichtbaar voor de client.

De aanvraag die je integratie ontvangt

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

Voor een menu is type gelijk aan select en bevat context.selected_option de gekozen waarde.

Je antwoord

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

• update: vervangt de tekst en eigenschappen van het bericht, bijvoorbeeld om knoppen te verwijderen nadat ze zijn gebruikt (een lege props).
• ephemeral_text: een bericht dat alleen de persoon die heeft geklikken kan zien.
• goto_location: een URL om te openen.
• Een leeg berichtlichaam verandert niets.

De server wacht zo lang als de Time-out integratieverzoek toelaat (standaard 30 seconden). Integratie-URL’s op adressen in een privénetwerk moeten door een systeembeheerder worden toegestaan, net als webhooks.

Dialoogvensters

Een dialoogvenster is een formulier dat boven de chat wordt geopend. Je kunt er alleen een openen als antwoord op iets dat de persoon zojuist heeft gedaan, zoals een slash-opdracht of een knop, omdat het de trigger_id van die aanvraag nodig heeft. De trigger_id is geldig zolang de integratie-aanvraagtimeout.

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

Elk element accepteert display_name, name, help_text, placeholder, default en optional.

Bij het verzenden stuurt Antimatter een POST-aanvraag naar de url van het dialoogvenster:

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

Antwoord met een leeg berichtlichaam om het dialoogvenster te sluiten, of houd het open en toon wat er fout is:

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

{"error": "…"} toont een bericht voor het hele formulier. Met notify_on_cancel wordt bij het sluiten van het dialoogvenster "cancelled": true verzonden. Dialoogvensters werken op dezelfde manier in apps: de OpenInteractiveDialog van de plug-in-API accepteert dezelfde aanvraag.