Gateway Channel Directory

Let your bot enumerate every channel it can see — before anyone messages it

Discover every Discord and Slack channel your bot can address, without waiting for someone to say @bot first.

Quick Start

1. Run an agent on the gateway

   Nothing to enable — if Discord or Slack is configured, its channels are auto-listed on every refresh. Your agent can address every visible channel without a prior inbound message:

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Announcer",
       instructions="Post the daily standup summary to every team channel.",
       model="gpt-4o-mini",
   )
   
   agent.start("Post 'Standup at 10:00 GMT' to every channel in the directory.")

2. Configure Discord or Slack

   Enumeration works out of the box — no new keys are required:

   # gateway.yaml
   channels:
     discord:
       platform: discord
       token: "${DISCORD_BOT_TOKEN}"
       # Guilds intent is already enabled by the adapter.
   
     slack:
       platform: slack
       bot_token: "${SLACK_BOT_TOKEN}"
       # Paginates public + private channels your bot user can access.

How It Works

ChannelDirectory.refresh_from_adapters asks each adapter for its channels, then merges them into the observed set.

Each adapter returns a list of ChannelRef descriptors. Only .id is consumed by the directory; name and type are for logging and UI.

Adapters implement list_channels() optionally. refresh_from_adapters looks it up via getattr(adapter, "list_channels", None) and skips any adapter that doesn’t provide it — Telegram, custom webhook, and IRC descriptor-only adapters stay observed-only, so nothing regresses.

Behavior Details

The directory degrades gracefully — a slow or empty adapter yields fewer entries, never an exception.

Slack pagination and timeout

Slack’s async client is driven from the synchronous refresh loop by a sync-safe wrapper — asyncio.run(...) when no loop is running, or a short-lived worker thread when a loop is already active. This works whether the gateway starts inside an existing asyncio.run or from a plain sync entrypoint.

Best Practices

How has_channel gates agent sends

ChannelDirectory.has_channel(platform, channel_id) is also the authority behind send_message‘s destination attestation. A chat is “known” to the gateway if it is a home channel, an alias, or an observed channel in the directory. See Destination Attestation.

Related