A Telegram bot is not working: diagnose the failing step

“Not working” can mean a bot never replies, a group is missing from its settings, spam remains visible, or a moderation action happens without a log entry. These are different failures. Start with the smallest observable problem, then change one thing and repeat the same test.

Do not remove and re-add the bot, recreate its account or reset every rule as your first response. Those actions can interrupt protection and destroy useful evidence without fixing the cause. If legitimate members are being harmed right now, first pause the identified rule and arrange human moderation while you investigate.

Choose the symptom you can actually observe

Start at the failing step, not at a random setting
Observation	First check	What it does not prove
No private reply to Start	The exact bot account, whether you blocked it, and whether Telegram messages send normally.	That group filtering is misconfigured.
Private reply works; group is missing	The bot's group membership and your administrator access.	That all saved settings were deleted.
Settings open; test message remains	The selected group, enabled rule, author role and deletion setting.	That the service never received the message.
Message disappears; member is not muted	The separate member action and restriction permission.	That deletion and muting share one switch.
Action happens; log is empty	Logging enabled, event category and destination delivery.	That the action did not occur.

Before editing, note when the problem began and the last known successful case. Ask other administrators whether they changed rights, a rule, a destination or another moderation bot. Keep this factual: “a new member's message stayed at 14:20 UTC” is more useful than “everything broke.”

1. Separate private-chat access from group operation

Open the official @defendy_bot and send /start in its private chat. Check whether it is blocked in your Telegram client. Confirm that an ordinary Telegram message can be sent, so a general connection problem is not mistaken for a bot problem.

A private reply tells you that this interaction succeeded. It does not certify that every background service or group module is healthy. Conversely, silence is not evidence that a particular filter needs to be reset.

Open Settings using the bot's current button. Do not troubleshoot a stale Mini App session by copying its full address into public chat: launch data can contain authentication information. Close and reopen it from the bot first. If the private reply arrives but Settings is missing or consistently fails to open, record that distinction and use the support route.

Avoid repeated rapid commands while waiting. They add noise to the incident and make it harder to identify the first useful response.

2. Check whose group and whose permissions you are testing

In Telegram's group administrator list, verify that the intended bot is still an administrator. In the Mini App, check the group name and ID. A setting saved for a test group will not change the live group.

There are two permission questions: can the bot perform the action, and can your account configure or request it? A moderator role inside Defendy does not automatically grant every Telegram administrator power. Consult roles and bot permissions for the action in question.

After a change to the administrator roster, a Telegram administrator can run /reload in the group. It refreshes Defendy's administrator list. It does not restart a server, restore deleted messages or clear the group's configuration. Check the command's response rather than assuming it succeeded.

Defendy's onboarding message may list rights missing for full functionality. Treat it as a prompt to review the intended workflows. A broad onboarding warning and a failure to delete one message are not the same diagnosis; adding every permission can hide the real issue while expanding access unnecessarily.

Do not apply a BotFather fix to someone else's bot

Telegram's Bots FAQ distinguishes message visibility for administrator bots and privacy-mode bots. An administrator bot does not need privacy mode disabled to receive ordinary group messages.

Only the owner can change a bot's BotFather configuration. For a hosted service such as Defendy, your useful checks are group membership, permissions, rules and support. For your own bot, delivery configuration is a separate branch covered below.

The bot stopped responding after a group upgrade

Ask whether the basic group was recently converted to a supergroup. Telegram documents this as group migration; a Bot API error can include the new identifier in migrate_to_chat_id. A name that looks unchanged in the app is not enough to prove an integration still targets the current chat.

Record the upgrade time and the exact migration-related response, if one appeared. Check that the panel or notification integration points to the current group. If the target is stale or unclear, send the relevant chat identifier and redacted error privately to the bot operator through the support route. Do not post bot tokens, Mini App launch data or a full member export.

Keep the existing configuration while the operator checks the mapping. Do not delete and recreate the group or rotate credentials as a first response. /reload refreshes the administrator list; it is not a documented repair for chat identifiers. This diagnostic does not establish whether every Defendy setting migrated automatically. Telegram's upgrade of one group is also different from moving a community to an unrelated group.

3. Distinguish an unsaved change from an unconfirmed refresh

