Bots i missatges interactius

Un compte de bot és un usuari creat per a un programa. Té el seu propi nom, imatge i tokens, i mostra una etiqueta BOT al costat del nom. Aquesta pàgina també cobreix els agents d'IA que executeu vosaltres mateixos, i les parts interactives dels missatges: botons, menús i diàlegs, que qualsevol integració pot utilitzar.

Per què un compte de bot

Els seus missatges provenen d'una identitat clara, amb una etiqueta BOT, en lloc de des del compte d'un company.
Els seus tokens continuen funcionant quan la persona que el va configurar canvia de rol o surt (excepte si el servidor desactiva els bots dels propietaris desactivats, vegeu més avall).
Els bots no poden iniciar sessió amb una contrasenya, i mai no veuen l'aplicació web.

Les aplicacions creen els seus propis bots, com els bots de Tasques pendents o de Guies d'actuació, a través de la API de plugins (EnsureBotUser). Els agents d'IA també són comptes de bot, però d'un tipus propi, mostrats amb una etiqueta AGENT: vegeu Agents.

Habilita els comptes de bot

Un administrador del sistema habilita Habilita la creació de comptes de bot a Consola del sistema › Integracions › Comptes de bot (ServiceSettings.EnableBotAccountCreation, AM_SERVICESETTINGS_ENABLEBOTACCOUNTCREATION). Per defecte, està desactivat. Només els administradors del sistema poden crear bots, llevat que atorguin aquest dret a altres rols a la configuració de permisos.

A la mateixa pàgina, Desactiva els comptes de bot quan el propietari es desactiva (ServiceSettings.DisableBotsWhenOwnerIsDeactivated, activat per defecte) desactiva un bot quan el compte del seu propietari es desactiva.

Crea un bot

Obriu el menú de l'equip, després Configuració de l’equip, feu clic a Integracions al final de les seves pestanyes, després Comptes de bot i Afegeix un compte de bot.
Introdueix un Nom d’usuari (lletres minúscules, números, punts, guions i guions baixos), i opcionalment una Icona del bot, un Nom per mostrar i una Descripció.
Tria el Rol: Membre, o Administrador del sistema per a un bot que gestioni el servidor. Atorga al bot el mínim que necessita.
Marca post:channels per permetre-li publicar en tots els canals públics, o post:all per a tots els canals, inclosos els privats i els missatges directes, sense haver de ser membre.
Estableix quan expira el seu token per defecte, i després tria Crea el compte de bot.
Copia el token d'accés que es mostra. No es mostrarà de nou.

Més endavant, Crea un nou token a la filera del bot afegeix un token, i cada token es pot desactivar o eliminar. Els tokens de bot funcionen fins i tot quan els tokens d'accés personals estan desactivats per a les persones.

Un bot pot portar atributs del servidor (els configurats a Consola del sistema › Attributs del sistema), establerts al formulari d'afegir/editar bot o des de Edita els atributs… al menú ⋯ del bot. Els estableix qui gestiona el bot: el seu propietari, amb el permís de gestió de bots, o qualsevol persona amb el permís de gestió dels bots d'altres; un atribut gestionat per l'administració del sistema encara requereix un administrador del sistema. El bot d'un agent d'IA no pertany a ningú, per tant, només algú amb el permís de gestió dels bots d'altres o un administrador del sistema pot establir-ne els atributs.

Mitjançant l'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"}'

Des de la línia d'ordres, iniciant sessió com a administrador (no en mode local): amctl bot create deploy-bot --display-name Deploy --with-token --expires-in 90d. Altres punts d'accés: GET /api/v4/bots, PUT /api/v4/bots/{bot_user_id}, POST /api/v4/bots/{bot_user_id}/disable i /enable, POST /api/v4/bots/{bot_user_id}/assign/{user_id} per canviar-ne el propietari.

Afegeix el bot a comunitats i canals

Un bot nou no pertany a cap comunitat. Afegeix-lo com si fos una persona, des de la gestió de membres de la comunitat o mitjançant l'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'"}'

Un bot amb post:channels o post:all pot publicar sense ser membre, però només rep esdeveniments WebSocket dels canals als quals hi és.

Publica com a bot

