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

# Inbox & Conversation Tools

> Read conversations and notes, add internal notes, close chats, and hand them to your team.

## What is this?

These tools let the assistant read your inbox the way a team member would — conversation lists, message history, notes and saved replies — and make small, approved changes like adding a note or closing a chat.

These tools belong to the [Workspace MCP](https://docs.xpressbot.org/api-reference/mcp/workspace/overview.md). Each tool below shows its **Mode** (**Read** runs immediately; **Write** asks your MCP client to confirm first) and the **Permission needed** for it to appear for your key — "None" means every connected key sees it.

## What can I do here?

* See the inbox workload and recent conversations
* Read what was said in a conversation, and its internal notes
* Add a note, close a conversation, or hand it to a human

## Tools

### `get_inbox_overview`

The inbox workload of the user's current channel: conversations by status, how many have unread messages, how many open ones nobody is assigned to, and how many were active in the last 24 hours. Users limited to their assigned conversations only get their own numbers.

**Mode:** Read · **Permission needed:** `inbox:view`

### `list_conversations`

The most recently active conversations in the user's current channel: contact name, channel type, status, priority, whether it is assigned, unread count and a preview of the last message. Filter by status or to unread only. Users limited to their assigned conversations only see their own.

**Mode:** Read · **Permission needed:** `inbox:view`

### `get_conversation`

Open a conversation in the user's current channel: status, priority, whether it is assigned, unread count, the customer's 24-hour reply window, and the contact (name, phone, email, labels). Pass conversationId (from list\_conversations) or contactId (from search\_contacts) to get that contact's conversations. Then use list\_messages to read what was said.

**Mode:** Read · **Permission needed:** `inbox:view`

### `list_messages`

Read the messages of one conversation (from list\_conversations or get\_conversation), oldest to newest in the returned page. Each message has direction (inbound = from the customer), who sent it (user, bot, automation, system), type, text, delivery status and any delivery error. Returns the latest messages by default; pass the returned nextBefore as before to read earlier ones.

**Mode:** Read · **Permission needed:** `inbox:view`

### `list_notes`

Read the internal notes on one conversation (from list\_conversations or get\_conversation), newest first: text, type (internal, follow-up, reminder, warning, info), status, reminder time and author. Customers never see notes.

**Mode:** Read · **Permission needed:** `inbox:view`

### `add_note`

Add an internal note to a conversation (from list\_conversations or get\_conversation). Notes are visible only to the team, never to the customer. Use for context, follow-ups or warnings the team should see.

**Mode:** Write · **Permission needed:** `notes:create`

### `list_canned_responses`

The user's own saved replies in the current channel (shortcut and text), for suggesting a ready-made answer.

**Mode:** Read · **Permission needed:** `inbox:view`

### `close_conversation`

Close (resolve) a conversation.

**Mode:** Write · **Permission needed:** `inbox:close`

### `handoff_to_human`

Hand a conversation over to the human team: stops the AI on it and puts it in the unassigned queue.

**Mode:** Write · **Permission needed:** `inbox:assign`

## Troubleshooting / Technical Notes

* **A tool I expect isn't offered.** The MCP server only offers tools whose required permission your API key's owner holds, re-checked on every call. Grant the permission shown on the tool — see [Team](https://docs.xpressbot.org/workspace/team.md).
* **A Write tool never seems to run.** Your MCP client asks you to approve every Write tool call. Check for a pending approval prompt.
* **A call returns an error.** See [MCP errors](https://docs.xpressbot.org/api-reference/mcp/errors.md).

## Related docs

* [Workspace MCP tool catalog](https://docs.xpressbot.org/api-reference/mcp/workspace/tools/overview.md)
* [Workspace MCP](https://docs.xpressbot.org/api-reference/mcp/workspace/overview.md)
* [Overview](https://docs.xpressbot.org/workspace/inbox/overview.md)
* [Notes](https://docs.xpressbot.org/workspace/contacts/notes.md)
* [Team](https://docs.xpressbot.org/workspace/team.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.