External Connectors

The optional Connector Service sends durable OpenAlice Inbox updates to a private Discord or Telegram bot chat. It is an outbound notification bridge, not another agent runtime, chat interface, or source of truth.

Workspace Session
  -> durable Inbox entry
  -> optional Connector Service
  -> linked Discord or Telegram owner

The local Inbox append always completes first. If an external platform is down, rate-limited, misconfigured, or disabled, the Inbox entry remains successful and unread state does not change.

Current scope

Connector Service 0.81 supports:

Discord app direct messages;
Telegram private bot chats;
one linked owner per adapter;
outbound Inbox notifications;
/link, /status, and /test control commands;
Markdown and static HTML report attachments.

It does not ingest ordinary external messages, broadcast to groups or channels, or let Discord/Telegram become an unsupervised command surface.

Set up a connector

Open Settings → Connectors. This surface owns credentials, linking, start and stop actions, and test delivery.

The setup progresses through visible states:

State	What to do
Credentials needed	Create a bot/application and save the required token
Ready to link	Start the adapter so it can receive `/link`
Starting	Wait for Guardian to reconcile the optional service
Awaiting link	Open the private bot chat and send `/link`
Linked	Use Send test or wait for an Inbox delivery
Linked offline	Start the connector when external delivery is wanted
Error	Inspect credentials and Connector logs; local Inbox remains available

Saving a token is not the same as linking an owner. The bot must be online when you send /link; OpenAlice then records the Discord user or Telegram private chat allowed to receive notifications and control commands.

Discord

Create a Discord application and bot, then save its credentials in OpenAlice. No guild or channel is required. Open the app's direct-message context and run /link from the account that should own the connector.

Discord ordinary DM text is not read. Only the registered slash commands enter the connector control plane.

Create a bot with BotFather, save its token, start the adapter, and send /link from the owner's private chat. The adapter uses private-chat long polling and rejects commands from any account other than the linked owner.

Settings and operations views

The two Connector surfaces deliberately have different jobs:

Settings → Connectors — credentials, setup sequence, enable/stop, linking, and test sends.
Beta → Connectors — read-only service health, adapter status, linked owner, and recent delivery evidence.

Stopping Connector Service is a global kill switch. It does not delete sealed tokens or the learned owner, so the same connector can be restarted later.

What gets delivered

Every external notification includes the Inbox message and visible Session signature when one exists:

pi · @resume-…

The @resumeId is the accountable sender; the runtime label is only supporting context.

Inbox documents are handled as follows:

Markdown and static HTML reports are sent as files rather than flattened into the chat message;
Alice reads the live Workspace file and sends a delivery copy; the Connector Service never reads a Workspace directly;
source and delivery hashes remain distinct when text encoding needs a safe UTF-8 normalization;
one notification carries at most five eligible files, each at most 1 MiB;
missing, oversized, unsupported, or path-escaping files do not block the text notification;
HTML stays an attachment with text/html media type and is never executed or translated by the connector.

Static HTML is a human-facing presentation asset. Keep a concise Markdown Inbox comment so both the user and other agents can understand the result without parsing the HTML report.

Delivery guarantees

Connector delivery is intentionally downstream of durable local state:

inbox push succeeds when the Inbox append succeeds, even if every connector fails;
an external failure never marks an Inbox entry read;
disabled Connector Service makes no external request;
an adapter awaiting /link is online but not delivery-ready;
degraded health and logs make partial or failed delivery visible to the operator.

Use /status inside the linked private chat to check the adapter, and /test or Send test in Settings for an explicit probe.

Privacy and security

Bot tokens are sealed at rest and never returned by the Settings API.
Each adapter authorizes exactly one linked owner account/private chat.
Connector Service runs as an optional Guardian child and can restart without restarting Alice or UTA.
A bounded private I/O journal stores correlation and delivery evidence for diagnostics; it does not store bot tokens.
Platform account and chat identifiers are pseudonymized in that journal.
Notification text is retained locally because it is the payload being tested; treat the OpenAlice data home as sensitive.

If you do not need external delivery, leave Connector Service disabled. Inbox, Workspaces, research, and Lite mode continue to work normally.

Next Steps

Inbox — Understand the durable source of every connector notification.
Sessions & Collaboration — Read the sender signature and follow up exactly.
Data & Credentials — Back up the sealed configuration and data home.
Docker — Run the optional service on an always-on host.

Search Documentation