@e9n/pi-channels

Two-way channel extension for pi — route messages between agents and Telegram, Slack, webhooks, or custom adapters.

Features

• Telegram adapter — bidirectional via Bot API; polling, voice/audio transcription, allowedChatIds filtering
• Slack adapter — bidirectional via Socket Mode + Web API
• Webhook adapter — outgoing HTTP POST to any URL
• Chat bridge — incoming messages are routed to the agent as prompts; responses sent back automatically; persistent (RPC) or stateless mode
• Event API — channel:send, channel:receive, channel:register for inter-extension messaging
• Custom adapters — register at runtime via channel:register event

Settings

Add to ~/.pi/agent/settings.json or .pi/settings.json:

{
  "pi-channels": {
    "adapters": {
      "telegram": {
        "type": "telegram",
        "botToken": "your-telegram-bot-token",
        "polling": true
      },
      "alerts": {
        "type": "webhook",
        "headers": { "Authorization": "Bearer your-webhook-secret" }
      }
    },
    "routes": {
      "ops": { "adapter": "telegram", "recipient": "-100987654321" }
    },
    "bridge": {
      "enabled": false
    }
  }
}

Secrets:

• Set secret values (tokens, keys) directly in settings.json
• Project settings override global ones

Adapter types

| Type | Direction | Key config | |------|-----------|------------| | telegram | bidirectional | botToken, polling, parseMode, allowedChatIds, transcription | | slack | bidirectional | botToken, appToken | | webhook | outgoing | method, contentType, payloadMode, headers |

Webhook migration note: custom Content-Type should be set via contentType. If both contentType and headers["Content-Type"] are provided, contentType wins.

Transcription (Voice & Audio)

The Telegram adapter supports transcribing voice messages and audio files. Add to the telegram adapter config:

{
  "telegram": {
    "type": "telegram",
    "botToken": "your-telegram-bot-token",
    "transcription": {
      "enabled": true,
      "provider": "openai"
    }
  }
}

Providers:

| Provider | Requirements | Notes | |----------|--------------|-------| | apple | macOS only | Free, offline, uses SFSpeechRecognizer. No API key needed. | | openai | OpenAI API key | Automatically uses pi's built-in OpenAI authentication if you've run /login openai. No explicit apiKey needed! Override with apiKey in config if you want to use a separate key. | | elevenlabs | ElevenLabs API key | Requires apiKey set directly in config. |

Transcription options:

• enabled — Enable transcription (default: false)
• provider — "apple", "openai", or "elevenlabs" (required)
• apiKey — For OpenAI: optional (uses pi's auth). For ElevenLabs: required (set directly in settings.json).
• model — Model name, e.g. "whisper-1" (OpenAI), "scribe_v1" (ElevenLabs)
• language — ISO 639-1 code, e.g. "en", "no" (optional)

Bridge settings

| Key | Default | Description | |-----|---------|-------------| | enabled | false | Enable on startup (also: --chat-bridge flag or /chat-bridge on) | | sessionMode | "persistent" | "persistent" = RPC subprocess with conversation memory; "stateless" = isolated per message | | sessionRules | [] | Per-sender mode overrides: [{ "match": "telegram:-100*", "mode": "stateless" }] | | idleTimeoutMinutes | 30 | Kill idle persistent sessions after N minutes | | maxQueuePerSender | 5 | Max queued messages per sender | | timeoutMs | 300000 | Per-prompt timeout (ms) | | maxConcurrent | 2 | Max senders processed in parallel | | typingIndicators | true | Send typing indicators while processing |

Tool: notify

| Action | Required params | Description | |--------|----------------|-------------| | send | adapter, (text or json) | Send a message via an adapter name or route alias | | list | — | Show configured adapters and routes | | test | adapter | Send a test ping |

For webhook sends, notify supports:

• payloadMode: "envelope" (default) or "raw"
• json: raw request body (auto-enables raw mode if provided; required for body-carrying raw methods)
• method: HTTP method override for raw mode (GET, HEAD, POST, PUT, PATCH, DELETE)
• contentType: Content-Type override for raw mode (applies only when a request body is sent)
• GET/HEAD raw requests are bodyless (do not provide json)

Commands

| Command | Description | |---------|-------------| | /chat-bridge | Show bridge status (sessions, queue, active prompts) | | /chat-bridge on | Start the chat bridge | | /chat-bridge off | Stop the chat bridge |

Install

pi install npm:@e9n/pi-channels

License

MIT