Inbox API
Sits on top of Conversations and powers the human-agent surface — who is currently viewing what, internal notes, saved filtered views, conversation routing, and quick-reply macros. Base path:/api/v1/inbox
Authentication: API key (X-API-Key) or session JWT. The dashboard uses a Clerk session, and server-to-server callers can use an API key against the same endpoints.
Live presence
Used by the inbox UI to show “X is viewing” + typing indicators. Heartbeat the viewing endpoint roughly every 20 seconds while the conversation is open. The server holds presence for a 30-second TTL, so a 20-second cadence keeps it alive with margin — heartbeating at the full 30 seconds races the TTL and intermittently drops your own presence.Internal notes
Team-only notes attached to a conversation. Never visible to the contact; surfaced inline with messages in the inbox UI.Saved views
Personal or team-wide filtered views over the conversation list — “My open WhatsApp conversations”, “VIP escalations”, “Stale > 4h”, etc.Routing rules
Auto-assign incoming conversations to agents or teams based on channel, contact, content, or time. Rules are evaluated in priority order; first match wins.Macros
Saved quick replies with optional variables, attachments, and post-actions (close, tag, assign).See also
- Conversations API — the lifecycle this surface decorates