Telegram Native MCP Documentation

Install through the marketplace API

import { installMarketplaceMcp } from '../api/marketplace';

await installMarketplaceMcp({
  offerId: <mcp-id>,
  agentUuid: '<agent-uuid>',
  installMode: 'purchase',
  notes: 'Enable Telegram Native MCP on the primary Telegram agent.'
});

Read installed attachment state

import { listAgentMcps } from '../api/agents';

const attachments = await listAgentMcps(<agent-id>);
const installed = attachments.find((item) => item.offer_slug === 'native-telegram');

if (installed?.status === 'active') {
  console.log('Telegram Native MCP is live on this agent');
}

Execute the AI runtime and read insights

import { apiFetch } from '../api/client';

await apiFetch('/api/mcp/native-telegram/runtime/execute', {
  method: 'POST',
  body: JSON.stringify({
    agent_uuid: '<agent-uuid>',
    intent: 'route_conversation',
    context: {
      platform: 'telegram',
      priority: 'high',
      resource: 'conversation-snapshot',
      conversation_id: '<conversation-id>'
    }
  })
});

const insights = await apiFetch('/api/mcp/native-telegram/runtime/insights');
console.log(insights.summary);

Marketplace mcp record

The catalog object returned by the marketplace mcp APIs.

export interface MarketplaceMcpRecord {
  id: number;
  slug: 'native-telegram';
  name: 'Telegram Native MCP';
  version: string;
  status: 'active' | 'published' | 'beta' | 'deprecated';
  description: string;
  author?: string | null;
  mcp_type: 'social';
  platform: 'telegram';
  capabilities: string[];
  required_permissions: string[];
  documentation_url?: string | null;
  pricing_model?: 'free' | 'one_time' | 'subscription' | 'revenue_share';
  price?: number | null;
  revenue_share_percent?: number | null;
  is_official?: boolean;
  install_count?: number;
  rating?: number;
  review_count?: number;
  created_at?: string;
  updated_at?: string;
}

Agent mcp attachment

The normalized attachment object created after installation.

export interface AgentMcpAttachment {
  id: number;
  agent_id: number;
  offer_id: number;
  offer_name: string;
  offer_slug: string;
  status: string;
  install_mode: 'trial' | 'purchase' | 'queued';
  billing_model: string;
  revenue_share_percent?: number | null;
  upfront_price?: number | null;
  notes?: string | null;
  created_at: string;
  activated_at?: string | null;
}

MCP runtime insight payload

The runtime object used by the AI execution and analytics layers.

export interface McpRuntimeInsight {
  mcp_slug: 'native-telegram';
  platform: 'telegram';
  agent_uuid: string;
  status: 'active' | 'degraded' | 'paused';
  summary: string;
  metrics: {
      reply_rate: 0.81,
      queue_pressure: 22,
      conversations_active: 184
  };
  controls: {
    automation_mode: 'assisted' | 'autonomous' | 'priority';
    access_tier: 'standard' | 'root';
  };
  updated_at: string;
}

MessagingSnapshot

A conversation-level payload for message queue state, routing outcome, and reply performance.

export interface MessagingSnapshot {
  mcp_slug: 'native-telegram';
  platform: 'telegram';
  conversation_id: string;
  queue_state: 'open' | 'pending' | 'escalated' | 'closed';
  assigned_route: 'ai' | 'hybrid' | 'human';
  reply_rate: number;
  queue_pressure: number;
  last_message_at: string;
  updated_at: string;
}