Roam MCP

List scheduled calendar events within a date range from the user's connected calendars (Google Calendar, Outlook). Returns upcoming meetings with times, attendees, and recurrence info. Note: returns scheduled events, not completed meeting transcripts, use meeting_list for transcripts.

Delete a bot message. Specify the message by chatId and timestamp. Idempotent. Requires a bot token or a personal token with useBotIdentity=true.

Read messages from a specific chat conversation. A chat target is required, provide exactly one of chatId, groupId, or userIds: - chatId: UUID of an existing conversation (from chat_list results) - groupId: UUID of a group (from group_list results), reads the group's channel - userIds: UUID(s) of users, opens or creates a DM conversation When "after" is specified, returns messages in forward chronological order (oldest first). Otherwise, returns messages in reverse chronological order (newest first). Parameters: - chatId (optional): UUID of a chat conversation - groupId (optional): UUID of a group - userIds (optional): Array of user UUIDs for a DM - threadTimestamp (optional): Thread root RFC3339 datetime (from a prior message's `timestamp`) to read thread replies - before (optional): Only messages before this time (RFC3339) - after (optional): Only messages after this time (RFC3339) - ascending (optional): Sort ascending by time (true/false) - limit (optional): Max messages per page (max 200) - cursor (optional): Pagination cursor from a previous response Each returned message carries: - `timestamp`, RFC3339 send time (with microsecond precision). Pass back into chat_post, chat_update, chat_delete, reaction_* as-is. - `threadTimestamp`, RFC3339 thread root (only on replies / when replying to a thread). - `userId`, UUID of the sender (resolve via the response envelope's `addresses` map; see below). - `text`, canonical message text with Slack-syntax mention tokens: `<@uuid>` for principals (users and bots), `<!subteam^uuid>` for groups and channels, and `<!channel>` for the broadcast. Tokens are never rewritten by the server. - `mentions`, flat list of payloads referenced by mention tokens in `text`: bare address UUIDs (from both `<@uuid>` and `<!subteam^uuid>` tokens) and the literal `"all"` for `<!channel>`. Order-preserving and deduplicated. Always present when `text` contains mentions; use this to know what was mentioned without re-parsing the regex. The response envelope additionally carries an `addresses` map keyed by UUID, every sender and mention-target address referenced on this page, with display name, type (`user`/`bot`/`userGroup`/`standardGroup`/`meetingGroup`/`teamRoam`), and type-specific fields (e.g. `botCode`, `email`, `isGuest`). Use it to render display names: replace `<@<uuid>>` and `<!subteam^<uuid>>` in `text` with `@` + `addresses.<uuid>.displayName`, and `<!channel>` with `@all`. The map omits IDs the caller is not authorized to view (cross-roam bots, private cross-account groups, etc.), render those as `@unknown`. To look up a message from a Roam chat link URL, use resolve_chat_link instead of parsing the URL yourself. To get a shareable link to a message, use create_chat_link instead of constructing the URL yourself.

List your recent conversations (DMs and groups), sorted by most recent activity.

Send a message to a chat conversation. Messages are delivered asynchronously by default, or can be scheduled for later with `sendAt`. Messages are sent as the bot persona associated with this token. Specify exactly one of chatId, groupId, or userIds to identify the target: - chatId: UUID of an existing conversation (from chat_list results) - groupId: UUID of a group (from group_list results), sends to the group's channel - userIds: UUID(s) of users, sends a DM (creates the conversation if needed) Parameters: - chatId (optional): UUID of a chat conversation - groupId (optional): UUID of a group - userIds (optional): Array of user UUIDs for a DM - text (required): Message text (markdown by default, set markdown=false for plain text) - threadTimestamp (optional): Reply to a thread (group chats only, not DMs), use a `timestamp` value from chat_history results - blocks (optional): Block Kit blocks for rich formatting - items (optional): Item IDs to attach - sender (optional): Override the bot sender's name and image. `sender.imageUrl` must be a Roam-hosted avatar URL. - sendAt (optional): RFC3339 datetime on a 15-minute UTC boundary (:00/:15/:30/:45), up to 30 days ahead. Incompatible with sync, poll, threadKey, and replyTimestamp. When set, the response is `{chatId, scheduledMessageId, sendAt}` instead of a message timestamp.

Cancel a pending scheduled message before it is sent, by the scheduledMessageId returned from chat_post. Only messages scheduled by this credential's bot identity can be canceled; already-sent messages return scheduled_message_already_sent.

Search chat messages matching a query and filters. This tool searches **across every chat the caller can see** (subject to chatTypes), so it is the right tool for a workspace-wide pulse, what is going on across all conversations, not just one. Prefer it over fanning out per-chat with chat_history when you want broad situational awareness. By default, searches every indexed chat type the caller can see, DMs, channels, teamRoam, and meeting channels (Magic Minutes summaries and other meeting-channel posts). Use chatTypes to narrow to specific types. To list recent messages across chats without a search query, use sort: "recent" with an empty query. Examples: - Search all chats: {"query": "budget report"} - List recent activity across the workspace: {"sort": "recent"} - List recent teamRoam messages: {"sort": "recent", "chatTypes": ["teamRoam"]} - List recent DMs: {"sort": "recent", "chatTypes": ["address"]} - Drop noisy automated channels: {"sort": "recent", "excludeChatIds": ["<chatId-from-prior-result>"]} - Drop a noisy bot sender: {"sort": "recent", "excludeUserIds": ["<userId-from-prior-result>"]} When summarizing recent activity, follow a two-pass workflow: 1. First pass: call chat_search with sort: "recent" and no exclusions to see who is posting where. 2. If a small number of chats or senders dominate the results with automated/bot noise (CI bots, deploy bots, alert webhooks, etc.), call chat_search again with those chat IDs in excludeChatIds and/or those sender userIds in excludeUserIds. The second pass should surface human conversation. Parameters: - query (optional): Search text - chatTypes (optional): Filter by chat type, array of "channel", "teamRoam", "address", or "meetingChannel" (default: all indexed types). - in (optional): Group names to search within - from (optional): Sender email addresses - with (optional): Conversation participant emails - excludeChatIds (optional): Chat IDs to exclude. Populate from the chatId field on prior results to drop automated/noisy channels. - excludeUserIds (optional): Sender user IDs to exclude. Populate from the `userId` field on prior results to drop automated/bot senders. - before/after (optional): Date filters (YYYY-MM-DD). Both are optional, omit both to search all time. Never set before and after to the same date (returns nothing). Dates are treated as midnight, so to search a single day like 2024-04-14, use after: "2024-04-14" and before: "2024-04-15". - has (optional): "mention" or "item" - sort (optional): "relevant" (default) or "recent". For recent messages with no query, prefer sort "recent" with no date filters. - limit (optional): Max results per page - cursor (optional): Pagination cursor from previous response Each returned message carries: - `timestamp`, RFC3339 send time (with microsecond precision). Pass back into chat_post, chat_update, chat_delete, reaction_* as-is. - `threadTimestamp`, RFC3339 thread root (only on replies / when replying to a thread). - `userId`, UUID of the sender (resolve via the response envelope's `addresses` map; see below). - `text`, canonical message text with Slack-syntax mention tokens: `<@uuid>` for principals (users and bots), `<!subteam^uuid>` for groups and channels, and `<!channel>` for the broadcast. Tokens are never rewritten by the server. - `mentions`, flat list of payloads referenced by mention tokens in `text`: bare address UUIDs (from both `<@uuid>` and `<!subteam^uuid>` tokens) and the literal `"all"` for `<!channel>`. Order-preserving and deduplicated. The response envelope additionally carries an `addresses` map keyed by UUID, every sender and mention-target address referenced on this page, with display name, type (`user`/`bot`/`userGroup`/`standardGroup`/`meetingGroup`/`teamRoam`), and type-specific fields (e.g. `botCode`, `email`, `isGuest`). Replace `<@<uuid>>` and `<!subteam^<uuid>>` in `text` with `@` + `addresses.<uuid>.displayName` to render, and `<!channel>` with `@all`. The map omits IDs the caller is not authorized to view (cross-roam bots, private cross-account groups, etc.), render those as `@unknown`. For excludeUserIds, pass the `userId` field from a prior result (matches the wire shape).

Update a bot message's content. Specify the message by chatId and timestamp. Supports text, markdown, block kit, and attachments. Requires a bot token or a personal token with useBotIdentity=true.

List conversations from the workspace's attendance/reporting log, with per-participant time-in-conversation detail. Supports date range filtering and pagination. WHEN TO USE THIS TOOL: - Use for attendance and usage questions: "who was in meetings yesterday", "how long did we spend in huddles last week", "which rooms get used". - Unlike meeting_list (which is transcript-oriented), conversation_list covers every conversation, including short huddles and calls without a transcript or recording, and reports how long each participant was present. - For meeting content (summaries, transcripts, action items), use meeting_list / meeting_info / meeting_transcript instead. WHAT IT RETURNS: - One entry per conversation: id, place, room, roomType, start/end times, and meetingLinkIds when the room was booked through a meeting link. - participants: each participant's name and total seconds in the conversation. Requires the user:read scope; emails additionally require user:read.email. ACCESS: - Org tokens list every conversation in the workspace (requires broad meeting access). - Personal tokens list only conversations the token owner participated in. A page may then contain fewer than `limit` matches (even zero) while more history remains, keep following nextCursor until it is empty. Parameters: - after (optional): RFC3339 datetime; only conversations after this time (switches results to ascending order) - before (optional): RFC3339 datetime; only conversations before this time - limit (optional): Max conversations per page (default 10, max 100) - cursor (optional): Pagination cursor from a previous response's nextCursor - expand (optional): Comma-separated extra fields. "ip" adds each participant's client IP address (org tokens only).

Create a shareable Roam link to a specific chat message. WHEN TO USE THIS TOOL: - When a user asks for a link to a message so they can share or reference it - To turn a message found via chat_history or chat_search into a URL that opens that message in Roam Parameters: - chatId, groupId, or userIds (exactly one required): the chat containing the message - timestamp (required): the message's timestamp in Unix microseconds - threadTimestamp (optional): the thread root's timestamp, required when the message is a thread reply The message must exist and be readable by this credential; otherwise the call fails and no link is returned. Returns the link URL along with the resolved chatId and timestamps. The link identifies the message but does not grant access, recipients see it only if they are members of the chat.

Get the authenticated user's identity: `id`, `name`, and (when the token has the `user:read.email` scope) `email`. This is a projection over `token.info` that returns only the user object, useful for quickly answering "who am I" without parsing the full token payload. For org tokens, returns the bot identity.

Join a public group/channel as the calling identity. Org tokens join as the bot; personal tokens join as the owner. Private groups cannot be joined. Idempotent if already a member.

List all bookings for a specific lobby. Supports date range filtering and pagination.

List Magicasts. Supports date range filtering and pagination. Returns metadata only (id, name, createdAt, owner, cover). Use magicast_info for transcript cues, chapters, and video.

Get a shareable player URL for a Magicast, creating the share link if one does not already exist (get-or-create). WHEN TO USE THIS TOOL: - Use this when the user wants a link to send someone so they can watch the Magicast in the Roam player. - Use this AFTER finding a Magicast ID via magicast_list or magicast_info. IMPORTANT: - This is NOT a read. It mints a Roam-hosted URL (`https://<roam>/share/<key>`) that can be distributed outside Roam. Only call it when the user actually wants a shareable link, reading a Magicast (magicast_info) never creates one. - Anyone with the returned URL can watch the Magicast (subject to the workspace's share settings), so treat it as a credential and only share it as the user intends. - It is idempotent: repeat calls for the same Magicast return the same URL rather than minting a new one. - There is no `https://ro.am/magicast/<id>` URL. The player URL is always `/share/<key>`. Parameters: - id (required): The Magicast ID (UUID) from magicast_list or magicast_info. Returns: - id: The Magicast ID. - url: The shareable URL (e.g. https://<roam>/share/<key>).

Create a new meeting link with a specified time window and optional host assignment.

Get details about a specific meeting link.

List meeting transcripts with optional date filters and pagination. WHEN TO USE THIS TOOL: - Use this tool FIRST when the user asks about meetings - Start by calling with NO date parameters to get the most recent meetings - Use the cursor from the response to page backwards through older meetings - For keyword searches (e.g., "meetings about budgets"), use meeting_search instead CRITICAL DATE FILTER GUIDANCE: - For recent requests (e.g., "recent meetings", "today", "yesterday", "this week", "last week"), DO NOT set after/before - For those requests, call meeting_list without date filters and page backwards with cursor; filter by returned start/end timestamps - Only set after/before when the user gave explicit calendar boundaries or you need a strict historical window - Avoid guessing relative dates for after/before EXPAND FIELDS: - For broad questions across many recent meetings (action items, weekly recaps, status updates, decision logs), pass `expand: "summary,actionItems,chapters"` so each returned item already carries that data. - This avoids firing one meeting_info per row, which is the slow path. Reserve meeting_info for when you need full detail (participants) on a specific meeting. - Allowed values are `summary`, `actionItems`, and `chapters`. Pass them as a single comma-separated string. - When `actionItems` is expanded, each entry includes `id`, `complete`, `assigneeId` (explicit assignment), `suggestedAssigneeId` (AI suggestion), and `suggestedAssigneeName` (display name for `assigneeId` when set, otherwise the AI-suggested name). On personal access tokens only, also includes `assignedToMe` and `suggestedForMe`. Skip `complete: true` items unless the user wants history. Prefer `assignedToMe: true`; treat `suggestedForMe: true` as a suggestion. - Meetings without a transcript (e.g. very short calls, calls without recording) will simply omit those fields. WORKFLOW: 1. Call meeting_list (no dates) to get recent meetings. Add `expand` if you need cross-meeting content rather than just titles. 2. Use the nextCursor to page backwards if the meeting isn't in the first page. 3. Use meeting_info with the ID for full detail (participants) on a specific meeting, or meeting_transcript for verbatim transcript. Parameters: - after (optional): Only include meetings after this time (RFC3339). Prefer leaving unset for recent-period requests. - before (optional): Only include meetings before this time (RFC3339). Prefer leaving unset for recent-period requests. - limit (optional): Maximum number of meetings to return - cursor (optional): Pagination cursor from a previous response to fetch the next page - expand (optional): Comma-separated extra per-meeting fields: `summary`, `actionItems`, `chapters`. Use this when scanning many meetings at once. Returns paginated meeting list with meeting name, start/end times, participant count, `hasVideo` (whether the meeting was video recorded), and `videoStatus` (`available`, `processing`, or `none`, once `available`, use meeting_share_link to get a shareable link to the recording). Each meeting includes an id for use with meeting_info and meeting_transcript. When expand is set, each item additionally carries the requested fields.

Ask a question or give an instruction about a meeting's transcript. Uses AI to answer based on the meeting content.

Search meeting recordings by content. Supports natural language queries like "meetings with John last week" or "discussions about the product launch". WHEN TO USE THIS TOOL: - Use this when searching for meetings by TOPIC or CONTENT (e.g., "meetings about budgets", "discussions with the marketing team") - Use this when the user mentions specific keywords or topics they want to find - For browsing by date only (e.g., "my meeting yesterday"), use meeting_list instead WORKFLOW: 1. Use meeting_search to find relevant meetings by content/topic 2. Use meeting_info with the result's meetingId (passed as the id parameter) to get detailed summary and chapters 3. If the summary doesn't answer the question, use meeting_transcript for the full transcript Parameters: - query (required): Search query for meeting content. Supports: - Keywords: "budget review", "product launch" - Natural language filters: "meetings with John last week", "calls about hiring in January" - after (optional): Only include meetings after this date (YYYY-MM-DD) - before (optional): Only include meetings before this date (YYYY-MM-DD) - timezone (optional): Timezone for date interpretation (e.g. America/New_York) Returns meeting results with: - meetingId (pass this as the id parameter to meeting_info and meeting_transcript) - Meeting name and date - Highlighted matches showing where query terms appear in summaries and transcripts

Retrieve the verbatim transcript for a meeting as WebVTT (timestamped cues with speaker names in `<v>` tags). WHEN TO USE THIS TOOL: - Use this ONLY when meeting_info's summary doesn't contain the specific detail needed - Use this when the user needs exact quotes or specific wording from the meeting - Use this when looking for detailed context not captured in the summary WORKFLOW: 1. First use meeting_list or meeting_search to find the meeting 2. Use meeting_info to get the summary and chapter list 3. If the summary is insufficient, use this tool for the verbatim transcript Parameters: - id (required): The meeting ID (UUID) from meeting_list or meeting_search results Note: Transcripts can be very long. Prefer meeting_info first, its summary usually answers the question. ERRORS: A 404 with code `transcript_pending` means the meeting is in progress or the transcript is still processing, it will exist soon; do not retry in a tight loop. A 404 with code `transcript_unavailable` means the meeting was not transcribed and the transcript will never exist, stop retrying.

List OnAir broadcast events.

Update an existing OnAir event. hosts[].imageUrl must be a Roam-hosted avatar URL from asset_create with purpose "avatar".

Add guests to an OnAir event.

Get details about an OnAir event guest.

Remove a guest from an OnAir event.

List emoji reactions and poll votes on a message.

Returns information about the current API token, including the authenticated user's identity (ID, name, email), the OAuth client ID, scopes, account, and bot persona (if any).

List recent FAILED webhook delivery attempts for the authenticated client, timeouts (statusCode 0, error "timeout"), connection errors, and non-2xx responses. Use this to diagnose why an endpoint is not receiving events. Successful deliveries are not recorded. Each row has timestamp, webhookId, event, url, statusCode, error (class), response (server's error body, when any), durationMs, and messageId. Results are newest-first and strictly scoped to the caller's own subscriptions. Failures are retained for about 30 days.