Communication Gateways

​

Overview

​

Platform adapters

​

Prerequisites

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

​

Architecture

Platform (Slack, Telegram, ...)
          |
          v   webhook POST  or  outbound WS / poll
  /api/channels/webhook/{type}/{config_id}  <---  HTTP ingress
          |                                         |
          v                                         v
  ChannelConfig (Fernet-encrypted creds)     GatewayRunner (runner.py)
          |                                         |
          |    inbound MessageEvent                 |
          +---------------------------------------->+
                                                    |
                                                    v
                                  TaskQueue (ARQ cloud / asyncio desktop)
                                                    |
                                                    v
                                       Agent worker runs agent loop
                                                    |
                                                    v
                                   Redis XADD -> gateway_delivery_stream
                                                    |
                                                    v
                                  GatewayRunner._delivery_consumer
                                                    |
                                                    v
                                    adapter.send_gateway_response(chat_id, text)
                                                    |
                                                    v
                                      Reply lands in the original chat

• One adapter per ChannelConfig row. Adapters are keyed by config_id inside GatewayRunner.adapters.
• Per-session ordering: the runner derives a session_key from platform:chat_type:chat_id[:thread_id] so concurrent messages in the same chat are serialized.
• Response routing uses Redis XREADGROUP on gateway_delivery_stream, so only the pod holding the session’s adapter delivers the reply.
• A PlatformIdentity row links a platform account (telegram:12345) to an OpenSail User, gating who the agent will respond to.

​

Identity pairing

​

Per-platform setup

​

Creating schedules

POST /api/schedules
{
  "project_id": "...",
  "agent_id": "...",
  "name": "Friday summary",
  "schedule": "every Friday at 9am",
  "timezone": "America/New_York",
  "repeat": null,
  "prompt_template": "Summarize this week and post the highlights.",
  "deliver": "telegram:123456789"
}

• Natural language parser: orchestrator/app/services/gateway/schedule_parser.py
• Any valid 5-field cron passes through unchanged.
• CronScheduler (orchestrator/app/services/gateway/scheduler.py) ticks every GATEWAY_TICK_INTERVAL, picks due schedules, enqueues the agent task, increments runs_completed, and updates next_run_at.

​

Delivery targets

​

Agents sending messages

send_message(
  channel="discord",
  target="<chat_id>",
  text="Hello from the agent",
)

• send_message is a dangerous tool and is subject to plan-mode and approval gating (see DANGEROUS_TOOLS in the agent docs).
• The backend resolves the right ChannelConfig for the current user and calls its adapter. Targets for DMs are the platform user ID; for channels, the channel or chat ID.
• For quick Discord notifications without a full bot, set AGENT_DISCORD_WEBHOOK_URL and the tool will post through that webhook even if no Discord ChannelConfig exists.

​

Credential security

• Credentials are serialized to JSON and Fernet-encrypted before insert. See encrypt_credentials in orchestrator/app/services/channels/registry.py.
• CHANNEL_ENCRYPTION_KEY must be a base64 Fernet key. If a raw string is provided, the registry derives a Fernet key through SHA-256 to avoid a cold-start crash, but this path is a fallback, not a recommendation.
• GET endpoints on /api/channels never return raw credentials. The UI masks values via _mask_credentials in orchestrator/app/routers/channels.py.
• Webhook URLs include a per-config webhook_secret (see generate_webhook_secret) on top of platform signature verification: HMAC-SHA256 for Slack and WhatsApp, Ed25519 for Discord, secret-token header for Telegram.
• Key rotation: generate a new key, re-encrypt existing rows, set the new key. Channel credentials are small, so a migration script that reads decrypted values and writes them back with the new key works cleanly.

​

Voice transcription

​

Testing and debugging

• kubectl logs deploy/tesslate-gateway --context=<name> or docker compose logs -f gateway. Look for [GATEWAY], [TG-GW], [SLACK-GW], [DISCORD-GW], [SIGNAL-GW] prefixes.
• GET /api/gateway/status returns shard count, adapter count, heartbeat, last sync timestamp.
• ChannelMessage rows log inbound and outbound messages with direction, status, platform_message_id, and the associated task_id. Query by channel_config_id.
• POST /api/gateway/reload forces a diff-based adapter resync.

​

Common failure modes

​

Production notes

• GATEWAY_SHARD and GATEWAY_NUM_SHARDS shard ChannelConfig rows across gateway replicas. Each config is pinned to a shard via channel_configs.gateway_shard.
• Use a Recreate update strategy with replicas=1 per shard so there is only ever one active adapter per config. The file lock at GATEWAY_LOCK_DIR is defense in depth for Docker Compose.
• GATEWAY_SESSION_IDLE_MINUTES controls how long an inactive session holds its place in the runner’s per-session ordering (default 1440).
• GATEWAY_TICK_INTERVAL is the cron scheduler granularity. Sixty seconds is a good default. Dropping below 30 raises load without gaining much resolution.
• Heartbeat keys tesslate:gateway:active:{config_id} expire every 120 seconds. Use them in Grafana for liveness.
• The gateway_delivery_stream Redis Stream is capped at GATEWAY_DELIVERY_MAXLEN entries (default 10000) so crashes never lose pending deliveries forever.

​

Where to next