How to read a Telegram Bot API error before you look it up

Telegram's HTTP status codes are coarse - almost everything is a 400 - but the description string is precise and documented. Read the description, not the code, and you will usually know the fix before you finish the sentence.

Last verified: 2026-08-20 against the Telegram Bot API. Error strings quoted below are the literal responses the API returns.

A failed call always has the same shape:

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 34",
  "parameters": {"retry_after": 34}
}

Three fields matter. error_code mirrors the HTTP status. description is the real error - a stable, documented English string, usually prefixed with the status name (Bad Request:, Forbidden:, Conflict:). And the optional parameters object carries machine-readable follow-ups: retry_after (seconds to wait) and migrate_to_chat_id (the group became a supergroup; here is its new ID). Code that logs only the status code throws away everything useful.

The five families, by symptom:

This guide walks each family code-first. If your bot is silent and you do not have an error string yet, start instead with our symptom-first companion, Telegram bot not responding - and for any literal string, the Telegram error directory has a dedicated page per error.

409 Conflict: the errors that make a bot silent

Telegram permits exactly one consumer of updates per bot token - you either poll with getUpdates or receive pushes at a webhook, never both, and never two pollers. Both violations return 409, and both silence your bot while every other part of the system looks healthy.

{"ok":false,"error_code":409,"description":"Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first"}

A webhook is registered against the token and your code is polling. Many libraries swallow this error and retry forever, so the process runs, the logs look fine, and nothing ever arrives. Fix: deleteWebhook?drop_pending_updates=true, then restart polling - or stop polling if the webhook was intentional. Full handling on the webhook-active 409 page.

{"ok":false,"error_code":409,"description":"Conflict: terminated by other getUpdates request; make sure that only one bot instance is running"}

Two processes are polling the same token, and each message goes to whichever holds the connection - the classic bot that answers roughly half the time. Hunt for a dev process left running, a container scaled to two replicas, or an old deploy that never died. Polling does not scale horizontally; if you need more than one instance, use webhooks behind a load balancer. Details on the terminated-by-other-getUpdates page.

Both 409s are configuration states, not transient faults: retrying without changing anything reproduces them forever. The one-command diagnostic is getWebhookInfo - an empty url means polling mode, a populated one means webhook mode, and a URL you do not recognise means a stale deploy is stealing your updates.

400 Bad Request: sends that fail because of the message itself

The 400 family is the largest, and it splits by what you got wrong. First, the message content errors - these are deterministic, so the bot works for most messages and dies on specific ones.

{"ok":false,"error_code":400,"description":"Bad Request: can't parse entities: Can't find end of the entity starting at byte offset 42"}

