Bots και διαδραστικά μηνύματα

Ο λογαριασμός Bot είναι ένας χρήστης που δημιουργείται για ένα πρόγραμμα. Διαθέτει δικό του όνομα, εικόνα και διακριτικά, και εμφανίζει την ετικέτα BOT δίπλα στο όνομά του. Αυτή η σελίδα καλύπτει επίσης τους πράκτορες AI που εκτελείτε μόνοι σας, καθώς και τα διαδραστικά μέρη των μηνυμάτων: κουμπιά, μενού και παράθυρα διαλόγου, τα οποία μπορούν να χρησιμοποιηθούν από οποιαδήποτε ολοκλήρωση.

Γιατί λογαριασμός bot

Τα μηνύματά του προέρχονται από μια σαφή ταυτότητα, με την ετικέτα BOT, αντί να στέλνονται από τον λογαριασμό ενός συναδέλφου.
Τα tokens του συνεχίζουν να λειτουργούν όταν ο χρήστης που τον δημιούργησε αλλάζει ρόλο ή αποχωρεί (εκτός αν ο διακομιστής απενεργοποιεί τα bots των απενεργοποιημένων ιδιοκτητών, δείτε παρακάτω).
Τα bots δεν μπορούν να συνδεθούν με κωδικό πρόσβασης και δεν βλέπουν ποτέ την εφαρμογή του web.

Οι εφαρμογές δημιουργούν τα δικά τους bots, όπως τα bots Todo ή Playbooks, μέσω του API plugin (EnsureBotUser). Οι πράκτορες AI είναι επίσης λογαριασμοί Bot, δικού τους είδους, οι οποίοι εμφανίζονται με την ετικέτα ΠΡΑΚΤΟΡΑΣ: δείτε Πράκτορες.

Ενεργοποίηση λογαριασμών bot