Open the specific module, not just the overview. Check whether it is enabled, whether its list contains the intended entry, and whether the action matches what you expected.

A form with a Save button needs to be saved before leaving.
Ordinary switches and selectors save on change. After an error, reopen the section and inspect the actual value.
“Saved, but the latest data could not be loaded” means the write succeeded but the refresh did not. Use Check again; do not keep resubmitting the change.
An invalid-settings or loading-error state is not proof that the module is off. Capture the message and resolve the read problem before overwriting values.
Coming soon is not a broken button. Anti-flood, anti-raid and whole-settings import/export are not available controls in the current menu.

A screenshot is useful if it shows the selected group, module and error. Crop unrelated member information, private message text and any authentication material before sharing it.

4. Reproduce one match and one non-match

Use a private test group where possible, with an ordinary member who agrees to the trial. An administrator account, another bot or a post sent on behalf of a channel may follow a different path from a regular participant's message.

Here is a hypothetical test: a stopword list contains the unique word trialmarker, matching is Exact, deletion is enabled and the member action is None. Send that word as a new message, then “The meeting starts soon.” Record what happens to each. This isolates a simple deterministic rule; do not use AI classification to prove basic connectivity.

If the expected match survives, inspect the entry, matching mode, relevant exceptions and deletion control before adding broader rules. If the allowed message disappears, look for a second filter, another bot or a human action. Changing this list will not fix an action caused elsewhere.

None means no member punishment; it does not disable message deletion. The reverse is also important: disabling deletion does not disable a configured warning, mute or ban. A warning can trigger escalation. Review both controls before testing, and use only disposable content.

Do not treat a manual /spam check as a dry run. In Defendy it can delete a message identified as spam, and a non-spam outcome can be quiet. Absence of a public explanation alone is not evidence of failure. See manual spam checks.

If behavior changes after an edit or reaction

Use an isolated test group and an ordinary participant who agreed to the test. Keep one stop-word rule with a unique marker and Exact matching, member action None, and deletion enabled; check exemptions and other filters first. Use disposable text and media.

Send harmless text, then replace its entire text with trialmarker. Record the original and edited versions separately. If deleted, use a new message for the next test.
Send a photo with a harmless caption, then replace only its caption with trialmarker. Keep this separate from the text-message test.
Send another harmless message. Add or remove a reaction without editing its text. Observe whether anything changes; a reaction need not produce an action.

For each step, record the group and message ID or link, time with timezone, author role and exemptions, original/changed content, observed deletion, warning or restriction, and any available log entry. An empty log is not proof that an update never arrived. Send only the sanitized sequence through the private support route if the cause remains unclear.

Telegram's edited_message description includes changes to fields a bot may not use or receive. In Telegram staff's clarification, this includes reactions and other non-content changes. A separate report about reactions and member tags is a report to investigate, not confirmation of a universal Telegram fault or a reproduced Defendy penalty.

Defendy checks ordinary group-message edits subject to exemptions. Automatic filter warnings use time-limited deduplication by group and message ID, so another edit does not promise another warning. In the reviewed implementation, channel-post updates are not subscribed to, and automatic discussion forwards and their edits are excluded. Test the participant's message rather than the channel post or its discussion root.

5. Check the action and the evidence trail independently

When a rule matches but the expected action fails, inspect the exact permission and target. Telegram administrator accounts cannot be used as ordinary-member targets for restriction tests. Use a fresh disposable message for deletion tests; Telegram's deletion method has time and message-type restrictions, so an old post is a poor diagnostic sample.

For missing logs, verify all three parts of Logging: the main switch, the event category, and delivery to the chosen destination or topic. The setup uses a separate logging bot. A test delivery does not establish that filter events are selected, and a disabled category cannot supply a complete record of what happened during the gap.

If CAPTCHA alone fails, follow CAPTCHA troubleshooting and reproduce the real invitation path. A working text filter says nothing about a join-request flow.

If you own the bot: check its connected service

A bot newly registered through BotFather has an identity, not working moderation software. Check that the service or no-code workflow providing its behavior is configured and running. If the problem started after connecting a second platform, inspect that change before rotating credentials or deleting the original setup.

