# Roam on boxd

> Roam HQ provides APIs for secure messaging, chat, file sharing, and collaboration with enterprise-grade security and compliance features.

- Page: https://boxd.sh/integrations/roam/
- CLI: `run roam` (39 commands, 6 marked common)
- SDK: `import { roam } from "@boxd/run"`; every parameter and response type is at `@boxd/run/roam`
- Triggers: none
- Connect: `run auth roam` (Sign in with Roam), or https://app.boxd.sh/integrations/detail/roam
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth roam      # once: prints a link to connect your account
run roam           # list its commands
run roam get-scim-schema --help
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, roam } from "@boxd/run";

every("1 hour", async () => {
  const result = await roam.getScimSchema({ schemaId: "…" });
  console.log(result);
});
```

Run it with `run roam.run.ts`. Roam has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run roam <command> --help` lists the optional ones. "common" marks what `run roam` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-group-members` | `roam.addGroupMembers()` | `--group` | 2 | Add one or more group members and/or admins to an existing Roam group |
| `add-reaction` | `roam.addReaction()` | `--chat` `--message-id` `--name` `--timestamp` | 0 | Add an emoji reaction to a message in a chat |
| `create-group` | `roam.createGroup()` | `--name` | 5 | Create a group address that can be used for chat |
| `create-scim-group` | `roam.createScimGroup()` | `--display-name` | 2 | Create a new group in your Roam organization using SCIM 2.0 |
| `create-user` | `roam.createUser()` | `--emails` `--name` `--userName` | 5 | Create a new user in Roam via SCIM 2.0 protocol for automated user provisioning |
| `delete-group` | `roam.deleteGroup()` | `--id` | 0 | Archive a group in Roam using SCIM 2.0 protocol |
| `delete-user` | `roam.deleteUser()` | `--id` | 0 | Archive a user in Roam using SCIM 2.0 protocol |
| `get-address-info` ·common | `roam.getAddressInfo()` | `--addr` | 0 | 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 |
| `get-chat-history` | `roam.getChatHistory()` | `--chat` | 5 | Lists messages in a chat, filtered by date range (after/before) |
| `get-meeting-link` ·common | `roam.getMeetingLink()` | `--id` | 0 | Get a meeting link |
| `get-resource-types` | `roam.getResourceTypes()` | — | 0 | Returns the list of SCIM 2.0 resource types supported by Roam |
| `get-scim-config` | `roam.getScimConfig()` | — | 0 | Retrieve Roam's SCIM service provider configuration |
| `get-scim-schema` ·common | `roam.getScimSchema()` | `--schemaId` | 0 | Retrieves the definition of a specific SCIM 2.0 schema by its unique identifier (URN) |
| `get-scim-user` | `roam.getScimUser()` | `--id` | 0 | Retrieve a single user by their Roam Person ID using SCIM 2.0 protocol |
| `get-test` | `roam.getTest()` | — | 0 | Test endpoint for API connectivity |
| `get-token-info` | `roam.getTokenInfo()` | — | 0 | Retrieves information about the current Roam access token |
| `get-user-info` | `roam.getUserInfo()` | `--id` | 1 | Get detailed information about a single user in your Roam workspace |
| `list-chats` | `roam.listChats()` | — | 2 | 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 |
| `list-group-members` | `roam.listGroupMembers()` | `--group` | 2 | List members in a group in your Roam workspace |
| `list-groups` | `roam.listGroups()` | — | 3 | Returns a paginated list of groups in your Roam organization via SCIM 2.0 |
| `list-lobbies` | `roam.listLobbies()` | — | 1 | Lists active lobbies in your Roam account |
| `list-meetings` | `roam.listMeetings()` | — | 4 | Lists all meetings in your home Roam, filtered by date range |
| `list-recordings` | `roam.listRecordings()` | — | 4 | List all recordings in your home Roam |
| `list-schemas` | `roam.listSchemas()` | — | 0 | List all SCIM 2.0 schemas supported by Roam |
| `list-scim-users` | `roam.listScimUsers()` | — | 3 | List users in your Roam organization using SCIM 2.0 protocol |
| `list-transcripts` | `roam.listTranscripts()` | — | 4 | Lists all transcripts in your Roam workspace, filtered by date range |
| `list-user-audit-log` | `roam.listUserAuditLog()` | `--date` | 2 | Get a list of user audit log entries for the account |
| `list-users` | `roam.listUsers()` | — | 3 | List all users in the Roam workspace |
| `lookup-user` | `roam.lookupUser()` | `--email` | 0 | Look up a user in your Roam workspace by their email address |
| `patch-group` | `roam.patchGroup()` | `--id` `--operations` | 0 | Partially updates a group using SCIM 2.0 protocol |
| `patch-user` | `roam.patchUser()` | `--id` `--operations` | 0 | Partially updates a user using SCIM 2.0 protocol |
| `post-chat` ·common | `roam.postChat()` | `--chat` | 8 | Post a message to a chat |
| `remove-group-members` | `roam.removeGroupMembers()` | `--group` `--members` | 0 | Remove one or more members from a group in your Roam workspace |
| `replace-group` | `roam.replaceGroup()` | `--displayName` `--id` | 2 | Fully replaces a group's attributes using SCIM 2.0 protocol |
| `replace-user` | `roam.replaceUser()` | `--emails` `--id` `--name` `--userName` | 5 | Fully replaces (updates) a user's attributes in Roam via SCIM 2.0 protocol |
| `send-message` ·common | `roam.sendMessage()` | `--recipients` `--text` | 2 | Sends the given message to the specified recipients |
| `send-typing` | `roam.sendTyping()` | `--user-ids` | 0 | Notify other chat participants that you are typing |
| `update-meeting-link` | `roam.updateMeetingLink()` | `--id` `--name` | 3 | Update settings for an existing meeting link in Roam |
| `upload-item` ·common | `roam.uploadItem()` | `--file` | 1 | Upload a file to Roam so it can be sent as a chat attachment |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.