Common troubleshooting guide for building Telegram customer service system: Token, Webhook, agent login and diversion failure

Building a stable Telegram customer service system is an urgent need for many cross-border teams, Web3 project parties and community operators. However, in the actual deployment process, various types of faults emerged one after another, from Bot Token failure to Webhook conflicts, from agents being unable to log in to session offloading not working. This article uses TG-Staff as the main scenario, summarizes the six most common types of faults encountered when building Telegram customer service systems, and provides practical troubleshooting methods. Whether you have just signed up for a trial or have already launched operations, this troubleshooting guide can help you quickly locate the problem and restore customer service operations.

Fault 1: Bot Token is invalid or expired

Bot Token is the unique identity credential of Telegram Bot, which is equivalent to the “password” between your customer service system and Telegram server. Once the Token expires, the entire customer service system will be unable to receive or send any messages.

How to determine whether the Token is valid?

The most straightforward way is to test via the Telegram Bot API. Execute the following request in the terminal or browser:

https://api.telegram.org/bot<你的Token>/getMe

If {"ok":true,"result":{"id":...}} is returned, the Token is valid. If {"ok":false,"error_code":401,"description":"Unauthorized"} is returned, the Token has expired.

Common reasons for token failure include:

• Manually reset the Token in BotFather
• Bot is recreated after being deleted
• Permission changes caused Token to be revoked by Telegram

After Token is updated, does the Webhook need to be reset?

**need. ** After the Token is replaced, the Webhook configuration corresponding to the old Token will also become invalid. You must rebind the webhook, otherwise the bot cannot receive user messages.

Procedure in TG-Staff console:

1. Log in to app.tg-staff.com and enter the corresponding project
2. Click “Project Settings” → “Bot Settings”
3. Paste the new Token obtained from BotFather in the Token input box
4. After clicking “Save”, the system will automatically reset the Webhook

Fault 2: Webhook conflict and connection failure

Webhook is the bridge between Telegram Bot and customer service system. When the Bot receives a user message, the Telegram server will push the message to the URL you specify through the Webhook. If multiple services occupy the same webhook at the same time, conflicts will occur.

What is a webhook conflict? How to detect?

Webhook conflict means that the current Webhook address of the Bot points to a non-TG-Staff URL (such as other customer service platforms, custom scripts or test servers). Detection method:

1. Visit in the browser: https://api.telegram.org/bot<你的Token>/getWebhookInfo
2. Check the returned url field - if it points to an address other than https://app.tg-staff.com/... format, there is a conflict

Two ways to resolve webhook conflicts

Method 1: One-click repair in TG-Staff console

On the project settings page, if a Webhook conflict is detected, the console will display a warning prompt. Click the “Reset Webhook” button, and the system will automatically clear the old configuration and bind the correct address.

Method 2: Manually clear and then rebind

If the automatic repair fails, you can manually call the Telegram API to clear the conflict:

https://api.telegram.org/bot<你的Token>/deleteWebhook

Returns {"ok":true} after successful execution. Then re-trigger Webhook binding in the TG-Staff console.

Fault 3: The agent cannot log in or cannot see the session

Agents are the core executors of the customer service system. When agents report that they cannot log in or cannot see any sessions after logging in, it usually involves three levels: account status, agent quota, and project permissions.

What should I do if the agent login prompts “Account is not activated”?

First check whether the agent has been removed from “Agent Management” by the administrator. Secondly, confirm whether the seat quota of the current package has been exhausted. The seat quotas for each TG-Staff package are as follows (subject to the official website):

Package type	Seat quota	Applicable scenarios
Free trial	Limited	Test evaluation
Standard Edition	3 Agents	Small Teams
Professional Edition	20 Agents	Medium to Large Teams

If the seat quota is full, you need to upgrade the package or release inactive seat quotas.

Agents cannot see any sessions after logging in

This is the most common configuration failure. Troubleshooting steps:

1. Check the project customer service scope: The administrator enters “Project Settings” → “Customer Service Scope” and confirms that the agent has been checked
2. View diversion rule configuration: If the diversion rule is set to “Designated Customer Service” and the agent is not included, no session will be received.
3. Confirm agent online status: If the offloading rule is “Online Priority”, the agent must remain online to receive new sessions

Fault 4: Session offloading (rotating distribution/online priority) does not work

Session offloading is a mechanism by which the customer service system automatically assigns users to appropriate agents. TG-Staff supports two distribution modes: Allocation in turns (default, polling authorized agents in order) and Online priority (allocation to online agents first, fallback to allocation in turns when all offline). If offloading does not take effect after configuration, there are usually the following reasons.

Round robin vs online priority: Which one to choose?

