Roam
Roam HQ provides APIs for secure messaging, chat, file sharing, and collaboration with enterprise-grade security and compliance features.
Verdict
Common use cases
- Provision new hires in Roam from onboarding chat
- Archive inactive groups during quarterly cleanup
- Add emoji reactions to standup updates
- Create project groups and assign admins instantly
- Pull user details for support ticket triage
Integration
- Vendor
- Roam
- Category
- communication
- Auth
- API_KEY
- Tools
- 39
- Composio slug
roam
Tools
- Add group members
Add one or more group members and/or admins to an existing Roam group. Use this tool when: - You need to add new members to an existing group - You need to promote existing members to admin status - You want to bulk add multiple users to a
- Add Reaction to Message
Add an emoji reaction to a message in a chat. Use this action when you want to react to a message with an emoji in a Roam chat. The action requires the message ID, chat ID, reaction name, and timestamp. Required scope: chat:send_message or
- Create Group
Create a group address that can be used for chat. Groups which specify an admin will operate in an "Admin only" management mode, where only admins may change settings. Otherwise, all members have that capability. Groups require at least one
- Create Roam SCIM Group
Tool to create a new group in your Roam organization using SCIM 2.0. Use when you need to provision a new group for managing user access and permissions via the SCIM 2.0 protocol. The displayName is required and must be 64 characters or les
- Create Roam User
Create a new user in Roam via SCIM 2.0 protocol for automated user provisioning. Use when you need to add a new user to your Roam organization. The userName must match the primary email address exactly. The role defaults to 'User' but can b
- Delete Roam Groupdestructive
Archive a group in Roam using SCIM 2.0 protocol. This is a soft delete operation that archives the group. Use when you need to archive a group that is no longer needed while preserving data for audit purposes. Returns 204 No Content on succ
- Delete Roam Userdestructive
Archive a user in Roam using SCIM 2.0 protocol. This is a soft delete operation that deprovisions the user. Use when you need to remove a user from the organization while preserving their data for audit purposes. Returns 204 No Content on s
- Get Address Info
Get information about a chat address, which is the name for any entity that may participate in a chat, such as a user, visitor, or bot. Use this action to retrieve details like display name, email, profile image, and other information about
- Get chat history
Lists messages in a chat, filtered by date range (after/before). The ordering of results depends on the filter specified: - If no parameters provided: returns most recent messages, sorted in reverse chronological order. - If 'after' is spec
- Get meeting link
Tool to get a meeting link. Use when you need to retrieve information about a specific meeting link by its ID. Requires the 'meetinglink:read' scope.
- Get Roam SCIM Resource Types
Returns the list of SCIM 2.0 resource types supported by Roam. Use this action to discover what resource types are available in the Roam SCIM API. Currently returns User and Group resource types. This endpoint requires no parameters.
- Get SCIM schema
Retrieves the definition of a specific SCIM 2.0 schema by its unique identifier (URN). This endpoint returns the complete schema definition including all attributes, their types, mutability, and other properties. Common schemas include: - u
- Get SCIM service provider config
Tool to retrieve Roam's SCIM service provider configuration. Use when you need to discover Roam's SCIM API capabilities including supported authentication schemes, bulk operations, filtering, and other service provider features. This endpoi
- Get token info
Retrieves information about the current Roam access token. Use this tool to: - Get the bot's chat address - Check the OAuth scopes granted to the current token - Retrieve information about the associated Roam workspace Returns the chat addr
- Get user by ID (SCIM)
Tool to retrieve a single user by their Roam Person ID using SCIM 2.0 protocol. Use when you need to get detailed information about a specific user including their name, email, active status, and role in Roam. The user ID is the SCIM user I
- Get user info
Get detailed information about a single user in your Roam workspace. Requires user:read scope. Additional scopes (user:read.email, user:read.status) needed for expanded fields.
- List group members
List members in a group in your Roam workspace. Use this tool when: - You need to see all members of a specific group - You want to check who has access to a group - You need to paginate through large groups Access conditions: - The group m
- List Roam Chats
Lists all accessible chats, which consist of all DMs, MultiDMs, and Channels that your bot has been added to, in addition to all public channels. Supports pagination via cursor and limiting the number of results. Use this action to discover
- List Roam Lobbies
Lists active lobbies in your Roam account. Returns all lobby configurations with their IDs, display names, URLs, and active status. Use this action to discover available lobbies before performing operations on them.
- List Roam Meetings
Lists all meetings in your home Roam, filtered by date range. Supports pagination via cursor and limiting the number of results. Returns meeting details including meeting ID, room, time, and participants. Use this action to discover availab
- List Roam Recordings
Tool to list all recordings in your home Roam. Use when you need to retrieve recordings with optional date range filtering (after/before) or pagination. Supports filtering by date range and paginating through large result sets.
- List Roam Transcripts
Lists all transcripts in your Roam workspace, filtered by date range. Supports pagination via cursor and limiting the number of results. Returns transcript metadata (id, meetingId, start, end, participants) without full content. Use this ac
- List SCIM Groups
Returns a paginated list of groups in your Roam organization via SCIM 2.0. Use when you need to retrieve all groups in your Roam organization using the SCIM protocol. Supports pagination using startIndex and count parameters. Note: The filt
- List SCIM Schemas
Tool to list all SCIM 2.0 schemas supported by Roam. Use when you need to discover available SCIM resource schemas. Returns the core User and Group schemas plus Roam's custom role extension schemas.
- List User Audit Log
Tool to get a list of user audit log entries for the account. Use when you need to retrieve audit logs for compliance and security monitoring purposes. This action requires the 'userauditlog:read' scope and organization-level access. Requir
- List Users
Tool to list all users in the Roam workspace. Use when you need to retrieve a list of users with optional pagination and expanded fields like status. Required scope: user:read (add user:read.email for emails, user:read.status for presence s
- List users (SCIM)
Tool to list users in your Roam organization using SCIM 2.0 protocol. Use when you need to retrieve a paginated list of users in your Roam workspace via the SCIM 2.0 API for identity provider integration. Supports pagination via startIndex
- Lookup user by email
Look up a user in your Roam workspace by their email address. Use when you need to find a user's details including their ID, name, and profile information. Required scopes: user:read and user:read.email.
- Patch a group
Partially updates a group using SCIM 2.0 protocol. Use this action to add or remove members from a group, or replace the group's display name. The PATCH operation supports 'add', 'remove', and 'replace' operations on group attributes. Examp
- Patch user (SCIM)
Partially updates a user using SCIM 2.0 protocol. Use when you need to modify specific attributes of an existing user without replacing the entire resource. Currently, Roam only supports the 'replace' operation on the 'active' attribute, wh
- Post message to chat
Post a message to a chat. Messages can be plain markdown text or rich Block Kit layouts with headers, sections, buttons, and more. Messages may be posted to a chat, a group, or addresses such as users or bots. Use syntax <@USER_ID> for ment
- Remove group membersdestructive
Tool to remove one or more members from a group in your Roam workspace. Use when you need to remove users from a specific group. Note: The group must be public in the user's Roam, or the app must be a member of the group to remove members.
- Replace Roam SCIM Group
Fully replaces a group's attributes using SCIM 2.0 protocol. Use when you need to completely replace all attributes of an existing group, including its display name and member list. This is a full update (PUT), not a partial update (PATCH).
- Replace Roam User
Fully replaces (updates) a user's attributes in Roam via SCIM 2.0 protocol. Use when you need to update all user attributes at once. This is a full replacement operation - all required fields must be provided. Note: This is a PUT operation
- Send message to group
Sends the given message to the specified recipients. At this time, we only support sending to a single group recipient. You can obtain the group ID on the Group Settings page.
- Send Typing Indicator
Tool to notify other chat participants that you are typing. Use when you want to show a typing indicator to one or more users in a chat conversation. This is typically used before sending a message to let recipients know you're composing a
- Test API Connectivity
Test endpoint for API connectivity. Use this endpoint to verify that the Roam API is accessible and authentication is working correctly. Returns a confirmation message on successful connection.
- Update a meeting link
Update settings for an existing meeting link in Roam. Use this action when you need to modify the name, start time, or end time of an existing meeting link. The meeting link ID is required to identify which meeting to update. Note: The host
- Upload File to Roam
Upload a file to Roam so it can be sent as a chat attachment. Use when you need to upload a file, image, or document to Roam before sending it in a chat message. Returns an item ID that can be used with the chat.post endpoint. Supported fil
Setup
Setup guide
- 11. In Switchy, open your workspace settings and navigate to the Integrations tab. 2. Search for Roam and click Connect. 3. You'll be prompted to enter a Roam API key — generate one from your Roam admin dashboard under API Settings. 4. Copy the key and paste it into Switchy's prompt, then click Authorize. 5. Switchy confirms the connection and lists the 39 available tools. 6. Open any Space and type '@Roam get address info for [email]' to test — the MCP should return display name, email, and profile details. 7. If the response fails, verify your API key has read/write permissions for users and groups. 8. To invoke other tools, @mention Roam in any message and describe the task in plain language — Switchy routes the request to the appropriate tool.
What teammates see: by default, memories from Roam are scoped to the Space (PROJECT visibility) - you can mark any memory PRIVATE or share it ORG-wide.
Works well with
Top models
Compatibility data appears once enough Spaces have used this MCP together with a given model.
How Switchy teams use it
Starter prompts
Create Project Group
@Roam create a group called 'Q2 Product Launch' and make alice@company.com and bob@company.com adminsOpen in a Space →
Onboard New User
@Roam create a new user with email newperson@company.com, first name Jordan, last name Lee, and set them as activeOpen in a Space →
Add Members to Group
@Roam add charlie@company.com and dana@company.com to the 'Q2 Product Launch' group as membersOpen in a Space →
React to Message
@Roam add a thumbs-up reaction to message ID abc123 in chat xyz789Open in a Space →
Archive Old Group
@Roam archive the group 'Old Marketing Campaign' since the project wrapped last quarterOpen in a Space →
Example outputs
Illustrative - representative of the model's voice and quality, not literal recordings.
@roam show me all members in the #product-team group and their admin status
Based on the group lookup, #product-team currently has 8 members: 3 admins (alice@company.com, bob@company.com, charlie@company.com) and 5 regular members (dana@company.com, evan@company.com, fiona@company.com, greg@company.com, hannah@company.com). The group was created on March 12, 2024, and operates in admin-only management mode, meaning only the 3 admins can modify group settings or membership.
This example uses the address-info and group-lookup tools to surface membership data. Requires read access to group metadata. Note that Roam groups can have different management modes — this example shows an admin-only group, but your org may use open-membership groups where all members can invite others.
@roam add dana@company.com and evan@company.com to the #launch-planning group as regular members
Successfully added 2 members to #launch-planning: dana@company.com and evan@company.com are now regular members (non-admin). They can participate in group chats and view shared content, but cannot modify group settings or add other members since this group operates in admin-only mode. Both users will receive a notification about being added to the group.
This example demonstrates the add-group-members tool, which modifies group membership. Requires write access to the target group and assumes the requesting user has admin privileges. If the group is in open-membership mode, the permission model differs. Adding members triggers in-app notifications to the new members.
@roam create a new group called #q1-retrospective with me and alice@company.com as admins, then draft a welcome message summarizing our Q1 goals
Created group #q1-retrospective with you and alice@company.com as admins. The group is now active and set to admin-only management mode. Here's a draft welcome message for the group: 'Welcome to the Q1 Retrospective space. This group is for reviewing our Q1 performance against three key goals: (1) ship v2.0 of the mobile app, (2) reduce support ticket resolution time by 30%, and (3) onboard 5 enterprise customers. Let's use this space to share wins, lessons learned, and action items for Q2.' You can post this message or edit it before sending.
This example chains the create-group tool with AI reasoning to generate contextual content. Requires group-creation permissions in your Roam org. The AI drafts the message based on typical Q1 goal patterns, but you'll need to provide actual goal data for accurate content. Group creation is immediate; the message is a draft you must explicitly send.
Use-case deep-dives
When Roam's SCIM provisioning beats manual chat setup
A 6-person agency adds two contractors for a three-week project. The team lead needs them in four Slack-style group chats by Monday morning. Roam's SCIM user creation and group membership tools handle this in one prompt: create the accounts, add them to the right groups, set permissions. The win is speed—no back-and-forth with IT, no manual invite links. The threshold: if you're adding people once a quarter, the API_KEY setup overhead isn't worth it. But if you onboard contractors or clients weekly, Roam's 39 tools turn repetitive admin work into a two-minute AI task. The buying call is clear: teams that treat chat provisioning as a workflow, not a one-off, get their time back.
Using reaction tools to route support threads at scale
A 12-person customer success team uses Roam for client communication. They triage 40+ inbound threads daily by adding emoji reactions: 👀 means claimed, ✅ means resolved, 🔥 means escalated. The Roam MCP's "Add Reaction to Message" tool lets an AI assistant auto-tag threads based on keywords or sentiment—no human has to read every message to decide which emoji to drop. The trade-off: this only works if your team already uses reactions as a routing system. If you're still doing manual assignment or status updates in separate tools, the MCP won't fix that workflow gap. The call: if emoji-based triage is already your process, Roam's MCP automates the busywork. If not, fix the process first.
When soft-delete user tools matter for audit trails
A 20-person fintech startup needs to deprovision a departing employee from Roam while keeping their chat history intact for SOC 2 audits. The "Delete Roam User" tool does a soft archive—the user loses access, but their messages stay searchable for compliance. The MCP handles this in a single call, no manual export or screenshot ritual. The boundary: if you're in a low-stakes vertical where you can hard-delete accounts, this feature is overkill. But if you're in healthcare, finance, or legal, the soft-delete SCIM flow is the difference between passing an audit and scrambling to reconstruct chat logs. The buying decision: regulated teams pay for tools that preserve evidence. Roam's MCP does that without extra steps.
Frequently asked
What does the Roam MCP let me do in Switchy?
It lets your AI agents manage Roam chats, groups, and users directly from Switchy. Agents can create groups, add members, send messages, react with emoji, and provision users via SCIM. You connect once with an API key; agents then handle tasks like onboarding new hires to the right channels or archiving old groups without switching apps.
Do I need admin access to connect Roam?
Yes. The API key you provide must have admin-level permissions in your Roam organization. Without admin access, you won't be able to create groups, manage members, or provision users via SCIM. If you're not an admin, ask your Roam workspace owner to generate the key and share it with you.
Can the Roam MCP read message history or search past chats?
No. The 39 tools focus on group management, user provisioning, and sending or reacting to messages. There's no tool for searching message history or retrieving past conversations. If you need to analyze chat data, you'll need to export it from Roam directly or use their reporting API separately.
Why use this instead of just logging into Roam?
Agents can automate repetitive admin tasks—like adding new hires to five groups at once, or archiving users when they leave—without you clicking through Roam's UI. It's faster for bulk operations and lets you chain Roam actions with other tools in Switchy, like pulling employee data from your HRIS and provisioning them in one prompt.
Who on my team should connect the Roam integration?
Whoever owns your Roam admin account. That person generates the API key and pastes it into Switchy. Once connected, any teammate in your Switchy workspace can invoke Roam tools in their prompts. The key doesn't expire unless you revoke it in Roam, so you only set it up once.