Mga bot at interaktibong mensahe

Ang bot account ay isang user na ginawa para sa isang programa. May sariling pangalan, larawan, at tokens ito, at may BOT tag na nakalagay sa tabi ng pangalan nito. Tinatalakay din ng pahinang ito ang mga interaktibong bahagi ng mga mensahe: mga button, menu, at dialog, na maaaring gamitin ng anumang integration.

Bakit kailangan ng bot account

• Ang mga mensahe nito ay mula sa malinaw na identidad, na may BOT tag, sa halip na mula sa account ng isang kapwa-employee.
• Ang mga token nito ay patuloy na gumagana kahit magbago ng role o umalis ang taong nag-set nito (maliban kung na-disable ng server ang mga bot ng mga deaktibadong owner, tingnan sa ibaba).
• Hindi makapag-sign in ang mga bot gamit ang password, at hindi nila nakikita ang web app.

Lumilikha ang mga app ng sarili nilang bot, tulad ng mga bot ng Todo o Playbooks, gamit ang plugin API (EnsureBotUser).

Pahintulutan ang paggawa ng bot account

I-on ng isang system admin ang Pahintulutan ang paggawa ng Bot Account sa System Console › Mga Integration › Mga bot account (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Off ito sa default. Ang mga system admin lamang ang makakagawa ng bot, maliban kung ibinigay nila ang karapatan sa ibang role sa mga setting ng pahintulot.

Sa parehong pahina, ang I-disable ang mga bot account kapag na-deactivate ang owner (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, on sa default) ay nagpapahina ng bot kapag na-deactivate ang account ng owner nito.

Lumikha ng bot

1. Buksan ang avatar sa itaas na kanang sulok, tapos Mga Integration › Mga bot account, tapos Magdagdag ng Bot Account.
2. Ilagay ang Username (mga malaking titik, numero, tuldok, dash, at underscore), at opsyonal na Bot Icon, Display Name, at Paglalarawan.
3. Piliin ang Role: Miyembro, o System Admin para sa bot na pamamahala sa server. Bigyan ang bot ng pinakamaliit na karapatan na kailangan lang.
4. Tikman ang post:channels para payagan itong mag-post sa bawat pampublikong channel, o post:all para sa lahat ng channel, kabilang ang mga pribadong channel at Direct Message, nang hindi miyembro.
5. Itakda kailan mag-expire ang default token nito, tapos piliin ang Lumikha ng Bot Account.
6. Kopyahin ang access token na ipinapakita. Hindi na ito ipapakita ulit.

Pagkatapos, ang Lumikha ng Bagong Token sa linya ng bot ay nagdadagdag ng token, at bawat token ay maaaring i-disable o burahin. Gumagana ang mga bot token kahit na-off ang mga personal access token para sa mga tao.

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

Mula sa command line, na-sign in bilang admin (hindi sa local mode): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Iba pang mga endpoint: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable at /enable, POST /api/v4/bots/{bot_user_id}/assign/{user_id} upang palitan ang kanyang owner.

Idagdag ang bot sa mga community at channel

Ang bagong bot ay wala sa anumang community. Idagdag ito gaya ng tao, mula sa member management ng community o gamit ang 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'"}'

Ang bot na may post:channels o post:all ay maaaring mag-post nang hindi miyembro, ngunit tinatanggap lamang nito ang mga WebSocket event para sa mga channel na kabilang dito.

Mag-post bilang bot

Gumamit ng token ng bot sa anumang API call; ang POST /api/v4/posts ang pinakakaraniwan (tingnan ang Mga pangunahing resource). Para sumulat direkta sa isang tao, buksan muna ang direct message channel:

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

Para mag-react sa sinasabi ng mga tao, sundan ang WebSocket gamit ang token ng bot at sagutin ang mga posted event na mahalaga sa iyo. Huwag pansinin ang mga mensahe ng sarili ng bot upang maiwasan ang loop.

Ang mensahe na nakikita lamang ng isang tao (ephemeral message) ay ipinapadala gamit ang POST /api/v4/posts/ephemeral at {"user_id", "post": {"channel_id", "message"}}. Kailangan nito ang create_post_ephemeral permission, na karaniwang may-ari lamang ng mga system admin. Karaniwang ipinapadala ng mga integrations ang mga ephemeral message bilang sagot sa mga slash command at button.

Mga interactive na mensahe: mga button at menu

Ang anumang mensahe na may attachment ay maaaring magdala ng mga aksyon: mga button, at mga menu para pumili. Gumagana ito sa mga mensahe na ipinapadala gamit ang API, webhooks, at mga sagot ng slash command. Kapag gumamit ng isa ang isang tao, tinatawag ng Antimatter ang URL ng iyong integration.

{
  "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: mga letra, numero, dash, at underscore, magkakaiba para sa bawat aksyon ng mensahe. Ito ay nililikha kapag hindi mo ito isinulat.
• style (mga button): default, primary, success, good, warning, danger, o hex color.
• options (mga menu), o data_source: users o channels para pumili ng tao o channel. Ang default_option ay nagpili nang unti ng isang halaga.
• integration.url: ang destinasyon ng click. Maaaring gamitin ng isang app (plugin) ang sarili nitong route, tulad ng /plugins/com.example.deploy/actions. Ang integration.context ay para sa iyo: bumabalik ito kasama ang click, at hindi nakikita ng mga client.

Ang request na tinatanggap ng iyong integration

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

Para sa menu, ang type ay select at ang context.selected_option ang naglalaman ng napiling halaga.

Ang iyong sagot

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

• update: nagpapalit ng teksto at mga katangian ng mensahe, halimbawa upang alisin ang mga pindutan pagkatapos gamitin (isang walang laman na props).
• ephemeral_text: isang mensahe na nakikita lamang ng taong nag-click.
• goto_location: isang URL na buksan.
• Ang walang laman na body ay hindi nagbabago ng anumang bagay.

Naghihintay ang server hangga't pinapayagan ng Integration request timeout (30 segundo ang default). Ang mga integration URL sa mga private network address ay dapat payagan ng isang system admin, katulad ng sa mga webhook.

Mga Dialog

Ang dialog ay isang form na bumubukas sa itaas ng chat. Maaari itong buksan lamang bilang sagot sa bagong ginawa ng tao, tulad ng slash command o pindutan, dahil kailangan nito ang trigger_id ng request na iyon. Ang trigger_id ay bida hangga't tagal ng 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"}
      ]
    }
  }'

Ang bawat element ay tumatanggap ng display_name, name, help_text, placeholder, default at optional.

Kapag ipinasa ng tao, nagpapa-POST ang Antimatter sa url ng dialog:

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

Sagutin gamit ang walang laman na body upang isara ang dialog, o ituloy ang pagbubukas nito at ipakita kung ano ang mali:

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

Ang {"error": "…"} ay nagpapakita ng mensahe para sa buong form. May notify_on_cancel, ang pagsasara ng dialog ay nagpapadala ng "cancelled": true. Gumagana nang magkakatulad ang mga dialog sa mga app: ang OpenInteractiveDialog ng plugin API ay tumatanggap ng parehong request.