pachca-bots

pachca-bots

Quick start

Ask the user for a Pachca token (bot: the API tab of the bot in Integrations → Bots, user: Integrations → API).

Run commands via npx -y @pachca/cli with the --token flag:

npx -y @pachca/cli <command> --token $PACHCA_TOKEN

Or set the PACHCA_TOKEN environment variable:

export PACHCA_TOKEN=<token>
npx -y @pachca/cli <command>

Help: npx -y @pachca/cli --help | Workflows: npx -y @pachca/cli guide

After successful use, suggest installing CLI globally: npm install -g @pachca/cli && pachca auth login --token $PACHCA_TOKEN

Before you start

If the user has a saved profile — check:
```
npx -y @pachca/cli auth status
```
If OK — run commands without --token.
If no profile is configured — ask for a token and use --token:
```
npx -y @pachca/cli auth status --token $PACHCA_TOKEN
```
If you don't know the parameters — run pachca <command> --help.

Workflows

Create a bot via the API and get a token

Create a bot. Only with a user token (not a bot token); nickname must end with _bot. Webhook parameters (Webhook URL, events, commands) can be set immediately or later. The bot token's scopes can be limited with the flag --scopes (if not specified, the bot gets the default set):
```
pachca bots create --name="Бот задач" --nickname="tasks_bot" --scopes='["messages:create"]'
```
Save access_token from the response — it is returned only once. It is not shown again; you can only reissue it with the command pachca bots recreate-token <ID>
The response will also include id of the bot (its user_id) — it is needed for further calls, for example to add the bot to a chat

Bots can only be created with a user token — not with a bot token. access_token is given once at creation, it cannot be seen again, only reissued. With the flag --empty the bot is created without a token and incoming webhook, as in the interface, and tokens are issued to it by pachca bots create-token.

Configure a bot with an outgoing webhook

Create a bot, specifying the Webhook URL and events right away in a single call (details of creation and working with the token are in the scenario "Create a bot via the API and get a token"):

pachca bots create --name="Бот задач" --nickname="tasks_bot" --outgoing-url="https://example.com/webhook" --events='["message_new"]' --trigger-on=commands --commands='["/task"]'

Save access_token from the response (returned only once)
Use the saved access_token to send messages on behalf of the bot

Alternative — create and configure the bot in the interface. The Webhook URL and events can also be set later with the PUT /bots/{id} method.

Update the bot's Webhook URL

With a user token (with permission to edit the bot) — update the URL via id of the bot. An empty string disables the webhook:
```
pachca bots update <bot_id> --outgoing-url="https://example.com/webhook"
```
id of the bot can be found with the method pachca bots list
Or: the bot updates its own webhook with its own token — without id and without administrator involvement (the scope bot_self:webhook:write):
```
pachca bots update-webhook --outgoing-url="https://example.com/webhook"
```

Two paths: via id with a user token (the right to edit the bot) or by the bot itself with its own token (PUT /bot/webhook). An empty outgoing_url disables the webhook.

Bot token rotation

With a user token (the bot creator or an administrator, if the bot is open to administrators) — reissue the main token via id of the bot: the one without a name, and if there is none, the oldest one. The previous value is invalidated immediately:
```
pachca bots recreate-token <bot_id>
```
Or: the bot reissues its main token itself (scope bot_self:write). If the request is made with the main token, it is invalidated immediately — be sure to save the new access_token from the response, otherwise the bot will lose access to the API:
```
pachca bots recreate-token-self
```
Reissue a separate bot token by its id from pachca bots list-tokens: the value changes, the name and permissions remain:
```
pachca bots reissue-token <bot_id> <token_id>
```
Save the new access_token from the response — it is returned only once. Update the secret in CI or the secret store

The new value is returned once. The self path (POST /bot/recreate_token) reissues the bot's main token — if the bot uses it, capture the new token from the response in the same operation.

Issue a separate token to the bot

With a user token (the bot creator or an administrator, if the bot is open to administrators), get the catalog of permissions that can be granted to this bot:
```
pachca bots list-scopes <bot_id>
```
Issue a token with a name and permissions from the catalog. Without --scopes the token is issued without permissions, a permission not from the catalog is rejected with 400:
```
pachca bots create-token <bot_id> --name="Сервер уведомлений" --scopes='["messages:create"]'
```
Save token from the response — the full value is returned only once. Thereafter, in the list pachca bots list-tokens it comes masked

A separate token is convenient for each service that operates on behalf of the bot: it is revoked with the command pachca bots delete-token, without affecting the others. Permissions are changed by pachca bots update-token — they take effect immediately, no need to reissue the token.

Enable employee impersonation authorization for the bot