Ένας διαχειριστής συστήματος ενεργοποιεί την επιλογή Ενεργοποίηση δημιουργίας λογαριασμών bot στη Κονσόλα συστήματος › Ολοκληρώσεις › Λογαριασμοί bot (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Είναι απενεργοποιημένη από προεπιλογή. Μόνο διαχειριστές συστήματος μπορούν να δημιουργήσουν bots, εκτός αν χορηγήσουν το δικαίωμα σε άλλους ρόλους στις ρυθμίσεις δικαιωμάτων.

Στην ίδια σελίδα, το Απενεργοποίηση λογαριασμών bot όταν ο ιδιοκτήτης απενεργοποιείται (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, ενεργοποιημένο από προεπιλογή) απενεργοποιεί ένα bot όταν απενεργοποιείται ο λογαριασμός του ιδιοκτήτη του.

Δημιουργία bot

Ανοίξτε το μενού της ομάδας, στη συνέχεια Ρυθμίσεις ομάδας, κάντε κλικ στην επιλογή Ολοκληρώσεις στο τέλος των καρτελών της, έπειτα Λογαριασμοί Bot και Προσθήκη λογαριασμού Bot.
Εισάγετε ένα Όνομα χρήστη (μικρά γράμματα, αριθμοί, τελείες, παύλες και κάτω παύλες) και, προαιρετικά, ένα Εικονίδιο bot, ένα Εμφανιζόμενο όνομα και μια Περιγραφή.
Επιλέξτε τον Ρόλο: Μέλος, ή Διαχειριστής συστήματος για ένα bot που διαχειρίζεται τον διακομιστή. Δώστε σε ένα bot μόνο ό,τι χρειάζεται.
Σημειώστε post:channels για να του επιτρέψετε να δημοσιεύει σε κάθε δημόσιο κανάλι, ή post:all για κάθε κανάλι, συμπεριλαμβανομένων των ιδιωτικών και των άμεσων μηνυμάτων, χωρίς να είναι μέλος.
Ορίστε πότε λήγει το προεπιλεγμένο token και στη συνέχεια επιλέξτε Δημιουργία λογαριασμού bot.
Αντιγράψτε το token πρόσβασης που εμφανίζεται. Δεν θα εμφανιστεί ξανά.

Στη συνέχεια, η επιλογή Δημιουργία νέου token στη σειρά του bot προσθέτει ένα token, και κάθε token μπορεί να απενεργοποιηθεί ή να διαγραφεί. Τα tokens των bots λειτουργούν ακόμη και όταν τα tokens πρόσβασης για τους χρήστες είναι απενεργοποιημένα.

Ένα bot μπορεί να φέρει χαρακτηριστικά διακομιστή (αυτά που έχουν ρυθμιστεί στην Κονσόλα συστήματος › Χαρακτηριστικά Συστήματος), τα οποία ορίζονται στη φόρμα Προσθήκης/Επεξεργασίας Bot ή μέσω της επιλογής Επεξεργασία χαρακτηριστικών… στο μενού ⋯ του bot. Τα ορίζει whoever διαχειρίζεται το bot: ο κάτοχός του, με το δικαίωμα διαχείρισης bots, ή οποιοσδήποτε έχει το δικαίωμα διαχείρισης των bots άλλων. Ένα χαρακτηριστικό που διαχειρίζεται ο διαχειριστής συστήματος απαιτεί πάντα διαχειριστή συστήματος. Το bot ενός πράκτορα AI δεν ανήκει σε κάποιον, οπότε μόνο κάποιος με δικαίωμα διαχείρισης των bots άλλων ή ένας διαχειριστής συστήματος μπορεί να ορίσει τα χαρακτηριστικά του.

Μέσω της 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"}'

Από τη γραμμή εντολών, συνδεδεμένος ως διαχειριστής (όχι σε τοπική λειτουργία): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Άλλοι τελικοί σημείοι: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable και /enable, POST /api/v4/bots/{bot_user_id}/assign/{user_id} για αλλαγή του ιδιοκτήτη.

Προσθήκη του bot σε κοινότητες και κανάλια

Ένα νέο bot δεν ανήκει σε καμία κοινότητα. Προσθέστε το όπως ένα άτομο, από τη διαχείριση μελών της κοινότητας ή μέσω της 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'"}'

Ένα bot με post:channels ή post:all μπορεί να δημοσιεύει χωρίς να είναι μέλος, αλλά λαμβάνει γεγονότα WebSocket μόνο για τα κανάλια στα οποία συμμετέχει.

Δημοσίευση ως bot

Χρησιμοποιήστε το token του bot σε οποιαδήποτε κλήση API· το POST /api/v4/posts είναι το πιο συνηθισμένο (βλ. Κύριοι πόροι). Για να γράψετε απευθείας σε κάποιον, ανοίξτε πρώτα το άμεσο μήνυμα:

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

Για να αντιδράσετε σε ό,τι λένε οι χρήστες, παρακολουθήστε το WebSocket με το token του bot και απαντήστε στα γεγονότα posted που σας ενδιαφέρουν. Αγνοήστε τα ίδια τα μηνύματα του bot για να αποφύγετε βρόχους.

Ένα μήνυμα που μπορεί να δει μόνο ένα άτομο (ephemeral message) αποστέλλεται με POST /api/v4/posts/ephemeral και {"user_id", "post": {"channel_id", "message"}}. Απαιτεί την άδεια create_post_ephemeral, την οποία έχουν από προεπιλογή μόνο οι συστημικοί διαχειριστές. Οι ενσωματώσεις συνήθως αποστέλλουν ephemeral messages ως απαντήσεις σε εντολές καθέτου και κουμπιά.

Πράκτορες

Ένας πράκτορας είναι ένας λογαριασμός Bot του είδους agent: οι χρήστες έχουν "is_agent": true, τα bots "kind": "agent", και το περιβάλλον εργασίας εμφανίζει την ετικέτα ΠΡΑΚΤΟΡΑΣ αντί για BOT. Οι πράκτορες δημιουργούνται μόνο από διαχειριστές συστήματος (πράκτορες σε επίπεδο διακομιστή), στην Κονσόλα συστήματος › AI › Συνδέσεις μοντέλων, και από διαχειριστές ομάδας (της ομάδας τους), στην καρτέλα AI των ρυθμίσεων ομάδας, ή μέσω του /api/v4/ai/agents (δείτε το API). Ένα bot που δημιουργείται με POST /bots ή από μια εφαρμογή είναι πάντα ένα απλό bot.

Ένας ενσωματωμένος πράκτορας λαμβάνει απαντήσεις από τον διακομιστή, μέσω μιας σύνδεσης μοντέλου. Ένας εξωτερικός πράκτορας είναι δικός σας για εκτέλεση: ένα πρόγραμμα αλλού (για παράδειγμα, ένας πράκτορας κωδικοποίησης σε ένα έργο) που συνδέεται ως ο πράκτορας και απαντά όπως θα απαντούσε ένα άτομο. Το Antimatter δεν απαντά για λογαριασμό του.

Η κατάσταση ενός ενσωματωμένου πράκτορα ορίζεται από τον διακομιστή: Σε σύνδεση όσο η σύνδεση του μοντέλου αποκρίνεται, Απών όταν δεν αποκρίνεται (εκτός λειτουργίας, λήξη χρονικού ορίου, απόρριψη κλειδιού) και Εκτός σύνδεσης όταν είναι απενεργοποιημένος ή δεν διαθέτει χρησιμοποιήσιμη σύνδεση ή μοντέλο. Ο έλεγχος εκτελείται όταν αλλάζει ο πράκτορας ή η σύνδεσή του, όταν δοκιμάζεται μια σύνδεση, σε κάθε κλήση μοντέλου του πράκτορα και κάθε 10 λεπτά. Κανείς δεν μπορεί να ορίσει την κατάσταση ενός ενσωματωμένου πράκτορα: τα PUT /users/{id}/status και τα endpoints προσαρμοσμένης κατάστασης επιστρέφουν 403 (api.status.agent.app_error), ακόμη και για διαχειριστές συστήματος, ενώ τα UpdateUserStatus, SetUserStatusTimedDND, UpdateUserCustomStatus και RemoveUserCustomStatus του plugin API το απορρίπτουν με τον ίδιο τρόπο. Η κατάσταση ενός εξωτερικού πράκτορα ακολουθεί τη δική του σύνδεση και μόνο το δικό του token μπορεί να την αλλάξει.

Εκτέλεση εξωτερικού πράκτορα

Ένας διαχειριστής προσθέτει τον πράκτορα στην Κονσόλα συστήματος › AI › Συνδέσεις μοντέλων (ή στην καρτέλα AI μιας κοινότητας), με τύπο Εξωτερικός πράκτορας, και επιλέγει ποιοι μπορούν να επικοινωνήσουν μαζί του. Η σελίδα εμφανίζει στη συνέχεια τις οδηγίες σύνδεσης.
Δώστε του ένα token: ένας διαχειριστής συστήματος ανοίγει τις Ολοκληρώσεις › Λογαριασμοί bot, εντοπίζει τον λογαριασμό του πράκτορα και επιλέγει Δημιουργία νέου token, ή καλεί το API tokens με το αναγνωριστικό χρήστη του πράκτορα:
```
curl -X POST https://chat.example.com/api/v4/users/$AGENT_USER_ID/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
  -d '{"description": "agent"}'
```
Το πρόγραμμα καλεί το API και ανοίγει το WebSocket με Authorization: Bearer <token>, διαβάζει τις αναφορές και τα άμεσα μηνύματα από τα γεγονότα posted και απαντά μέσω POST /posts, μέσα στο νήμα του μηνύματος.

Ενημερώνει τους χρήστες για τις ενέργειές του ορίζοντας τη δραστηριότητά του:

curl -X PUT https://chat.example.com/api/v4/ai/agents/$AGENT_USER_ID/activity \
  -H "Authorization: Bearer $AGENT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"state": "working", "text": "Running the tests", "thread_post_id": "'$ROOT_ID'"}'

Το αναγνωριστικό του πράκτορα σε αυτές τις διαδρομές είναι το αναγνωριστικό χρήστη του. Κρατήστε το token μυστικό: οποιοσδήποτε το έχει μπορεί να αναρτήσει ως ο πράκτορας.

Δραστηριότητα

state: idle, thinking, working, waiting (για κάποιον), blocked ή offline. Οι καταστάσεις απασχόλησης (thinking, working, waiting, blocked) επιστρέφουν σε idle μετά από expires_in_seconds: 10 λεπτά από προεπιλογή, έως 24 ώρες.
text: λίγες λέξεις για την εργασία, μία γραμμή με έως 200 χαρακτήρες. Η διεπαφή το εμφανίζει στη λίστα μελών και στην κάρτα προφίλ.
thread_post_id: το νήμα στο οποίο εργάζεται, το οποίο το πρόγραμμα πρέπει να μπορεί να διαβάσει. Δίνεται μόνο σε όσους έχουν δικαίωμα ανάγνωσής του.

Ποιος μπορεί να δει ότι ο πράκτορας μπορεί να διαβάσει τη δραστηριότητά του (GET /ai/agents/{agent_id}/activity ή POST /ai/agents/activity/ids με μια λίστα αναγνωριστικών) και λαμβάνει το γεγονός WebSocket agent_activity_changed, χωρίς το νήμα. Οι ενσωματωμένοι πράκτορες ορίζουν μόνοι τους τη δραστηριότητά τους.

Ενώ ένας ενσωματωμένος πράκτορας γράφει την απάντησή του, ο διακομιστής στέλνει το αναπτυσσόμενο κείμενο σε γεγονότα agent_post_stream στο κανάλι: post_id, channel_id, root_id, user_id, message (το κείμενο μέχρι στιγμής) και control (start, text, end, error ή cancel). Ένα γεγονός post_edited μεταφέρει το τελικό μήνυμα. Οι πελάτες που αγνοούν τη ροή βλέπουν την απάντηση μόλις αποθηκευτεί.

Διαδραστικά μηνύματα: κουμπιά και μενού

Κάθε μήνυμα με συνημμένα μπορεί να φέρει ενέργειες: κουμπιά και μενού για επιλογή. Λειτουργούν σε μηνύματα που δημοσιεύονται μέσω API, webhooks και απαντήσεων εντολών καθέτου. Όταν κάποιος χρησιμοποιήσει μία από αυτές, το Antimatter καλεί το 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 ή select.
id: γράμματα, αριθμοί, παύλες και κάτω παύλες, διαφορετικό για κάθε ενέργεια του μηνύματος. Δημιουργείται αυτόματα αν το αφήσετε κενό.
style (κουμπιά): default, primary, success, good, warning, danger ή ένα χρώμα σε hex.
options (μενού), ή data_source: users ή channels για επιλογή χρήστη ή καναλιού. Το default_option προεπιλέγει μια τιμή.
integration.url: η διεύθυνση στην οποία αποστέλλεται η κλικ. Μια εφαρμογή (πρόσθετο) μπορεί να χρησιμοποιήσει τη δική της διαδρομή, όπως /plugins/com.example.deploy/actions. Το integration.context είναι δικό σας: επιστρέφει μαζί με την κλικ και οι πελάτες δεν το βλέπουν ποτέ.

Το αίτημα που λαμβάνει η ολοκλήρωσή σας

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

Για ένα μενού, το type είναι select και το context.selected_option περιέχει την επιλεγμένη τιμή.

Η απάντησή σας

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

update: αντικαθιστά το κείμενο και τις ιδιότητες του μηνύματος, για παράδειγμα για να αφαιρέσει τα κουμπιά μόλις χρησιμοποιηθούν (κενό props).
ephemeral_text: ένα μήνυμα που βλέπει μόνο το άτομο που κλικάρει.
goto_location: μια διεύθυνση URL που ανοίγει.
Ένα κενό σώμα μηνύματος δεν αλλάζει τίποτα.

Ο διακομιστής περιμένει όσο επιτρέπει το Χρονόριο αιτήσεων ολοκληρώσεων (30 δευτερόλεπτα από προεπιλογή). Οι διευθύνσεις ολοκληρώσεων σε διευθύνσεις ιδιωτικού δικτύου πρέπει να επιτρέπονται από έναν διαχειριστή συστήματος, όπως και για τα webhooks.

Πλαίσια διαλόγου

Ένα πλαίσιο διαλόγου είναι ένα φόρμα που ανοίγει πάνω από τη συνομιλία. Μπορείτε να ανοίξετε ένα μόνο ως απάντηση σε κάτι που έκανε μόλις το άτομο, μια εντολή καθέτου ή ένα κουμπί, επειδή χρειάζεται το trigger_id του αιτήματος αυτού. Το trigger_id είναι έγκυρο για όσο διαρκεί το 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"}
      ]
    }
  }'