You set parse_mode and the text contains characters the parser reads as markup. MarkdownV2 requires escaping _ * [ ] ( ) ~ ` > # + - = | { } . ! even in prose - a sentence ending in a full stop can fail. Escape interpolated user content, or switch to HTML parse mode, which needs only &, <, >. The byte offset in the description points at the exact culprit; the can't parse entities page has escaping tables for both modes.

Bad Request: message is too long
Bad Request: message text is empty

Text messages cap at 4,096 characters - AI-generated replies overrun this constantly, so split on a paragraph boundary before sending (message is too long). The empty variant usually means an interpolation produced "" or a template variable never resolved (message text is empty).

Then the addressing errors:

Bad Request: chat not found
Bad Request: user not found
Bad Request: chat_id is empty

chat not found means the chat_id does not correspond to a chat your bot can reach: a username where a numeric ID is needed, a dropped negative sign (group IDs are negative, supergroups start with -100), a chat ID truncated by a 32-bit integer column, or a group the bot was removed from. A user ID your bot has never seen in an update gives user not found - Telegram bots cannot look up arbitrary users; they can only address chats they have met.

400 Bad Request: editing, deleting, and replying to messages

A second cluster fires when you manipulate existing messages. Each description names its own rule:

The callback-query row deserves emphasis because its symptom is so misleading: users report "the buttons stopped working", but the bot is receiving every tap - it is just answering after the query expired. The same acknowledge-first pattern that keeps webhooks healthy applies here: answer the callback immediately, then do the slow work.

400 Bad Request: group permissions and the supergroup migration

Group-related 400s look like bugs and are actually group administration:

Bad Request: have no rights to send a message
Bad Request: not enough rights to send text messages to the chat
Bad Request: CHAT_WRITE_FORBIDDEN

All three mean the bot is in the chat but muted: restricted by an admin, stripped of send permissions, or blocked from writing in that channel or topic. The fix is in the group's member settings, not in code - promote the bot or lift the restriction (have no rights to send a message, CHAT_WRITE_FORBIDDEN).

The one that breaks bots permanently:

{"ok":false,"error_code":400,"description":"Bad Request: group chat was upgraded to a supergroup chat","parameters":{"migrate_to_chat_id":-1001234567890}}

When a group upgrades to a supergroup its chat ID changes forever, and the old ID never works again. Telegram hands you the new ID in parameters.migrate_to_chat_id - store it the moment you see it, and also handle the migrate_to_chat_id field that arrives in updates when the migration happens. Bots that ignore this silently lose the group; the supergroup migration page has the handler pattern.

400 Bad Request: webhook registration refused

These fire at setWebhook time, which is good news - the failure is loud and immediate instead of silent:

Bad Request: bad webhook: HTTPS url must be provided for webhook
Bad Request: bad webhook: Webhook can be set up only on ports 80, 88, 443 or 8443
Bad Request: bad webhook: failed to resolve host

The rules behind them: webhooks are HTTPS-only with no development exception; only four ports are allowed, so the dev server on port 3000 can never receive a webhook (the ports 80, 88, 443, 8443 page covers the workarounds - a reverse proxy or a tunnel); and the hostname must resolve on the public internet, so localhost and internal DNS names are rejected (failed to resolve host).

Once registration succeeds, failures move to delivery time and stop being errors you receive - they become entries in getWebhookInfo's last_error_message field, which is where you look when a registered webhook goes quiet. That debugging path - certificates, timeouts, the acknowledge-then-process pattern - is shared across every platform, and our webhook debugging guide walks it in one pass. The mechanics of what a webhook actually is, if the term is new, take two minutes to absorb.

400 Bad Request: files, photos, and buttons

Media and keyboard errors round out the 400 family:

The 64-byte callback_data cap is the one that surprises people: serializing a JSON state object into the button works in testing and breaks the moment the state grows. Store state server-side, keyed by a short ID.

403 Forbidden: the recipient is the problem, and retrying is pointless

Every 403 means the same thing structurally: your request was valid, your token is fine, and the recipient is unreachable as a matter of policy. None of them are fixed by retrying - the correct response is always to update your database and stop sending.

{"ok":false,"error_code":403,"description":"Forbidden: bot was blocked by the user"}

The user blocked your bot. There is no API to check block status in advance - the send attempt is the check. Mark the chat inactive; bots that keep retrying blocked users burn their own rate limit (bot was blocked by the user).

Forbidden: bot can't initiate conversation with a user

The rule every notification system meets on day one: a Telegram bot can never message someone first. The user must send /start or tap a deep link like https://t.me/YourBotName?start=user_12345 before you may send anything. A phone number or user ID from another system grants nothing (can't initiate conversation).

The rest of the family, by literal string:

• Forbidden: bot was kicked from the group chat - removed by an admin; delete the stored chat and stop.
• Forbidden: user is deactivated - the account was deleted or deactivated; permanently unreachable.
• Forbidden: bot is not a member of the channel chat - to post to a channel the bot must be added as an administrator, not merely know the channel's ID.
• Forbidden: bot can't send messages to bots - bots cannot talk to each other, by design. If two of your systems need to communicate, use your own backend, not Telegram.

A well-behaved sender treats any 403 as a permanent state transition for that chat. Log it once, flag the record, move on.

429 Too Many Requests: flood control and retry_after

The bot that answered everything in testing and drops messages at launch is meeting flood control:

{"ok":false,"error_code":429,"description":"Too Many Requests: retry after 34","parameters":{"retry_after":34}}

Telegram's published guidance for bots: roughly 30 messages per second overall, about 1 message per second sustained to an individual chat, and around 20 messages per minute to a single group. The full set of ceilings lives on the Telegram limits page.

The contract when you exceed one: honour retry_after exactly. Retrying sooner extends the penalty, and sustained abuse can get a token limited far longer than the number suggests. The wrong fix is a sleep sprinkled into the send loop; the right fix is a token-bucket queue that paces broadcasts below 30 per second and spaces per-chat sends - the same architecture every platform ends up needing, as our chatbot API rate limiting guide covers cross-platform. Back-off rules and code patterns are on the 429 reference page, and the general concept on the rate limiting glossary page.

A subtler 429 trigger affects conversational bots: sending three quick bubbles to feel human - greeting, question, menu - can trip the per-chat limit for one user. Insert a short delay between bubbles; it also reads more naturally.

401 Unauthorized and 404 Not Found: the token itself

When every call fails, stop debugging payloads - the token is broken in one of two ways:

{"ok":false,"error_code":401,"description":"Unauthorized"}
{"ok":false,"error_code":404,"description":"Not Found"}

401 Unauthorized means the token has a valid shape but does not authenticate: revoked via BotFather (regenerating a token instantly kills the old one), or corrupted in transit into your environment - a trailing newline from a secrets manager, quote characters included in the value, or a truncated paste. 404 Not Found usually means the token is malformed enough that the URL path itself is wrong - a missing bot prefix (/bot<TOKEN>/getMe), a typo'd method name, or an empty token variable producing /bot/getMe.

Verify the token in isolation before touching anything else: open https://api.telegram.org/bot<TOKEN>/getMe in a browser, or use our Telegram bot token checker, which runs the same call from the browser and explains the response. A healthy token returns the bot's username and ID. If getMe succeeds locally but production returns 401, the token is fine and the deployed environment variable is not.

One trap with no error at all: a valid but wrong token - the staging bot's token deployed to production. Both tokens pass getMe, sends succeed, and users report silence because the replies are going out through a bot nobody is looking at. When logs show success and users see nothing, confirm which bot the token belongs to.

502 and 504: when the failure is not yours

Two gateway errors round out the list, and they matter mostly because of what you should not do about them:

• 502 Bad Gateway - the Bot API server itself is having trouble, or a proxy between you and it is. Transient; retry with back-off.
• 504 Gateway Timeout - the request did not complete in time. Also transient, but if it correlates with your own long-polling timeout settings, tune getUpdates' timeout parameter rather than hammering.

The rule for 5xx is the inverse of the 403 rule: these are the only errors in this guide where blind retrying is correct, provided it backs off. Everything else in this guide is deterministic - a 400 will fail identically on retry, a 403 is a policy state, a 409 is configuration. A retry queue that cannot tell these classes apart will hammer permanent errors and give up on transient ones; classify on error_code first, then on the description string.

Distinguish carefully between a 502 from Telegram and a 502 in your webhook's last_error_message - the second means Telegram called your server and your server answered 502, which is your app crashing, not Telegram's. getWebhookInfo tells you which side you are on.

Avoiding this layer altogether

Every error family above is transport plumbing: update-consumer exclusivity, escaping rules, per-chat pacing, token hygiene, migration handling. None of it is your product, and all of it recurs on every platform under different names - Meta's error codes, Slack's, LINE's. Handling it well is genuinely necessary if you operate the Bot API directly, and genuinely undifferentiating work if what you actually want is a bot that answers customers.

A managed platform absorbs this layer. With Conferbot's Telegram integration, you connect a bot token and build the conversation in a visual flow editor - webhook lifecycle, retry classification, rate-limit pacing, and message formatting are handled for you, and the same flow deploys to WhatsApp, LINE, and a website widget without re-implementing each platform's error table.

Start free with Conferbot - no credit card required, so you can compare a managed flow against your hand-rolled handler this afternoon.

If you are staying hands-on: bookmark the Telegram error directory for the string-level pages, keep the limits page next to your queue configuration, and when the bot is silent with no error in sight, work through the symptom-first guide - between the two, every failure in this family tree has a page.

FAQ

What does error 409 mean in the Telegram Bot API?

Conflict: two things are competing for the same bot token's updates. Either a webhook is registered while your code polls with getUpdates - fix with deleteWebhook - or two processes are polling simultaneously, which splits messages between them roughly at random. Telegram allows exactly one update consumer per token. Call getWebhookInfo to see which state you are in before changing any code.

How do I fix "Bad Request: chat not found" on Telegram?

The chat_id does not correspond to a chat your bot can reach. Check for a username used where a numeric ID is required, a dropped negative sign - group IDs are negative and supergroup IDs start with -100 - a value truncated by a 32-bit integer column, or a group that upgraded to a supergroup and changed its ID. Store chat IDs as 64-bit integers or strings and handle migrate_to_chat_id.

What causes "Forbidden: bot was blocked by the user"?

Exactly what it says: the user blocked your bot, and there is no API to check block status in advance - the send attempt is the check. Mark that chat inactive in your database and stop sending, because retries will never succeed and only consume your rate limit. Treat every 403 in the family the same way: a permanent state change for that recipient, not a transient fault.

What is retry_after in a Telegram 429 error?

The number of seconds Telegram requires you to wait before the next request, returned in the parameters object alongside the literal description "Too Many Requests: retry after N". Honour it exactly - retrying sooner extends the penalty. If you hit 429 regularly, the structural fix is a token-bucket queue pacing sends below roughly 30 messages per second overall and about one per second per chat.

Why does my Telegram bot get 401 Unauthorized on every call?

The token does not authenticate: it was regenerated in BotFather - which instantly invalidates the old value - or the environment variable is corrupted by a trailing newline, included quotes, or truncation. Test the token alone with getMe in a browser or a token checker tool. If getMe works locally but production fails, the token is fine and the deployed environment variable is what is broken.

What is the difference between Telegram error 401 and 404?

401 Unauthorized means the token is well-formed but invalid - revoked or corrupted. 404 Not Found usually means the request URL itself is wrong: a missing bot prefix before the token, a typo in the method name, or an empty token variable collapsing the path. Both make every call fail, so verify the exact URL string and the token value together before debugging anything else.

How do I fix "can't parse entities" errors from Telegram?

Your parse_mode treats part of the text as markup. MarkdownV2 demands escaping for sixteen characters including underscore, brackets, hyphen, and even the full stop, so unescaped user content fails on names and product codes. Escape everything you interpolate, or switch to HTML parse mode, which only needs ampersand and angle brackets escaped. The byte offset in the error points at the exact failing character.

Why do sends to a group suddenly fail after it becomes a supergroup?

Upgrading a group to a supergroup permanently changes its chat ID, and the old ID stops working forever. Telegram tells you twice: the failed send returns "group chat was upgraded to a supergroup chat" with the new ID in parameters.migrate_to_chat_id, and an update carrying migrate_to_chat_id arrives at migration time. Store the new ID the moment you see either signal.

What are the file size limits for Telegram bots?

On the default cloud Bot API server, bots can download files up to 20MB and upload files up to 50MB; exceeding either returns "Bad Request: file is too big". Running Telegram's self-hostable Bot API server raises both limits to roughly 2000MB and also lifts the webhook port restriction - worthwhile only when large media is a real requirement rather than a default choice.

Why is BUTTON_DATA_INVALID returned for my inline keyboard?

The callback_data on an inline button exceeds the 64-byte cap or contains invalid content. Serializing JSON state into the button is the usual cause - it fits during testing and overflows when the state grows. Store the state server-side keyed by a short opaque token, and put only that token in callback_data. The companion BUTTON_URL_INVALID means a button URL is malformed.

Should I retry failed Telegram Bot API requests?

Only by class. Retry 5xx errors with back-off, and 429 after exactly retry_after seconds. Never blind-retry 400s - they are deterministic and will fail identically - and never retry 403s, which are permanent recipient states like blocks and kicks. The 409s are configuration conflicts that persist until you change the setup. A retry queue that cannot classify by error_code hammers permanent errors and abandons transient ones.

Where do webhook delivery errors appear if Telegram does not return them?

In getWebhookInfo. Registration problems fail loudly at setWebhook time with a bad webhook description, but once a webhook is registered, delivery failures stop being API responses - Telegram records the latest one in the last_error_message field, with a timestamp in last_error_date and a pending_update_count showing the backlog. A populated last_error_message plus a climbing count means your endpoint is rejecting every delivery.

The full guide, with diagrams and the latest checks, is at https://www.conferbot.com/blog/telegram-bot-api-error-codes.

Why Slack bots fail silently, and where to look first

Slack's failure modes are unusually quiet. A missing scope, an unverified request URL and a bot that was never invited to the channel all produce the same observable symptom: nothing happens. Your logs are empty because the request never arrived.

Last verified: August 2026 against the Slack Events API and OAuth scopes model.

Before changing code, answer one question: is your endpoint receiving anything at all? Add a log line as the very first statement in your handler, before any parsing or validation, and send a message that should trigger the bot.

That single log line eliminates roughly half the possible causes in under a minute.

1. URL verification: "Your URL didn't respond with the value of the challenge parameter"

Before Slack will deliver any event, it verifies you own the endpoint. This is the same push shape as any incoming webhook: Slack POSTs a JSON body:

{
  "token": "Jhj5dZrVaK7ZwHHjRyZWjbDl",
  "challenge": "3eZbrw1aB1m5zVFQrRvBiVAG1MMqbGqBGRTLBSFwhcSFrSKzHJ",
  "type": "url_verification"
}

You must respond with the challenge value and nothing else. This must happen before any signature verification, authentication middleware or body parsing that might reject an unfamiliar payload:

app.post('/slack/events', (req, res) => {
  if (req.body.type === 'url_verification') {
    return res.send(req.body.challenge);   // plain text, first thing
  }
  // ... normal event handling below
});

Five reasons this fails

• Signature verification runs first. Your middleware rejects the verification request because it does not match an expected shape. Handle url_verification before any guard.
• You returned JSON instead of the raw string. Returning {"challenge": "..."} also works if the content type is correct, but returning the plain string is more reliable.
• A redirect sits in front. Slack does not follow redirects during verification. If your URL 301s from HTTP to HTTPS or from a bare domain to www, register the final URL directly.
• Authentication is required. Any auth layer, IP allowlist or WAF rule in front of the endpoint blocks Slack. The events path must be publicly reachable.
• Cold start timeout. Slack allows about 3 seconds. A serverless function with a slow cold start fails verification, then succeeds when you retry immediately because the instance is warm - which makes this look intermittent.

During local development, use a tunnel such as ngrok, and remember the URL changes every restart on the free tier - you must re-verify each time. If that becomes tedious, Socket Mode removes the public endpoint requirement entirely and is the better development path.

2. Scopes: the reinstall step everyone forgets

Slack's most common runtime error:

{"ok": false, "error": "missing_scope", "needed": "chat:write", "provided": "channels:read,users:read"}

Helpfully, the response names exactly what you need. The trap is what comes next.

Adding a scope in the app configuration does nothing until the app is reinstalled to the workspace. The token you already hold was issued with the old scope set and does not gain new permissions retroactively. Change scopes, then go to OAuth & Permissions -> Reinstall to Workspace, and use the newly issued token. Skipping the reinstall is the single most common Slack integration mistake.

The scopes a conversational bot actually needs

Two distinctions matter. Public and private channel history are separate scopes, so a bot that reads public channels fine and sees nothing in private ones needs groups:history. And bot tokens (xoxb-) differ from user tokens (xoxp-): most bot actions need the bot token, and using the wrong one produces confusing permission errors.

App manifests remove the drift between environments

A meaningful share of scope mismatches come from configuring scopes by hand in one environment and forgetting to replicate the change in another. Slack's App Manifest feature collapses the whole configuration - display information, bot scopes, event subscriptions, slash commands, interactivity settings and Socket Mode - into a single YAML or JSON document under the app's App Manifest tab. Treating that file as version-controlled configuration, rather than clicking through the dashboard per environment, means a scope added for staging cannot silently fail to reach production, and a manifest diff shows you exactly what changed before you reinstall. It will not save you from the reinstall step itself - a manifest update to oauth_config.scopes still requires reinstalling to take effect - but it does remove the class of bug where two environments quietly diverge.

3. Events not firing at all

If your endpoint verified successfully but no events arrive, work these in order.

You subscribed to no events

Verifying the URL and subscribing to events are separate steps. Under Event Subscriptions -> Subscribe to bot events, add the specific events you need - most commonly message.channels, message.im, message.groups and app_mention. An empty subscription list means Slack has nothing to send.

You subscribed to the wrong message event

Message events are split by conversation type, and each is a distinct subscription:

• message.channels - public channels
• message.groups - private channels
• message.im - direct messages
• message.mpim - group direct messages

A bot that responds in public channels and ignores DMs is subscribed to message.channels but not message.im. This is the Slack equivalent of the intent split in other platforms.

The bot is not in the channel

Subscribing to message.channels does not deliver messages from channels the bot has not joined. Invite it with /invite @yourbot in each channel where it should work. A bot that works in one channel and not another has almost always just not been invited.

Attempting to post to a channel it is not in returns:

{"ok": false, "error": "not_in_channel"}

The chat:write.public scope allows posting to public channels without an invite, but it does not grant the ability to read them - you still need the bot in the channel to receive messages.

Your app is on the wrong delivery mode

Socket Mode and the Events API are mutually exclusive. If Socket Mode is enabled, Slack pushes over a WebSocket and ignores your request URL entirely - so a perfectly correct HTTP endpoint receives nothing. Teams that enable Socket Mode for local development and forget to disable it before deploying hit this exactly once, and it is baffling until you know. Socket Mode has its own token requirement too: it needs a separate app-level token starting with xapp-, generated from the app's Basic Information page with the connections:write scope, which is easy to skip if you only ever set up a bot token before.

4. The 3-second rule and the retry storm

Slack requires an HTTP 200 within 3 seconds of delivering an event. Miss it and Slack retries - up to three times, at roughly increasing intervals (the first retry lands almost immediately, the second after about a minute, the third after about five minutes). Your handler runs again each time, and the user receives the same reply three or four times.

This is the cause of nearly every "my Slack bot sends duplicates" report, and it becomes certain the moment you add an AI model call to the handler.

Acknowledge first, then work:

app.post('/slack/events', async (req, res) => {
  res.sendStatus(200);              // acknowledge immediately, always
  await handleEvent(req.body);      // then take as long as you need
});

For slash commands and interactive components you can also respond immediately with a placeholder and update it later using the response_url, which stays valid for 30 minutes and accepts up to five follow-up messages.

Detect retries rather than reprocessing them

Slack marks retried deliveries with headers you should check:

X-Slack-Retry-Num: 1
X-Slack-Retry-Reason: http_timeout

X-Slack-Retry-Reason is worth logging on its own - besides http_timeout it can read connection_failed, ssl_error, http_error or too_many_redirects, and each points somewhere different: a timeout means your handler is too slow, but ssl_error or too_many_redirects means the retry never had a chance to reach your code regardless of how fast it responds. If X-Slack-Retry-Num is present at all, acknowledge and return without reprocessing. Combine that with deduplication on event_id and duplicate replies disappear entirely - even if a genuine timeout occurs.

The acknowledge-first pattern and the raw-body signature check are the same on every platform that calls you over HTTP; our cross-platform webhook debugging guide shows the Node implementation once and maps it to Slack, Meta, Telegram and Discord.

5. Infinite loops, thread targeting and ID mistakes

The bot replying to itself

Bot messages generate message events too. Without a guard, your bot replies to its own reply indefinitely until Slack rate limits it. Check for the bot marker as the first line of the handler:

if (event.bot_id || event.subtype === 'bot_message') return;

Two unguarded bots in one channel will do this to each other and produce thousands of messages in seconds.

Message subtypes you probably want to ignore

Edits, deletions, joins and file shares all arrive as message events with a subtype. A bot that responds to message_changed will reply again every time someone edits a message. Handle only the subtypes you intend to.

Replying in the wrong place

To reply inside a thread, pass thread_ts - the ts of the parent message. Omit it and your reply lands in the channel, out of context. Conversely, passing thread_ts when you meant to post to the channel buries the message in a thread nobody is watching.

channel_not_found

Usually a channel name used where an ID was required. Slack channel IDs look like C01ABCDEF; using #general works in some endpoints and not others. Store IDs rather than names - names change, IDs do not. The same error appears for private channels the bot has not been invited to, since it genuinely cannot see them.

Rate limits

Slack rate limits per method in tiers, and chat.postMessage is generally around one message per second per channel with short bursts tolerated. Exceeding it returns HTTP 429 with a Retry-After header in seconds - honour it exactly rather than retrying immediately. Web API methods beyond message-sending are grouped into four broader tiers, each method carrying its own per-minute ceiling per workspace; the tier for any given method is documented on its own reference page. A bot calling a Tier 1 method - the most restrictive tier - in a tight loop, such as polling users.info once per incoming message instead of caching the result, will get throttled long before it comes anywhere near the chat.postMessage limit. Caching lookups you would otherwise repeat on every event is the single highest-leverage fix for Slack rate limiting, well before backoff logic matters. For the equivalent ceilings on WhatsApp, Telegram and Discord, see our platform limits directory.

The diagnostic checklist

Row 8 deserves emphasis. Slack's missing_scope response includes both needed and provided, which is as close to a self-diagnosing error as any platform offers. Code that logs only a status code discards the answer. For the platforms that publish full numeric code sets, our error-code directory maps each code to its fix.

6. Buttons, modals and slash commands that do nothing

Interactive components fail differently from events, and they fail more visibly - the user sees a spinner or an error in the Slack client rather than silence.

The Interactivity request URL is separate

This is the most common cause and the least obvious. Event Subscriptions and Interactivity & Shortcuts have their own separate request URLs. Verifying your events endpoint does nothing for button clicks. If your bot posts a message with buttons and nothing happens when they are pressed, open Interactivity & Shortcuts, turn interactivity on, and set a request URL there too - it can be the same endpoint, but it must be configured.

Interaction payloads are form-encoded, not JSON

Slack sends interactive payloads as application/x-www-form-urlencoded with a single payload field containing JSON as a string. An endpoint that only parses JSON receives nothing usable:

app.post('/slack/interactive', (req, res) => {
  res.sendStatus(200);                          // acknowledge first
  const payload = JSON.parse(req.body.payload); // note: not req.body
  handleInteraction(payload);
});

A handler that works perfectly for events and throws on every button click is almost always missing this. Make sure your body parser handles URL-encoded bodies on that route.

trigger_id expires in 3 seconds

Opening a modal requires a trigger_id from the interaction payload, and it is valid for 3 seconds only. You cannot defer, queue, or await an AI call before calling views.open - the trigger will be dead. Open the modal immediately with a loading state, then update it with views.update once the slow work finishes.

The error you get is expired_trigger_id, and it appears intermittently under load, which makes it look like a flaky network problem rather than a design constraint.

Slash commands have their own URL too

Each slash command is registered individually under Slash Commands, each with its own request URL. Commands also require the app to be reinstalled after being added. And a command name already taken by another app in that workspace will silently route to the other app - if your /help command triggers something unexpected, a competing app owns it.

Block Kit validation failures

Malformed Block Kit JSON returns invalid_blocks with little detail. Common causes are exceeding 50 blocks in a message, a text field over 3,000 characters, more than 5 buttons in an actions block, or a missing required field on an element. Validate structures in Slack's Block Kit Builder before shipping - it catches these instantly, and the API does not.

7. Four tokens that look similar and do different jobs

A share of "my bot is not responding" reports trace back to the right code holding the wrong kind of token. Slack issues several, and they are only distinguishable by their prefix:

The two mistakes worth watching for: a Socket Mode connection that refuses to open despite a correct bot token is almost always missing the separate xapp- app-level token with connections:write, and a script that copies whichever token is closest at hand from the dashboard tends to grab the user token by accident, since it is listed right next to the bot token under OAuth & Permissions. Both look, superficially, like a OAuth scope problem, and neither is fixed by adding scopes.

Confirm which token you are actually holding

Rather than guessing from the prefix, call auth.test with the token in question:

curl -X POST https://slack.com/api/auth.test \
  -H "Authorization: Bearer YOUR_TOKEN"

The response identifies exactly what the token is - the workspace (team), the bot or user it belongs to (user_id, bot_id if applicable), and whether it is even valid. This is the fastest way to confirm a "permission denied" report is really a wrong-token report before you spend time auditing scopes that were never the problem. It is a single cheap request worth running before anything else in this section, and it takes less time than reading this paragraph.

8. Workspace installs, org-wide apps and admin approval

A bot that works in your development workspace and cannot be installed - or installs and sees nothing - in a customer's workspace is usually hitting an administrative control rather than a technical one.

App approval is on by default in many organisations

Workspace admins can require approval before any app is installed. Your OAuth flow completes, the user sees "request sent to your admin", and nothing works until someone approves it. There is no technical workaround - the install genuinely has not happened. If you distribute a Slack app, your onboarding needs to account for this delay explicitly rather than assuming installation is instant.

Org-wide installs behave differently from workspace installs

In Slack Enterprise Grid, an app can be installed to a single workspace or org-wide across many. Org-wide installs return a different token context, and code that assumes one team_id per token breaks - events arrive with varying team identifiers and API calls need the right context. If your app is only ever used in one workspace this never surfaces; the first Enterprise Grid customer surfaces it immediately.

Token storage for multi-workspace apps

A distributed app receives a distinct bot token per installation. Hardcoding a single token from your own workspace - which works throughout development - fails the moment a second workspace installs. Store tokens keyed by team_id (and enterprise_id for Grid) and look up the right one per incoming event.

Token rotation

Apps with token rotation enabled receive tokens that expire and must be refreshed with a refresh token. If your app worked for hours and then began returning token_expired, rotation is enabled and you are not refreshing. Either implement the refresh flow or disable rotation if your security posture allows.

A note on Slack Connect channels

Shared channels with external organisations impose extra restrictions. Bots may not see all messages in a Slack Connect channel, and some API methods behave differently. If your bot works in internal channels and misses messages in a shared one, this is why - and it is a platform constraint rather than a configuration you can change.

Where Slack shows up as a real support channel

Internal Slack bots absorb this guide's failure modes as a one-time cost - fix the scopes and reinstall once, and the bot mostly stays fixed. The calculation is different when Slack is a customer-facing or department-facing support surface rather than a hobby integration, because every new workflow risks reopening the scope-and-reinstall cycle. Slack shows up this way most often in tech companies routing product and engineering questions, HR teams fielding policy and benefits questions where our guide to Slack and Teams employee support covers the conversation design side, government agencies running internal case coordination, and manufacturing teams using it for shift and maintenance coordination. If the workflow is IT ticketing specifically, Slack IT support is the more direct read, and Slack chatbots for business covers the broader case for the channel.

Slack is not the only workplace chat platform with this exact list of failure modes - Microsoft Teams has its own version, covered in Teams chatbots for HR, and a business running both ends up maintaining two independent scope-and-webhook lifecycles for the same underlying conversation.

When the plumbing stops being worth it

Everything above is transport work: challenge handshakes, OAuth scope lifecycles, event subscription matrices, acknowledgement deadlines, retry deduplication, rate pacing. It is the same list for every Slack app ever built, and none of it is your product.

That is a reasonable investment for an internal tool. It is a poor one when Slack is one of several channels you are expected to keep alive, because each platform has a completely different version of the same list. Which channels are worth keeping alive at all is the subject of our channel strategy guide, and our guides to Telegram bots not responding, Discord bots not responding and chat widgets not showing on a website exist precisely because those lists share nothing with this one. Our guide to chatbot API rate limiting goes deeper on the pacing problem than any single platform's docs will.

Conferbot's Slack integration is on the Business plan and handles installation, scopes, event delivery and acknowledgement timing for you. You build the conversation once in a visual flow editor and the same flow runs on Microsoft Teams, Telegram, WhatsApp, Discord and a website widget, with formatting adapted per platform. Conversations can push data out through Conferbot's built-in integrations - Webhook, Zapier, Slack, Mailchimp, Stripe, SalesForce, HubSpot, Google Sheets, Airtable, Calendly and Google Calendar - or through the API directly. If you would rather expose your own systems to the bot as callable tools, the chatbot MCP server guide covers that pattern.

Start free with Conferbot - 600 conversations a month, no credit card. If you are debugging today, run the checklist above first; if you are about to write this plumbing for a third platform, that is the signal to stop.

Running the same bot inside Microsoft Teams? The failure list there is different again - manifest IDs, expiring client secrets, tenant policies and the @mention rule - and it is covered in our Microsoft Teams bot not responding guide.

FAQ

Why does Slack say my URL didn't respond with the value of the challenge parameter?

Slack POSTs a url_verification payload containing a challenge string, and your endpoint must echo that value back within about 3 seconds. The usual cause is signature-verification or authentication middleware running first and rejecting the request - handle url_verification as the very first statement in your handler. Slack also does not follow redirects during verification, so register the final URL rather than one that 301s.

How do I fix a Slack missing_scope error?

The error response names exactly what you need in its needed field. Add that scope under OAuth & Permissions, then reinstall the app to the workspace and use the newly issued token. Adding a scope without reinstalling changes nothing, because the token you already hold was issued with the old scope set - this is the most common Slack integration mistake.

Why is my Slack bot not receiving any events?

Check four things in order: that you actually subscribed to bot events rather than only verifying the URL; that you subscribed to the right message event, since public channels, private channels and DMs are separate subscriptions; that the bot has been invited to the channel with /invite @yourbot; and that Socket Mode is off, because it overrides your request URL entirely.

Why does my Slack bot work in channels but not in DMs?

Message events are split by conversation type and each is a distinct subscription. You need message.im for direct messages alongside message.channels for public channels, plus the im:history and im:write scopes. Subscribing to message.channels alone gives you exactly this symptom.

Why does my Slack bot send the same message multiple times?

Your handler is not returning HTTP 200 within Slack's 3-second window, so Slack retries up to three times and your code processes the event each time. Acknowledge immediately with res.sendStatus(200) and do the work afterwards. Also check the X-Slack-Retry-Num header and skip reprocessing when it is present, and deduplicate on event_id.

What does Slack error not_in_channel mean?

The bot is trying to post to a channel it has not joined. Invite it with /invite @yourbot in that channel. The chat:write.public scope allows posting to public channels without an invite, but it does not let the bot read them - you still need it in the channel to receive messages.

What is the difference between Socket Mode and the Events API in Slack?

Socket Mode delivers events over a WebSocket your app opens outbound, requiring no public endpoint, which makes it ideal for local development and firewalled environments. The Events API POSTs to a public HTTPS request URL. They are mutually exclusive - with Socket Mode enabled, Slack ignores your request URL completely, which catches out teams who enable it for development and forget to disable it before deploying.

Which scopes does a Slack chatbot need?

At minimum chat:write to send messages and app_mentions:read to receive mentions. Add im:history and im:write for direct messages, channels:history for public channel messages, groups:history for private channels (a separate scope), users:read to resolve names, and chat:write.public to post to public channels without an invite.

Why is my Slack bot replying to itself in a loop?

Bot messages generate message events too. Add if (event.bot_id || event.subtype === 'bot_message') return; as the first line of your handler. Without it the bot replies to its own reply indefinitely until Slack rate limits it, and two unguarded bots in one channel will generate thousands of messages in seconds.

What does channel_not_found mean in Slack?

Usually a channel name used where an ID was required - Slack channel IDs look like C01ABCDEF, and #general does not work in every endpoint. Store IDs rather than names, since names change and IDs do not. The same error also appears for private channels the bot has not been invited to, because it genuinely cannot see them.

How long does a Slack app have to respond to an event?

Three seconds to return HTTP 200. For slash commands and interactive components you can respond immediately with a placeholder and then update it using the response_url, which remains valid for 30 minutes and accepts up to five follow-up messages. Any handler that calls an AI model will exceed 3 seconds, so acknowledge first as a matter of course.

What are Slack API rate limits for posting messages?

Slack rate limits per method in tiers, and chat.postMessage is generally around one message per second per channel with short bursts tolerated. Exceeding it returns HTTP 429 with a Retry-After header in seconds, which you should honour exactly rather than retrying immediately.

The full guide, with diagrams and the latest checks, is at https://www.conferbot.com/blog/slack-bot-not-responding.

First, separate the two symptoms - they have nothing in common

"Bot offline" and "bot online but silent" are completely different failures. Fixing one will never fix the other, and most wasted debugging time comes from treating them as the same problem.

Last verified: August 2026 against the Discord Developer Portal and Gateway API. Error codes quoted are the literal values Discord returns.

If your bot is green and ignoring messages, skip straight to the next section. That is the single most common Discord bot problem, and it has one cause. If instead you have a literal error code in hand, the Discord error-code directory maps every JSON error and gateway close code to its fix.

Check the invite as well: if the bot is online but cannot post or moderate, paste its invite link into the Discord permissions calculator to see exactly which permissions it was added with. The Message Content intent is a separate switch in the Developer Portal, not a permission.

1. The Message Content intent - the cause of most silent bots

Since Discord's 2022 privacy changes, message content is a privileged intent. Without it, your bot still receives every MESSAGE_CREATE event, but the content field arrives as an empty string. Your command matching compares "" against "!help", finds no match, and does nothing - with no error, no exception and no log line.

That silence is what makes this so hard to diagnose. The bot is connected, events are flowing, your handler is running. It just cannot see what anyone typed.

The fix requires two changes, and people usually only make one

Step 1 - enable it in the portal. Go to the Discord Developer Portal, open your application, select Bot in the sidebar, scroll to Privileged Gateway Intents, and toggle on Message Content Intent. Save.

Step 2 - request it in your code. The portal toggle grants permission; your gateway connection must still ask for it. In discord.js:

const { Client, GatewayIntentBits } = require('discord.js');

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,   // the one people forget
  ],
});

In discord.py:

import discord

intents = discord.Intents.default()
intents.message_content = True          # the one people forget

client = discord.Client(intents=intents)

Step 3 - restart the process. Intents are negotiated when the gateway connection is established. Changing the portal toggle while the bot is running has no effect until it reconnects. A surprising number of "I enabled it and it still doesn't work" reports are just a bot that was never restarted.

Three privileged intents, and what each unlocks

The 100-server wall

Once a bot reaches 100 servers it must be verified to continue using privileged intents. If you are approaching that number, apply early - verification is a manual review and takes time. Unverified bots are capped at 100 servers (the API refuses further joins with error 30001), and privileged intents need approval once a bot reaches the review threshold - Discord's docs currently phrase it as more than 10,000 unique users, older guidance said 100 servers. Crossing that line without approval means the intents switch off and the bot goes silent for its entire user base at once, which is a memorable way to discover this rule.

Or sidestep it: use slash commands

Slash command interactions deliver their arguments directly in the interaction payload, so they work without the Message Content intent at all. If your bot only needs explicit commands rather than reading ambient conversation, migrating from prefix commands to slash commands removes this entire problem - and removes the 100-server verification requirement along with it.

2. Gateway error 4014: disallowed intents

If the bot never comes online and the connection drops immediately, check for this close code:

Gateway closed: 4014 - Disallowed intent(s)

This is the exact inverse of the previous section: your code is requesting a privileged intent that the portal has not granted. Discord refuses the connection outright rather than downgrading it. The gateway 4014 reference page has the library-specific fixes.

Two fixes, depending on what you actually need:

• Enable the intent in the Developer Portal (Bot -> Privileged Gateway Intents), or
• Remove it from your intents list in code if the bot does not genuinely require it

The frequent trigger is copying a starter template that requests Intents.all() or every GatewayIntentBits value. That works on a fresh unverified bot only if you have toggled all three privileges on. Request the minimum set your features need - it connects more reliably and delays the verification requirement.

The neighbouring close codes

Note the difference between 4013 and 4014: 4013 means the value is not a real intent, 4014 means it is real but you are not allowed it. If you are constructing the bitfield by hand, stop - use the library's named constants.

3. Token invalid, and the Git commit that killed it

Close code 4004 or an immediate Improper token has been passed means the token is bad. Beyond the usual copy-paste errors, one cause is worth calling out because it produces a bot that worked yesterday and does not today:

Discord automatically invalidates tokens it finds in public repositories. Their scanner monitors GitHub and other public sources. Commit your token, and it stops working - often within minutes, with no notification beyond an email to the application owner. If your bot died suddenly and nothing changed on your side, check whether the token reached a public repo, a Pastebin, a screenshot in a support thread, or a Discord message in a public channel.

The remedy is the same either way: regenerate the token in the Developer Portal, move it into an environment variable or secrets manager, and add the file that held it to .gitignore. Regenerating immediately invalidates the previous token, so redeploy everywhere at once or you will have half your instances failing.

Other reliable token failures:

• Client secret used instead of bot token. They are different strings on adjacent pages of the portal. The client secret is for OAuth flows and will never authenticate a gateway connection.
• The Bot prefix. The Authorization header needs Bot <token> with a space. Most libraries add this for you - if you are calling the REST API directly with fetch or curl, you must add it yourself.
• Trailing newline from a secrets file. Trim the value before use.

4. Missing Permissions (50013) and Missing Access (50001)

Your bot is online, receiving events, and its replies never appear. The API is almost certainly returning:

{"message": "Missing Permissions", "code": 50013}
{"message": "Missing Access", "code": 50001}

Discord permissions resolve through several layers, and a bot can hold a permission at server level while being denied it in the exact channel where you are testing:

1. @everyone server-wide permissions
2. Permissions from each role the bot holds
3. Channel-level overwrites - these override the above and are where the problem usually lives
4. Category overwrites, inherited by channels that sync with the category

A single deny on a channel overwrite beats any allow granted higher up. Denies win. The 50013 reference page walks the overwrite layers in order. 50001 is the channel-visibility version of the same problem and has its own page at Missing Access.

Check it the fast way

Server Settings -> Roles -> select your bot's role -> the permission list shows server-wide grants. Then right-click the specific channel -> Edit Channel -> Permissions, and look for the bot's role or the bot itself with a red X.

The permissions a conversational bot needs in each channel it works in:

• View Channel - without it the bot cannot see the channel exists
• Send Messages - the obvious one
• Read Message History - required to reply to a specific message
• Embed Links - rich embeds are silently dropped without it
• Attach Files - only if you send images or documents
• Use External Emojis - if your replies use emojis from other servers

The role hierarchy rule

A bot can only manage roles below its own highest role in the list. A moderation bot that cannot assign a role, kick a member or add a nickname is usually positioned too low in Server Settings -> Roles. Drag the bot's role above the roles it needs to manage. This produces the specific symptom of a bot that moderates most members successfully and fails on the ones with elevated roles.

Threads and forums are separate

Sending in a thread requires Send Messages in Threads, which is a distinct permission from Send Messages. A bot that works in a normal channel and fails in a thread has hit exactly this. Archived threads must also be unarchived before a message can post to them.

5. Slash commands that never appear

Registered commands that do not show in the client have three usual causes, in this order.

The applications.commands scope was missing from the invite

This is the big one, and it is invisible after the fact. If you invited the bot with a URL that requested only the bot scope, the server never authorised it to register slash commands - and no amount of re-registering fixes it. Your invite URL needs both:

https://discord.com/api/oauth2/authorize?client_id=YOUR_ID&permissions=YOUR_PERMS&scope=bot%20applications.commands

The fix is to re-invite the bot using a URL that includes applications.commands. You do not need to kick it first - visiting the corrected URL and re-authorising adds the missing scope to the existing installation.

Global commands take up to an hour

Global commands propagate across Discord's infrastructure and can take up to one hour to appear. Guild-scoped commands register instantly. During development, always register to a single test guild - otherwise you will spend an afternoon convinced your registration code is broken when it worked the first time.

// Instant - use during development
await rest.put(Routes.applicationGuildCommands(clientId, testGuildId), { body: commands });

// Up to 1 hour - use for production release
await rest.put(Routes.applicationCommands(clientId), { body: commands });

Command permissions are restricting visibility

Server admins can restrict which roles and channels a command appears in, via Server Settings -> Integrations -> your bot. A command that is invisible to regular members but visible to you as an admin has been restricted here, not broken in code.

The 3-second interaction deadline

A separate and very common failure: you must acknowledge an interaction within 3 seconds or Discord shows "The application did not respond" and the interaction token becomes invalid. Any bot that calls an AI model, queries a database or hits an external API will exceed this.

Defer immediately, then follow up:

await interaction.deferReply();          // buys you up to 15 minutes
const answer = await callSlowThing();    // now take your time
await interaction.editReply(answer);

This single pattern accounts for most "my AI bot says it did not respond but the logs show it worked" reports.

6. DMs, mentions and the events you are not subscribed to

Guild messages and direct messages arrive through different intents. A bot subscribed to GuildMessages but not DirectMessages works perfectly in servers and ignores every DM:

intents: [
  GatewayIntentBits.Guilds,
  GatewayIntentBits.GuildMessages,
  GatewayIntentBits.DirectMessages,     // separate subscription
  GatewayIntentBits.MessageContent,
]

Two more DM-specific rules catch people out:

• Users can block DMs from server members in their privacy settings. Sending to someone with this enabled returns Cannot send messages to this user (code 50007). There is no way to detect this in advance and no workaround - it is a user preference.
• In discord.js, DM channels may need partials enabled to receive events for channels that were not cached at startup. Without Partials.Channel, DMs from users the bot has not interacted with in that session can be missed.

Mention matching that fails on nicknames

If your bot responds to being @-mentioned, do not string-match the mention text. When a user has a server nickname, the mention renders differently, and matching on <@123456> will miss <@!123456>. Use the library's mention helper - message.mentions.has(client.user) in discord.js - which handles both forms.

The infinite loop guard

Always ignore messages from bots, including your own, as the first line of your handler:

if (message.author.bot) return;

Without it, a bot that replies to messages will reply to its own reply, forever, until Discord rate limits it. Two bots in the same channel without this guard will do it to each other and generate thousands of messages in seconds.

7. Rate limits, reconnect loops and sharding

Discord returns 429 with a retry_after value in seconds. Well-maintained libraries queue and retry automatically, so if you are seeing raw 429s you are probably calling the REST API directly.

Two limits matter more than the general one (the full set of REST, gateway and interaction ceilings is on the Discord limits page):

• Global: around 50 requests per second across your whole application.
• Per route: tighter and specific. Message sends in a single channel are limited to roughly 5 per 5 seconds, which is easy to hit with a bot that splits replies into several bubbles.

Exceeding limits repeatedly can trigger a Cloudflare ban at the IP level, which returns HTML rather than JSON and lasts an hour or more. If your bot suddenly gets unparseable responses from the API, this is why - and it usually follows a reconnect loop.

Identify limits and the crash loop

Gateway identifies are limited to roughly 1,000 per day. A bot crash-looping on startup - throwing an exception after connecting, being restarted by the supervisor, connecting again - burns through that budget and gets locked out of connecting entirely. If a bot has been failing all day and now cannot connect at all even after the bug is fixed, wait for the daily reset.

Sharding at 2,500 guilds

Bots in 2,500 or more guilds must shard. Discord refuses the connection otherwise. Most libraries provide a sharding manager that handles this, but it is a deliberate step you have to take - it does not happen automatically as you grow.

8. HTTP interactions: the other way a bot can go silent

Everything above assumes your bot holds a persistent WebSocket connection to the gateway, which is how discord.js and discord.py work by default. Discord also supports a second, gateway-free transport for slash commands: an Interactions Endpoint URL, configured under General Information in the Developer Portal. Instead of pushing interaction payloads down a socket, Discord POSTs each one to your HTTPS endpoint - the same shape as a webhook. Bots built on serverless functions often use this so they never need a long-running process.

This path fails differently, and more silently, than a gateway disconnect.

The PING/PONG handshake

The moment you save an Interactions Endpoint URL, Discord sends a synthetic PING payload (type: 1) to it and expects a 200 response containing a PONG (also type: 1) within a few seconds. Fail that check and Discord refuses to save the URL at all - there is no partial state where the field is set but broken, so if your endpoint field is empty, this handshake is what rejected it.

Signature verification, not a bearer token

Every request Discord sends to an interactions endpoint carries X-Signature-Ed25519 and X-Signature-Timestamp headers. You must verify them - by concatenating the timestamp with the raw request body and checking the Ed25519 signature against your application's public key - before parsing the JSON. Skipping this, or verifying against the parsed body instead of the raw bytes, produces a rejected handshake that looks identical to a network problem. Discord deliberately sends malformed test requests to confirm you are actually checking the signature rather than always returning 200.

Because this endpoint only ever carries interactions - never raw MESSAGE_CREATE events - a bot built entirely on it can never read prefix commands, regardless of intents. If you switched to this transport and prefix commands stopped working while slash commands kept working, that is expected, not a regression. It is also the same 3-second acknowledgement deadline as the gateway path: return a DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE response type immediately if the real answer needs an API call or model inference.

If the endpoint fails Discord's validation and you are not sure whether the fault is the Ed25519 check, the PING handler or the network in front of it, our webhook debugging guide has a platform-neutral order for isolating which of the three it is.

Running Discord as a support or sales channel, not just a community server

Most of this guide describes problems that show up whether the bot is a hobby project or a revenue channel. But the two use it very differently. A community bot can absorb an afternoon of gateway debugging as a side quest; a business relying on Discord for support, onboarding or sales cannot, because every hour spent on intents and close codes is an hour not spent on the conversation itself.

Discord shows up as a real support and community surface across a specific set of industries more than others: education, where servers double as course cohorts and study groups; media and creator businesses, where a server is the primary fan community; tech companies, where Discord has become the default place developer communities live; and nonprofits, who use it as a low-cost volunteer and donor hub. If community moderation and growth - rather than transport debugging - is the actual problem you are solving, our guide to Discord bot community management is the more relevant next read.

What changes when you stop hand-rolling the transport

Conferbot's Discord integration is on the Pro plan and up, and it removes every failure mode in this guide from your side of the line: gateway connection, intent negotiation, permission checks and interaction deadlines are handled by the platform, so a flow change is a visual edit rather than a redeploy. Conversations can also branch out to real systems through Conferbot's fixed integration set - Webhook, Zapier, Slack, Mailchimp, Stripe, SalesForce, HubSpot, Google Sheets, Airtable, Calendly and Google Calendar - or through the raw API if you need something the built-in integrations do not cover. There is no bring-your-own retrieval pipeline and no canned-response library bolted on; a flow is a flow, and it runs the same way on Discord as it does everywhere else it deploys.

The invite URL that grants a bot the applications.commands scope is itself an OAuth 2.0 authorization request - the same protocol Slack, Google and most SaaS integrations use for delegated access, which is worth knowing if you are debugging why a scope change did not take effect: like Slack, some scope changes require the authorization to be redone, not just re-saved.

The diagnostic order that finds it fastest

Step 3 is the one to reach for first when the bot is online. Printing message.content and seeing an empty string is the definitive confirmation of the intents problem, and it takes ten seconds to check.

When to stop maintaining the plumbing

Everything above is transport-layer work: intent negotiation, gateway close codes, permission resolution, interaction deadlines, shard counts, rate limiting, identify budgets. None of it is your product. It is the toll for operating the Discord API directly, and it is the same toll for every bot on the platform - our guides to Telegram bots not responding and Slack bots not responding exist because those platforms make you pay an entirely different version of the same tax, and our piece on API rate limiting covers the pacing problem in more depth than any single-platform guide can.

That is a fine trade for a community bot you enjoy building. It is a worse one when Discord is a support or sales channel for a business, and considerably worse when Discord is one of several channels you are expected to keep alive - because each platform has an entirely different version of this same list. If your visitors also reach you through a website, the same class of debugging shows up there too; see our guide to a chat widget not showing on your website when that is the channel giving you trouble.

Conferbot's Discord integration handles connection, intents, permissions and interaction deadlines for you: you connect the bot and build the conversation in a visual flow editor rather than in gateway code. The same flow runs on Telegram, WhatsApp, Slack and a website widget, with buttons and media adapting to each platform automatically.

Start free with Conferbot - the free plan includes 600 conversations a month and needs no credit card, so you can have the same flow running on a second channel this afternoon.

If you are debugging today, work the table above - if the bot is online and silent, it is the Message Content intent far more often than anything else. If you are on your third channel and writing the same plumbing a third time, that is the signal to stop.

FAQ

Why is my Discord bot online but not responding to commands?

Almost always the Message Content intent. Since 2022 it is a privileged intent, and without it your bot still receives message events but the content field arrives empty, so command matching silently never matches. Enable Message Content Intent in the Developer Portal under Bot -> Privileged Gateway Intents, add it to your intents array in code, and restart the process - all three steps are required.

How do I fix Discord gateway error 4014?

Error 4014 means Disallowed intent(s): your code requests a privileged intent that is not enabled in the Developer Portal. Either enable that intent under Bot -> Privileged Gateway Intents, or remove it from your intents list if the bot does not need it. It is commonly caused by copying a template that requests Intents.all().

What is the difference between Discord gateway errors 4013 and 4014?

4013 means Invalid intent(s) - the bitfield contains a value that is not a real intent, usually from hand-computing the number. 4014 means Disallowed intent(s) - the intent is real but your application has not been granted it in the Developer Portal. Use your library's named intent constants to avoid 4013 entirely.

Why does my Discord bot send no messages despite being online?

The API is likely returning code 50013 Missing Permissions or 50001 Missing Access. Channel-level permission overwrites beat server-wide role grants, so a bot can hold Send Messages at server level and be denied it in the specific channel you are testing. Check the channel's permission settings for a red X against the bot's role.

Why don't my slash commands appear in Discord?

Three usual causes. The invite URL omitted the applications.commands scope, so the server never authorised command registration - re-invite with scope=bot%20applications.commands. Or you registered globally, which takes up to an hour to propagate; register to a test guild during development for instant results. Or a server admin restricted the command under Server Settings -> Integrations.

What does "The application did not respond" mean in Discord?

Your bot did not acknowledge the interaction within Discord's 3-second deadline, so the interaction token expired. Call deferReply() immediately on receiving the interaction, which extends your window to 15 minutes, then send the real answer with editReply(). This is the standard fix for any bot that calls an AI model or external API.

Do I need the Message Content intent for slash commands?

No. Slash command arguments arrive in the interaction payload itself, so slash commands work without the Message Content intent entirely. Migrating from prefix commands to slash commands removes this problem and also avoids the privileged-intent verification requirement at 100 servers.

Why did my Discord bot token suddenly stop working?

Discord scans public sources including GitHub and automatically invalidates any bot token it finds. If your bot died with no change on your side, check whether the token reached a public repo, a screenshot, or a public message. Regenerate the token, move it into an environment variable, and redeploy everywhere at once since regenerating invalidates the old one immediately.

Why can't my Discord bot assign roles?

Role hierarchy. A bot can only manage roles positioned below its own highest role in Server Settings -> Roles. If it moderates most members successfully but fails on those with elevated roles, drag the bot's role above the roles it needs to manage. The bot also needs the Manage Roles permission itself.

Why does my Discord bot work in servers but ignore DMs?

Guild messages and direct messages use separate intents. Add GatewayIntentBits.DirectMessages alongside GuildMessages. In discord.js you may also need Partials.Channel to receive events for DM channels that were not cached at startup. Note that users can also block DMs from server members, which returns error 50007 with no workaround.

When does a Discord bot need to be verified?

At 100 servers. Beyond that, privileged intents require verification, which is a manual review - apply early, because a bot that reaches 100 servers unverified loses privileged intents and goes silent for its entire user base at once. Separately, bots in 2,500 or more guilds must implement sharding.

Why is my Discord bot repeating itself in a loop?

It is responding to its own messages. Add if (message.author.bot) return; as the first line of your message handler. Without that guard a bot replies to its own reply indefinitely until Discord rate limits it, and two unguarded bots in one channel will generate thousands of messages in seconds.

The full guide, with diagrams and the latest checks, is at https://www.conferbot.com/blog/discord-bot-not-responding.

Start here: one command tells you which half of the problem you have

Before you change any code, call getWebhookInfo. Its response splits every "bot not responding" problem into two families, and the fix is completely different for each.

Last verified: August 2026 against the Telegram Bot API. Error strings quoted below are the literal responses the API returns.

Open this in a browser, replacing <TOKEN> with your bot token:

https://api.telegram.org/bot<TOKEN>/getWebhookInfo

Read the url field in the JSON that comes back:

Two more fields in that response are worth more than an hour of debugging:

• pending_update_count - if this number is large and climbing, Telegram has updates for you and nothing is collecting them. Your bot is not being ignored by Telegram; your bot is not listening.
• last_error_message - if this is populated, Telegram tried to deliver and your server rejected it. The message is usually blunt and correct: Connection refused, SSL error, Wrong response from the webhook: 502 Bad Gateway.

The rest of this guide walks the nine causes in rough order of how often they actually turn out to be the answer. If you have a literal error string in hand, the Telegram error-code directory maps each one to its fix.

Fastest first check: the Telegram webhook checker reads getWebhookInfo for you, explains pending_update_count and the last delivery error in plain English, and can reset or delete the webhook from your browser. If the bot answers but in the wrong chat, the chat ID finder lists every chat it can see.

1. The 409 conflict: getUpdates and webhook cannot coexist

The exact error is:

{"ok":false,"error_code":409,"description":"Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first"}

Telegram permits exactly one consumer of updates per bot token. You either poll with getUpdates or you receive pushes at a webhook. Never both. When a webhook is registered and your code starts polling, the poll fails with 409 and your bot goes silent - even though the process is running and the logs may look healthy, because many libraries swallow this error and retry forever. The 409 reference page covers this variant on its own.

To switch to polling, remove the webhook first:

https://api.telegram.org/bot<TOKEN>/deleteWebhook?drop_pending_updates=true

The drop_pending_updates=true parameter matters more than people expect. Without it, every message queued while the bot was down gets delivered the instant you start polling. A bot that was offline for two days will replay two days of conversations at once, sending welcome messages and notifications to people who moved on long ago. Include the flag unless you specifically want the backlog.

The variant nobody expects: two copies of your own bot

A 409 also appears with a different description when two processes poll the same token:

Conflict: terminated by other getUpdates request; make sure that only one bot instance is running

This is the classic symptom of a bot that responds to roughly half the messages, seemingly at random. Two instances are both long-polling; each message goes to whichever one happened to be holding the connection. Common sources: a local dev process still running while production is live, a container that was scaled to 2 replicas, a nodemon or watchdog restart that left the old process alive, or a free-tier host that spun up a second dyno.

Polling does not scale horizontally. If you need more than one instance, you need webhooks and a load balancer in front of them. The two-process variant has its own page at terminated by other getUpdates request.

2. Privacy mode: why the bot works in DMs but ignores your group

If your bot replies fine in a one-to-one chat but is completely silent in a group, privacy mode is the cause about nine times out of ten.

By default, a bot added to a group receives only a narrow slice of messages:

• Messages that start with a slash command (/start, /help)
• Messages that explicitly @-mention the bot
• Replies to one of the bot's own messages
• Service messages (people joining, leaving, being promoted)

Everything else - ordinary conversation between members - is never delivered to your bot at all. This is a deliberate privacy protection, not a bug, and it means no amount of code fixing will help. Your handler is correct; the update never arrives.

To turn it off, talk to @BotFather:

/setprivacy  ->  select your bot  ->  Disable

Then comes the step that trips up most people: the change does not apply to groups the bot is already in. You must remove the bot from the group and re-add it. Until you do, it keeps operating under the privacy setting that was active when it joined.

One alternative is worth knowing: promoting the bot to group admin also grants it visibility of all messages, regardless of the privacy setting. If you cannot re-add the bot for social reasons - a large community that would notice - promoting it to admin achieves the same result.

The command-suffix trap in groups

In a group containing more than one bot, Telegram clients append the bot username to commands: a user tapping /help actually sends /help@YourBotName. Handlers matching the literal string /help will not fire. Match on the command prefix and strip anything after @, or use a framework helper that normalises this for you. This produces the specific and confusing symptom of a bot that works in a test group and fails in the real one.

3. The webhook is set, and quietly failing every delivery

When getWebhookInfo shows a URL plus a populated last_error_message, Telegram is doing its job and your endpoint is refusing the handoff. The messages are terse but accurate. Here is what each one actually means.

Four webhook rules that are easy to violate

Telegram is strict about webhook endpoints in ways that other platforms are not:

• HTTPS only. A plain HTTP URL is rejected at registration time. There is no development exception.
• Only four ports. 443, 80, 88 and 8443. A webhook on port 3000 will never be called, and Telegram will not warn you clearly about why - the registration error is Bad webhook: webhook can be set up only on ports 80, 88, 443 or 8443.
• Self-signed certificates require an upload. You must supply the public certificate with the setWebhook call. A self-signed cert without the upload fails every delivery.
• Respond fast, and respond 200. Any non-2xx counts as a failure and triggers a retry with backoff. Retries mean duplicate processing, which is why users sometimes receive the same reply three times.

The pattern that prevents timeout failures

The single most valuable structural change you can make is to stop doing work inside the webhook handler. Acknowledge, then process:

app.post('/telegram-webhook', (req, res) => {
  res.sendStatus(200);        // acknowledge first, always
  queue.push(req.body);       // then do the slow part off the request path
});

A handler that calls an LLM, queries a database and hits a CRM before responding will exceed Telegram's patience under load. Telegram retries, your bot double-replies, and the failure looks intermittent and impossible to reproduce - because it only happens when the downstream call is slow.

The four-port rule and the file-size limit both trace back to one thing

The port restriction (443, 80, 88, 8443) and the fact that a bot can only send files up to 50MB and download files up to 20MB both come from the same source: by default your bot talks to Telegram's shared cloud Bot API server, and that server enforces both limits for every bot on it. Telegram also publishes the Bot API server itself as software you can run yourself. A self-hosted local Bot API server lifts the port restriction entirely - webhooks can use any port - and raises the file-size ceiling to roughly 2000MB in each direction. It is a meaningful operational step up from calling api.telegram.org directly, and it is only worth taking if large media or the port restriction is an actual blocker, not a default choice.

Everything in this section - unreachable hosts, certificate chains, slow handlers, the raw-body signature trap - has an equivalent on Meta, Slack and Discord; our webhook not firing debugging guide covers the shared causes and the one debug order that finds them.

4. 403 Forbidden: the user blocked your bot, or never started it

Two 403 responses look similar and mean different things:

{"ok":false,"error_code":403,"description":"Forbidden: bot was blocked by the user"}
{"ok":false,"error_code":403,"description":"Forbidden: bot can't initiate conversation with a user"}

The first is exactly what it says. The user blocked you. There is no recovery path and no API to check block status in advance - the send attempt is the check. The correct response is to mark that chat inactive in your database and stop sending (the bot was blocked by the user page has the handling pattern). Bots that keep retrying blocked users burn rate limit on messages that will never arrive.

The second is a rule people meet the first time they try to build a notification system: a Telegram bot can never message someone first. The user must initiate by sending /start, or by tapping a deep link. If you have a phone number or a user ID from elsewhere, that is not enough - Telegram requires the user to opt in inside Telegram itself.

The standard pattern is a deep link that carries your own identifier:

https://t.me/YourBotName?start=user_12345

When the user taps it, your bot receives /start user_12345, and you can map their Telegram chat ID to your internal user record. From that moment you are allowed to send. This is the same opt-in model most platforms use, and it is why a Telegram notification flow always begins with a link rather than a phone number. Hand-building these links is easy to get wrong - a stray space or an unencoded character breaks the parameter silently - so a small Telegram link generator that produces the correctly formatted ?start= URL for you is worth using rather than concatenating strings by hand, especially once the link is going into a QR code or an email template where you cannot easily eyeball it.

5. Rate limits: the bot that works in testing and dies at launch

A bot that answered every message during development and started dropping replies the day it launched is usually hitting rate limits, not bugs. Telegram's published guidance for bots (the full set of ceilings is on the Telegram limits page):

When you exceed a limit the API returns 429 with a retry_after value in seconds:

{"ok":false,"error_code":429,"description":"Too Many Requests: retry after 34","parameters":{"retry_after":34}}

Honour retry_after exactly - the 429 reference page covers the back-off rules. Retrying sooner extends the penalty, and sustained abuse can get a token limited for far longer than the number suggests. The fix for broadcasts is a token-bucket queue that paces sends below 30/second rather than a loop that fires as fast as the network allows.

A subtler version affects conversational bots: sending three quick bubbles to feel human - a greeting, then a question, then a menu - can trip the per-chat limit for that user. Insert a short delay between bubbles, which is also better conversation design, since three messages arriving in the same instant reads as a machine rather than a person.

Telegram also offers a paid path past the 30/second ceiling for bots that need genuine bulk broadcast volume: enabling paid broadcasts through BotFather raises the outbound cap to roughly 1,000 messages per second, billed per message above the free 30/second tier in Telegram Stars. That is a broadcast-scale feature, not something a conversational support bot needs - if you are hitting 30/second in normal use, the fix is almost always pacing or batching, not paying for more headroom.

6. Token problems, and the deploy that quietly used the wrong one

A malformed or revoked token returns:

{"ok":false,"error_code":401,"description":"Unauthorized"}

Verify the token in isolation before suspecting anything else - our Telegram bot token checker does the same getMe call from the browser:

https://api.telegram.org/bot<TOKEN>/getMe

A healthy token returns the bot's own username and ID. If getMe works from your laptop but the deployed bot returns 401, the token is fine and your environment variable is not - it is missing, truncated, or shadowed by another value.

Three failure modes account for most of these:

• A trailing newline. Tokens pasted into a secrets manager or a .env file often carry \n. Trim the value before use; the API rejects it and the error gives no hint about whitespace.
• Quotes included. TELEGRAM_TOKEN="123:ABC" in some shell and container setups produces a token that literally contains quote characters.
• The staging token in production. If you built a second bot for testing, both tokens are valid and both pass getMe. The bot responds - just not the one anyone is looking at. If users report silence while your logs show successful sends, check which bot the token belongs to.

Note also that regenerating a token via BotFather immediately invalidates the old one. If a bot stopped working the moment someone "rotated the key for security", that is your answer.

7. The bot sends nothing because the message itself is invalid

Some "not responding" reports are really "responding with an error you are not logging". The most common is a parse failure:

{"ok":false,"error_code":400,"description":"Bad Request: can't parse entities: Can't find end of the entity starting at byte offset 42"}

This happens when you set parse_mode to MarkdownV2 or HTML and the message body contains characters the parser treats as markup. MarkdownV2 is particularly unforgiving: it requires escaping for _ * [ ] ( ) ~ ` > # + - = | { } . !, including inside ordinary prose. A perfectly innocent sentence ending in a full stop will fail.

