Hey Haydn, sorry to hear you're stuck on getting accurate unread counts for Hangouts/Chat via the Gmail API—this is a tricky quirk of how Google syncs Chat messages with Gmail's labeling system. Let's break down why this is happening and what you can do to fix it:

Why messagesUnread stays at 0 #

The core issue here is that Google's Hangouts/Chat backend automatically marks new chat messages as "read" in Gmail as soon as they sync to any connected device or service—even if you haven't manually opened the message. This includes:

• Background sync on mobile Hangouts/Chat apps
• Hidden browser tabs with Gmail or Chat open
• Default integration settings that auto-mark messages as read when synced

When this happens, the messagesUnread value for the CHAT label never increments, even though a new message was received. Your manual test of marking messages as unread works because you're explicitly overriding Gmail's auto-marked status.

Solutions to get accurate unread counts #

1. Use the Google Chat API (Recommended) #

The Gmail API isn't designed to track Chat-specific unread states—for that, Google provides the dedicated Google Chat API, which is built to handle Chat conversation and message statuses.

You can use the conversations.list endpoint to fetch all your Chat conversations, and check the unreadCount field for each conversation:

GET https://chat.googleapis.com/v1/users/me/conversations?fields=conversations(unreadCount,name)

This will give you the exact number of unread messages per conversation, and the total unread count is just the sum of all unreadCount values. This avoids the Gmail auto-marked read issue entirely.

2. Query Gmail API for unread Chat messages directly #

If you need to stick with the Gmail API, instead of relying on the label's messagesUnread field, run a search query to fetch all unread messages tagged with the CHAT label:

GET https://www.googleapis.com/gmail/v1/users/me/messages?q=label:chat%20is:unread

The number of messages returned in the messages array is your real unread Chat count. This bypasses the label's cached messagesUnread value and pulls the current state of unread messages directly.

3. Disable auto-read sync in Google settings #

To prevent Gmail from auto-marking Chat messages as read, double-check these settings:

• In Gmail web settings: Go to Chat and Meet > Uncheck "Chat" (if you don't use Gmail's Chat integration) or adjust the "Mark messages as read" behavior.
• In Google Chat settings: Turn off options like "Mark messages as read when you open Chat" or "Mark messages as read when you scroll past them".
• Ensure all mobile Hangouts/Chat apps are fully closed (not running in background) and logged out if you're not using them.

Final Notes #

Your temporary workaround of comparing messagesTotal works, but it's clunky because it requires manual confirmation. The Chat API is the most reliable long-term solution since it's purpose-built for this use case.

内容的提问来源于stack exchange，提问作者HaydnH