Utilitza el token del bot amb qualsevol crida a l'API; POST /api/v4/posts és la més habitual (vegeu Recursos principals). Per escriure directament a algú, obre primer el canal de missatges directes:

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

Per reaccionar al que diuen les persones, segueix el WebSocket amb el token del bot i respon als esdeveniments posted que t'interessen. Ignora els propis missatges del bot per evitar bucles.

Un missatge que només pot veure una persona (un missatge efímer) s'envia amb POST /api/v4/posts/ephemeral i {"user_id", "post": {"channel_id", "message"}}. Requereix el permís create_post_ephemeral, que per defecte només tenen els administradors del sistema. Les integracions solen enviar missatges efímers com a resposta a comandes amb barra i botons.

Agents

Un agent és un compte de bot del tipus agent: els usuaris tenen "is_agent": true, els bots "kind": "agent", i la interfície mostra una etiqueta AGENT en lloc de BOT. Els agents només els creen els administradors del sistema (agents de tot el servidor), a Consola del sistema › IA › Connexions de models, i els administradors de l'equip (els del seu equip), a la pestanya IA de la configuració de l'equip, o amb /api/v4/ai/agents (vegeu l'API). Un bot creat amb POST /bots o per una aplicació és sempre un bot normal.

Un agent Integrat és respost pel servidor, amb una connexió de model. Un Agent extern és de la vostra responsabilitat executar-lo: un programa en un altre lloc (un agent de programació en un projecte, per exemple) que inicia sessió com a agent i respon com ho faria una persona. Antimatter no respon per ell.

L'estat d'un agent integrat el fixa el servidor: En línia mentre la seva connexió de model respon, Absent quan no ho fa (caiguda, temps d'espera exhaurit, clau refusada) i Desconnectat quan està apagat o no té cap connexió o model utilitzable. Es comprova quan l'agent o la seva connexió canvien, quan es prova una connexió, en cada crida al model de l'agent i cada 10 minuts. Ningú pot establir l'estat d'un agent integrat: PUT /users/{id}/status i els punts d'accés d'estat personalitzat responen amb 403 (api.status.agent.app_error), també per als administradors del sistema, i les API de connectors UpdateUserStatus, SetUserStatusTimedDND, UpdateUserCustomStatus i RemoveUserCustomStatus ho refusen de la mateixa manera. L'estat d'un agent extern, en canvi, segueix la seva pròpia connexió, i només el seu propi token el pot canviar.

Executar un agent extern

Un administrador afegeix l'agent a Consola del sistema › IA › Connexions de models (o a la pestanya IA d'una comunitat), amb el tipus Agent extern, i tria qui hi pot parlar. La pàgina mostra a continuació com connectar-lo.
Proporcioneu-li un token: un administrador del sistema obre Integracions › Comptes de bot, troba el compte de l'agent i tria Crea un nou token, o bé crida l'API de tokens amb l'ID d'usuari de l'agent:
```
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"}'
```
El programa crida l'API i obre el WebSocket amb Authorization: Bearer <token>, llegeix les seves mencions i missatges directes dels esdeveniments posted, i respon amb POST /posts, dins del fil del missatge.

Mostra a les persones què està fent establint la seva activitat:

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

L'ID de l'agent en aquests paths és el seu ID d'usuari. Manteniu el token en secret: qualsevol que el tingui pot publicar com a agent.

Activitat

state: idle, thinking, working, waiting (esperant algú), blocked o offline. Els estats ocupats (thinking, working, waiting, blocked) tornen a idle després de expires_in_seconds: 10 minuts per defecte, 24 hores com a màxim.
text: unes paraules sobre la tasca, una línia de 200 caràcters com a màxim. La interfície el mostra a la llista de membres i a la targeta de perfil.
thread_post_id: el fil en el qual treballa, que el programa ha de poder llegir. Només es proporciona a qui el pot llegir.

Qui pot veure que l'agent pot llegir la seva activitat (GET /ai/agents/{agent_id}/activity, o POST /ai/agents/activity/ids amb una llista d'IDs) i rep l'esdeveniment WebSocket agent_activity_changed, sense el fil. Els agents integrats defineixen la seva activitat per si mateixos.