This is the classic cause of a bot that handles most messages and dies on specific ones - a customer whose name contains an underscore, a product code with a hyphen, an address with brackets. It looks intermittent; it is entirely deterministic.

Three practical defences:

• Escape all interpolated user content before inserting it into a formatted message. Never trust that a name or a search term is markup-safe.
• Prefer HTML parse mode over MarkdownV2. It needs only three escapes - &, <, > - which is far easier to get right.
• Log the full API response body, not just the status code. Telegram tells you the exact byte offset that failed, and that detail is lost if you only log "send failed".

The related error Bad Request: message is too long fires at 4,096 characters. AI-generated replies overrun this regularly, so split long responses on a paragraph boundary before sending rather than discovering the limit in production.

8. Chat not found, and other identifier mistakes

{"ok":false,"error_code":400,"description":"Bad Request: chat not found"}

This means the chat_id you sent does not correspond to a chat your bot can reach. In order of likelihood:

• You used a username where an ID was needed. A bot can address a public channel as @channelname, but private chats require the numeric ID.
• The group was upgraded to a supergroup. This changes the chat ID, and the old one stops working permanently. Telegram sends a migrate_to_chat_id field in an update when it happens - handle it and store the new ID, or your bot silently loses the group.
• Negative sign dropped. Group and channel IDs are negative, and supergroup IDs begin with -100. Storing a chat ID in a column that strips the sign, or as an unsigned integer, produces exactly this error.
• The bot was removed from the group and nobody updated the record.

