Skip to main content

GetInbox retrieves the agent's inbox with all data needed for display.

GET 
/api/v1/engagements/inbox

Returns a unified view of engagements with:

  • Per-agent unread counts (from agent_message_reads)
  • Last message preview (denormalized for performance)
  • Embedded contact, channel, and agent info
  • Typing indicators

This is the primary endpoint for inbox/messenger UI rendering. A single call provides all data needed to display the inbox list.

Sorting​

  • "last_message" (default): Most recent activity first
  • "unread_first": Unread engagements first, then by time
  • "priority": Highest priority first, then by time

Filters​

  • status/statuses: Filter by engagement status
  • assigned_to_me: Only my assigned engagements
  • unassigned: Only unassigned engagements
  • channel_type: Filter by channel (whatsapp, voice, etc.)
  • search: Search contact name, subject, or last message

Response​

  • data: Inbox items with full embedded data
  • total_unread: Total unread count for badge display

Errors​

  • PERMISSION_DENIED: Caller lacks engagements:read permission

Request​

Responses​

A successful response.