إيقاف مؤشر الكتابة (Stop Typing)

State Cleanup: Mastering the Stop Typing Engine

The /v2/send/stop-typing endpoint is the essential "Cleanup Crew" of the Wawp presence system. While simple in its objective—to remove the "typing..." or "recording audio..." indicators—it plays a critical role in maintaining the professional polish of your WhatsApp integration. In a high-stakes customer support or sales environment, a "typing..." indicator that lingers indefinitely without a resulting message is a significant UX failure that signals system malfunction or agent indecision.

🏗️ The Presence Termination Pipeline

When you explicitly call /stop-typing, Wawp executes a coordinated cleanup across the WhatsApp stack:

1. The PAUSE Signal: The engine transmits a specialized PAUSE packet to the target chatId. This packet instructs the recipient's WhatsApp client to immediately hide all presence indicators.
2. Override of Implicit Timeouts: While WhatsApp has a native timeout (usually 10–20 seconds), explicit calls to /stop-typing provide instant feedback. This is crucial for fast-paced, multi-step conversational flows where states change rapidly.
3. Internal Buffer Clearance: Wawp clears the local session's presence-tracking buffer to ensure that subsequent typing requests are treated as fresh starts, preventing "Presence Stuttering" on the recipient's UI.

🛡️ Strategic Best Practices for Presence Hygiene

1. The "Message-Sent" Auto-Stop

It is a common misconception that you must call /stop-typing immediately before sending a message.

• Fact: Sending any message (Text, Image, PDF, etc.) to a chat automatically triggers the "Stop Typing" behavior on the WhatsApp network.
• Optimization: To save API calls and reduce latency, do not call /v2/send/stop-typing before or after sending your final message. The message delivery itself is the most efficient way to clear the status.

2. Handling Workflow Cancellations

This is the most critical use case for the explicit stop endpoint.

• Scenario: An agent starts a response in your CRM but then decides the inquiry belongs to a different department. They close the chat tab or transfer the ticket.
• Best Practice: Your CRM should automatically trigger /v2/send/stop-typing whenever an agent's focus leaves a chat that was previously in a "Typing" state. This prevents the "Phantom Agent" effect where a customer sees someone typing for minutes with no result.

3. Graceful AI Failure Recovery

If your AI backend (e.g., GPT-4 or Claude) times out or returns an error while a "typing..." indicator is active, your system must handle the cleanup.

• Implementation: Wrap your AI generation logic in a try...catch...finally block. In the finally section, if no message was successfully sent, trigger /v2/send/stop-typing. This ensures that even in the event of a crash, the customer isn't left staring at a perpetual typing status.

🧩 Advanced Use Cases

The "Search Transition" UX

In complex bot flows where a user requests a search (e.g., "Find my order"), you can use /v2/send/start-typing to show work is in progress. If the search returns 0 results, trigger /v2/send/stop-typing before sending the "No results found" text. This momentary clearing of the status creates a distinct visual "Beat" in the conversation, signaling that one phase of logic has ended and another (the error message) has begun.

Agent Transfer Synchronization

When transferring a chat between human agents, the secondary agent may want to "Pick up" the thread quietly. Triggering stop-typing during the handoff ensures the transition is visually seamless for the customer, with no overlapping or conflicting indicators from two different sessions.

🛠️ Common Pitfalls and Solutions

• Double-Counting Latency: If your network is slow, calling /stop-typing followed immediately by a message might cause the message to arrive before the stop signal is processed, leading to a brief flicker. Solution: Rely on the "Auto-Stop" property of messages whenever possible.
• Rate Limit Caution: While presence signals are lightweight, WhatsApp still tracks the frequency of these specialized packets. Avoid sending more than 3 stop-typing calls per second to the same chat to ensure your instance maintains a high trust score.
• Group Environment Noise: In group chats with 200+ participants, presence indicators can be noisy. Use /stop-typing only when an agent was definitely "Active" and now definitely is "Not."

Summary of Capabilities:

• Explicitly terminate the "typing..." or "recording audio..." presence indicators.
• Native integration with WhatsApp PAUSE signaling for instant recipient feedback.
• Essential for cleaning up states after agent transfers or workflow cancellations.
• Zero-latency override of standard 20-second network-level timeouts.
• Foundation for reliable "Try/Finally" error handling in automated AI bot systems.
• Ensures a polished, professional conversational aesthetic by preventing "Phantom Typing."