Τύπος στοιχείου	Τι εμφανίζει
`text`	Ένα πεδίο μίας γραμμής. `subtype`: `text`, `email`, `number`, `password`, `tel` ή `url`. Τα `min_length` και `max_length` το περιορίζουν.
`textarea`	Ένα πεδίο πολλαπλών γραμμών.
`select`	Μια λίστα: `options`, ή `data_source` `users`, `channels`, ή `dynamic` με `data_source_url`. Το `multiselect` επιτρέπει πολλαπλές τιμές.
`bool`	Ένα πεδίο επιλογής (checkbox).
`radio`	Μία επιλογή από τις `options`.
`date`, `datetime`	Μια ημερομηνία, ή ημερομηνία και ώρα.
`action_button`	Ένα κουμπί που καλεί το `action_button_url` μόνο του, ξεχωριστά από την υποβολή του διαλόγου. Το `help_text` του εμφανίζεται από κάτω.
`collapsible`	Μια αναδιπλούμενη ομάδα στοιχείων. Με `sub_type: "grid"`, οι θυγατρικοί του δέκτες διατάσσονται ως πίνακας αντί να στοιβάζονται: ο καθένας είναι μια γραμμή και τα δικά του στοιχεία είναι τα κελιά αυτής της γραμμής.

Κάθε στοιχείο δέχεται display_name, name, help_text, placeholder, default και optional.