A related trap: chat IDs can exceed 32 bits. Storing them in a 32-bit integer column truncates the value and produces "chat not found" for a subset of users - typically the newest ones, since IDs increase over time. Use a 64-bit integer or a string.

9. The bot responds, but users cannot find how to talk to it

A final category is not technically a failure. The bot works; nobody triggers it.

If you never called setMyCommands, Telegram's menu button shows nothing, and users are left guessing what to type. Registering commands makes them appear in the slash menu and in the blue menu button next to the input field:

https://api.telegram.org/bot<TOKEN>/setMyCommands?commands=[{"command":"start","description":"Start the bot"},{"command":"help","description":"Show what I can do"}]

Two related details matter for real usage:

• Clients cache the command list. After updating commands, the change can take a while to appear for users who already have the chat open. Test in a fresh client before concluding the call failed.
• Only /start is guaranteed. It is the one command every Telegram user knows to try, and it is what the deep link sends. Whatever else you build, /start should return a clear description of what the bot does and what to say next.

If your bot is genuinely conversational rather than command-driven, say so in the /start reply. Users default to hunting for commands, and a bot that accepts natural language but never says so gets far fewer conversations than it should.

The 5-minute diagnostic, in order

Run these in sequence. Most bots are fixed before step 4.

That last row deserves emphasis. A large share of "my bot mysteriously stopped responding" reports resolve the moment someone logs the response body instead of the status code. Telegram's error descriptions are unusually specific - they name the byte offset, the seconds to wait, the method to call. Code that catches an exception and logs "send failed" throws away the fix.

