Caspian
Caspian is an agent communication SDK that lets your agent send and receive messages across Slack, Discord, Telegram, email, WhatsApp, X, and more through a single unified interface. It solves the problem of building and maintaining separate channel adapters for each platform, letting you focus on your agent's logic instead of plumbing. It is for developers building AI agents that need to interact with humans on the channels they already use.
✨ Key features
- Declarative rules with @cx.on_message filters for channel, command, chat kind, overlap.
- Hosted or self-host mode with same handler code.
- Webhook verification for Slack, Meta, Telegram, X, and email.
- Offline fakes for every channel with 650+ tests.
- Rich messaging: typing, streaming, media, blocks, buttons, reactions.
- Model tools from the same surface via cx.tools(thread).
🎯 Use cases
- Customer support agents that answer on email, Slack, Instagram DM, etc.
- Sales and lead follow-up on the channel the lead used.
- Personal assistants with one identity across email, Telegram, and Slack.
- Community bots that work in Discord, Slack, and DMs.
- Integrating with OpenClaw or OpenCode agents.
📦 Installation
🧰 Requirements: Python 3.10+ or Node 18+ / Bun, API key from dashboard.trycaspianai.com, and platform-specific tokens for self-host.
pip install caspian-sdk # Python 3.10+
npm install caspian-sdk # TypeScript / Node 18+ / Bun
🚀 Usage
from caspian import Caspian
cx = Caspian(api_key="...") # or CASPIAN_API_KEY in .env
cx.channels.add("telegram", bot_token="...") # Telegram is BYO BotFather token
@cx.on_message({"overlap": "queue", "ack": "On it…"})
def handle(thread, msg, ctx):
thread.post(f"You said: {msg.text}")
cx.run() # polls the gateway — Ctrl+C to stop
⚠️ Good to know
X is not free: DM send/receive needs a paid X API subscription; GSM modem SMS requires your own modem and SIM with carrier compliance.
❓ FAQ
What is the difference between hosted and self-host mode?
Hosted mode uses the Caspian gateway for inbound events and your process polls for messages. Self-host mode runs adapters in your process with your own platform tokens and webhooks/sockets.
Can I use the same handler code for multiple channels?
Yes, you add channels with cx.channels.add() and your @cx.on_message rules apply to all of them.
How do I handle webhook verification?
Caspian automatically verifies webhooks for Slack, Meta, Telegram, X, and signed email webhooks, rejecting mismatches.
Is there a CLI available?
Yes, there is a CLI in packages/cli that supports commands like init, channels add, call, and threads tail.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.