channel-bridge

Purpose

This skill facilitates cross-channel messaging routing between Signal, Telegram, and Discord. It handles message formatting (e.g., converting Markdown to plain text), differentiates between simple message sends and session-based transmissions, supports broadcasting to multiple channels, and manages reactions across platforms.

When to Use

Use this skill when integrating disparate messaging apps, such as forwarding alerts from Signal to Discord for team notifications, broadcasting updates across Telegram and Signal for distributed teams, or routing user reactions (e.g., likes) from Discord to Signal for unified feedback tracking. Apply it in scenarios requiring real-time cross-platform communication without manual intervention.

Key Capabilities

Message Formatting: Automatically converts content formats; e.g., use Discord's Markdown syntax and strip it for Signal via the format flag.
Routing Options: Distinguishes between message (simple send) and sessions_send (persistent session-based routing) using API parameters like type: "message" or type: "sessions_send".
Broadcasting: Sends messages to multiple channels simultaneously; e.g., specify targets with a JSON array like ["signal:group1", "discord:channel2"].
Reactions Handling: Propagates reactions (e.g., emojis) across platforms; e.g., map Discord reactions to Signal reactions via a predefined config mapping.
Error Resilience: Includes retry logic for failed transmissions, with configurable thresholds.

Usage Patterns

Always initialize with authentication via environment variables (e.g., $SIGNAL_API_KEY, $TELEGRAM_BOT_TOKEN). For CLI, pipe inputs directly; for API, use HTTP requests with JSON payloads. Pattern 1: Single-channel routing—send a message from one platform to another. Pattern 2: Broadcast—specify multiple targets in a single command. Pattern 3: Reaction handling—monitor and forward reactions using webhooks. Validate inputs first (e.g., check message length limits per platform: Signal=4096 chars, Discord=2000 chars). For sessions, establish a persistent connection by including --session-id in commands.

Common Commands/API

Use the CLI tool or REST API for interactions. CLI commands require the channel-bridge binary; API endpoints are under /api/v1/.

CLI Command for Sending a Message:
```
channel-bridge send --from signal --to telegram --message "Hello team" --format markdown
```
This routes a formatted message; add --broadcast for multi-target, e.g., --to "discord:channel1,signal:group2".
API Endpoint for Sessions Send: POST /api/v1/sessions_send Body: {"from": "discord", "to": ["telegram"], "content": "Update", "type": "sessions_send", "session_id": "abc123"} Include headers: Authorization: Bearer $DISCORD_API_KEY.
CLI for Broadcasting with Reactions:
```
channel-bridge broadcast --from tg --to "signal,discord" --message "Alert" --reactions true
```
This enables reaction forwarding; reactions are mapped via a config file, e.g., JSON: {"👍": "thumbsup"}.
API for Reaction Handling: POST /api/v1/reactions Body: {"source": "discord", "reaction": "👍", "targets": ["signal"]} Use this to propagate reactions; requires prior webhook setup.

Config format: Use a YAML file for platform settings, e.g.:

signal:
  api_key: $SIGNAL_API_KEY
  default_group: group1
telegram:
  bot_token: $TELEGRAM_BOT_TOKEN

Integration Notes

Integrate by setting environment variables for authentication: e.g., export $SIGNAL_API_KEY for Signal access. For API integrations, use libraries like requests in Python:

import requests
response = requests.post('http://localhost:8080/api/v1/send', json={'from': 'tg', 'to': 'discord', 'message': 'Test'}, headers={'Authorization': f'Bearer {os.environ["TELEGRAM_BOT_TOKEN"]}'})

Ensure your app handles platform-specific requirements, like Discord webhooks for real-time updates. For multi-service setups, chain this skill with other distributed-comms tools via shared session IDs. Test integrations in a sandbox environment first.

Error Handling

Check response codes from commands/API; e.g., CLI returns non-zero exit codes for failures. Common errors: 401 for auth issues (verify $SERVICE_API_KEY), 400 for invalid formats (e.g., mismatched message types). Implement retries with exponential backoff: in code, use a loop like:

for attempt in range(3):
    try:
        response = requests.post(...)  # API call
        break
    except Exception as e:
        if attempt == 2:
            log_error(e)

Log errors with details (e.g., "Failed broadcast: Signal timeout") and use the --debug flag in CLI for verbose output. For reactions, handle platform mismatches by skipping unsupported types.

Usage Examples

Route a Message from Telegram to Signal and Discord: Use this for alerts: channel-bridge send --from tg --to "signal:alerts, discord:general" --message "System down" --format plain. This broadcasts the message, formats it appropriately, and logs the transmission ID for tracking.
Handle Reactions in a Broadcast Scenario: For feedback loops: channel-bridge broadcast --from discord --to "tg:group1" --message "Vote now" --reactions true. If a user reacts with 👍 on Discord, it forwards as a custom emoji to Telegram, using the reaction mapping from your config.

Graph Relationships

Cluster Relation: Belongs to "distributed-comms" cluster, enabling interoperability with other comms skills.
Service Links: Interacts with "signal" for messaging, "telegram" for bot operations, and "discord" for webhook events.
Tag Connections: Associated with tags ["signal", "telegram", "discord", "messaging", "channel"], linking to related skills in the graph.