Where Telegram earns its place as a business channel

Telegram's low friction - no app review, instant deep links, a bot that can be built and deployed in an afternoon - is exactly what makes it attractive past the hobby-project stage, and exactly why the failure modes above start to cost more once real customers depend on the bot. Telegram shows up as a genuine support and sales channel most often in ecommerce, for order updates and abandoned-cart recovery where a deep link replaces an app install; logistics, where drivers and dispatchers already live in Telegram in many regions; education, running cohort announcements and Q&A alongside a course; media and publishing, distributing content and running reader communities; nonprofits, coordinating volunteers at low cost; and tech companies, where it is often the default support channel for a technical audience. Our longer guides to Telegram for business and Telegram bots for customer support cover the conversation and workflow side once the transport layer is no longer the problem.

Avoiding this class of problem entirely

Every cause above comes from operating the Bot API directly: you own the webhook lifecycle, the polling process, the retry semantics, the rate limiting, the escaping and the opt-in mapping. That is entirely reasonable for a hobby bot or a team with backend capacity to spare.

It is a poor trade when the bot is a support or sales channel for a business, because none of that work is differentiating. The webhook conflict, the parse-mode escaping and the token-bucket queue are the same problems for every bot on the platform - and every other chat platform makes you pay a version of the same tax under a different name, as our guides to Discord bots not responding, Slack bots not responding and chat widgets not showing on a website cover for their respective transports, and chatbot API rate limiting covers in general.