Telegram uses either webhook delivery or long polling for a bot's updates; they are mutually exclusive. Ask the workflow maintainer to inspect delivery errors without exposing credentials. Do not change a hosted vendor's endpoint, paste token-bearing API URLs into a browser for a public screenshot, or connect a production bot to a second tool “just to test.”

A prolonged outage: cover the gap and recover deliberately

Start an incident record at the first observed failure, with a time zone and the last known successful action. Distinguish the outage window you observed from a duration you are guessing. If the settings page loads but deletion fails, record deletion as unverified; do not label every module unavailable without checking it.

Keep the group usable while automation is uncertain

Assign one moderator to incident decisions and another available person to member questions. If only one person is on duty, reduce the workload to what they can safely manage. Agree a review time and a verified place for updates. A useful notice says which workflow is unreliable, what temporary rule applies and where members can reach a human; avoid promising a restoration time you do not know.

Use temporary measures proportionate to the harm: manual removal of clear spam, supervised invitations, or narrower member permissions if the volume cannot be handled safely. Record every temporary change and its previous value. Do not remove useful permissions from all members indefinitely because one filter failed. If nobody can moderate safely, consider a clearly announced temporary posting pause, with a named person responsible for reopening.

Keep an incident list of manually handled cases so another administrator does not repeat the same sanction after service returns. Store only the identifiers, time, decision and outcome needed for that check. An incident spreadsheet or staff message is a team procedure; this guide does not imply Defendy has a built-in recovery queue.

Understand what the bot may have missed

Telegram holds undelivered Bot API updates for no more than 24 hours. This is a delivery limit, not a guarantee that a hosted service will process every message from the last day. Updates already received by the service, its own processing state and the modules involved are separate questions for the operator.

Do not assume that reconnecting performs a complete history scan. For the affected interval, review what remains visible and the available Recent Actions and moderation records. Record periods that cannot be verified. A quiet log does not prove there were no violations.

Deletion has a different boundary: the standard bot deleteMessage method generally requires a message to be less than 48 hours old, along with appropriate authority. Do not confuse this with update retention or Telegram's auto-delete timer; use the deletion and retention guide. A late cleanup attempt can fail even after new messages are processing normally.

Check recovery without duplicating harm

Before repeating a failed-looking command, inspect the actual result. Delayed delivery, a late log entry or another moderator's manual action can make the timeline confusing. Telegram update delivery has identifiers for handling repetitions and ordering; that platform mechanism does not by itself certify the application's recovery behavior.

Work through the affected workflows:

Send one permitted message and one harmless test violation from an ordinary member. Verify the message outcome and any configured member action separately.
Reconcile the incident list against the current state. Do not issue another warning or ban solely because the original notification is missing.
Inspect unresolved CAPTCHA challenges, join requests, timed sanctions and scheduled posting changes. A new /start response does not establish that older work finished or was canceled.
If delayed actions keep reversing manual recovery, pause that workflow and ask the operator to investigate the specific case. Do not fight the bot with repeated unmute commands.
Remove temporary restrictions one at a time. Recheck allowed participation after each change and after the next relevant timed transition.

Close the incident when current moderation tests pass, temporary changes have been reviewed, unresolved cases have an owner and members know the normal contact route again. State any historical interval that remains unverified. “Current processing restored; yesterday's missing period still under review” is a useful, honest result.

Recover with one verified change

Apply the smallest change supported by the evidence, then repeat the violation and allowed-message tests. If someone lost access, review and reverse that person's restriction separately. Disabling a rule does not automatically undo its previous actions, and unbanning does not recreate deleted content.

Keep a short incident note: symptom, cause if established, setting changed, observed result and person responsible. If the cause is still unknown, say so and keep the affected workflow under human supervision.

For support, send the group ID through the verified private support route, the time with timezone, the module, expected and observed behavior, and a sanitized reproduction. State the test author's role and any displayed error. Never include bot tokens, Telegram login codes, full Mini App launch URLs or an entire private conversation.

Evidence and limits

The original diagnostic steps were reviewed on 6 October 2026 against the Defendy implementation and product troubleshooting reference. The prolonged-outage and recovery section, including the linked Telegram delivery and deletion limits, was checked on 7 October 2026. The examples are diagnostic plans, not claimed live tests. They help narrow a cause; they do not establish the availability of the hosted service at the time you read this article.