Telegram Session Distribution Troubleshooting: A Guide to Fixing Unassigned New Sessions and Agents Not Receiving Messages

Session distribution is one of the core features of a B2B SaaS customer service system—it determines whether new users entering a Telegram Bot can be promptly assigned to available agents. However, many teams encounter issues when configuring TG-Staff, such as “new sessions not being picked up,” “agents online but not receiving messages,” or “sessions remaining unassigned.”

This article serves as a session distribution troubleshooting guide for operations and customer service team managers. We will start with the most common fault symptoms, break down the configuration logic step by step, and provide a printable checklist for troubleshooting. If you are using Telegram Bot for customer support or community management, this article will help you quickly pinpoint issues and restore normal workflow to your customer service system.

Overview of Common Session Distribution Issues

Before diving into troubleshooting, confirm which scenario you are facing. The following three issues are most common, each with different causes:

• New sessions never assigned to any agent: After a user enters the Bot, agents cannot see the new session, or the session remains in an “unassigned” state.
• Agents online but not receiving new session notifications: Agents are logged into the web portal and show as online, but new sessions do not pop up—only discovered after manual refresh.
• Missing or delayed messages: Agents reply to messages, but users do not receive them, or user messages do not appear in the session window.

This article focuses on the first two scenarios. If you are experiencing message delays or loss, first check whether the Bot Token is valid, the network is stable, and whether content moderation rules (Pro version) have been triggered.

Step 1: Check Agent Online Status and Account Login

