ControlAgentNet.Channels.Telegram 0.1.7

ControlAgentNet.Channels.Telegram

<p align="center"> <img src="https://img.shields.io/github/license/ControlAgentNet/ControlAgentNet.Channels.Telegram" alt="License"> <img src="https://img.shields.io/github/actions/workflow/status/ControlAgentNet/ControlAgentNet.Channels.Telegram/ci.yml?branch=main" alt="CI"> <img src="https://img.shields.io/nuget/v/ControlAgentNet.Channels.Telegram" alt="NuGet Version"> </p>

Telegram bot channel for ControlAgentNet agents.

What This Repository Contains

This repository publishes the ControlAgentNet.Channels.Telegram package.

It adds a Telegram channel to a ControlAgentNet host application. Polling is the default update mode, and webhook delivery can be enabled from configuration.

What It Does

This package connects Telegram bot messages to IAgentOrchestrator and sends agent responses back to Telegram chats.

Use it when you want:

• a Telegram bot interface for your agent
• polling-based operation by default
• webhook operation when the host exposes an HTTP endpoint
• chat allow-listing through authorized chat ids

This repository does not include the base runtime itself. You still need the base packages from ControlAgentNet.Agents.

Installation

dotnet add package ControlAgentNet.Agents
dotnet add package ControlAgentNet.Channels.Telegram

Usage

using Microsoft.AspNetCore.Builder;
using ControlAgentNet.Agents;
using ControlAgentNet.Channels.Telegram;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControlAgentAgent(builder.Configuration, builder.Environment, options =>
{
    options.Id = "telegram-agent";
    options.Name = "Telegram Agent";
    options.Instructions = "You are a helpful assistant.";
})
    .AddTelegramChannel();

var app = builder.Build();

app.MapTelegramWebhook();

await app.RunAsync();

MapTelegramWebhook() is required only when Mode is Webhook. It is safe to leave it mapped while using the default polling mode.

Polling-only worker hosts can use Host.CreateApplicationBuilder(args) and omit MapTelegramWebhook().

Configuration

Minimal Required Configuration

Only BotToken is required to activate the Telegram channel. If BotToken is empty, the hosted service is still registered but stays idle.

{
  "ControlAgentNet": {
    "Channels": {
      "Telegram": {
        "BotToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER"
      }
    }
  }
}

Use environment variables or a secret store in production:

ControlAgentNet__Channels__Telegram__BotToken="YOUR_BOT_TOKEN_FROM_BOTFATHER"

Polling Configuration

Polling is the default transport mode.

{
  "ControlAgentNet": {
    "Channels": {
      "Telegram": {
        "BotToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
        "Mode": "Polling",
        "AuthorizedChatIds": [123456789],
        "PollingIntervalMs": 1000
      }
    }
  }
}

Webhook Configuration

Set Mode to Webhook, expose the mapped endpoint, and configure the public URL that Telegram can reach.

{
  "ControlAgentNet": {
    "Channels": {
      "Telegram": {
        "BotToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
        "Mode": "Webhook",
        "AuthorizedChatIds": [123456789],
        "Webhook": {
          "Url": "https://example.com/controlagentnet/telegram/webhook",
          "Path": "/controlagentnet/telegram/webhook",
          "SecretToken": "YOUR_RANDOM_SECRET",
          "DropPendingUpdates": false,
          "MaxConnections": 40
        }
      }
    }
  }
}

The default endpoint path is /controlagentnet/telegram/webhook. If you change Webhook.Path, keep it aligned with Webhook.Url and call app.MapTelegramWebhook() after building the ASP.NET host.

Azure OpenAI Transcription Configuration

The built-in transcription provider is Azure OpenAI. These settings are required only when using the built-in provider and setting Transcription.Enabled to true.

{
  "ControlAgentNet": {
    "Channels": {
      "Telegram": {
        "BotToken": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
        "AuthorizedChatIds": [123456789],
        "PollingIntervalMs": 1000,
        "Transcription": {
          "Enabled": true,
          "Provider": "AzureOpenAI",
          "Endpoint": "https://YOUR-RESOURCE.openai.azure.com/",
          "ApiKey": "YOUR_AZURE_OPENAI_KEY",
          "Deployment": "whisper",
          "ApiVersion": "2024-06-01",
          "Language": "es"
        }
      }
    }
  }
}

Store bot tokens and API keys in environment variables or secret stores, not in committed config files.

Local Base References

By default this repository restores ControlAgentNet.Core, ControlAgentNet.Runtime, and ControlAgentNet.Agents from NuGet. For local coordinated development against the sibling base repository, pass UseLocalControlAgentNet=true:

