Connect Telegram: step-by-step guide
Sends alerts on failure (one per test with NEXUS_TELEGRAM_NOTIFY=true) and the reports and files you choose to share, through a bot of your own. There is no shared bot. This guide takes you from nothing to a verified connection, and lists the errors you can meet with their cause and fix.
Last updated:
Keep your credentials private. Never paste a token, key, password or webhook URL into a chat. Type it only in Studio → Settings → Integrations, where it is saved in your workspace's .env file and shown as dots. The same goes for an AI assistant: it can walk you through this guide, but it never needs your token.
What you need
- A Telegram account.
- A bot of your own, created once with @BotFather, and its token.
- A phone or Telegram app to scan the pairing QR.
- Before you switch it on: Telegram can receive files such as reports and PDFs, and they go to Telegram's servers. In a regulated environment, ask your compliance team first.
Get the credentials
- In Telegram, open https://t.me/BotFather and send /newbot. Give the bot a name and a username.
- BotFather answers with the bot token (for example 123456:ABC…). Copy it.
- Keep it in your clipboard. Do not paste it anywhere except the Studio (next step).
Connect it in the Studio
- In the Studio, open Settings → Integrations → Connect Telegram.
- Paste the bot token and save. The pairing QR appears.
- Scan the QR with your phone and tap Start in Telegram. Within seconds the Studio shows "alerts go to chat …" and the bot says "Connected to Nexus StudioQA."
- Turn on
TELEGRAM_ENABLED. For one alert per failing test, also turn onNEXUS_TELEGRAM_NOTIFY.
Check that it works
- After the scan, the bot sends "Connected to Nexus StudioQA. Failed tests will be reported here." to your chat.
- The Studio shows "alerts go to chat" with the chat masked.
Common errors
| What you see | Cause | Fix |
|---|---|---|
| "Telegram is off" | TELEGRAM_ENABLED is false, and pairing needs it on. | Turn on TELEGRAM_ENABLED and press Connect Telegram again. |
| "No bot token" | TELEGRAM_TOKEN is empty. | Paste the token from BotFather in Settings → Integrations and save. |
| "Telegram: Unauthorized" (or "Not Found") | The bot token is wrong, was revoked in BotFather, or was cut when copied. | Send /token to BotFather to get the token again (or create a new bot), and save it. |
| "The QR expired before it was scanned" | The QR is valid for a few minutes only. | Press Connect Telegram to make a new one and scan it right away. |
| The QR was scanned but the Studio still waits | The scan opened the chat but Start was not tapped, or the Studio window was closed. | Tap Start in the bot's chat. If it still waits, make a new QR. |
| "could not reach Telegram (ENOTFOUND)" or "did not answer within 20 s" | This PC cannot reach api.telegram.org: a VPN, firewall or proxy, or no network. | Check the network from the same PC and retry. |
| No alert arrives after a failure | TELEGRAM_ENABLED is false, no chat is paired, or per-test alerts are off (NEXUS_TELEGRAM_NOTIFY). | Pair a chat, and turn on both switches. |
Settings keys
| Key | What it does | Valid value | How to check it |
|---|---|---|---|
TELEGRAM_ENABLED | Send alerts to Telegram | true or false | The pairing QR needs it on. |
TELEGRAM_TOKEN | Telegram bot access code (secret, saved only on this computer) | The bot token from BotFather, like 123456:ABC…, one line | The QR appears only if Telegram accepts it. |
TELEGRAM_CHAT_ID | Telegram chat for alerts | Filled by the QR pairing; do not type it | The Studio shows "alerts go to chat …". |
NEXUS_TELEGRAM_NOTIFY | Telegram alert per failure | true or false | One alert per failing test arrives. |
More: all integrations, the Settings guide, troubleshooting. Other guides: Jira Cloud, Azure Boards, Slack, Microsoft Teams, GitHub Issues.
Still stuck? Write to [email protected] with the exact error line the Studio shows. Do not include a token.