How to build a channel

rustup target add wasm32-wasip2

cargo install wasm-tools

my-channel/
├── Cargo.toml
├── src/
│   └── lib.rs
├── wasm/
│   └── my-channel.wasm         # built artifact
└── manifest.toml

// Generate bindings from the WIT file
wit_bindgen::generate!({
    world: "sandboxed-channel",
    // Relative to the guest crate, e.g. crates/extensions/packages/<name>/wasm-src.
    path: "../../../../ironclaw_wasm/wit/channel.wit",
});

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 config_json
        let config: MyConfig = serde_json::from_str(&config_json)
            .unwrap_or_default();

        // The manifest [channel.ingress] controls how the host routes inbound
        // webhooks. The ChannelConfig here configures runtime registration with
        // the platform API (e.g., registering a webhook URL with Telegram).
        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,
                },
            ],
            poll: None,
        })
    }

    /// 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(),
    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(),
});

// On respond, the stored sender_id becomes the recipient:
fn on_respond(response: AgentResponse) -> Result<(), String> {
    let metadata: MyMessageMetadata = serde_json::from_str(&response.metadata_json)?;
    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), None);

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), None);

my-channel/
├── Cargo.toml
├── src/
│   └── lib.rs
├── wasm/
│   └── my_channel.wasm
└── manifest.toml

cd 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 wasm/my_channel.wasm \
  2>/dev/null || cp target/wasm32-wasip2/release/my_channel.wasm wasm/my_channel.wasm
wasm-tools strip wasm/my_channel.wasm -o wasm/my_channel.wasm

// Logging and time
channel_host::log(channel_host::LogLevel::Info, "message");
let _now = channel_host::now_millis();

// Durable per-channel workspace key-value storage
let _ = channel_host::workspace_write("state/offset", "12345");
let _ = channel_host::workspace_read("state/offset");

// Make outbound HTTP requests to the messaging platform API
let _response = channel_host::http_request("POST", &url, &headers, Some(&body), None);

// Emit an inbound message to the agent
channel_host::emit_message(&EmittedMessage { /* ... */ });

// Check whether a deployment secret exists
let has_secret = channel_host::secret_exists("telegram_bot_token");

// Store binary attachment data received during a webhook or poll callback
let _ = channel_host::store_attachment_data("attachment-id", &bytes);

// Pairing: create a code for a user to prove ownership of a platform account
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_metadata_round_trip() {
        let metadata = MyMessageMetadata {
            chat_id: "123".into(),
            sender_id: "user_456".into(),
            original_message_id: "msg_789".into(),
        };
        let serialized = serde_json::to_string(&metadata).expect("serialize");
        let deserialized: MyMessageMetadata =
            serde_json::from_str(&serialized).expect("deserialize");
        assert_eq!(deserialized.chat_id, "123");
        assert_eq!(deserialized.sender_id, "user_456");
    }

    #[test]
    fn test_rejects_missing_fields() {
        let json = r#"{"chat_id":"123"}"#;
        let result: Result<MyMessageMetadata, _> = serde_json::from_str(json);
        assert!(result.is_err());
    }
}

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