Caspian SDK: One Handler for Slack, Discord, Telegram, Email and WhatsApp
Agent communication SDK. The open-source agent communication layer for AI agents — email, WhatsApp, Slack, Discord, Telegram, SMS. Python & TypeScript.
At a glance
- What is it?
- Caspian is an AGPL-licensed Python and TypeScript SDK that turns per-channel adapter code into a single on_message handler. The hosted gateway path and the self-host path are genuinely different deployment models, and the licence is the first thing to check before you install it.
- Who is it for?
- Caspian fits teams whose agent already works and whose remaining problem is channel plumbing: you want one on_message handler instead of separate slack_bolt, discord.py and python-telegram-bot integrations. It does not fit you if AGPL-3.0 is incompatible with how you ship, or if your agent only talks to other agents over A2A or ACP.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 22 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The adapter layer Caspian is trying to delete
The problem Caspian names is narrow and concrete. An agent that needs to reach people on Slack, Discord, Telegram and email normally starts with four client libraries, four auth flows, four payload shapes, four retry paths and four dedup caches before the agent has said anything. The README puts that at roughly 1,500 lines of code in its side-by-side comparison, and claims the largest open source agent frameworks each built 25 or more channel adapters while still spending 8 to 15 percent of their issue trackers on channel plumbing. Those numbers come from the project's own marketing copy, not from an independent measurement, so treat them as the author's framing rather than a finding.
The audience is anyone shipping an agent that has to hold a conversation with a human on a messaging platform. The README draws the line explicitly: most agent communication work is agent-to-human, not agent-to-agent. Protocols like A2A and ACP connect agents to each other. Caspian connects an agent to the people it works for. If your agent only ever exchanges messages with other agents, this SDK is aimed at a different problem and you should look at the agent-to-agent protocols instead.
channels.add() and the single on_message handler
The public surface is a Caspian object with a channels collection. Each platform is registered with one call: cx.channels.add("telegram", bot_token="...") on the hosted path, or cx.channels.add("telegram", via="self-host", bot_token="...", webhook_url="https://your.server/telegram") on the self-host path. Handlers are then attached with a decorator that takes a rules dictionary. The README shows {"overlap": "queue", "ack": "On it..."} for the hosted example and {"channel": "telegram"} for the self-host example, which suggests the rules object can filter by channel and control what happens when a second message arrives while the first is still being handled.
The handler signature is uniform across channels: def handle(thread, msg, ctx). The thread object carries the reply path, so thread.post(...) is how the agent answers regardless of whether the underlying transport is a Telegram bot API call, a Slack message, or an email reply. That uniformity is the whole product. The README's claim that "Adding a channel is one more channels.add() call, handler rules stay the same" is the design contract, and the side-by-side table is there to make the contrast concrete.
What the supplied material does not show is the internals: how a thread is keyed across channels, how deduplication is implemented, or what the ctx object contains. The README mentions "threading, webhook verification, and platform quirks handled" without describing the mechanism. The CLI hints at the thread key format, since caspian threads tail telegram:123:456 takes a channel-prefixed identifier, but that is an inference from a command example rather than a documented schema.
Hosted polling versus self-host webhooks
There are two deployment models and they behave differently enough that the choice matters. On the hosted path, Caspian's gateway owns inbound traffic and your process polls for events. The README's own comment on cx.run() says "polls the gateway, Ctrl+C to stop." That is a pull loop. It means your process does not need a public URL, but it also means delivery depends on your process being up and on the polling interval, and the material does not document what happens to events while the process is stopped.
On the self-host path, your process owns the tokens and there is no gateway polling. You supply a webhook_url and call cx.handle("telegram", request_body, request_headers) from your own HTTP route. Discord and Slack can alternatively receive over a held-open socket with cx.listen("discord"), which the README says requires the optional extra caspian-sdk[discord]. So there are really three inbound shapes: gateway polling, HTTP webhook, and socket. The README does not state which channels support which shape, and it does not say whether the hosted gateway is available for every channel listed in the project description (email, WhatsApp, Slack, Discord, Telegram, SMS, iMessage, X, Linear). That gap is worth resolving before you design around it.
One asymmetry is documented: Telegram is described as "BYO BotFather token" on the hosted path, meaning you create the bot yourself and hand Caspian the token. Whether the other channels work the same way is not stated in the material provided.
Installing it and the CLI's actual commands
Installation is two lines depending on language: pip install caspian-sdk for Python 3.10 or newer, npm install caspian-sdk for TypeScript on Node 18 or newer, with Bun also listed. You need an API key from dashboard.trycaspianai.com, and the Python example notes it can also come from CASPIAN_API_KEY in a .env file.
The rewrite CLI lives in packages/cli and is written in TypeScript with Bun. The README describes it as "a thin client of the same SDK surface," with catalog discovering and call invoking. The commands shown are caspian init, which mints a key into ~/.caspian/.env or the project .env; caspian channels add telegram; caspian channels add telegram --via self-host --bot-token "$TG" --webhook-url https://myapp.example.com/hook; caspian call post --thread telegram:123:456 --text "shipping now"; and caspian threads tail telegram:123:456. The full command map is in packages/cli/README.md, which is not included in the material here.
There is also an agent-facing path: the README suggests pasting a prompt into a coding agent that tells it to read https://api.trycaspianai.com/SKILL.md and follow it end to end. That is a live document served from the API host, so its contents are not fixed by the repository and cannot be reviewed from the source alone. If you use that path, the guide is the thing you are trusting.
The 0.6.x to 1.0 break and the AGPL-3.0 licence
The README states that version 1.0 is a full rewrite and that the public surface is Caspian, not the legacy CommClient from 0.6.x, with a migration section further down the document. The only release listed in the material is v0.1.2, dated 2026-07-21 and labelled "open core launch." That is a discrepancy worth noting: the README talks about 1.0 and a 0.6.x migration path, while the release list shows a 0.1.2 open core launch. The material does not reconcile these, so the version you actually get from PyPI or npm is something to check directly rather than assume.
The licence is AGPL-3.0 per the repository metadata. The README's own badge points at a LICENSE file labelled Apache-2.0. These two do not agree, and the difference is significant: AGPL-3.0 imposes network-copyleft obligations that Apache-2.0 does not. If you plan to run a modified Caspian as part of a network service, that distinction determines what you owe downstream users. I am not giving legal advice here; the point is that the repository metadata and the README badge disagree, and you should read the LICENSE file in the repository root before you build anything on top of it. The project also describes itself as "open core," which implies some functionality is not in this repository, though the material does not say which parts.
Where a thin wrapper is the wrong tool
The honest limitation is that Caspian is an abstraction over other people's APIs, and abstractions over messaging platforms leak. The README claims platform quirks are handled, but it does not enumerate them. If your product depends on a platform feature that Caspian has not modelled, such as a specific Slack block type, a Discord interaction component, or email attachment handling, you may end up reaching past the SDK anyway, and then you have both the SDK and the raw client in your dependency tree.
The hosted path adds a second consideration: your inbound messages flow through Caspian's gateway. For some teams that is fine. For teams with data residency requirements, or for anyone who does not want message content transiting a third-party service, the self-host path is the only viable option, and it requires a public webhook URL plus your own token management. The README's self-host example shows the webhook_url being passed at channel registration, so you need that endpoint reachable before the channel is useful.
The third case is scale of a specific kind. If you only ever need one channel, the abstraction earns less than it costs. A single slack_bolt app is not 1,500 lines. Caspian pays off when the second and third channels arrive.
What you would use instead, and how it differs
The most direct alternative is not another SDK but the platform libraries themselves: slack_bolt, discord.py, python-telegram-bot, and smtplib or imaplib for email, which the README names in its "without Caspian" column. The difference in approach is not quality, it is where the abstraction sits. Those libraries are thin, well-documented bindings to one platform each, and they expose that platform's full surface. Caspian is a normalising layer that trades platform-specific depth for a uniform handler signature. If your agent needs deep access to one platform's features, the platform library wins. If it needs shallow access to five platforms, Caspian's trade is the right one.
Two other categories are worth naming because the README draws the boundary itself. Agent-to-agent protocols like A2A and ACP solve a different problem: they connect agents to each other, not agents to people. Adopting Caspian will not help you there. And for the specific case of an agent that lives entirely inside a coding environment, the README's own answer is not the SDK but the SKILL.md guide, which is a prompt-driven integration rather than a library dependency.
Maintenance cost and what to verify before adopting
The maintenance story has three moving parts. First, the SDK is a wrapper around platform APIs that change, so its release cadence is tied to theirs, not to yours. Second, the CLI is a separate package in packages/cli written in TypeScript and Bun, so a Python-only team takes on a Bun toolchain if they want the CLI rather than the library. Third, there is a hosted service behind the default path, which means an account, an API key, and a dependency on an external gateway for the polling model.
The version situation is the thing to check first. The README describes a 1.0 rewrite and a 0.6.x migration, while the release list shows v0.1.2 as an open core launch. Confirm which version pip and npm resolve to, then read the migration section if you are coming from 0.6.x, because the public class name changed from CommClient to Caspian. After that, read the LICENSE file in the repository root to settle the AGPL-3.0 versus Apache-2.0 question, since the metadata and the badge disagree. Finally, check packages/cli/README.md for the full command map, because the five commands quoted above are a sample and not the whole surface.
Editorial conclusion
Caspian fits teams whose agent already works and whose remaining problem is channel plumbing: you want one on_message handler instead of separate slack_bolt, discord.py and python-telegram-bot integrations. It does not fit you if AGPL-3.0 is incompatible with how you ship, or if your agent only talks to other agents over A2A or ACP. Before adopting, verify three things against the repository rather than the README: which channels actually support via="self-host", whether Telegram is still the only channel documented as bring-your-own BotFather token, and how the hosted gateway's polling loop behaves when your process is down, because cx.run() is a poll loop and not a webhook receiver.
Community notes