Telegram Channel

Telegram channels connect one Telegram bot to one Netmind Cloud Agent. NCA receives Telegram messages through a webhook and sends agent replies back through the Telegram Bot API.

Prerequisites

CHANNELS_ENABLED=true on the API service
PUBLIC_API_BASE_URL set to the public HTTPS base URL of the API service
An existing NCA agent
A Telegram bot token from @BotFather

Telegram webhooks require a public HTTPS URL. Localhost URLs will not work unless they are exposed through a tunnel.

Create the Telegram bot

Open Telegram and start a chat with @BotFather.
Send /newbot.
Choose a display name and a globally unique username ending in bot.
Copy the bot token. It should look like 123456789:AAH....
For group use, open BotFather’s bot settings and turn off Group Privacy if the bot needs to receive normal group messages.

Configure in Admin

Open Admin, then go to Channels.
Create a new channel and choose Telegram.
Select the agent that should receive messages.
Enter a label and paste the bot token.
Create the channel.

NCA calls Telegram setWebhook automatically after the channel is created. The webhook target is:

{PUBLIC_API_BASE_URL}/api/channels/hooks/telegram/{channelId}

NCA also stores a generated webhook secret and writes the bot username back into channel config.

API payload

{
    "agentId": "agt_...",
    "provider": "telegram",
    "label": "engineering-telegram",
    "config": {
        "mentionOnly": true,
        "shareSessionInChannel": false,
        "threadIsolation": true,
        "progressMode": "preview"
    },
    "credentials": {
        "botToken": "123456789:AAH...",
        "webhookSecret": null
    }
}

Send this body to POST /api/channels. The API validates the token, registers the webhook, and activates the channel when registration succeeds.

Configuration

Field	Required	Default	Notes
`botUsername`	No	Auto-filled	Telegram username returned by `getMe`. Used to detect `@bot` mentions in groups.
`mentionOnly`	No	`true`	In group chats, only respond when the bot is mentioned. Private chats always respond.
`shareSessionInChannel`	No	`false`	When `true`, all users in the same group share one agent session unless a thread scope is used.
`threadIsolation`	No	`true`	Uses Telegram topic `message_thread_id` or the replied message as the session scope.
`progressMode`	No	`preview`	`preview` edits one progress message while the agent works. `final` only sends the final reply.

Credentials

Field	Required	Notes
`botToken`	Yes	Token from `@BotFather`. Stored encrypted.
`webhookSecret`	No	Leave `null` on create. NCA generates one and uses it to verify Telegram webhook deliveries.

Verify

Use the channel detail page test action, or call:

curl -X POST "$NCA_API_URL/channels/{channelId}/test" \
    -H "Authorization: Bearer $NCA_TOKEN"

A healthy channel reports the bot identity and confirms that Telegram’s webhook URL matches the NCA inbound URL.

Troubleshooting

webhook URL does not match: check PUBLIC_API_BASE_URL, then register or test the channel again.
getMe failed: the bot token is wrong or revoked.
Group messages do not arrive: disable Group Privacy in BotFather or use commands/replies that Telegram forwards to bots.
Group messages arrive but are ignored: set mentionOnly=false, mention the bot username, or verify botUsername was auto-filled.