Mentre un agent integrat escriu la seva resposta, el servidor envia el text en creixement en els esdeveniments agent_post_stream al canal: post_id, channel_id, root_id, user_id, message (el text fins al moment) i control (start, text, end, error o cancel). Un esdeveniment post_edited conté el missatge final. Els clients que ignoren el flux veuen la resposta una vegada desada.

Missatges interactius: botons i menús

Qualsevol missatge amb adjunts pot portar accions: botons i menús per triar. Funcionen en missatges publicats mitjançant l'API, webhooks i respostes a comandes amb barra. Quan algú n'usa un, Antimatter crida l'URL de la teva integració.

{
  "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: lletres, números, guions i guions baixos, diferent per a cada acció del missatge. Es genera si el deixes buit.
style (botons): default, primary, success, good, warning, danger, o un color en hexadecimal.
options (menús), o data_source: users o channels per triar una persona o un canal. default_option preselecciona un valor.
integration.url: on s’envia el clic. Una aplicació (connector) pot utilitzar la seva pròpia ruta, com ara /plugins/com.example.deploy/actions. integration.context és vostre: torna amb el clic i els clients mai el veuen.

La sol·licitud que rep la vostra integració

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

Per a un menú, type és select i context.selected_option conté el valor triat.

La vostra resposta

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

update: substitueix el text i les propietats del missatge, per exemple per eliminar els botons un cop utilitzats (un props buit).
ephemeral_text: un missatge que només veu la persona que ha fet clic.
goto_location: una URL per obrir.
Un cos buit no canvia res.

El servidor espera tant com permet el Temps d’espera de la sol·licitud d’integració (30 segons per defecte). Les URL d’integració en adreces de xarxa privada han de ser permeses per un administrador del sistema, com passa amb els webhooks.

Diàlegs

Un diàleg és un formulari que s’obre sobre el xat. Només podeu obrir-ne un com a resposta a alguna cosa que la persona acabi de fer, com ara una comanda amb barra o un botó, perquè necessita el trigger_id d’aquesta sol·licitud. El trigger_id és vàlid durant el temps d’espera de la sol·licitud d’integració.

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

Tipus d’element	Què mostra
`text`	Un camp d’una línia. `subtype`: `text`, `email`, `number`, `password`, `tel` o `url`. `min_length` i `max_length` el limiten.
`textarea`	Un camp de diverses línies.
`select`	Una llista: `options`, o `data_source` `users`, `channels`, o `dynamic` amb un `data_source_url`. `multiselect` permet diversos valors.
`bool`	Una casella de selecció.
`radio`	Una elecció entre `options`.
`date`, `datetime`	Una data, o una data i hora.
`action_button`	Un botó que crida `action_button_url` per si sol, independentment de l'enviament del diàleg. El seu `help_text` es mostra a sota.
`collapsible`	Un grup plegable d'elements. Amb `sub_type: "grid"`, els seus contenidors fills es disposen com una taula en lloc d'apilar-se: cadascun és una fila, i els seus elements propis són les cel·les d'aquesta fila.

Cada element accepta display_name, name, help_text, placeholder, default i optional.

submit_buttons al diàleg anomena un element select estàtic: les seves opcions es converteixen en els botons d'enviament del diàleg, un per opció, en lloc d'un únic botó Envia, i aquest select no es mostra. size ("small", "medium" o "large"; "small" si s'omet) sol·licita un diàleg més ample. refresh_on_return (requereix source_url) torna a obtenir el diàleg des de source_url quan es tanca un diàleg obert a sobre, perquè pugui mostrar què ha canviat. Un size o sub_type no reconegut no impedeix que s'obri el diàleg: recorre al valor predeterminat i el servidor només ho registra al registre.

Quan la persona envia el formulari, Antimatter fa una sol·licitud POST a l’url del diàleg:

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

Respondeu amb un cos buit per tancar el diàleg, o manteneu-lo obert i mostreu què no va bé:

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

{"error": "…"} mostra un missatge per a tot el formulari. Amb notify_on_cancel, tancar el diàleg envia "cancelled": true. Els diàlegs funcionen de la mateixa manera en les aplicacions: l’OpenInteractiveDialog de l’API de connectors accepta la mateixa sol·licitud.