Quickstart

Install the SDK, get a key, and reply to a real message, in about two minutes. This walks through email, which needs no signup and no tokens.

1. Install the SDK

pip install caspian-sdk

npm install caspian-sdk

Python needs 3.12+; the JS package needs Node 18+ and ships full TypeScript types.

2. Get an API key

Free channels (email, Telegram, Discord, Slack, SMS with your own number) need no signup. Mint an instant key:

curl -s -X POST https://api.trycaspianai.com/v1/projects/sandbox \
  -H 'Content-Type: application/json' -d '{"name":"my-agent"}'

You get back { "project_id": "...", "api_key": "comm_sandbox_..." }. Save it to a .env file next to your code. The SDK reads it automatically:

COMM_API_KEY=comm_sandbox_xxxxxxxx
COMM_BASE_URL=https://api.trycaspianai.com

3. Connect a channel and write your handler

The handler is the same for every channel. Here it answers email:

from caspian_sdk import CommClient

client = CommClient()                      # reads COMM_API_KEY / COMM_BASE_URL

inbox = client.connect_email()             # a real @trycaspianai.com address
print("Agent address:", inbox["address"])

@client.on_message
def handle(message):
    # message.text, message.sender, message.conversation_id, same on every channel
    message.reply(f"Thanks! You said: {message.text}")

client.listen()                            # blocks, dispatching messages forever

import { CommClient } from "caspian-sdk";

const client = new CommClient();                 // reads COMM_API_KEY / COMM_BASE_URL

const inbox = await client.connectEmail();       // a real @trycaspianai.com address
console.log("Agent address:", inbox.address);

client.onMessage(async (message) => {
  // message.text, message.sender, message.conversationId, same on every channel
  await message.reply(`Thanks! You said: ${message.text}`);
});

await client.listen();                           // runs forever; pass an AbortSignal to stop

4. Send it a message

Run your program, then email the address it printed from any mail client. Your handler fires and the reply lands back in the same thread. That's the whole loop: inbound message → your handler → reply, on any channel.

5. Add more channels

Every other channel is one more connect_*() call against the same handler, no new code:

client.connect_telegram(bot_token="123:abc")   # from @BotFather
client.install_slack(display_name="Acme Bot")   # one-click, returns an authorize_url
client.connect_discord(bot_token="...")

await client.connectTelegram({ botToken: "123:abc" });   // from @BotFather
await client.installSlack({ displayName: "Acme Bot" });  // one-click, returns authorize_url
await client.connectDiscord({ botToken: "..." });

See the Channels overview for what each one needs, and Behavior guides to make your agent reply the right way on each platform.