A managed platform handles the transport layer so the failure modes in this guide never reach you. With Conferbot's Telegram integration, available from the Pro plan up, you connect a bot token and build the conversation in a visual flow editor - webhook registration, retries, rate limiting and message formatting are handled for you. The same flow deploys to WhatsApp, Discord, Slack and a website widget without rewriting it per platform, and message formatting adapts to each one's capabilities automatically. Conversations can hand data off through Conferbot's built-in integrations - Webhook, Zapier, Slack, Mailchimp, Stripe, SalesForce, HubSpot, Google Sheets, Airtable, Calendly and Google Calendar - or through the API for anything more custom.

Start free with Conferbot - the free plan includes 600 conversations a month and needs no credit card, so you can have the same flow running on a second channel this afternoon.

If you are debugging a Telegram bot today, work the diagnostic table above first - the answer is usually in getWebhookInfo. If you find yourself rebuilding the same transport plumbing for a third channel, that is the point where a platform starts paying for itself.

FAQ

Why is my Telegram bot online but not responding to messages?

A bot showing online only means its token is valid - it says nothing about whether updates are reaching your code. The most common cause is a webhook registered against the token while your code polls with getUpdates, which returns a 409 conflict that many libraries silently retry. Call getWebhookInfo: if the url field is populated but you expect polling, run deleteWebhook. If pending_update_count is large and climbing, nothing is consuming updates at all.

