Last updated on 22nd April 2026

Telegram

Our Telegram integration lets you send deployment notifications to any Telegram chat, group, or channel via the Telegram Bot API. Messages are delivered as formatted text including the deployment status, server, deployer, and revision range.

To set up a new notification, click the Integrations link on the left-hand side of your project, then click New Integration. Select Telegram from the service picker.

You will need to provide two values:

  • A bot token obtained from Telegram's BotFather
  • A chat ID identifying the chat, group, or channel that should receive the notifications

See the sections below for how to obtain each.

Once both values are entered, choose when to trigger the integration (deployment started, completed, and/or failed), and which servers it should fire for. Click Create Integration to save.

Creating a bot and getting the token

Telegram bots are created through a special bot called BotFather.

  1. Open Telegram and search for @BotFather. Start a chat with it.
  2. Send the command /newbot.
  3. BotFather will ask for a display name — this is shown to users (for example, "Acme DeployHQ Bot").
  4. It will then ask for a username, which must be unique and end with bot (for example, acme_deployhq_bot).
  5. BotFather will reply with a message containing your bot token. It looks like 123456789:ABCdefGhIjKlMnOpQrStUvWxYz-0123456789. Keep this secret — anyone with the token can control your bot.

Paste the token into the Bot Token field of the DeployHQ integration form. The token is stored securely and is not shown back in the form when you edit the integration later.

Getting a chat ID

The chat ID depends on where you want notifications delivered.

Personal chat with the bot

  1. Open the link BotFather gave you, for example t.me/acme_deployhq_bot, and click Start.
  2. Send the bot any message, such as hi. Bots cannot message you until you message them first.
  3. In a browser, open https://api.telegram.org/bot<TOKEN>/getUpdates, replacing <TOKEN> with your bot token.
  4. Find the "chat":{"id":...} value in the JSON response. For a personal chat, this is a positive integer.

Group or supergroup

  1. Add your bot to the group. Only users who are allowed to add members in that group can do this.
  2. Send any message in the group so there is something for the bot to see.
  3. Visit https://api.telegram.org/bot<TOKEN>/getUpdates and find the "chat":{"id":...} value. For groups and supergroups, the ID is negative and typically starts with -100.

Channel

If your channel has a public username (for example @deployhqupdates), you can use that directly as the chat ID. Otherwise, add the bot to the channel as an admin, post a message from the channel, and read the numeric ID from getUpdates.

Paste the chat ID (or @username) into the Chat ID field of the DeployHQ integration form.

What the notification looks like

Each message contains:

  • A bold header with the deployment status and project name
  • The server or server group
  • The deployer's name
  • The start and last revision
  • An overview, if one was added
  • The latest commit message
  • A View report link back to the deployment report in DeployHQ (shown only for completed deployments)

Security

The bot token grants full control over the bot, including the ability to read messages in every chat the bot has access to. Treat it like a password.

  • If you suspect the token has leaked, open @BotFather, send /revoke, select your bot, and BotFather will issue a new token. The old one stops working immediately.
  • Update the integration in DeployHQ with the new token via the Edit page.

API access

This integration can also be created and managed via the DeployHQ API by setting hook_type to telegram and providing bot_token and chat_id in the properties hash.