This is the most overlooked root cause of issues. Many teams assume that “agent logged into Telegram” means online, but in TG-Staff, **agents must log into the web portal (https://app.tg-staff.com/）并保持会话页面打开**，才能接收新会话。

Troubleshooting Steps:

1. Confirm the agent account is logged into the Web portal (check if the avatar in the top-right corner shows online status).
2. Verify that the browser allows TG-Staff to send notifications (Chrome Settings → Privacy and Security → Site Settings → Notifications, ensure app.tg-staff.com is not blocked).
3. Ask the agent to manually refresh the conversation page: press F5 or click the browser refresh button, wait 5 seconds to see if new conversations appear.
4. If the agent has been inactive for a long time, the login may have expired. Log out and log back in, then test once.

Common Misconception: Agents log into the TG-Staff Bot on mobile (e.g., @tgstaff_robot) thinking they can receive conversations this way. In reality, agents must use the Web portal to serve users.

Step 2: Verify Routing Rules Configuration

If the agent is logged in and status is normal, but new conversations are still not assigned, the next step is to check the project-level routing rules.

In the TG-Staff console, each Bot project can configure routing rules independently. Two modes are supported:

Agent Order and Polling Logic in Round-Robin Mode

• Round-Robin is the default mode. The system polls agents in list order, assigning the conversation to the next available online agent.
• If an agent is offline, the system skips them and polls the next agent.
• Key Point: If all agents are offline, new conversations remain in “Unassigned” status until an agent comes online and manually claims them or the system reassigns.

Example: A project has 3 agents (A, B, C) in order A → B → C. When a new conversation enters, the system checks if A is online: if online, assign; if offline, check B, and so on. If A, B, C are all offline, no assignment occurs.

Fallback Mechanism in Online-First Mode When All Offline

• Online-First mode prioritizes assigning conversations to currently online agents (not in fixed order, but randomly or based on load).
• When all agents are offline, the system falls back to round-robin logic. This means if all agents are offline, new conversations remain in “Unassigned” status.
• Recommendation: If your team has multiple agents and some are not often online, use “Online-First” mode to ensure online agents receive conversations promptly.

Troubleshooting Steps:

1. Go to TG-Staff Console → Project Settings → Conversation Routing Rules.
2. Confirm the current mode is what you expect (Round-Robin vs Online-First).
3. Check if the agent list is empty—if no agents are in the list, no one can receive conversations.
4. If using “Specified Agents” scope, ensure all target agents are added (see Step 3).

Step 3: Check Project Agent Scope Settings

This is a very subtle configuration point. In the TG-Staff project settings, there is an “Agent Scope” option with two choices:

• All Agents: All agents in the project can receive conversations for this Bot.
• Specified Agents: Only selected agents can receive conversations.

If you chose “Specified Agents” but forgot to add the target agent to the list, that agent will not receive new conversations even if online.

Troubleshooting Steps:

1. Go to Project Settings → Agent Scope.
2. Confirm whether it is “All Agents” or “Specified Agents.”
3. If it is “Specified Agents,” check if the list includes all agent accounts that need to serve.
4. If an agent is not in the list, click “Add Agent” to add them, then save.

Step 4: Troubleshoot Issues with the Redirect Link and Bot

If you use redirect links (magic links) to guide users from ads or social media into the Bot, you also need to check whether the link itself is configured correctly.

Redirect links are official domain short links provided by TG-Staff (e.g., https://app.tg-staff.com/{code}). Before redirecting, they capture the visitor’s IP, browser information, and URL parameters. If the link is broken or misconfigured, users may not trigger session routing.

Troubleshooting steps:

1. In the TG-Staff console → Redirect Link Management, find the corresponding link.
2. Check whether the Bot Token associated with the link is valid—if the Token is reset or the Bot is deleted, the link will become invalid.
3. Confirm the link has not expired (redirect links can have an expiration date).
4. Open the redirect link in an incognito browser and observe whether the redirect target is correct (it should redirect to your Telegram Bot conversation page).
5. If the Bot does not respond after the redirect, check whether the Bot is running (send /start to the Bot in Telegram to test).

Quick test method: Open the redirect link in a Chrome incognito window and observe the final URL in the address bar. If it redirects to the wrong Bot or shows a 404, the link configuration is incorrect and needs to be regenerated.

Step 5: Check System Logs and User Profiles for Advanced Troubleshooting

If all the above steps have been checked but the issue persists, you can use the User Profile and Data Statistics features provided by TG-Staff Professional Edition for in-depth troubleshooting.

• User Profile: View the complete record of a specific session, including assignment time, agent actions, and whether content moderation was triggered. This helps you determine whether it is a configuration issue or occasional network latency.
• Data Statistics: View metrics such as session assignment success rate, agent online duration, and average response time. If the assignment success rate drops sharply over a period, it may indicate a batch failure.

Standard Edition users: If you cannot use advanced statistics features, you can directly contact the TG-Staff customer service Bot (@tgstaff_robot), provide your project ID and fault description, and the technical support team will assist in troubleshooting.

Session Routing Troubleshooting Checklist (Quick Reference)

Below is a printable checklist for quick reference:

#	Check Item	Status (✓ / ✗)
1	Agent logged into Web portal (https://app.tg-staff.com/）？	☐
2	Agent status shows “Online”?	☐
3	Browser allows TG-Staff to send notifications?	☐
4	Routing rules are not empty (at least one agent in project settings)?	☐
5	Routing rule mode is correct (Round Robin or Online Priority)?	☐
6	Project customer service scope includes the agent (if set to “Specified Agents”)?	☐
7	Bot Token is valid and the Bot is still running?	☐
8	Redirect link has not expired and points to the correct Bot?	☐
9	Agent has not manually marked sessions as “Completed” causing inability to receive new sessions?	☐
10	Tried reloading the session page or logging out and back in?	☐

If all 10 items pass but the problem persists, contact TG-Staff support or refer to the official documentation (https://docs.tg-staff.com/）获取更多配置细节。

FAQ

Q: New sessions show “Unassigned” but the agent is online. What should I do?

A: First confirm the agent is logged into the TG-Staff Web portal (not just Telegram). Then check whether the project customer service scope includes the agent and whether the routing rule is set to “Specified Agents” but the agent is not added. Finally, try reloading the session page or logging out and back in.

Q: When an agent is offline, who will new sessions be assigned to?

A: It depends on the routing rules. In “Round Robin” mode, the system skips offline agents and assigns the session to the next available online agent. If all agents are offline, new sessions will remain in “Unassigned” status until an agent comes online and manually claims them or the system re-assigns them. In “Online Priority” mode, it also falls back to Round Robin logic.

Q: The redirect link is broken. How do I troubleshoot?

A: Check whether the redirect link uses the correct Bot Token and whether the Bot corresponding to that Token is still running. Try opening the link in an incognito browser and observe whether the redirect target is correct. If the link has expired, regenerate it in the TG-Staff console.

Q: Why doesn’t the agent receive new session notifications (no popup/sound)?

A: Check whether the browser allows the TG-Staff Web portal to send notifications (Chrome/Safari settings). Additionally, the agent must keep the session page open (cannot minimize or switch to another tab), otherwise the browser may suppress notifications.

Q: Does the free trial support session routing?

A: Yes. During the free trial, session routing features are fully available, including both Round Robin and Online Priority modes. After the trial ends, you need to subscribe to Standard or Professional Edition to continue using them (see the official website pricing page for details).

---

Experience stable session routing now: Sign up for TG-Staff free trial for 3 days, no credit card required, to test all configurations on a real project. If you encounter any unsolvable issues, contact @tgstaff_robot for technical support. For more configuration details, refer to the official documentation (https://docs.tg-staff.com/）。