How do I fix "Conflict: can't use getUpdates method while webhook is active"?

Call https://api.telegram.org/bot/deleteWebhook?drop_pending_updates=true and restart your bot. Telegram allows only one update consumer per token, so a registered webhook blocks polling entirely. Include drop_pending_updates=true unless you want every message queued while the bot was down to replay at once.

Why does my Telegram bot work in private chat but not in groups?

Privacy mode. By default a bot in a group only receives slash commands, @-mentions, replies to its own messages, and service messages - ordinary conversation is never delivered. Disable it with /setprivacy in @BotFather, then remove the bot from the group and re-add it, because the change does not apply to groups it has already joined. Promoting the bot to group admin achieves the same visibility.

What does "Forbidden: bot can't initiate conversation with a user" mean?

A Telegram bot can never message someone first. The user must send /start or tap a deep link such as https://t.me/YourBotName?start=user_12345 before your bot is permitted to send anything. Having their phone number or user ID from another system does not grant permission - the opt-in has to happen inside Telegram.

Why does my bot only respond to about half the messages?

Two processes are polling the same token. Each long-poll connection claims updates exclusively, so messages are split unpredictably between the instances. Check for a local dev process still running, a container scaled beyond one replica, or an old deploy that was never stopped. Polling cannot be scaled horizontally - use webhooks if you need multiple instances.