With a user token (the bot creator or an administrator, if the bot is open to administrators), enable authorization: where the secret is stored, the redirect URIs, and the permissions the bot will request from the employee. Take the permissions from pachca bots list-scopes:
```
pachca bots update <bot_id> --oauth-client='{"confidential":true,"redirect_uris":["https://example.com/oauth/callback"],"scopes":["messages:read","messages:create"]}'
```
Save client_secret from the server client response — it is returned only once. client_id comes in oauth_client and is not secret

For the bot to appear in the storefront, add a description and publish the page:

pachca bots update <bot_id> --promo='{"description":"Собирает сводку по задачам","published":true}'

Whether authorization is enabled is shown by oauth_client_enabled: oauth_client may also come for a bot with authorization disabled. --oauth-client=null disables it and revokes the authorizations issued by employees; a new secret is issued by pachca bots rotate-client-secret.

Find and delete a bot

With a user token (scope bots:read) get the list of bots available to you for editing: those created by you and those whose settings grant you access. Filter by name using the parameter query, take the next page from meta.paginate.next_page:
```
pachca bots list --query="задач"
```
Take id of the required bot from the list and delete it (scope bots:write). Available to the bot creator and to an administrator, if the bot is open to administrators — chat owners cannot delete a bot. All bot tokens are invalidated immediately, the bot is removed from all chats, and its webhooks are deleted:
```
pachca bots delete <bot_id>
```

Deletion is irreversible: the bot token is invalidated immediately, and the bot is removed from chats. The event is recorded in the audit log as bot_deleted.

Periodic digest/report

On a schedule (cron/scheduler): collect data from your system
Compose the message text with the required metrics or summary

Send the message to the channel:

pachca messages create --entity-id=<chat_id> --content="Дайджест за сегодня: ..."

There is no built-in scheduler — use cron, celery, sidekiq, etc. on your side.

Inventory of all bots in the space

Get all bots in the space, not just those available for editing:
```
pachca bots list-company --all
```
The scope is required company_bots:read, the space owner role and the "Corporation" plan, otherwise the method responds 403. Filter by name — the flag --query
For each bot, check whether the settings are exposed: for bots that are unavailable to the token owner for editing, only name и nicknameare filled in, the remaining webhook fields come null

The settings of such a bot can only be obtained with the token that has access to edit it

Every request to the space's bot list is written to the audit log as company_bots_accessed.

Limitations

Rate limit: ~50 req/sec. On 429 — wait and retry.
webhook.name: max 255 characters
webhook.nickname: max 255 characters
webhook.trigger_on: allowed values — commands (Only for commands (trigger words) from commands), all_messages (For all messages in chats where the bot is present), unfurl (For link previews)
webhook.template_engine: allowed values — liquid (Liquid — conditions, loops and filters), mustache (Mustache — simple substitution without logic)
webhook.who_can_add: allowed values — creator (Bot creator only), creator_admin (Company creator and administrators), creator_admin_user (Company creator, administrators and members), anyone (Public bot: any employee except guests and multi-guests can add it)
webhook.kind: allowed values — simple (Custom format: the message is assembled from the request body using the bot's template), gitlab (GitLab: Pacha parses the request and assembles the message itself), grafana (Grafana: Pacha parses the request and assembles the message itself)
name: max 255 characters
limit: max 50
Pagination: cursor-based (limit + cursor)

Endpoints

Method	Path	Description
POST	/bot/recreate_token	Rotation of the bot's own token
PUT	/bot/webhook	Self-registration of the bot webhook
GET	/bots	Bot list
POST	/bots	New bot
GET	/bots/{id}	Bot information
PUT	/bots/{id}	Bot editing
DELETE	/bots/{id}	Bot deletion
POST	/bots/{id}/recreate_token	Bot token rotation
POST	/bots/{id}/rotate_client_secret	Client secret rotation
GET	/bots/{id}/scopes	Bot permissions catalog
GET	/bots/{id}/tokens	Bot token list
POST	/bots/{id}/tokens	New bot token
PUT	/bots/{id}/tokens/{token_id}	Bot token modification
DELETE	/bots/{id}/tokens/{token_id}	Bot token deletion
POST	/bots/{id}/tokens/{token_id}/reissue	Bot token reissue
GET	/company/bots	Space bot list
GET	/webhooks/events	Event history
DELETE	/webhooks/events/{id}	Event deletion

Advanced workflows

For advanced workflows, read the files in references/: references/handle-incoming-webhook-event.md — Handle incoming webhook event references/link-unfurling.md — Link unfurling references/handle-button-click-callback.md — Handle button click (callback) references/monitoring-and-alerts.md — Monitoring and alerts references/process-events-via-history-polling.md — Process events via history (polling)

references/webhook-events.md — Webhook event types

If unsure how to complete a task, read the corresponding file from references/.