Build a Telegram Announcement Bot with the SDK

Use @chirpie/sdk to push deploy notices, changelogs, and release announcements into a Telegram channel from your own code.

Updated September 2026

How do you build a Telegram announcement bot?

Create a bot with @BotFather, add it as an admin to your channel, connect it to Chirpie with the bot token and chat ID, then call chirpie.createPost() from @chirpie/sdk whenever you have something to announce. There is no Telegram library to learn — it is the same call you would use to post to X.

Step 1 — Create the bot and get the chat ID

Message @BotFather, send /newbot, and follow the prompts. You get a token that looks like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ.
Add the bot to your channel or group as an administrator with permission to post.
Note the chat ID. Public channels can use @yourchannelname; private channels and groups use the numeric form, e.g. -1001234567890.

Step 2 — Connect it to Chirpie

Telegram does not use OAuth, so the connect call is a single request:

curl -X POST https://chirpie.ai/api/v1/accounts \
  -H "Authorization: Bearer chirpie_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "telegram",
    "bot_token": "123456789:ABCdefGHIjklMNOpqrSTUvwxYZ",
    "chat_id": "-1001234567890"
  }'

Or from the SDK:

import { ChirpieClient } from "@chirpie/sdk";

const chirpie = new ChirpieClient({ apiKey: process.env.CHIRPIE_API_KEY! });

const account = await chirpie.connectTelegramAccount({
  platform: "telegram",
  bot_token: process.env.TELEGRAM_BOT_TOKEN!,
  chat_id: process.env.TELEGRAM_CHAT_ID!,
});

console.log(account.id); // save this — it is your account_id

The bot token is stored encrypted. Keep it out of your repo; read it from an environment variable.

Step 3 — Send your first announcement

npm install @chirpie/sdk

import { ChirpieClient } from "@chirpie/sdk";

const chirpie = new ChirpieClient({ apiKey: process.env.CHIRPIE_API_KEY! });

await chirpie.createPost({
  account_id: process.env.TELEGRAM_ACCOUNT_ID!,
  text: "v2.4.0 is live. Scheduler retries now back off, and thread publishing is atomic.",
});

That is the whole bot. Everything else is deciding when to call it.

Step 4 — Wire it into your deploy pipeline

A small helper that any part of your app can call:

// lib/announce.ts
import { ChirpieClient, ChirpieApiError } from "@chirpie/sdk";

const chirpie = new ChirpieClient({ apiKey: process.env.CHIRPIE_API_KEY! });

export async function announce(text: string, mediaUrls?: string[]) {
  try {
    const post = await chirpie.createPost({
      account_id: process.env.TELEGRAM_ACCOUNT_ID!,
      text,
      media_urls: mediaUrls,
    });
    return post.id;
  } catch (err) {
    if (err instanceof ChirpieApiError) {
      console.error(`Telegram announce failed: ${err.code} (${err.status}) — ${err.message}`);
      return null;
    }
    throw err;
  }
}

Call it from a release script, a webhook handler, or a cron job:

import { announce } from "./lib/announce";

await announce(
  [
    "Deploy complete.",
    "",
    `Version: ${process.env.RELEASE_TAG}`,
    `Commit: ${process.env.GIT_SHA?.slice(0, 7)}`,
  ].join("\n"),
);

Newlines survive intact, so multi-line release notes read well in Telegram.

How do you post images or a multi-part update?

Telegram accepts up to 10 images or a video per post. Pass public URLs:

await announce("New dashboard shipped.", [
  "https://cdn.example.com/dashboard-1.png",
  "https://cdn.example.com/dashboard-2.png",
]);

For a longer narrative, use a thread. Telegram supports native reply threading, so each part replies to the last:

await chirpie.createThread({
  account_id: process.env.TELEGRAM_ACCOUNT_ID!,
  posts: [
    { text: "Release 2.4.0 — three things worth knowing." },
    { text: "1. Scheduled threads now publish atomically." },
    { text: "2. Retries cap at three attempts, five minutes apart." },
    { text: "3. Media is stored at schedule time, so expiring URLs are fine." },
  ],
});

How do you schedule an announcement?

await chirpie.createPost({
  account_id: process.env.TELEGRAM_ACCOUNT_ID!,
  text: "Maintenance window starts in one hour.",
  schedule_at: "2026-09-20T14:00:00Z",
});

schedule_at is UTC and must be in the future. Posts publish within about five minutes of the target, and scheduled posts on the same account must be at least five minutes apart.

Telegram specifics

Constraint	Value
Max message length	4,096 characters
Images per post	Up to 10 (JPEG, PNG, GIF, WebP, 10 MB each)
Video	MP4, up to 50 MB
Threading	Native, via replies
Analytics	Not available — Telegram exposes no metrics API

The bot must be an administrator of the channel with posting rights. A bot that is merely a member cannot post, and the API will surface an upstream error.

How do you let an AI agent trigger it?

Add the MCP server and the same channel becomes available to Claude or Cursor:

npm install -g chirpie
chirpie login
claude mcp add chirpie -- npx @chirpie/mcp

Summarise the last 10 commits and send it to our Telegram channel.

FAQ

Do I need to run a Telegram bot server? No. Chirpie calls the Bot API for you. There is nothing to host and no webhook to expose.

Can one bot post to several channels? Connect the bot once per chat ID. Each connection is its own Chirpie account with its own account_id.

Can the bot read replies? No. Chirpie is a publishing layer — it sends messages, it does not consume updates.

Are there analytics for Telegram? No. Telegram does not expose per-message metrics, so GET /api/v1/analytics/posts/:id has nothing to return for Telegram posts.

Can I delete a sent message? Yes. DELETE /api/v1/posts/:id removes it from Chirpie and from the channel.

Is the bot token safe? It is encrypted at rest. Keep your own copy in an environment variable or secret manager, never in source control.