What ports can a Telegram webhook use?

Only 443, 80, 88 and 8443, and the URL must be HTTPS. A webhook on any other port - port 3000 being the usual mistake - will never receive a delivery. Self-signed certificates additionally require uploading the public certificate with the setWebhook call.

What are Telegram bot rate limits?

Roughly 30 messages per second overall, about 1 message per second sustained to an individual chat, and around 20 messages per minute to a single group. Exceeding a limit returns HTTP 429 with a retry_after value in seconds, which you should honour exactly - retrying sooner extends the penalty.

Why do I get "can't parse entities" when sending a message?

Your message contains characters that the chosen parse_mode treats as markup. MarkdownV2 requires escaping for _ * [ ] ( ) ~ ` > # + - = | { } . ! even in ordinary prose, so a sentence ending in a full stop will fail. Escape interpolated user content, or use HTML parse mode which needs only &, < and > escaped.

Why does my bot suddenly get "chat not found" for a group that worked before?

The group was almost certainly upgraded to a supergroup, which permanently changes its chat ID. Telegram sends a migrate_to_chat_id field in an update when this happens - store the new ID when you see it. Also confirm you are preserving the negative sign and using a 64-bit integer, since group IDs are negative and can exceed 32 bits.

How do I check whether my Telegram bot token is valid?

Open https://api.telegram.org/bot/getMe in a browser. A valid token returns the bot's username and ID; an invalid one returns 401 Unauthorized. If this works locally but the deployed bot returns 401, the token is fine and your environment variable is wrong - usually a trailing newline, included quote characters, or the staging token deployed to production.

Why is my bot sending the same reply multiple times?

Your webhook handler is too slow, so Telegram times out and retries the delivery, and your code processes the same update more than once. Return HTTP 200 immediately and push the work onto a queue rather than calling an LLM or database before responding. Deduplicating on update_id gives you a second layer of protection.

Is there a limit to Telegram message length?

Yes, 4,096 characters per message. Exceeding it returns "Bad Request: message is too long" and nothing is delivered. AI-generated replies overrun this regularly, so split long output on a paragraph boundary before sending.

The full guide, with diagrams and the latest checks, is at https://www.conferbot.com/blog/telegram-bot-not-responding.