Get Agent Inbox
REST API - Agents
Get Agent Inbox
List the conversations that reached an agent by email or WhatsApp
GET
Get Agent Inbox
Agents can be reached on inbound channels: email (when an email trigger is configured) and WhatsApp (on a user’s personal Omni). This endpoint lists those conversations - the agent’s inbox - newest first, with filters for channel, date range and title text.
It is agent-wide: every sender’s conversation with this agent, not just the caller’s. For an agent’s full task history across all sources, use Get Agent Tasks instead.
Path Parameters
string
required
Unique identifier of the agent (UUID format)
Query Parameters
string
Comma-separated channels to include:
email, whatsapp. Defaults to every channel enabled on the agent. Asking for a channel the agent does not have returns 400.string
Only conversations created at or after this ISO date/datetime. A bare date (
2026-08-01) covers that whole UTC day.string
Only conversations created at or before this ISO date/datetime. A bare date covers the whole day.
string
Case-insensitive text matched against conversation titles.
integer
default:20
Maximum conversations to return (1-50).
Response
array
Inbound conversations, newest first
array
Inbound channels enabled on this agent. An empty array means the agent has no inbox at all - clients should hide the surface rather than show an empty list.
integer
Number of matching conversations before
limit was appliedExample Requests
Everything in the inbox
Search one channel
A date range
Example Response
Use Cases
- Inbox view: render everything people sent an agent, across channels
- Lookup: find the conversation a specific person or subject started
- Triage: filter by date range to review what arrived while nobody was watching
Notes
- Only top-level conversations are listed; sub-tasks spawned inside a conversation are excluded
- Each channel is queried separately and the results merged, so a channel that is temporarily unavailable degrades the list rather than failing it - the request only errors when every requested channel fails
senderis null when the conversation came from an identity with no email on file- The agent itself can list the same conversations in chat, so “what emails did you get?” is answered from real data rather than guessed
See Also
- Get Agent Tasks - all tasks for an agent, any source
- Get Task Thread - the messages inside one conversation
- List Tasks - tasks across all agents
Authorizations
API Key for authentication
Path Parameters
Query Parameters
Comma-separated channels to include (email, whatsapp). Defaults to every channel enabled on the agent.
ISO date/datetime - only conversations created at or after it (a bare date covers the whole UTC day).
ISO date/datetime - only conversations created at or before it.
Case-insensitive text matched against conversation titles.
Max conversations to return.
Required range:
1 <= x <= 50
