> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbox API

> Real-time collaboration, saved views, routing rules, internal notes, typing indicators, and macros that power the human side of the unified inbox.

# Inbox API

Sits on top of [Conversations](/api-reference/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.

| Method   | Path                                     | Purpose                                |
| -------- | ---------------------------------------- | -------------------------------------- |
| `POST`   | `/api/v1/inbox/{conversationId}/viewing` | Heartbeat — register caller as viewing |
| `DELETE` | `/api/v1/inbox/{conversationId}/viewing` | Unregister (tab close / route away)    |
| `GET`    | `/api/v1/inbox/{conversationId}/viewers` | Who is currently viewing               |
| `POST`   | `/api/v1/inbox/{conversationId}/typing`  | Toggle the caller's typing state       |

## Internal notes

Team-only notes attached to a conversation. Never visible to the contact; surfaced inline with messages in the inbox UI.

| Method | Path                                            | Purpose                            |
| ------ | ----------------------------------------------- | ---------------------------------- |
| `POST` | `/api/v1/inbox/{conversationId}/internal-notes` | Post an internal note              |
| `GET`  | `/api/v1/inbox/{conversationId}/internal-notes` | List internal notes (newest first) |

## Saved views

Personal or team-wide filtered views over the conversation list — "My open WhatsApp conversations", "VIP escalations", "Stale > 4h", etc.

| Method   | Path                       | Purpose                       |
| -------- | -------------------------- | ----------------------------- |
| `GET`    | `/api/v1/inbox/views`      | List personal + team views    |
| `POST`   | `/api/v1/inbox/views`      | Create a view                 |
| `PATCH`  | `/api/v1/inbox/views/{id}` | Rename, reorder, or re-filter |
| `DELETE` | `/api/v1/inbox/views/{id}` | Delete                        |

## 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.

| Method   | Path                               | Purpose                                      |
| -------- | ---------------------------------- | -------------------------------------------- |
| `GET`    | `/api/v1/inbox/routing-rules`      | List rules                                   |
| `POST`   | `/api/v1/inbox/routing-rules`      | Create a rule                                |
| `PATCH`  | `/api/v1/inbox/routing-rules/{id}` | Update name, priority, condition, action     |
| `DELETE` | `/api/v1/inbox/routing-rules/{id}` | Delete a rule                                |
| `POST`   | `/api/v1/inbox/routing-rules/test` | Dry-run a rule against a sample conversation |

## Macros

Saved quick replies with optional variables, attachments, and post-actions (close, tag, assign).

| Method   | Path                                             | Purpose                         |
| -------- | ------------------------------------------------ | ------------------------------- |
| `GET`    | `/api/v1/inbox/macros`                           | List personal + shared macros   |
| `POST`   | `/api/v1/inbox/macros`                           | Create a macro                  |
| `GET`    | `/api/v1/inbox/macros/popular`                   | Most-used macros for this user  |
| `PATCH`  | `/api/v1/inbox/macros/{id}`                      | Update a macro                  |
| `DELETE` | `/api/v1/inbox/macros/{id}`                      | Delete a macro                  |
| `POST`   | `/api/v1/inbox/conversations/{convId}/run-macro` | Apply a macro to a conversation |

## See also

* [Conversations API](/api-reference/conversations) — the lifecycle this surface decorates