> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bumbleagi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Presence & social surfaces

> Telegram, Discord, CLI — how social adapters plug into one entity.

**Presence** is how the same entity speaks on different channels. Each **social adapter** (platform implementation) converts a vendor’s APIs and events into Bumblebee’s internal message shape and delivers replies back — including typing indicators, chunking, attachments, and tool-activity lines when enabled.

## Declarative wiring

Platforms are listed under **`presence.platforms`** in the entity YAML. Each entry has a **`type`** (`telegram`, `discord`, `cli`, …) plus type-specific options (tokens via env vars, allowlists, channels, proactive targets).

The harness starts only the platforms that are **configured and authenticated** (e.g. missing `TELEGRAM_TOKEN` skips Telegram with a warning).

## First-class social adapters today

| Platform     | Role                                                                                                                                   |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Telegram** | Long-polling bot; optional per-user / per-chat allowlists, operator controls, concurrent updates, poll tuning.                         |
| **Discord**  | Bot token + channel list; optional proactive channel; chunk replies and presence sync with emotion state.                              |
| **CLI**      | Interactive terminal for local development; disabled automatically in **`bumblebee worker`** so headless servers do not wait on a TTY. |

Platform-specific guides: [Telegram](/guides/telegram), [Discord](/guides/discord).

## Shared pipeline

For every inbound message (any platform):

1. The adapter builds a normalized input (person id, channel, text/media metadata).
2. **`Entity.perceive`** runs the full cognition pipeline — memory, routing, tools, reply assembly.
3. The adapter sends the reply (chunked if needed), updates typing/presence, and surfaces tool activity if `presence.tool_activity` is on.

So **you do not duplicate personality or memory per network** — one entity, many sockets.

## Security and boundaries

* **Allowlists** (Telegram `allowed_user_ids` / `allowed_chat_ids`) limit who can trigger the bot in untrusted environments.
* **Tokens** should stay in environment variables or secret managers, not committed YAML.
* **Worker mode** assumes untrusted cloud: combine with [execution policy](/deployment/hybrid-railway) (`BUMBLEBEE_EXECUTION_REQUIRE_RAILWAY`, RPC URLs) if tools must not run arbitrary commands on the worker host.

## Building a new adapter (advanced)

The platform layer is an **abstract interface**: `connect`, `on_message`, `send_message` / chunking helpers, `send_tool_activity`, presence hooks, and person identity helpers. A new adapter:

1. Implements that contract against the vendor’s SDK or HTTP API.
2. Registers with the entity in the same loop that constructs Telegram/Discord today (`main` / presence bootstrap).

Keeping adapters **thin** — translate I/O only — preserves testability and avoids duplicating cognition logic.

Deeper internal background: [Architecture: Presence](/architecture/presence).