How to build a channel

rustup target add wasm32-wasip2

cargo install wasm-tools

channels-src/
└── my-channel/
    ├── Cargo.toml
    ├── src/
    │   └── lib.rs
    └── my-channel.capabilities.json

~/.ironclaw/channels/
├── my-channel.wasm
└── my-channel.capabilities.json

// Generate bindings from the WIT file
wit_bindgen::generate!({
    world: "sandboxed-channel",
    path: "../../wit/channel.wit",  // Adjust path as needed
});

use serde::{Deserialize, Serialize};

// Re-export generated types
use exports::near::agent::channel::{
    AgentResponse, ChannelConfig, Guest, HttpEndpointConfig, IncomingHttpRequest,
    OutgoingHttpResponse, PollConfig,
};
use near::agent::channel_host::{self, EmittedMessage};

struct MyChannel;

impl Guest for MyChannel {
    /// Called once when the channel starts.
    /// Returns configuration for webhooks and polling.
    fn on_start(config_json: String) -> Result<ChannelConfig, String> {
        // Parse config from capabilities file
        let config: MyConfig = serde_json::from_str(&config_json)
            .unwrap_or_default();

        Ok(ChannelConfig {
            display_name: "My Channel".to_string(),
            http_endpoints: vec![
                HttpEndpointConfig {
                    path: "/webhook/my-channel".to_string(),
                    methods: vec!["POST".to_string()],
                    require_secret: true,  // Validate webhook secret
                },
            ],
            poll: None,  // Or Some(PollConfig { interval_ms, enabled })
        })
    }

    /// Handle incoming HTTP requests (webhooks).
    fn on_http_request(req: IncomingHttpRequest) -> OutgoingHttpResponse {
        // Parse webhook payload
        // Emit messages to agent
        // Return response to webhook caller
    }

    /// Called periodically if polling is enabled.
    fn on_poll() {
        // Fetch new messages from API
        // Emit any new messages
    }

    /// Send a response back to the messaging platform.
    fn on_respond(response: AgentResponse) -> Result<(), String> {
        // Parse metadata to get routing info
        // Call platform API to send message
    }

    /// Send a proactive message without a prior inbound event.
    fn on_broadcast(user_id: String, response: AgentResponse) -> Result<(), String> {
      // Send a message to a known user or chat ID.
    }

    /// React to agent status changes such as thinking or tool activity.
    fn on_status(update: StatusUpdate) {
      // Show typing indicators or status messages when useful.
    }

    /// Called when channel is shutting down.
    fn on_shutdown() {
        channel_host::log(channel_host::LogLevel::Info, "Channel shutting down");
    }
}

// Export the channel implementation
export!(MyChannel);

// When receiving a message, store routing info:
#[derive(Debug, Serialize, Deserialize)]
struct MyMessageMetadata {
    chat_id: String,           // Where to send response
    sender_id: String,         // Who sent it (becomes recipient)
    original_message_id: String,
}

// In on_http_request or on_poll:
let metadata = MyMessageMetadata {
    chat_id: message.chat.id.clone(),
    sender_id: message.from.clone(),  // CRITICAL: Store sender!
    original_message_id: message.id.clone(),
};

channel_host::emit_message(&EmittedMessage {
    user_id: message.from.clone(),
    user_name: Some(name),
    content: text,
    thread_id: None,
    metadata_json: serde_json::to_string(&metadata).unwrap_or_default(),
});

// In on_respond, use the ORIGINAL message's metadata:
fn on_respond(response: AgentResponse) -> Result<(), String> {
    let metadata: MyMessageMetadata = serde_json::from_str(&response.metadata_json)?;

    // sender_id becomes the recipient!
    send_message(metadata.chat_id, metadata.sender_id, response.content);
}

// The host replaces {TELEGRAM_BOT_TOKEN} with the actual token
let url = "https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/sendMessage";
channel_host::http_request("POST", url, &headers_json, Some(&body));

let headers = serde_json::json!({
    "Content-Type": "application/json",
    "Authorization": "Bearer {WHATSAPP_ACCESS_TOKEN}"
});
channel_host::http_request("POST", &url, &headers.to_string(), Some(&body));

cd channels-src/my-channel
cargo build --release --target wasm32-wasip2

# Convert the raw wasm module into a component and strip it
wasm-tools component new target/wasm32-wasip2/release/my_channel.wasm -o my-channel.wasm \
  2>/dev/null || cp target/wasm32-wasip2/release/my_channel.wasm my-channel.wasm
wasm-tools strip my-channel.wasm -o my-channel.wasm

mkdir -p ~/.ironclaw/channels
cp my-channel.wasm ~/.ironclaw/channels/my-channel.wasm
cp my-channel.capabilities.json ~/.ironclaw/channels/

rustup target add wasm32-wasip2
./channels-src/telegram/build.sh

mkdir -p ~/.ironclaw/channels
cp channels-src/telegram/telegram.wasm channels-src/telegram/telegram.capabilities.json ~/.ironclaw/channels/

channel_host::log(channel_host::LogLevel::Info, "message");

let _now = channel_host::now_millis();

let _ = channel_host::workspace_write("state/offset", "12345");
let _ = channel_host::workspace_read("state/offset");

let _response = channel_host::http_request("POST", &url, &headers, Some(&body));

channel_host::emit_message(&EmittedMessage { /* ... */ });

let has_secret = channel_host::secret_exists("telegram_bot_token");

let _ = channel_host::store_attachment_data("attachment-id", &bytes);

let _ = channel_host::pairing_upsert_request("telegram", "123456", "{}")?;
let _ = channel_host::pairing_resolve_identity("telegram", "123456")?;
let _ = channel_host::pairing_read_allow_from("telegram")?;

const OFFSET_PATH: &str = "state/last_offset";

fn on_poll() {
    let offset = channel_host::workspace_read(OFFSET_PATH)
        .and_then(|s| s.parse::<i64>().ok())
        .unwrap_or(0);

    let updates = fetch_updates(offset);
    let mut new_offset = offset;

    for update in updates {
        if update.id >= new_offset {
            new_offset = update.id + 1;
        }
        emit_message(update);
    }

    if new_offset != offset {
        let _ = channel_host::workspace_write(OFFSET_PATH, &new_offset.to_string());
    }
}

if !payload.statuses.is_empty() && payload.messages.is_empty() {
    return;
}

if sender.is_bot {
    return;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_parse_webhook() {
        let json = r#"{\"messages\":[]}"#;
        let v: serde_json::Value = serde_json::from_str(json).expect("valid json in test");
        assert!(v.get("messages").is_some());
    }
}

let preview: String = content.chars().take(50).collect();