dotnet restore ControlAgentNet.Channels.Telegram.slnx /p:UseLocalControlAgentNet=true
dotnet build ControlAgentNet.Channels.Telegram.slnx -c Release /p:UseLocalControlAgentNet=true
dotnet test ControlAgentNet.Channels.Telegram.slnx -c Release --no-build /p:UseLocalControlAgentNet=true

The default base path is ../ControlAgentNet.Agents relative to this repository. Override it when the repos are not siblings:

dotnet build ControlAgentNet.Channels.Telegram.slnx /p:UseLocalControlAgentNet=true /p:ControlAgentNetBasePath=/absolute/path/to/ControlAgentNet.Agents

Do not use UseLocalControlAgentNet=true for package publishing; releases should validate the NuGet dependency graph.

Configuration Options

Required Settings By Scenario

Environment variable examples:

ControlAgentNet__Channels__Telegram__BotToken="YOUR_BOT_TOKEN_FROM_BOTFATHER"
ControlAgentNet__Channels__Telegram__Mode="Webhook"
ControlAgentNet__Channels__Telegram__AuthorizedChatIds__0="123456789"
ControlAgentNet__Channels__Telegram__Webhook__Url="https://example.com/controlagentnet/telegram/webhook"
ControlAgentNet__Channels__Telegram__Webhook__Path="/controlagentnet/telegram/webhook"
ControlAgentNet__Channels__Telegram__Webhook__SecretToken="YOUR_RANDOM_SECRET"
ControlAgentNet__Channels__Telegram__Transcription__Enabled="true"
ControlAgentNet__Channels__Telegram__Transcription__Provider="AzureOpenAI"
ControlAgentNet__Channels__Telegram__Transcription__Endpoint="https://YOUR-RESOURCE.openai.azure.com/"
ControlAgentNet__Channels__Telegram__Transcription__ApiKey="YOUR_AZURE_OPENAI_KEY"
ControlAgentNet__Channels__Telegram__Transcription__Deployment="whisper"
ControlAgentNet__Channels__Telegram__Transcription__ApiVersion="2024-06-01"

Voice Notes

• text messages continue working with no extra configuration
• voice notes are transcribed only when an IAudioTranscriptionService is configured
• Azure OpenAI is the built-in default transcription provider
• custom providers can replace Azure OpenAI through dependency injection
• the agent receives the transcribed text
• if a voice note arrives and transcription is not configured, the bot replies that audio transcription is not available

Custom Transcription

Azure OpenAI is registered as the default IAudioTranscriptionService, but hosts can replace it:

builder.Services.AddControlAgentAgent(builder.Configuration, builder.Environment, options =>
{
    options.Id = "telegram-agent";
    options.Name = "Telegram Agent";
})
    .AddTelegramChannel()
    .AddTelegramTranscription<MyTranscriptionService>();

Custom providers implement:

public sealed class MyTranscriptionService : IAudioTranscriptionService
{
    public bool IsConfigured => true;

    public Task<string?> TranscribeAsync(
        AudioTranscriptionRequest request,
        CancellationToken cancellationToken)
    {
        // Send request.Audio to OpenAI, Whisper local, Foundry, or another provider.
        return Task.FromResult<string?>("transcribed text");
    }
}

You can also pre-register IAudioTranscriptionService before calling AddTelegramChannel(); the channel preserves existing registrations.

When a custom provider is registered, Azure OpenAI settings are not required unless that provider chooses to read them.

Message Contract

Telegram messages are normalized into the shared IncomingMessage contract from ControlAgentNet.Core.

• ChannelId is telegram
• ChannelType is Chat
• ConversationId uses the Telegram chat id and message thread id when present
• UserId uses the Telegram sender id when available
• captions are passed as Text
• audio files, documents, and images are passed as IncomingAttachment
• Telegram ids and platform-specific values are kept in Metadata

Agents should read IncomingMessage and stay independent of Telegram.Bot types.

Build

dotnet restore ControlAgentNet.Channels.Telegram.slnx
dotnet build ControlAgentNet.Channels.Telegram.slnx -c Release
dotnet test ControlAgentNet.Channels.Telegram.slnx -c Release --no-build
dotnet pack ControlAgentNet.Channels.Telegram.slnx -c Release -o artifacts/nuget --no-build

Sample

The repository includes samples/HelloWorld.Telegram to demonstrate the package with a local inline engine.

By default the sample starts with an empty bot token, so the Telegram channel remains installed but idle until you configure a real token.

Security

• configure AuthorizedChatIds in production whenever possible
• keep the bot token out of committed config files
• if no bot token is configured, the channel remains idle

Versioning

• local builds: 0.1.7-dev
• pull requests: 0.1.7-preview.<run_number>
• pushes to main: 0.1.7-alpha.<run_number>
• tags like v0.1.7: exact stable package version 0.1.7

See VERSIONING.md for the release flow.