Bots och interaktiva meddelanden

Ett botkonto är en användare som skapats för ett program. Det har ett eget namn, en bild och egna token, och visas med en BOT-etikett bredvid namnet. Denna sida behandlar även de interaktiva delarna av meddelanden: knappar, menyer och dialogrutor, som alla integrationer kan använda.

Varför ett bot-konto

• Dess meddelanden kommer från en tydlig identitet med en BOT-etikett, istället för från en kollegas konto.
• Dess token fortsätter att fungera när den person som skapade det byter roll eller lämnar (såvida inte servern inaktiverar bots med inaktiverade ägare, se nedan).
• Bots kan inte logga in med lösenord och de ser aldrig webbappen.

Appar skapar egna bots, till exempel bots för Att göra och Playbook, via plugin-API:t (EnsureBotUser).

Aktivera bot-konton

En systemadministratör aktiverar Aktivera möjligheten att skapa botkonton i Systemkonsol › Integrationer › Botkonton (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Inställningen är inaktiverad som standard. Endast systemadministratörer kan skapa botar, om de inte ger rättigheten till andra roller i behörighetsinställningarna.

På samma sida inaktiverar Spärra bot-konton när dess ägare blir avaktiverad (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, aktiverad som standard) en bot när dess ägares konto avaktiveras.

Skapa en bot

1. Öppna din profilbild i övre högra hörnet, välj sedan Integrationer › Botkonton och därefter Lägg till bot-konto.
2. Ange ett Användarnamn (gemina bokstäver, siffror, punkter, bindestreck och understreck) och, om så önskas, en Bot-ikon, ett Visningsnamn och en Beskrivning.
3. Välj Roll: Medlem, eller Systemadministratör för en bot som administrerar servern. Ge en bot så lite behörighet som möjligt.
4. Markera post:kanaler för att låta boten skriva i alla publika kanaler, eller post:all för att den ska kunna skriva i alla kanaler, inklusive privata kanaler och direktmeddelanden, utan att vara medlem.
5. Ställ in när dess standardtoken upphör att gälla och välj sedan Skapa konto.
6. Kopiera den åtkomsttoken som visas. Den visas inte igen.

Senare, Skapa ny token på botens rad, lägger till en token, och varje token kan inaktiveras eller tas bort. Bot-token fungerar även när personliga åtkomsttoken är inaktiverade för användare.

Med API:t:

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

Från kommandoraden, inloggad som administratör (inte i lokalt läge): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Andra ändpunkter: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable och /enable, samt POST /api/v4/bots/{bot_user_id}/assign/{user_id} för att ändra ägaren.

Lägg till boten i samhällen och kanaler

En ny bot finns i inget samhälle. Lägg till den som en person, antingen via samhällets hantering av medlemmar 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:kanaler eller post:all kan skriva utan att vara medlem, men den tar endast emot WebSocket-händelser för de kanaler den är medlem i.

Skriv inlägg som boten

Använd botens token i valfri API-anrop; POST /api/v4/posts är det vanligaste (se Huvudresurser). För att skriva direkt till någon, öppna först direktmeddelandekanalen:

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

För att reagera på vad andra skriver, följ WebSocket med botens token och svara på de posted-händelser du är intresserad av. Ignorera botens egna meddelanden för att undvika loopar.

Ett meddelande som bara en person kan se (ett tillfälligt meddelande) skickas med POST /api/v4/posts/ephemeral och {"user_id", "post": {"channel_id", "message"}}. Det kräver behörigheten create_post_ephemeral, som endast systemadministratörer har som standard. Integrationer skickar oftast tillfälliga meddelanden som svar på snedstreckskommandon och knappar.

Interaktiva meddelanden: knappar och menyer

Valfritt meddelande med bilagor kan bära åtgärder: knappar och menyer att välja från. De fungerar i meddelanden som skickats via API:et, webhooks och svar på snedstreckskommandon. När någon använder en åtgärd anropar Antimatter din integrationens 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 eller select.
• id: bokstäver, siffror, bindestreck och understreck, unika för varje åtgärd i meddelandet. Genereras om du lämnar den ut.
• style (knappar): default, primary, success, good, warning, danger eller en hex-färg.
• options (menyer), eller data_source: users eller channels för att välja en person eller en kanal. default_option förval ett värde.
• integration.url: vart klicket skickas. En app (plugin) kan använda sin egen route, till exempel /plugins/com.example.deploy/actions. integration.context är din: den kommer tillbaka med klicket och klienterna ser den aldrig.

Begäran som din integration 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"}
}

För en meny är type select och context.selected_option innehåller det valda värdet.

Ditt svar

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

• update: ersätter meddelandets text och egenskaper, till exempel för att ta bort knapparna när de har använts (en tom props).
• ephemeral_text: ett meddelande som endast den som klickade ser.
• goto_location: en URL som ska öppnas.
• En tom body ändrar ingenting.

Servern väntar så länge som Timeout vid integrationer tillåter (30 sekunder som standard). Integrations-URL:er på privata nätverksadresser måste tillåtas av en systemadministratör, precis som webhooks.

Dialoger

En dialog är ett formulär som öppnas ovanför chatten. Du kan endast öppna en som svar på något personen just gjorde, ett snedstreckskommando eller en knapp, eftersom den behöver den begäran trigger_id. trigger_id är giltig så länge som integration request timeout.

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

Varje element tar display_name, name, help_text, placeholder, default och optional.

När personen skickar in formuläret POST:ar Antimatter till 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
}

Svara med en tom body för att stänga dialogen, eller håll den öppen och visa vad som är fel:

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

{"error": "…"} visar ett meddelande för hela formuläret. Med notify_on_cancel skickas "cancelled": true när dialogen stängs. Dialoger fungerar på samma sätt i appar: plugin-API:ets OpenInteractiveDialog tar samma begäran.