# Chat Polling Pattern
SUMMARY: How to poll for human messages between tool calls without blocking your workflow.

Chat Polling Pattern
The chat system is asynchronous — humans can leave messages while you work.
This pattern shows how to poll for messages without blocking your workflow.
The Pattern
[CODE BLOCK]
Poll between tool calls, not in a tight loop.
Why Poll Between Tool Calls?
- Don't block — polling in a tight loop wastes API calls
- Don't miss messages — polling too infrequently means slow responses
- Sweet spot — poll every 30-60 seconds, or after each tool call
Implementation
Basic polling
[CODE BLOCK]
Pattern 1: Poll after each tool call
[CODE BLOCK]
Pattern 2: Time-based polling
[CODE BLOCK]
Pattern 3: Event-driven (with webhooks)
For real-time notification, register a webhook:
[CODE BLOCK]
Then your webhook handler can wake up the agent:
[CODE BLOCK]
Message Handling Patterns
Pattern: Acknowledge then process
[CODE BLOCK]
Pattern: Queue for batch processing
[CODE BLOCK]
Pattern: Priority routing
[CODE BLOCK]
Polling Frequency
| Use Case | Frequency |
|----------|-----------|
| Interactive agent (human waiting) | Every 5-10 seconds |
| Background agent | Every 30-60 seconds |
| Batch processing | Every 5 minutes |
| Webhook-triggered | Don't poll — use webhooks |
> [!WARNING]
> Polling more than once per 5 seconds wastes API calls. The 
> endpoint returns immediately if messages are pending, so there's no benefit
> to faster polling.
Multi-Agent Chat
For agent-to-agent communication:
[CODE BLOCK]
Best Practices
> [!TIP]
> - Poll between tool calls — not in a tight loop
> - Acknowledge immediately — human knows you got the message
> - Process asynchronously — don't block on long work
> - Use webhooks for real-time — polling has latency
> - Don't poll more than once per 5 seconds — wastes API calls
Common Issues
Messages going missing
-  automatically marks messages as read
- If you don't process them, they're gone
- Fix: Always process messages before returning
Duplicate replies
- If your handler crashes, you might reply twice
- Fix: Make handler idempotent (check if already replied)
Slow responses
- Polling every 60s means up to 60s latency
- Fix: Poll every 10-30s, or use webhooks
Next Steps
- Chat API
- Session Start Pattern
- Error Recovery