Η παράμετρος submit_buttons στον διάλογο ονομάζει ένα στατικό στοιχείο select: οι επιλογές του γίνονται τα κουμπιά υποβολής του διαλόγου, ένα ανά επιλογή, αντί ενός μόνο κουμπιού Υποβολή, και το ίδιο το select δεν εμφανίζεται. Η παράμετρος size ("small", "medium" ή "large"· "small" αν παραλειφθεί) ζητάει έναν πιο φαρδύ διάλογο. Η παράμετρος refresh_on_return (απαιτεί source_url) επαναφέρει τον διάλογο από το source_url μόλις κλείσει ένας διάλογος που άνοιξε από πάνω του, ώστε να δείξει τι άλλαξε. Μια μη αναγνωρισμένη τιμή size ή sub_type δεν εμποδίζει τον διάλογο από το να ανοίξει: επιστρέφει στην προεπιλογή και ο διακομιστής το καταγράφει μόνο.

Όταν το άτομο υποβάλει, το Antimatter αποστέλλει POST στη διεύθυνση 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
}

Απαντήστε με κενό σώμα για να κλείσετε το διάλογο, ή κρατήστε το ανοιχτό και δείξτε τι είναι λάθος:

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

{"error": "…"} εμφανίζει ένα μήνυμα για όλο το φόρμα. Με notify_on_cancel, το κλείσιμο του διαλόγου αποστέλλει "cancelled": true. Τα διαλόγοι λειτουργούν με τον ίδιο τρόπο στις εφαρμογές: η OpenInteractiveDialog της API πρόσθετων δέχεται το ίδιο αίτημα.