Features	Rotation	Online Priority
Allocation logic	Polling in a fixed order	Find online agents first
Applicable scenarios	Team agents are all online	Agents’ online time is not fixed
Offline processing	Skip offline agents	Fall back to turn allocation when all offline

Troubleshooting steps for shunt failure

1. Confirm agent online status: In online priority mode, if all agents are offline, new sessions will not be allocated
2. Check item customer service scope: Ensure that all agents participating in diversion are within the “customer service scope”
3. Verify that the diversion link is used correctly: The diversion link must be generated by TG-Staff (supported by the Standard Edition and above packages), not the Bot native link. Native links will not trigger diversion logic

Fault 5: Diversion link (magic link) jumps abnormally or fails to attribute

Diversion links (also called magic links) are official domain name short links provided by TG-Staff, which are used for advertising traffic attribution and multi-channel tracking. When a user clicks on the link, the system captures the visitor’s IP, browser information, and URL parameters, and then jumps to the Bot to start a conversation.

Common causes of jump exceptions

• Link expiration: Each diversion link has a validity period and cannot be redirected after expiration.
• Package Limitation: Diversion link is a function of the standard version and above packages, and cannot be used by free trial users
• URL parameters are truncated: If the utm_* parameters in the ad link are spliced incorrectly, attribution data may be missing.

Troubleshooting methods for attribution failure

1. Check the diversion link format: it should be in https://app.tg-staff.com/{code} format
2. Verify advertising link parameters: Ensure that utm_source, utm_medium, utm_campaign and other parameters are correctly spliced after the offloading link
3. Test the jump process: manually open the diversion link in the browser and confirm that it can jump to the Bot normally.

Fault 6: The message fails to be sent or the automatic translation does not take effect

Agents fail to send messages or automatic translation does not work. This is usually related to content risk control interception, translation quota being exhausted, or the function switch not being enabled.

Content risk control interception

The professional version’s content risk control feature detects risky words before agents send messages. If the message hits a risky phrase, a secondary confirmation window will pop up or the sending will be blocked directly. Troubleshooting method:

• Check the configuration of “Internal Control Management” → “Risk Phrases” to confirm whether legal content has been intercepted by mistake
• For Web3 projects, pay attention to wallet address monitoring: if a specific TRC20/ERC20 address is configured in the risk phrase, agents will be intercepted when sending messages containing this address.

Automatic translation does not take effect

Automatic translation needs to meet three conditions:

1. The package includes translation quota (the standard version includes AI translation, and the professional version additionally supports Google professional translation and DeepL professional translation)
2. The translation switch has been turned on in the current session (upper right corner of the agent interface)
3. The translation quota for the day has not been exhausted (the remaining quota can be viewed on the console)

FAQ

**Q: After resetting the Bot Token, will TG-Staff be automatically updated? ** Answer: No. You need to obtain a new Token from BotFather and then manually update it in the “Project Settings” of the TG-Staff console. The system will automatically reset the webhook after the update.

**Q: Will TG-Staff prompt me when webhook conflicts? ** Answer: Yes. When you try to bind a bot, the console will display a warning if it detects that the webhook points to another service. You can clear conflicts and rebind with one click.

**Q: The agent cannot see any sessions after logging in. What is the reason? ** Answer: The most common reason is that the agent has not been added to the “Customer Service Scope” of the project. The administrator is asked to check the agent in “Project Settings → Customer Service Scope” and ensure that the diversion rule is enabled.

**Q: Are diversion links (magic links) available to free trial users? ** A: Not available. Diversion links are a feature of the Standard Edition and above packages. Free trial users can only use Bot native links and cannot implement attribution tracking.

**Q: Content risk control intercepts legitimate messages sent by agents, what should I do? ** Answer: Administrators can adjust or remove triggering rules in “Internal Control Management → Risk Phrases”. If it is intercepted by mistake, you can temporarily release it and then modify the phrase configuration.

Conclusion and action suggestions

When building a Telegram customer service system, Token, Webhook, agents, and diversion are the four links most prone to failure. Most problems can be quickly solved using the troubleshooting methods provided in this article. If you are new to TG-Staff, it is recommended to register for a free trial (3 days) and go through the entire process in the test environment before officially launching it.

Action Recommendations:

1. Register for trial: app.tg-staff.com Try the 3-day free trial now
2. Check the complete document: docs.tg-staff.com for more detailed operation guide
3. Contact customer service: If you encounter problems that cannot be solved, you can directly contact @tgstaff_robot for technical support

Building a reliable Telegram customer service system is not difficult. The key is to understand common faults in advance and master troubleshooting methods. I hope this guide can help you avoid detours and make your customer service system truly a boost to your business growth.