Convo integrations

Public UTCP catalog and installation instructions. Catalog definitions contain no bot-specific credentials, accounts, database exports or tokens. The bot receives available definitions and chooses whether/how to configure its own environment.

Catalog URL:

https://git.barglvojtech.net/convo/integrations/raw/branch/main/.well-known/utcp/providers.json

Register that URL in Studio's catalog source textarea, or through the bot catalog API using url and enabledItems. null/omission selects all present and future items, [] selects none; otherwise use provider name values. The catalog currently contains simplex_chat, with an isolated per-bot local UTCP endpoint. Studio's fixed Convo management provider remains dynamically generated by each installation.

Installation metadata

• metadata.installation_path: a URL path relative to the catalog document, such as instructions/simplex.md. This is not a path on the Studio host.
• metadata.installation_url: an absolute HTTP(S) installation document URL.
• metadata.installation_instructions_url: the existing absolute URL spelling, retained for compatible clients.

Existing installation_instructions_url takes precedence, followed by installation_url, then the resolved installation_path. Studio preserves the original path in stored definitions and adds the resolved compatibility URL when publishing its aggregated catalog. This keeps nested and re-exported catalogs from accidentally rebasing installation instructions to the wrong host.

Instructions describe setup; they are not automatically executed. SimpleX's guide covers a verified CLI, persistent profile, Supervisor services, scheduled checks, SSE notifications and migration of existing accounts without replacing identity. The bot owns reaction and contact policy; enabling a definition is not an assertion that setup has already happened. Never forward Convo credentials to third-party instruction URLs.

Contributing

Add a provider to .well-known/utcp/providers.json and its guide under .well-known/utcp/instructions/. Keep technical name separate from the human metadata.display_name, and validate with python3 scripts/validate.py. Generic definitions must preserve upstream transport semantics; a SimpleX CLI WebSocket is not an HTTP API. Runtime build recipes live in convo/runtime.

Studio vendors a pinned copy of the guides for its existing installation URLs and offline compatibility. This repository is the canonical source; update Studio's integration lock/snapshot when changing those compatibility guides.

Studio types and per-bot configuration

metadata.convo_type selects a Studio editor. simplex provides the SimpleX policy form; unknown types retain a generic JSON configuration editor. Legacy convo_template remains readable when the canonical field is absent.

Users configure catalog integrations in each bot's Integrations settings. Any provider value can be overridden except its name, which identifies the provider within its catalog. No catalog allowlist is needed. Values are private to that bot; the shared source is immutable. Arrays are replaced whole, and overlapping JSON Pointer paths are rejected. {} resets configuration to source defaults while preserving observed profile/address state. Source refresh retains user overrides.

GET/PUT /api/bots/{botId}/catalogs/{catalogId}/providers/{name}/overrides uses the catalog revision in If-Match. PUT requires a user session authorized for that bot. Bot credentials can inspect effective configuration with catalog_provider_get, but cannot change user overrides. Configuring a provider does not enable it. Invalid combined definitions are rejected.