The Ghost in the Machine: Mastering WhatsApp Presence

Presence information—the delicate dance of "Online", "Typing...", and "Last Seen"—is the heartbeat of real-time communication. In the context of the Wawp API, managing presence is not just about vanity metrics; it is a critical component of Trust Engineering and Session Health.

The /v2/presence-overview category encompasses the tools you need to signal your bot's availability to the world and, conversely, to understand the availability of your users.

🧠 The Psychology of "Online"

Before diving into code, it is essential to understand how humans perceive presence on WhatsApp.

1. The Expectation of Immediacy

When a user sees your business account is Online, they expect a reply within seconds.

• The Risk: If your bot marks itself as online continuously (24/7) but takes 5 minutes to process a request due to queueing, users will perceive the service as "broken" or "ignoring them."
• The Strategy: Use the Set Presence endpoint to toggle your state to available only when your webhook consumer is healthy and processing at full speed. If your backend is under maintenance, explicitly set your presence to unavailable.

2. The Provenance of "Last Seen"

For personal accounts, "Last Seen" is a casual privacy feature. For business automation, it is a Liveness Probe.

• Trust Signal: A business account that was "Last seen today at 10:00 AM" feels active. An account "Last seen Dec 12, 2023" feels abandoned/dead.
• Automation: You can use a scheduled job to momentarily toggle your presence to online and back to offline once every few hours. This updates your "Last Seen" timestamp, reassuring users that the line is still active even if no messages are being sent.

🏗️ Technical Architecture of Presence

WhatsApp's presence system is built on a Publish-Subscribe (PubSub) model, which differs significantly from the standard Request-Response HTTP model.

1. The Subscription Model (/subscribe)

You cannot simply "GET" the status of any random number on WhatsApp. That would be a massive privacy breach and a technical impossibility given the billions of users.

• The Mechanism: To receiving presence updates for a specific user (e.g., to know when they come online), your device must explicitly Subscribe to their presence feed.
• duration: These subscriptions are ephemeral. They typically last about 20-60 seconds. After that, the WhatsApp server stops sending you updates to save bandwidth.
• Implication: You must implement a "Heartbeat" loop if you need to track a user continuously during a live support session.

2. The Reciprocity Rule

In strict privacy settings, a user may not share their status with you unless you share yours with them.

• API Behavior: If you force your own presence to offline (ghost mode), you might find that the API returns null or outdated data when you try to query users.
• Best Practice: Maintain a "Title-for-Tat" configuration. If you want to see them, let them see you.

3. The "Typing" Indicator

While not strictly a "Presence" state (it's an ephemeral event), the "Typing..." indicator is closely related.

• Gap Filling: It bridges the gap between "Read" (Double Blue Checks) and "Response".
• UX Tip: Always trigger /v2/send/start-typing before your bot begins a long processing task (like generating an AI image). This buys you 5-10 seconds of user patience.

🛡️ Anti-Ban & Rate Limiting

Scanning for presence is one of the most dangerous activities for a WhatsApp bot.

Why is it risky?

Malicious actors use "Presence Checking" to build databases of active phone numbers (e.g., checking 1 million random numbers to see which ones are registered). WhatsApp's AI defenses are extremely aggressive against this pattern.

The Golden Rules:

1. Never Check Strangers: Only query the presence of users who have messaged you first.
2. No Bulk Scanning: Never loop through your entire contacts database checking status.
3. Context Aware: Only subscribe to presence when a conversation is active (i.e., within the 24-hour service window).
4. Rate Limits: The API will return 429 Too Many Requests if you subscribe to more than ~50 users per minute.

🚀 Strategic Implementation Patterns

Pattern A: The "Live Agent" Handoff

When a user asks to speak to a human:

1. Check User: Call /v2/presence/{chatId} to see if the user is currently looking at the chat.
2. Route:
   • If Online: Route to a Priority Queue for immediate pickup.
   • If Offline: Route to a standard ticket system and send an email notification instead.

Pattern B: The "Optimistic" Blast

Marketing messages have higher conversion rates when delivered while the phone is in the user's hand.

1. Monitor: For a small cohort of VIP users, listen for valid presence_update webhook events.
2. Trigger: If a VIP comes online, trigger the pending offer message immediately.
3. Result: The notification arrives while they are already unlocking their phone, maximizing visibility.

Pattern C: The "Ghost" Admin

Startups often want to monitor groups without being noticed.

1. Set Status: Call /v2/presence with status: unavailable.
2. Disable Read Receipts: Update privacy settings.
3. Result: Your bot can read every message and log data, but to the group members, it appears completely offline and silent, reducing the "Big Brother" effect.

🧩 Integration with Webhooks

While these HTTP endpoints allow you to act, the primary way to consume presence data is via Webhooks.

• Event: presence_update
• Payload: Contains id (Subject) and status (available/unavailable).
• Note: You will only receive these webhooks for users you have recently subscribed to or currently have an open chat with. You will not get a firehose of the entire world's activity. (See the Webhooks Documentation for payload examples).