Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dallay/corvus/llms.txt

Use this file to discover all available pages before exploring further.

Example: Telegram Channel

A complete example of integrating Telegram with Corvus. Source: examples/custom_channel.rs

Full Implementation

//! Example: Implementing a custom Channel for Corvus

use anyhow::Result;
use async_trait::async_trait;
use tokio::sync::mpsc;

/// Mirrors src/channels/traits.rs
#[derive(Debug, Clone)]
pub struct ChannelMessage {
    pub id: String,
    pub sender: String,
    pub content: String,
    pub channel: String,
    pub timestamp: u64,
}

#[async_trait]
pub trait Channel: Send + Sync {
    fn name(&self) -> &str;
    async fn send(&self, message: &str, recipient: &str) -> Result<()>;
    async fn listen(&self, tx: mpsc::Sender<ChannelMessage>) -> Result<()>;
    async fn health_check(&self) -> bool;
}

/// Example: Telegram channel via Bot API
pub struct TelegramChannel {
    bot_token: String,
    allowed_users: Vec<String>,
    client: reqwest::Client,
}

impl TelegramChannel {
    pub fn new(bot_token: &str, allowed_users: Vec<String>) -> Self {
        Self {
            bot_token: bot_token.to_string(),
            allowed_users,
            client: reqwest::Client::new(),
        }
    }

    fn api_url(&self, method: &str) -> String {
        format!("https://api.telegram.org/bot{}/{method}", self.bot_token)
    }
}

#[async_trait]
impl Channel for TelegramChannel {
    fn name(&self) -> &str {
        "telegram"
    }

    async fn send(&self, message: &str, chat_id: &str) -> Result<()> {
        self.client
            .post(self.api_url("sendMessage"))
            .json(&serde_json::json!({
                "chat_id": chat_id,
                "text": message,
                "parse_mode": "Markdown",
            }))
            .send()
            .await?;
        Ok(())
    }

    async fn listen(&self, tx: mpsc::Sender<ChannelMessage>) -> Result<()> {
        let mut offset: i64 = 0;

        loop {
            let resp = self
                .client
                .get(self.api_url("getUpdates"))
                .query(&[("offset", offset.to_string()), ("timeout", "30".into())])
                .send()
                .await?
                .json::<serde_json::Value>()
                .await?;

            if let Some(updates) = resp["result"].as_array() {
                for update in updates {
                    if let Some(msg) = update.get("message") {
                        let sender = msg["from"]["username"]
                            .as_str()
                            .unwrap_or("unknown")
                            .to_string();

                        if !self.allowed_users.is_empty() && !self.allowed_users.contains(&sender) {
                            continue;
                        }

                        let channel_msg = ChannelMessage {
                            id: msg["message_id"].to_string(),
                            sender,
                            content: msg["text"].as_str().unwrap_or("").to_string(),
                            channel: "telegram".into(),
                            timestamp: msg["date"].as_u64().unwrap_or(0),
                        };

                        if tx.send(channel_msg).await.is_err() {
                            return Ok(());
                        }
                    }
                    offset = update["update_id"].as_i64().unwrap_or(offset) + 1;
                }
            }
        }
    }

    async fn health_check(&self) -> bool {
        self.client
            .get(self.api_url("getMe"))
            .send()
            .await
            .map(|r| r.status().is_success())
            .unwrap_or(false)
    }
}

Setup Telegram Bot

1. Create Bot

  1. Open Telegram and search for @BotFather
  2. Send /newbot
  3. Follow prompts to choose name and username
  4. Save the bot token (e.g., 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

2. Get Your User ID

  1. Start a chat with your bot
  2. Send any message
  3. Visit https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
  4. Find your user ID in message.from.id

Integration Steps

1. Add to Corvus

Already implemented in src/channels/telegram.rs

2. Configure

# ~/.corvus/config.toml
[channels_config.telegram]
bot_token = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
allowed_users = ["alice", "bob"]  # or user IDs: ["123456789"]

3. Start Channel

corvus channel start
Or in daemon mode:
corvus daemon

4. Chat

Send a message to your bot on Telegram:
You: Hello, Corvus!
Bot: Hello! How can I help you today?

API Endpoints

getUpdates (Long Polling)

curl "https://api.telegram.org/bot<TOKEN>/getUpdates?offset=0&timeout=30"
Response:
{
  "ok": true,
  "result": [
    {
      "update_id": 12345,
      "message": {
        "message_id": 1,
        "from": {
          "id": 123456789,
          "username": "alice"
        },
        "chat": {
          "id": 123456789
        },
        "date": 1709654321,
        "text": "Hello, bot!"
      }
    }
  ]
}

sendMessage

curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "text": "Hello from Corvus!",
    "parse_mode": "Markdown"
  }'

Build docs developers (and LLMs) love