# Analytics
Source: https://docs.withrealm.com/admin/analytics
Track usage, activity, and engagement across your organization
The Analytics dashboard shows how your team uses Realm. Navigate to **Settings** > **Analytics** in the sidebar. The page has four tabs: **Users**, **Chats**, **RFPs**, and **Reports**.
On the **Users**, **Chats**, and **RFPs** tabs, use the date range picker and chart type button at the top to change the time window and switch between **Bar** and **Area** charts. The date range you pick stays the same when you switch tabs.
The headline number on the **Users** and **Chats** tabs shows the current value. When comparable data exists, it also shows the percentage change from the equivalent previous period (e.g. selecting the last 7 days compares against the 7 days before that). An up or down arrow and color show the direction of the change.
## Users
The **Users** tab opens by default. At the top, **Active users** shows the unique active users out of the users who were members at the end of the selected period. The chart below it shows a breakdown of active vs. inactive users over time. Each day uses the membership at the end of that day, so removing a member does not change earlier historical totals.
Below the chart, a table lists every member with their activity in the selected period:
| Column | What it shows |
| - | - |
| **Name** | The member's name. Hover over it to see their email |
| **Role** | The member's role, such as Admin, Member, or Collaborator |
| **Team** | The team the member belongs to |
| **Account created** | The date the member joined |
| **Last used** | The member's most recent sign-in or request. This is not limited to the selected period |
| **Chats** | Chat messages the member sent |
| **RFP rows filled** | RFP rows the member had Realm fill |
| **Agents created** | Agents the member created |
Click **Edit columns** to choose which columns to show. More columns are available there: **Email**, **Days active**, **Searches**, **Thumbs up**, **Thumbs down**, **RFPs started**, and **RFP rows approved**. Your column choice is remembered in your browser.
Click a column header to sort by it, and click it again to reverse the order. Use **Filter members** to find a person by name or email.
If you can manage members, you can set or change a member's team directly in the **Team** column.
## Chats
The **Chats** tab shows the total number of chat messages across Web, Slack, API, MCP, Workflow, and Operator. **Chats by type** breaks the total down by those sources. **Chats by agent** also appears when agent activity reporting is enabled and data is available.
## RFP analytics
Switch to the **RFPs** tab at the top of the page. The top chart shows RFPs started and completed over time, followed by a chart of filled RFP cells. Below the charts you can see summary statistics and breakdowns:
* **Rows approved without edits**: of the approved rows that received a generated answer, the share approved without anyone editing an answer cell after Realm answered it. Rows answered manually or imported are not counted, and an answer a person wrote before Realm filled the row does not count as an edit. Shown for the selected period and for each of the three equal-length periods before it, so you can compare against recent history. Each card is titled by how far back it sits (Selected period, Previous period, 2 periods back, 3 periods back) and shows the dates it covers. Each past period carries a percentage change showing how the selected period compares to it.
* **Avg. completion time**: the average time from starting an RFP to marking it complete, for RFPs completed in each period. Shown with the same three-period comparison and the same date ranges.
* **Rows approved** and **Rows declined**: the share of rows in each review state, for RFPs started in the selected period.
* **RFPs per owner**: how many RFPs each owner started and completed in the selected period.
* **Rows per assignee**: how many rows each assignee is responsible for, and how many of those are approved.
* **Fill stats for completed RFPs**: how the answer cells of all RFPs completed in the selected period were filled: the total number of answer cells, the share of them Realm filled, and the share of Realm-filled cells kept without edits. These count cells rather than rows, and they do not require the row to be approved, so they differ from the **Rows approved without edits** cards above. Hover over the icon next to a column header for an explanation of the number.
* **Completed RFPs**: the RFPs completed in the selected period, with their project, owner, completion date, and time to complete. Click **View fill stats** on a row to see the same fill statistics for that single RFP.
Click **Export RFP metrics** below the breakdowns to download all of the above as a CSV file.
## Reports
Switch to the **Reports** tab at the top of the page. Reports are Excel (`.xlsx`) workbooks containing overall usage data. Depending on your organization's configuration, they can also include user, query, and agent activity breakdowns for the selected date range.
To generate a report, pick a date range and click **Generate**. The report downloads automatically. Previously generated reports are listed below and can be re-downloaded at any time.
# API keys
Source: https://docs.withrealm.com/admin/api
Integrate Realm into your workflows with the REST API
The Realm API lets you use Realm assistants programmatically and manage documents from your own applications. Navigate to **Settings** > **API Keys** to create and manage your keys.
API keys are not available on trial plans.
## Creating a Key
Click **Create New Key** to open the creation dialog.
### Name and expiration
Give the key a descriptive name (e.g. "CRM Integration" or "Claude Code API key"). Choose an expiration from the dropdown, or select "Never" if the key should not expire.
### Agents
Control what the API key can do with agents and which agents it has access to.
| Setting | Description |
| - | - |
| **Read and write chats** | The key can create new chats, read existing chats, and delete chats |
| **All agents** | The key can chat with all agents, including any created in the future |
| **Select Agents** | Pick specific agents the key has access to. Only selected agents can be used with this key. |
### Documents
| Setting | Description |
| - | - |
| **Write documents to Realm** | The key can write and delete documents from custom integrations |
### Save your key
After clicking **Create Key**, the key is shown once in a dialog. Copy it immediately and store it in a safe place. You will not be able to view it again. If you lose it, you will need to create a new key.
## Managing keys
Each key shows its name, token prefix (for identification), created date, last used date, and expiration status. Expired or soon-to-expire keys are highlighted.
For each key, you can:
* **Edit** — update the name, agent access, permissions, or expiration
* **Regenerate** — create a new token value while keeping the same configuration. Applications using the old key will need to be updated.
* **Delete** — permanently revoke the key
## Settings
**API Keys for All Users** — By default, only admins can create API keys. Toggle this on to allow all users in your organization to create their own keys.
**Show API chats in history** — When enabled, conversations initiated through the API appear in your chat history.
## Using the API
All API requests require a Bearer token in the `Authorization` header:
```bash theme={null}
curl -X POST https://app.withrealm.com/api/v1/chat \
-H "Authorization: Bearer realm_api_..." \
-H "Content-Type: application/json" \
-d '{"message": "What are our open support tickets?"}'
```
For the full list of endpoints, usage details, and rate limits, see the [API Reference](/api-reference/introduction).
# Azure DevOps
Source: https://docs.withrealm.com/admin/data-sources/azure-devops
Connect Azure DevOps to sync work items and repos
Connect Azure DevOps to Realm to make work items, repositories, and documentation searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Azure DevOps, or click **Reconnect** if already connected.
## Connecting Azure DevOps
Click **Connect** on the Azure DevOps data source page. You'll be redirected to Microsoft's OAuth consent screen. Review the permissions and click **Accept**. The person connecting should be an Azure DevOps organization admin.
Once authorized, you'll be redirected back to Realm to select which projects to sync.
## What gets synced
| Content | Synced |
| - | - |
| Work items (tasks, bugs, user stories) and comments | Yes |
| Pull requests and PR comments | Yes |
| Repository documentation files (Markdown, HTML, text) | Yes |
## Selecting projects
After connecting, choose which Azure DevOps projects to sync. You can add or remove projects at any time from the data source page.
## Permissions
Realm enforces Azure DevOps' native permission model. Users can only see content they have access to in Azure DevOps.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Azure DevOps data visible to all Realm users.
# Chorus
Source: https://docs.withrealm.com/admin/data-sources/chorus
Connect Chorus to sync call recordings and transcripts
Connect Chorus to Realm to make call recordings and transcripts searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Chorus, or click **Reconnect** if already connected.
## Connecting Chorus
Connect Chorus using an API key. On the data source page, enter your Chorus API key and click **Submit**.
## What gets synced
| Content | Synced |
| - | - |
| Call transcripts (with speaker identification) | Yes |
| Call summaries and key takeaways | Yes |
| Call metadata (participants, duration, date) | Yes |
| Call metrics (talk ratio, filler words, longest monologue) | Yes |
| Deal context (account, opportunity) | Yes |
## Permissions
All synced Chorus data is visible to call participants and users with access in Chorus.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Chorus data visible to all Realm users.
# Clari
Source: https://docs.withrealm.com/admin/data-sources/clari
Connect Clari to sync call recordings and transcripts
Connect Clari (Copilot) to Realm to make call recordings, transcripts, and insights searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Clari, or click **Reconnect** if already connected.
## Connecting Clari
Connect Clari using an API key. On the data source page, enter:
1. **API key** and **API secret**
2. **Domain** (defaults to `https://rest-api.copilot.clari.com`)
## What gets synced
| Content | Synced |
| - | - |
| Call transcripts (with speaker identification) | Yes |
| Call summaries and action items | Yes |
| Call metadata (participants, duration, date) | Yes |
| Call metrics (talk ratio, questions asked, longest monologue) | Yes |
| Topic insights and annotations | Yes |
| Deal context (account, opportunity, stage, value) | Yes |
| Calls without transcripts | No |
## Permissions
Realm enforces Clari's native permission model. Users can only see calls they have access to in Clari, including private call restrictions.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Clari data visible to all Realm users.
# Coda
Source: https://docs.withrealm.com/admin/data-sources/coda
Connect Coda to sync docs and tables
Connect Coda to Realm to make documents, pages, and tables searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Coda, or click **Reconnect** if already connected.
## Connecting Coda
Connect Coda using an API key. On the data source page, enter your Coda API token.
To create an API token, go to [coda.io/account#apiSettings](https://coda.io/account#apiSettings) and generate a new token. The person connecting must have the **Org admin** role in Coda.
The Coda API for reading users and permissions is only available on **Enterprise** plans.
## What gets synced
| Content | Synced |
| - | - |
| Documents and all child pages | Yes |
| Page content (text and embedded tables) | Yes |
| Comments | No |
## Selecting documents
After connecting, choose which Coda documents to sync. You can add or remove documents at any time from the data source page.
## Permissions
Realm enforces Coda's native permission model. Users can only see documents they have access to in Coda.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Coda data visible to all Realm users.
# Confluence
Source: https://docs.withrealm.com/admin/data-sources/confluence
Connect Confluence to sync pages and content
Connect Confluence to Realm to make wiki pages, blogs, and embedded files searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Confluence, or click **Reconnect** if already connected. Follow the on-screen instructions to install the Realm app on your Confluence site.
## Connecting Confluence (Cloud)
Install the [Realm app from Atlassian Marketplace](https://marketplace.atlassian.com/apps/1233308/realm?tab=overview\&hosting=cloud) on the Confluence site you want to connect.
Then, navigate to [Atlassian Admin](https://admin.atlassian.com/) > **Apps** > **Sites** > **Your Site Name**.
Then click **Connected Apps**, find the Realm app, click the three dots, and click **Configure**.
The configuration page shows a token and an Atlassian user ID. Copy the token
into the **Client Key** field in Realm and the user ID into the **User ID**
field. If you are not also a Realm admin, send the configuration page to a
Realm admin so they can enter both values.
The person connecting should have access to the Confluence spaces you want to sync.
Depending on your organization's Atlassian settings, an admin may need to approve the app installation before it can be used.
## What gets synced
| Content | Synced |
| - | - |
| Pages | Yes |
| Blogs | Yes |
| Attached files (up to 10 MB) | Yes |
| Comments | No |
## Selecting spaces
After connecting, choose which Confluence spaces to sync. You can add or remove spaces at any time from the data source page.
## Permissions
Realm enforces Confluence's native permission model. Users can only see content they have access to in Confluence.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Confluence data visible to all Realm users.
## Smart features
Realm integrates with Confluence's content lifecycle:
| Confluence Feature | Realm Behavior |
| - | - |
| Verified pages | Auto-verified in Realm |
| Archived pages | Auto-hidden in Realm |
| Draft pages | Not shown until published |
## Confluence Data Center
For Confluence Data Center (self-hosted), connect using a Personal Access Token instead of the Marketplace app.
1. Follow [Atlassian's instructions](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html) to create a PAT. Disable "Automatic expiry" to prevent sync interruptions.
2. Enter the token and your Confluence instance URL on the data source page in Realm.
3. Select the spaces you want to sync.
## Configuring properties
You can configure which Confluence properties are synced from the data source page. This lets you control which metadata fields are included alongside page content.
# API data source
Source: https://docs.withrealm.com/admin/data-sources/custom-api
Push documents to Realm from any system using the REST API
Push documents from any system into Realm using the REST API. This is useful for syncing data from internal tools, custom databases, or any source without a native data source. Navigate to **Settings** > **Data sources** and click **Add** next to API data source.
## Setting up an API data source
On the Data sources page, click **Add** next to API data source and give it a name. After creating it, you can upload a custom icon on the data source page. The name and icon appear in search results so users can identify where the content came from.
Go to **Settings** > **API Keys** and click **Create New Key**. Enable the **Write documents to Realm** permission. Copy the key immediately, as it won't be shown again. See [API Keys](/admin/api) for full details.
Use the REST API to push documents to your data source. See the [Upsert Documents](/api-reference/documents/upsert-documents) API reference and the examples below.
## Pushing documents
Send a POST request to add or update documents. To update a document, send another request with the same `id`.
```bash theme={null}
curl -X POST https://app.withrealm.com/api/external/alpha/documents/{data_source_id} \
-H "Authorization: Bearer realm_api_..." \
-H "Content-Type: application/json" \
-d '{
"documents": [
{
"id": "doc-123",
"title": "Quarterly Review",
"content": "# Q4 Results\n\nRevenue grew 15%.",
"contentType": "markdown"
}
]
}'
```
See the [API Reference](/api-reference/documents) for the full document schema, including optional fields like `url`, `meta`, `createdAt`, `readAccess`, and `verified`.
Set `verified` to `true` on each upsert or upload while the source system
currently treats the document as authoritative. If a later request for the same
document omits `verified` or sends `false`, Realm stops asserting that
source-managed verification:
```json theme={null}
{
"documents": [
{
"title": "Official Security Policy",
"content": "...",
"contentType": "markdown",
"verified": true
}
]
}
```
## Uploading files
For binary files (PDFs, Word documents, etc.), use the two-step upload flow:
```bash theme={null}
# Step 1: Get an upload URL
curl -X POST https://app.withrealm.com/api/external/alpha/documents/{data_source_id}/upload \
-H "Authorization: Bearer realm_api_..." \
-H "Content-Type: application/json" \
-d '{"title": "Product Spec", "fileName": "spec.pdf", "contentType": "application/pdf"}'
# Step 2: Upload the file to the returned URL
curl -X PUT "{upload_url}" \
-H "Content-Type: application/pdf" \
--data-binary @spec.pdf
```
Realm automatically extracts text from uploaded files. See the [API Reference](/api-reference/documents) for details.
## Listing documents
Retrieve documents from your data source with cursor-based pagination:
```bash theme={null}
curl https://app.withrealm.com/api/external/alpha/documents/{data_source_id}?limit=20 \
-H "Authorization: Bearer realm_api_..."
```
Use the `nextCursor` from the response to fetch the next page. See the [API Reference](/api-reference/documents) for all query parameters.
## Deleting documents
Delete all documents older than a given timestamp:
```bash theme={null}
curl -X DELETE "https://app.withrealm.com/api/external/alpha/documents/{data_source_id}?older_than=2025-01-01T00:00:00Z" \
-H "Authorization: Bearer realm_api_..."
```
You can also delete individual documents by ID. See the [API Reference](/api-reference/documents) for all options.
## Access control
By default, documents are visible to all users in your organization. To restrict access, include a `readAccess` array with the email addresses of users who should see the document:
```json theme={null}
{
"documents": [{
"title": "Confidential Report",
"content": "...",
"contentType": "text",
"readAccess": ["alice@company.com", "bob@company.com"]
}]
}
```
## Sync behavior
Unlike native data sources, API data sources do not sync automatically. You are responsible for keeping documents up to date. Common approaches:
* **Cron job** that periodically exports data and pushes it to Realm
* **Webhook handler** that pushes documents when they change in your source system
* **CI/CD pipeline** that pushes documentation after each deploy
# Freshdesk
Source: https://docs.withrealm.com/admin/data-sources/freshdesk
Connect Freshdesk and Freshservice to sync tickets
Connect Freshdesk or Freshservice to Realm to make support tickets and conversations searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Freshdesk, or click **Reconnect** if already connected.
Realm supports both **Freshdesk** and **Freshservice** via this data source. Freshservice support is in beta.
## Connecting Freshdesk
Connect using an API key. On the data source page, enter:
1. **API key** - Find yours in Freshdesk ([instructions](https://support.freshdesk.com/support/solutions/articles/215517-how-to-find-your-api-key)) or Freshservice ([instructions](https://support.freshservice.com/support/solutions/articles/50000000306-where-do-i-find-my-api-key-)).
2. **Domain** - Your Freshdesk domain (e.g., `https://company-name.freshdesk.com/`) or Freshservice domain (e.g., `https://company-name.freshservice.com/`).
The API key should be from a user with an **Admin role** for full access to all tickets.
## What gets synced
| Content | Synced |
| - | - |
| Support tickets and custom fields | Yes |
| Ticket summary | Yes |
| Ticket conversations and thread messages | Yes |
| Resolution notes | Yes |
| Requester and company information | Yes |
| Knowledge base articles (Freshdesk only) | Yes |
| Attachments | No |
Freshdesk knowledge base (solution) articles are synced. Freshservice does not expose its solution articles to Realm, so they are not synced from a Freshservice connection.
## Permissions
Realm enforces Freshdesk's native permission model. Users can only see tickets they have access to in Freshdesk.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Freshdesk data visible to all Realm users.
The initial sync can take from hours to multiple days depending on your ticket volume.
# GitHub
Source: https://docs.withrealm.com/admin/data-sources/github
Connect GitHub to sync repos, issues, and pull requests
Connect GitHub to Realm to make repository documentation, issues, pull requests, wikis, and discussions searchable. Navigate to **Settings** > **Data sources** and click **Connect** on GitHub, or click **Configure** if already connected.
## Connecting GitHub
Click **Connect** on the GitHub data source page. You'll be redirected to GitHub's OAuth flow. Review the permissions and click **Authorize**. The person connecting should be a GitHub organization admin.
If GitHub shows **Request** or **Install and request**, GitHub sends an installation request to the owners of the selected organization. Realm for GitHub remains disconnected and does not sync data while approval is pending. After an owner installs the app, return to Realm and connect GitHub again.
Once authorized, you can configure which repositories to sync from the GitHub app settings page. Click **Configure** on the data source page to manage repository access.
## What gets synced
| Content | Synced |
| - | - |
| Documentation files (Markdown, HTML, text, PDFs) | Yes |
| Issues and issue comments | Yes |
| Pull requests, reviews, and PR comments | Yes |
| Wikis | Yes |
| Discussions and replies | Yes |
| Releases | No |
| Actions and workflows | No |
## Permissions
Realm enforces GitHub's native permission model. Public repositories are visible to every user in your Realm workspace. Content from a private repository is visible only to Realm users whose GitHub account is a collaborator on that repository.
To apply a private repository's collaborator list, Realm has to match each GitHub account to a Realm user by email. Authorizing the connection does not link the GitHub account of the admin who authorized it to their Realm account, so even that admin sees only public repositories until a match exists. A match is made from any of the following:
* **Public profile email.** The email shown on the user's public GitHub profile matches their Realm email. Users set this under GitHub **Settings** > **Public profile** > **Public email**.
* **Organization-verified domain email.** The GitHub organization has [verified a domain](https://docs.github.com/en/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization) and the user has a verified email on that domain that matches their Realm email.
* **Personal GitHub connection.** The user connects GitHub under **Settings** > **Personal integrations** in Realm. This links their GitHub account to their Realm account using all verified emails on the GitHub account and refreshes repository access right away. It syncs no additional data.
If private repositories are missing for a user, have them connect GitHub under **Personal integrations**. That works regardless of the user's GitHub profile or organization settings.
You can bypass GitHub permissions by switching to **Everyone in this organization** on the data source settings page, which makes all synced GitHub data, including private repositories, visible to all Realm users.
# Gong
Source: https://docs.withrealm.com/admin/data-sources/gong
Connect Gong to sync call recordings and transcripts
Connect Gong to Realm to make call recordings and transcripts searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Gong, or click **Reconnect** if already connected.
## Connecting Gong
Connect Gong using an API key. On the data source page, enter:
1. **API key** and **API key secret** - In Gong, go to **Company Settings** > **Ecosystem** > **API** > **API Keys** and click **Get API Key**.
2. **Domain** - Your Gong domain (the Base URL shown on the API Keys page).
The person connecting should be a Gong admin with access to all calls you want to sync.
## What gets synced
| Content | Synced |
| - | - |
| Call transcripts (with speaker identification) | Yes |
| Call metadata (participants, date, duration, direction) | Yes |
| Trackers and key topics | Yes |
| Call comments | Yes |
| CRM context (linked Salesforce/HubSpot data) | Yes |
## Permissions
Realm enforces Gong's native permission model. Users can only see calls they have access to in Gong.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Gong data visible to all Realm users.
## Retention period
You can configure a retention period for synced call data from the data source page. Options include:
| Setting | Description |
| - | - |
| **Indefinite** | Keep all synced call data |
| **1 month** | Remove call data older than 1 month |
| **3 months** | Remove call data older than 3 months |
| **6 months** | Remove call data older than 6 months |
| **1 year** | Remove call data older than 1 year |
# Google Drive
Source: https://docs.withrealm.com/admin/data-sources/google-drive
Connect Google Drive to sync documents and files
Connect Google Drive to Realm to make documents, spreadsheets, presentations, and other files searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Google Drive, or click **Reconnect** if already connected.
## Connecting Google Drive
Click **Connect** on the Google Drive data source page. You'll be redirected to
Google's OAuth consent screen. Realm requests permission to read Drive files
and their metadata, read accessible Cloud Identity groups and their members,
and identify the connecting account by email. Review the permissions and click
**Allow**. The person connecting should be a Google Workspace admin or have
access to the Shared Drives you want to sync.
The OAuth grant lets Realm discover the drives available to the connecting
account. It does not make every available drive searchable: Realm only syncs
the Shared Drives you select after authorization.
Once authorized, you'll be redirected back to Realm to select which drives to sync.
## What gets synced
| Content | Synced |
| - | - |
| Google Docs | Yes |
| Google Sheets (cell values, up to 5,000 rows per tab) | Yes |
| Google Slides (including speaker notes) | Yes |
| PDFs | Yes |
| Microsoft Office files (.docx, .pptx, .xlsx) | Yes |
| Plain text and VTT subtitle files | Yes |
| Google Forms | No |
| Google Sites | No |
| Images, videos, and folders | No |
| Comments and suggestions on files | No |
## Deleted files
When you delete a file in Google Drive, Realm removes it at the next sync. Realm does not wait for Google Drive to empty its trash. If you restore the file from the trash, Realm syncs it again.
When you delete a shortcut, Realm removes the files that it synced only through that shortcut.
## Selecting drives
After connecting, choose which Shared Drives to sync from the list of available drives. You can add or remove drives at any time from the data source page.
### Personal drives
In addition to admin-configured Shared Drives, individual users can connect their own Google Drive from **Settings** > **Preferences** > **Personal Drives**. Files synced this way respect Google Drive's native permissions, so other users who already had access to the same files will also see them in Realm.
## Reconnecting expired access
If Google revokes access or the OAuth refresh token expires, Realm stops the affected sync. For a Shared Drive connection, Realm marks the data source as disconnected and notifies organization admins. For a personal Drive, Realm disables that personal source and notifies its owner. Reconnect the affected Google Drive in Realm to authorize access again.
## Permissions
Realm enforces Google Drive's native permission model. Users can only see files they have access to in Google Drive.
If a Shared Drive contains a shortcut to a file outside that drive, Realm does not use the Shared Drive membership for the target file. Only the users and groups named in the sharing settings of the target file can see it in Realm. Link sharing and domain sharing on the target file do not give access in Realm. If the connected account cannot read the sharing settings of the target file, Realm does not index the target.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Google Drive data visible to all Realm users.
## Restricting API access
Realm only syncs the Shared Drives you select. To further limit the Google account that Realm can read from, connect with a dedicated Google Workspace user that only has access to the content you want to index.
In the [Google Admin console](https://admin.google.com/), go to **Directory** > **Users** and click **Add new user**. Create an account with a license that includes Google Drive, such as `realm@your-domain.com` or `realm-google-drive@your-domain.com`.
In Google Drive, open the Shared Drive that contains the content Realm should index. Select the file or folder, click **Share**, add the dedicated user, and give it **Viewer** access. Keep **General access** set to **Restricted** unless your organization intentionally uses broader access. Realm will only be able to index files and folders that this dedicated user can open.
To sync a whole Shared Drive instead, add the dedicated user as a member of that Shared Drive.
Sign in to Google as the dedicated user, then return to Realm and connect Google Drive from **Settings** > **Data sources** > **Google Drive**.
After authorizing Realm, select only the Shared Drives you want to sync. If you later remove the dedicated user's access in Google Drive, Realm will stop being able to read that content on future syncs.
In Google Drive, confirm the dedicated user can open only the files and Shared Drives you expect Realm to index. In Realm, run or wait for the sync, then check that searchable Google Drive results match that scope.
# HubSpot
Source: https://docs.withrealm.com/admin/data-sources/hubspot
Connect HubSpot to sync CRM data and content
Connect HubSpot to Realm to make CRM data, activities, and related content searchable. Navigate to **Settings** > **Data sources** and click **Connect** on HubSpot, or click **Reconnect** if already connected.
## Connecting HubSpot
Click **Connect** on the HubSpot data source page. You'll be redirected to
HubSpot's OAuth flow. Its consent page groups the requested access across CRM
objects, CMS content and domains, files, basic account information, one-to-one
emails, and tickets. Log in, review that access, and click **Connect app**. The
person connecting should be a HubSpot admin.
The OAuth grant controls what Realm is allowed to read from HubSpot. The object
and property selections on the Realm data source page control which of that
content is actually synced and made searchable.
## What gets synced
Realm syncs the following HubSpot objects. You can enable or disable each object, and configure which properties are synced per object, from the data source page. Companies, Contacts, Deals, and Tickets appear as standalone search results, while activities are threaded onto them.
| Content | Synced |
| - | - |
| CRM objects (Companies, Contacts, Deals, Tickets) | Configurable |
| Activities (Calls, Communications, Emails, Line items, Meetings, Notes, Quotes, Subscriptions, Tasks) | Configurable |
| File attachments on CRM records | Yes |
| Marketing data (campaigns) | No |
| Commerce data (invoices) | No |
| Reporting data (dashboards) | No |
## Configuring properties
For each object, you can choose which properties (fields) are synced. Focus on properties that contain useful searchable content.
## Permissions
All synced HubSpot data is searchable for users with a HubSpot account in your organization.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced HubSpot data visible to all Realm users.
# Intercom
Source: https://docs.withrealm.com/admin/data-sources/intercom
Connect Intercom to sync conversations and tickets
Connect Intercom to Realm to make conversations and tickets searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Intercom, or click **Reconnect** if already connected.
The Intercom data source is in **beta**.
## Connecting Intercom
Connect Intercom using an API key. On the data source page, enter your Intercom access token and click **Submit**.
To get an access token, create an app in the [Intercom Developer Hub](https://app.intercom.com/a/developer-signup) and copy the access token.
## What gets synced
| Content | Synced |
| - | - |
| Tickets | Yes |
| Support conversations | Yes |
Realm excludes replies authored by Intercom bots from searchable conversation content.
## Permissions
All synced Intercom data is visible to users with an Intercom account in your organization.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Intercom data visible to all Realm users.
The initial sync can take from hours to multiple days depending on the volume of conversations and tickets.
# Jira
Source: https://docs.withrealm.com/admin/data-sources/jira
Connect Jira to sync issues and projects
Connect Jira to Realm to make issues, comments, and project data searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Jira, or click **Reconnect** if already connected. Follow the on-screen instructions to install the Realm app on your Jira site.
## Connecting Jira
Install the [Realm app from Atlassian Marketplace](https://marketplace.atlassian.com/apps/1233308/realm?tab=overview\&hosting=cloud) on the Jira site you want to connect.
Then, navigate to [Atlassian Admin](https://admin.atlassian.com/) > **Apps** > **Sites** > **Your Site Name**.
Then click **Connected Apps**, find the Realm app, click the three dots, and click **Configure**.
The configuration page shows a token and an Atlassian user ID. Copy the token
into the **Client Key** field in Realm and the user ID into the **User ID**
field. If you are not also a Realm admin, send the configuration page to a
Realm admin so they can enter both values.
The person connecting should have access to the Jira projects you want to sync.
Depending on your organization's Atlassian settings, an admin may need to approve the app installation before it can be used.
## What gets synced
| Content | Synced |
| - | - |
| Issues (all types, including epics and sub-tasks) | Yes |
| Issue comments | Yes |
| Attached screenshots (OCR) | Yes |
| Custom fields | Configurable |
## Selecting projects
After connecting, choose which Jira projects to sync. You can add or remove projects at any time from the data source page.
## Permissions
Realm enforces Jira's native permission model. Users can only see issues they have access to in Jira.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Jira data visible to all Realm users.
## Jira Service Management
Realm's Jira data source also syncs **Jira Service Management** data. Service Management projects appear in the project list alongside standard Jira projects.
## Configuring properties
You can configure which Jira properties are synced from the data source page. This lets you control which issue fields are included alongside issue content.
# Linear
Source: https://docs.withrealm.com/admin/data-sources/linear
Connect Linear to sync issues and projects
Connect Linear to Realm to make issues, comments, and projects searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Linear, or click **Reconnect** if already connected.
## Connecting Linear
Connect Linear using an API key. On the data source page, enter your Linear API key and click **Submit**. The person connecting should be a Linear workspace admin.
Once connected, Realm begins syncing issues and comments from your Linear workspace.
## What gets synced
| Content | Synced |
| - | - |
| Issues and issue comments | Yes |
| Issue metadata (status, priority, assignee, labels) | Yes |
| Projects | Yes |
| Cycles | No |
| Attachments | No |
## Permissions
Realm enforces Linear's native permission model. Users can only see issues they have access to in Linear.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Linear data visible to all Realm users.
# Notion
Source: https://docs.withrealm.com/admin/data-sources/notion
Connect Notion to sync pages and databases
Connect Notion to Realm to make pages and databases searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Notion, or click **Reconnect** if already connected.
## Connecting Notion
Click **Connect** on the Notion data source page. You'll be redirected to Notion's OAuth flow. During the flow, you'll be asked to select which pages Realm can access. The person connecting should be a Notion admin.
Child pages are automatically included when you select a parent page. Select top-level pages to sync entire hierarchies.
## What gets synced
| Content | Synced |
| - | - |
| Pages (with full property metadata) | Yes |
| Child pages (automatically) | Yes |
| Databases | Yes |
| Database entries | Yes |
| Wiki homepages and nested pages | Yes |
| Archived pages | No |
| Comments | No |
## Permissions
Realm does not enforce Notion's document-level permissions. All synced Notion pages are visible to any user with a Notion account in your organization, regardless of their access in Notion.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Notion data visible to all Realm users.
## Wikis
Notion wikis are supported. Realm syncs a wiki's homepage content together with its nested pages, and reads verification details such as status, verifier, and verification dates from wiki pages into document metadata.
## Auto-verify pages
When enabled, Notion pages are automatically marked as verified in Realm. This feature can be toggled on the data source settings page when available for your organization.
# Outline
Source: https://docs.withrealm.com/admin/data-sources/outline
Connect Outline to sync wiki documents
Connect Outline to Realm to make wiki documents and their file attachments searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Outline, or click **Reconnect** if already connected.
## Before you connect
* An Outline API key that belongs to an Outline **admin**. Realm needs admin rights to read users, groups, and collection memberships, and to register a webhook.
* The URL of your Outline workspace, for example `https://wiki.example.com`.
* Realm must be able to reach your Outline instance over the network. For live updates, your Outline instance must also be able to send webhooks to Realm.
## Connecting Outline
In Outline, go to **Settings** > **API** and create a new API key. On the Realm data source page, enter your workspace URL and the API key.
## What gets synced
| Content | Synced |
| - | - |
| Published documents, including nested documents | Yes |
| File attachments on documents | Yes |
| Images in documents (text extracted) | Yes |
| Drafts and unpublished documents | No |
| Archived and deleted documents | No |
| Templates | No |
| Comments | No |
Changes in Outline reach Realm within about a minute through webhooks. A scheduled full sync reconciles anything a webhook missed.
## Selecting collections
Every collection the API key can read is synced by default. You can turn individual collections off at any time from the data source page.
## Permissions
Realm enforces Outline's native permission model, matched by email address. A document in a workspace-visible collection is visible to all Outline members; a document in a private collection is visible only to the groups and users that collection is shared with. Document-level shares are not synced, so a user who has access to a single document but not to its collection does not see it in Realm.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes the synced collection visible to all Realm users.
# Data sources
Source: https://docs.withrealm.com/admin/data-sources/overview
Connect your workplace tools so Realm can search and reference their content
Data sources sync knowledge into Realm's search engine so users can find and use it across search, chat, agents, and RFPs. Navigate to **Settings** > **Data sources** to connect and manage your sources.
**Data sources vs Tools:** Data sources sync knowledge *into* Realm. Tools let agents act *outward* by performing actions in external systems. See [Tools](/admin/tools) for more.
## Available data sources
Realm has native data sources for 20+ common workplace tools:
Messages, files, and threads
Docs, Sheets, Slides, PDFs
CRM data and content
Accounts, opportunities, contacts
Issues, epics, comments
Pages, blogs, files
Tickets and knowledge base
Documents and sites
Tickets and service management
Pages and databases
Conversations and tickets
Any public website
Repos, issues, and pull requests
Call recordings and transcripts
Issues and projects
Messages and channels
Docs and tables
Wiki documents and collections
Work items and repos
Knowledge base pages
Call recordings and transcripts
Call recordings and transcripts
Accounts, notes, and tasks
Push documents from any system
Don't see the tool you need? Contact [support@withrealm.com](mailto:support@withrealm.com). We're always adding new data sources.
## Permissions
Realm's search is permission-aware. For sources like Slack, Google Drive, and SharePoint, Realm syncs the full permission structure, including nested groups and role-based access. Users can only see search results and chat responses based on data they should have access to in the original system.
Due to API limitations, some data sources, such as HubSpot and Notion, use user-level access checks (i.e. the user has a matching account) rather than document-level permissions.
You can also override permissions per data source and make all synced data visible to everyone in your organization. This is configured on each data source's settings page.
For more details, see the [Security](/admin/security#permission-model) page.
## Sync frequency
Realm periodically refreshes each data source to keep results up to date. Sync frequency varies by source:
| Frequency | Sources |
| - | - |
| **Continuous (push)** | Slack, Teams, GitHub |
| **Every few minutes** | Zendesk, Google Drive, SharePoint, Jira, Salesforce, HubSpot |
| **Hourly** | Other sources (Confluence, Gong, etc.) |
The initial sync for a new data source can take anywhere from a few hours to several days depending on data volume. Once the initial sync completes, subsequent syncs are incremental and much faster.
## User-uploaded files
Users can upload their own files from the **Knowledge** page. Uploaded files can be private or shared with the organization. Shared files appear in the "Shared files" folder under Knowledge and are searchable by all users.
## Sync issues
If a data source has been disconnected, the connector page will show a warning and prompt you to reconnect. If a sync has failed for other reasons and hasn't completed for multiple days, reach out to Realm. We're happy to help. Sync issues like this can often require action on our end.
# Salesforce
Source: https://docs.withrealm.com/admin/data-sources/salesforce
Connect Salesforce to sync CRM data
Connect Salesforce to Realm to make cases, opportunities, knowledge articles, and other CRM data searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Salesforce, or click **Reconnect** if already connected.
## Connecting Salesforce
Click **Connect** on the Salesforce data source page. You'll be redirected to Salesforce's OAuth flow. Log in and allow access. The person connecting should be a Salesforce admin with full read access to the objects you want to sync (e.g. Account, Opportunity, Contact, Contract, Order, Case, Campaign, Lead, Product).
## What gets synced
| Content | Synced |
| - | - |
| Standard objects (Accounts, Opportunities, Contacts, Cases, Leads, Campaigns, Contracts, Orders, Products) | Configurable |
| Additional standard objects (managed content variants, assets, entitlements, service contracts, price books, reports, dashboards) | Configurable when available |
| Custom objects | Configurable |
| Knowledge articles | Yes |
| Notes | Yes |
| Activities (tasks and events) | Yes |
| Email messages | Yes |
| File attachments (ContentDocuments) | Yes |
Text extracted from image attachments (for example screenshots on cases) is also embedded into the parent case, so it is available when the case is used in search, chat, or agent runs. Other attached files are listed on the case by name.
## Configuring objects and fields
From the data source page, you can configure:
* **Which objects to sync** - Select from supported standard Salesforce objects and custom Salesforce objects. Realm does not show every Salesforce system object.
* **Which fields to include** - Choose which properties/fields are synced for each object. Focus on fields that contain useful searchable content rather than system fields.
* **Record type filtering** - Filter which record types to include for each object.
## Writing the Realm project link back to Salesforce
Realm can write a link to the Realm project into a field on the Salesforce opportunity. When someone links a project to an opportunity, Realm fills the field you choose with the project URL, so your sales team can open the response from Salesforce.
This is off until you set it up. To turn it on:
1. Connect an organization-wide Salesforce tool connection. The read-only data source connection above is not enough, because writing needs a connection that can update records. It must point at the same Salesforce org as the data source.
2. Open the Salesforce data source page and choose the Opportunity field that receives the link. Only text and URL fields the connected Salesforce user can edit are offered.
The write happens in the background, so the field is usually filled a few moments after linking. If Salesforce rejects the write, for example because the field was deleted or is not writable, Realm shows the error on the project and notifies the person who linked it, and you can retry from there.
The connection you use is the Salesforce user Realm writes as, so consider a dedicated integration user if you want these updates attributed to Realm rather than a person.
## Permissions
All synced Salesforce data is searchable for users with a Salesforce account in your organization.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Salesforce data visible to all Realm users.
# SharePoint
Source: https://docs.withrealm.com/admin/data-sources/sharepoint
Connect SharePoint to sync documents and sites
Connect SharePoint to Realm to make documents and site content searchable. Navigate to **Settings** > **Data sources** and click **Connect** on SharePoint, or click **Reconnect** if already connected. To change permission mode, click **Reconnect with app scopes** or **Reconnect with delegated scopes**.
## Connecting SharePoint
Click **Authorize** on the SharePoint data source page. You'll be redirected
to Microsoft's OAuth consent screen. It asks to read SharePoint sites,
files available to the connecting account, directory data, and accessible
OneNote notebooks, as well as basic profile information and ongoing access
so scheduled syncs can continue. Review the permissions and click
**Accept**. This does not start syncing any data yet.
After accepting, you'll be redirected back to Realm. Select which SharePoint sites and OneDrive drives to sync.
## Reconnecting expired access
If Microsoft access expires from inactivity or an admin revokes consent in Microsoft Entra, Realm marks the SharePoint connection as disconnected and notifies organization admins. Click **Reconnect** on the SharePoint data source page to authorize access again. This also restores syncing for OneNote notebooks and OneDrive drives selected through the SharePoint connection.
By default, Realm can only access files that the connecting user has access to (delegated scope). To let Realm index all files in SharePoint, you have two options:
* **Grant admin consent** in Microsoft Entra (see below)
* **Connect with app scopes** using the alternative connect button on the data source page
## Granting admin consent
To allow Realm to access all SharePoint content (not just what the connecting user can see), grant admin consent in Microsoft Entra:
1. Go to **Microsoft Entra admin center** > **Applications** > **Enterprise applications**
2. Find **Realm** in the list
3. Go to **Permissions** and click **Grant admin consent for \[your organization]**
Both delegated and application scopes still enforce user-level permissions in search results. The scope only affects what Realm can index.
## What gets synced
| Content | Synced |
| - | - |
| Documents and files in selected sites | Yes |
| SharePoint site pages | Yes |
| OneNote notebooks and pages | Yes |
| OneDrive files in selected drives | Yes |
| SharePoint lists | Yes |
Realm syncs non-hidden Microsoft Lists from selected SharePoint sites as searchable list items. Document libraries continue to sync through the normal SharePoint files path.
## File size limits
Realm skips files larger than these limits during sync:
| File type | Default limit |
| - | - |
| Plain text files | 20 MB |
| Word and PDF files | 50 MB |
| Spreadsheet/workbook files | 10 MB |
| PowerPoint files | 200 MB |
## Selecting sites and drives
After connecting, choose which SharePoint sites and OneDrive drives to sync. The data source page shows connected sites and drives, and you can add or remove them at any time. Realm only syncs content from the sites and drives you select.
## Permissions
Realm enforces SharePoint's native permission model. Users can only see documents they have access to in SharePoint.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced SharePoint data visible to all Realm users.
## Restricting API access
To limit what Realm can access:
1. Create a Microsoft service account that only has access to specific sites
2. Ensure the account can consent to applications
3. Use that account when connecting SharePoint
## Required scopes
The SharePoint integration requires:
* `Sites.Read.All`
* `Files.Read.All`
* `Directory.Read.All`
* `Notes.Read.All`
# Slab
Source: https://docs.withrealm.com/admin/data-sources/slab
Connect Slab to sync knowledge base posts
Connect Slab to Realm to make knowledge base posts and topics searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Slab, or click **Reconnect** if already connected.
## Connecting Slab
Connect Slab using an API token. On the data source page, enter your Slab API token and click **Submit**. The person connecting should be a Slab workspace admin.
## What gets synced
| Content | Synced |
| - | - |
| Posts (with full content) | Yes |
| Topic organization | Yes |
| Comments | No |
## Permissions
Realm enforces Slab's native permission model, including topic-level privacy settings (public, private, and secret topics). Users can only see posts from topics they have access to in Slab.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Slab data visible to all Realm users.
# Slack
Source: https://docs.withrealm.com/admin/data-sources/slack
Connect Slack as a data source or install the Slack app
Connect Slack to Realm in two ways:
* **Slack data source**: sync Slack messages, threads, and files so they are searchable in Realm.
* **Slack app only**: use Realm from Slack without syncing Slack messages into Realm knowledge.
Navigate to **Settings** > **Data sources** to connect Slack.
## Connect Slack as a data source
Use the Slack data source when you want Realm to search Slack messages and files as part of your knowledge base. Click **Connect** on the Slack data source page. You'll see two connection modes:
| Mode | Description |
| - | - |
| **All public channels** | Syncs public channels, plus private channels where the Realm app has been added |
| **Channels with bot only** | Syncs only channels where the Realm app has been added |
After selecting a mode, you'll be redirected to Slack's OAuth consent screen. Review the permissions and click **Allow**. The person connecting must be a Slack workspace admin.
## Connect Slack without syncing knowledge
Use the **Slack App** option when you want people to ask Realm questions from Slack, but you do not want Realm to sync Slack messages as knowledge.
Go to **Settings** > **Data sources**.
Scroll to **Other integrations**.
Click **Install** on **Slack App**.
Review the Slack permissions and click **Allow**. The person installing must be a Slack workspace admin.
This installs Realm in Slack without starting Slack message sync. Team members can mention `@Realm`, use DMs, and use the Slack app sidebar. For usage details, see [Slack app](/integrations/slack-app).
## What gets synced
By default, Realm syncs messages from **public channels** and any **private channels** where the Realm Slack App has been added. To add Realm to a private channel, tag `@Realm` in the channel.
| Content | Synced |
| - | - |
| Public channel messages and threads | Yes |
| Files shared in channels | Yes |
| Private channels (with Realm app added) | Yes |
| Slack Connect channels | Configurable (see below) |
| DMs | Contact Realm to enable |
| Canvases | Yes (synced as attachments) |
| Lists | No |
## Permissions
Realm mirrors Slack's permission settings. Users can only see messages from channels they have access to in Slack.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Slack data visible to all Realm users.
## Slack message history
Realm syncs historical messages via the Slack API, but due to rate limits this is very slow. Uploading a Slack workspace export is the recommended way to import your full message history.
### Exporting from Slack
As a Slack workspace admin, click **Admin** in the sidebar, then select **Workspace settings** > **Security**.
Click **Import & export data**, then select the **Export** tab. Choose a date range and click **Start export**. See [Slack's export guide](https://slack.com/intl/en-gb/help/articles/201658943-Export-your-workspace-data) for details on what's included per Slack plan.
Slack will send you an email when the export is ready. Download the ZIP file.
### Uploading to Realm
On the Slack data source page, scroll to **Slack Message History** and upload the ZIP file. The maximum file size is 10 GB. If your export is larger, perform multiple exports with different date ranges. A progress indicator will show the upload and processing status.
#### Import privacy settings
Use the **Import privacy settings** dropdown to control which messages are imported:
| Setting | Description |
| - | - |
| **Public only** | Only import messages from public channels |
| **All channels** | Import messages from all channels in the export |
Past imports are listed below with their status (synced, sync in progress, sync failed).
## Slack AI app view
To use Realm in Slack's AI app view, you need to enable AI apps in your Slack workspace settings. See [Slack's instructions for displaying AI apps](https://slack.com/intl/en-gb/help/articles/33077521383059-Display-AI-apps-in-Slack) and the [Slack App](/integrations/slack-app) page for more details.
## Noise reduction
Slack can be a noisy data source. To keep results relevant, Realm:
* Ignores threads with only bot messages and no human replies
* Ranks archived channels lower in search results
* Ranks very short messages lower in search results
## Required scopes
`im:history`, `im:read`, `im:write`, `chat:write`, `chat:write.customize`, `app_mentions:read`, `reactions:write`, `channels:read`, `groups:read`, `team:read`, `assistant:write`, `users:read`, `users:read.email`
`channels:history`, `channels:read`, `files:read`, `pins:read`, `reactions:read`, `team:read`, `users:read`, `users:read.email`, `im:history`, `im:read`, `chat:write`, `chat:write.customize`, `app_mentions:read`, `reactions:write`, `groups:read`, `assistant:write`, `mpim:history`, `mpim:read`, `groups:history`
`channels:history`, `channels:read`, `files:read`, `pins:read`, `reactions:read`, `team:read`, `users:read`, `users:read.email`, `search:read`
## Using Realm in Slack
Once connected, team members can interact with Realm directly in Slack. For usage details, see the [User guide: Slack app](https://realm.mintlify.app/integrations/slack-app).
### Slack Connect channels
Slack Connect channels (shared with external organizations) are not synced by default. You can configure this:
| Setting | Description |
| - | - |
| **Sync only selected** | Choose specific Slack Connect channels to sync. Click **Select channels** to pick from a list. |
| **Sync all** | Sync all Slack Connect channels |
### Public channel answer mode
Controls how Realm responds when mentioned in public channels (or private channels where the bot has been added):
| Mode | Description |
| - | - |
| **Preview** | The answer is posted as an ephemeral message only visible to the user who asked. They can then choose to share it to the channel or dismiss it. |
| **Share** | Realm answers directly in the channel, visible to everyone |
| **None** | Realm will not answer questions in channels |
If users report that an agent answer says "Only visible to you" and must be shared manually, the workspace is using **Preview** mode. Switch this setting to **Share** to post answers directly to Slack threads.
### Restrict bot to configured channels
When **Restrict mentions to assistant channels** is enabled, the Realm bot will only respond to mentions in Slack channels where an assistant is specifically configured. In all other channels, the bot will ignore mentions.
When disabled, the bot responds to mentions in any channel it has been added to.
This setting applies to all agents in your organization. Individual agents cannot override it.
# Teams
Source: https://docs.withrealm.com/admin/data-sources/teams
Connect Microsoft Teams to sync messages and channels
Connect Microsoft Teams to Realm to make channel messages, replies, and shared files searchable. Navigate to **Settings** > **Data sources** and click **Connect Teams** on Teams, or click **Reconnect** if already connected. Turn **Sync chats** on to include chats, or turn it off to sync only channel messages.
## Connecting Teams
Click **Connect Teams** on the Teams data source page. You'll be redirected to Microsoft's OAuth consent screen. Review the permissions and click **Accept**. The person connecting should be a Microsoft 365 admin.
Once authorized, you'll be redirected back to Realm to select which teams and channels to sync.
Use the **Sync chats** toggle to control whether Realm syncs Teams chats in addition to channels.
## What gets synced
| Content | Synced |
| - | - |
| Channel messages and replies | Yes |
| File attachments in messages | Yes |
| Chat messages (1-on-1 and group) | When **Sync chats** is turned on |
| Meeting recordings | No |
| Meeting transcripts (personal connection) | Yes |
## Selecting Teams
After connecting, choose which teams and channels to sync. You can add or remove teams at any time from the data source page.
## Permissions
Realm enforces Teams' native permission model. Users can only see messages from teams and channels they have access to in Teams.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Teams data visible to all Realm users.
## Sync chats
You can enable syncing of chat messages in addition to channel messages by turning on **Sync chats** on the data source page. Turn it off to sync only channel messages.
## Meeting transcripts
Meeting transcripts are synced through a personal connection instead of the organization-wide Teams data source. Each user connects their own Microsoft account from **Settings** > **Personal integrations** > **Teams transcripts**, and each synced transcript is visible only to that user. Meeting recordings are not synced.
# Vitally
Source: https://docs.withrealm.com/admin/data-sources/vitally
Connect Vitally to sync accounts, notes, tasks, meetings, and meeting transcripts
Connect Vitally to Realm to make customer accounts, notes, tasks, meetings, and meeting transcripts searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Vitally, or click **Reconnect** if already connected.
## Connecting Vitally
Connect Vitally using an API key. On the data source page, enter:
1. **API key**
2. **Subdomain** - Your Vitally subdomain
3. **Region** - US or EU
## What gets synced
| Content | Synced |
| - | - |
| Accounts (with health scores, MRR, NPS, custom traits) | Yes |
| Notes | Yes |
| Tasks | Yes |
| Conversations (metadata only, not message bodies) | Yes |
| Meetings | Yes |
| Meeting transcripts | Yes |
## Reconnecting an invalid API key
If your Vitally API key is revoked or rotated, Realm stops the sync, marks the data source as disconnected, and notifies organization admins. Enter a valid API key on the Vitally data source page to resume syncing.
## Permissions
All synced Vitally data is visible to all Realm users.
# Web pages
Source: https://docs.withrealm.com/admin/data-sources/web-pages
Sync content from any publicly accessible website
## Web pages
Realm can sync any publicly accessible website and add its content to your knowledge base.
## Setting up web scraping
Go to the Data sources page in Realm.
Open "Web Scraping", then click **Add Site**.
Insert the URL you wish to sync (e.g., `https://example.com/docs/`).
Realm only syncs this page and pages whose URL path is under it, so use
the root of the section you want. For example, `https://example.com/docs/`
syncs the pages under `/docs/`, while `https://example.com/docs/intro.html`
syncs only that single page.
If you want to sync only some of the pages under the start URL, add
include or exclude patterns.
Click Save to start the sync.
## Sync scope
The start URL defines the scope of the sync. Realm follows links from the
start URL, but only syncs pages on the same domain whose URL path begins
with the path of the start URL. Pages outside that scope are skipped, even
if the start page links to them.
The one exception is direct PDF links: a link ending in `.pdf` found on a
synced page is synced even when the file lives outside the path of the
start URL. PDF links that do not end in `.pdf` (for example, download
endpoints with query parameters) follow the normal scope rules.
To sync a whole site, use the site root (e.g., `https://example.com/`) as the
start URL. To sync one section, use that section's root
(e.g., `https://example.com/docs/`).
## URL patterns
Patterns narrow the sync further within the scope of the start URL. They cannot
extend the sync beyond pages under the start URL. Patterns use glob syntax
and are relative to the start URL. The start page itself is always synced,
even when it does not match the patterns. The examples below assume a start
URL of `https://example.com/`.
### Include patterns
When include patterns are set, only pages matching at least one of them are
synced:
| Pattern | Effect |
| - | - |
| `/docs/**` | Only sync pages under /docs |
| `/blog/2024/**` | Only sync 2024 blog posts |
### Exclude patterns
Pages matching an exclude pattern are skipped:
| Pattern | Effect |
| - | - |
| `/login` | Skip login page |
| `/admin/**` | Skip admin pages |
| `/**/*.pdf*` | Skip PDF files, including links with query parameters |
Patterns match the full URL, including any query string. Use `/**/*.pdf*`
rather than `/**/*.pdf` so links such as `/files/manual.pdf?download=1` are
also matched.
## Use cases
Sync public product docs from your website
Import external help center content
Track competitor public documentation
Sync partner documentation and resources
## Best practices
Only scrape websites that allow crawling. Check the site's robots.txt file.
Be specific with include/exclude patterns to avoid syncing irrelevant content.
Periodically review scraped content to ensure it remains relevant and accurate.
Begin with a specific section of a website before expanding to more pages.
## Limitations
* Only works with publicly accessible websites
* Only pages under the path of the start URL are synced (see [Sync scope](#sync-scope))
* Pages are discovered by following links and sitemaps, so pages that nothing links to may not be found, and very large sites may not be fully covered due to crawl depth and size limits
* Dynamic content (JavaScript-rendered) may not be fully captured
* Rate limiting may apply to prevent overloading target sites
# Zendesk
Source: https://docs.withrealm.com/admin/data-sources/zendesk
Connect Zendesk to sync tickets and knowledge base
Connect Zendesk to Realm to make support tickets and knowledge base articles searchable. Navigate to **Settings** > **Data sources** and click **Connect** on Zendesk, or click **Reconnect** if already connected.
## Connecting Zendesk
Connect Zendesk using an API key. On the data source page, enter:
1. **API key** - Follow [Zendesk's instructions](https://support.zendesk.com/hc/en-us/articles/4408889192858-Managing-API-token-access-to-the-Zendesk-API) to create one.
2. **Domain** - Your Zendesk domain (e.g., `https://company-name.zendesk.com/`)
3. **Email** - The email address associated with the API key. This must be the same email used to generate the key.
The connecting account should have access to all tickets you want to sync.
## What gets synced
| Content | Synced |
| - | - |
| Support tickets and custom fields | Yes |
| Ticket conversations and attached screenshots (OCR) | Yes |
| Help center articles | Configurable |
## Selecting help centers
After connecting, choose which Zendesk help centers to sync. You can add or remove help centers at any time from the data source page.
## Permissions
Realm enforces Zendesk's native permission model. Users can only see tickets they have access to in Zendesk.
You can override this by switching to "Everyone in this organization" on the data source settings page, which makes all synced Zendesk data visible to all Realm users.
## Configuring properties
You can configure which Zendesk properties are synced from the data source page. This lets you control which ticket fields are included alongside ticket content.
The initial sync can take from hours to multiple days depending on your ticket volume.
# Login methods
Source: https://docs.withrealm.com/admin/login-methods
Understand how users sign in to your Realm organization
Realm supports several sign-in methods. Your organization can have one or more methods enabled at the same time, and users see all enabled options on the sign-in page.
Login methods are configured by the Realm team on behalf of your organization. Contact [support@withrealm.com](mailto:support@withrealm.com) to enable or change login methods.
## Available methods
| Method | Description |
| - | - |
| **Email and password** | Users sign in with their email and a password. Enabled by default. |
| **Email link** | Users select **Email a sign-in link** and sign in from a one-time link sent to their email, without a password. Needs email and password login, and is enabled separately. |
| **Google** | Sign in with a Google account via OAuth. |
| **Microsoft** | Sign in with a Microsoft account via OAuth. |
| **SAML SSO** | Single sign-on through your identity provider (Okta, Azure AD, OneLogin, and others). See [SAML SSO](#saml-sso) below. |
## How sign-in works
When a user enters their email on the sign-in page, Realm looks up which organization and login methods are associated with that email. The page then shows only the login options enabled for that organization.
If your organization has [JIT provisioning](/admin/members-and-roles#just-in-time-jit-provisioning) enabled, users whose email matches a configured domain are automatically created in Realm the first time they sign in.
## SAML SSO
SAML SSO lets your team sign in to Realm using your existing identity provider (IdP). Setting up SAML requires coordination between your IdP admin and the Realm team.
### What you need to provide
Your identity provider will generate these values. Share them with the Realm team:
| Field | Description |
| - | - |
| **IdP Entity ID** | Your identity provider's identifier |
| **SSO URL** | The URL where Realm sends authentication requests |
| **X.509 Certificate** | The certificate used to verify SAML responses |
### What Realm provides
The Realm team will give you these values to enter in your identity provider:
| Field | Description |
| - | - |
| **SP Entity ID** | The identifier for Realm as a service provider |
| **ACS URL** | The Assertion Consumer Service URL where your IdP sends the SAML response |
### Attribute mapping
Realm expects the following attributes in the SAML response:
| Attribute | Required | Description |
| - | - | - |
| **email** | Yes | The user's email address (used as Name ID) |
| **firstName** | No | The user's first name |
| **lastName** | No | The user's last name |
### Troubleshooting
| Issue | Solution |
| - | - |
| "Invalid SAML response" | Check that the certificate matches and hasn't expired |
| Users can't sign in | Verify the ACS URL is correct in your IdP configuration |
| Attributes not mapping | Ensure your IdP sends email as the Name ID |
| Login popup does not open | Allow popups for your Realm site in the browser, then try again |
If you run into issues, reach out to [support@withrealm.com](mailto:support@withrealm.com) and we'll help get it sorted.
# MCP
Source: https://docs.withrealm.com/admin/mcp
Connect custom MCP servers to extend what your agents can do
MCP (Model Context Protocol) is an open protocol for connecting agents to external tools and data sources. You can add custom MCP servers to Realm to extend your agents' capabilities beyond built-in tools.
MCP servers are not available on trial plans.
## Adding a server
Click **Add MCP Server** from the Tools page. You can either connect a **Featured MCP Server** with one click, or add a custom server manually.
Provide the URL of the MCP server. Use the server's own documentation when
possible. As a rule of thumb, a URL ending in `/mcp` usually uses
Streamable HTTP, while one ending in `/sse` usually uses Server-Sent Events.
Select **Streamable HTTP** or **Server-Sent Events (SSE)** to match the
server.
Choose **OAuth**, **Bearer Token**, **Basic Auth**, or **Custom Headers**
and enter the required credentials. **Basic Auth** takes a username and
password, such as a service user ID and its token, and sends them as an
HTTP Basic `Authorization` header. The username can't contain a colon. You
can add headers such as `x-api-key` or vendor version headers. The
`Authorization` header is managed separately by the authentication type.
Optionally give the connection a descriptive name. This is useful when connecting to the same server multiple times with different credentials.
Click **Connect** to complete the setup. For OAuth, you first authorize
Realm with the provider. Realm then opens the server's page, which shows the
connection status and the server's tools.
## Featured servers
Realm highlights these featured MCP servers for quick one-click setup:
## Managing servers
Once added, you can **reconnect** or **delete** MCP servers from the Tools page.
Admins can also manage MCP connections created by other admins in the same
workspace, including updating connection names, bearer tokens, Basic auth
credentials, and custom header values. For OAuth connections, reconnection must be performed by the admin who
owns the connection. Other admins can remove the OAuth connection and create a
new one with their own credentials if needed.
When a connected server's authorization later fails (for example, an expired
OAuth token), its tools become unavailable to the agent. If the agent could
have used such a tool during a chat, the assistant message shows a **disconnected
connector** notice naming the affected server, with a **Reconnect** action for
connections you own. For connections owned by another admin, the notice asks you
to have the owner reconnect.
Realm also notifies you, in the app and by email, the first time a connection
fails. The connection's owner gets a notification with a **Reconnect** link. For
a connection shared with the whole workspace, admins who manage tools are
notified too, so a broken connection never silently stops agents and triggers
that depend on it. You are not notified again while the connection stays
failed. Reconnecting restores it.
A connection attempt that never finished, for example because the sign-in
window was closed, shows as **Not connected** with a **Connect** action for the
person who started it. Other admins don't see unfinished attempts.
# Users
Source: https://docs.withrealm.com/admin/members-and-roles
Manage users, roles, and provisioning in your Realm organization
The Users page lets you manage who has access to your Realm workspace. Navigate to **Settings** > **Users** in the sidebar.
The page shows how many members your workspace has, how many invitations are still pending, and how many members hold each role (for example Owner and Member). Pending invitations are not counted as members, so the member count matches the user count in **Analytics**. Use the search bar to find users by name or email. Users are split into **Members** and **Invited** sections, each showing the user's name, email, and role.
For eligible workspaces that are not on usage-based billing, members also have a **Daily automation** column. It shows the percentage remaining in each user's shared API chat and workflow allowance. The allowance resets each day at 00:00 UTC.
## Adding users
Click **Add users** in the top right corner of the Users page.
Type or paste one or more email addresses, separated by spaces, commas, or
newlines. You can copy a column of emails from a spreadsheet and paste it
directly into the field. The dialog shows whether any emails are already
invited or have existing accounts.
Select **Admin**, **Member**, or **Collaborator** for the invited users.
Users cannot be invited as Owner. An Owner can promote them after they
join.
Click **Invite**. Users receive an email with a link to join your workspace.
## Roles
Every organization has four default roles:
| Role | Description |
| - | - |
| **Owner** | Always has full access to everything, including role management. Every organization has at least one Owner. |
| **Admin** | Full control of the organization by default. Can manage users, data sources, tools, agents, and all settings. |
| **Member** | Full access to Realm features (chat, search, agents, tools). No admin permissions by default. |
| **Collaborator** | Limited access. Can edit RFPs, upload files to projects they are members of, search, and use Realm Chat (capped usage). |
The default roles are fixed: Owner, Admin, Member, and Collaborator permissions cannot be edited by your organization. Collaborator permissions are managed by the Realm team (some contracts specify exactly what Collaborators can do); contact [support@withrealm.com](mailto:support@withrealm.com) to change them. Billing and credits are managed by Owners. When you need a different combination of permissions, create a custom role.
### Custom roles
Owners can create custom roles under **Settings** > **Organization settings** > **Roles & permissions**. A custom role has full product access (the Member experience) plus the capabilities you pick: managing users, managing data connections, managing custom tools, creating agents and workflows, viewing analytics, managing billing, or managing organization settings.
For example, a "Connector" role with the "Manage data connections" capability can set up and maintain integrations, but cannot see users, analytics, or other admin pages.
To edit a role, open **Roles & permissions**, click the role, and adjust its capabilities. Changes apply immediately to everyone holding the role. A custom role can only be deleted once no users, pending invites, or SSO defaults reference it.
### Changing a user's role
Click the three-dot menu next to a user and select **Edit role**. Choose the new role and click **Save**.
Only Owners can grant the Owner role or change the role of another Owner. An organization must always keep at least one Owner, so the last Owner cannot be demoted or removed until another Owner is added.
## Removing users
Click **Remove users** in the top right, enter the email addresses you want to remove, then confirm. Like the add dialog, you can paste a comma- or space-separated list of emails. You can remove both active users and pending invitations.
When removing users in bulk, all of their agents, projects, and tables are
transferred to the admin who removed them. To choose a different recipient,
remove the user individually with the **Remove user** action below.
## Managing users
Click the three-dot menu next to any user to see available actions:
| Action | Description |
| - | - |
| **Edit role** | Change the user's role |
| **Resend invitation email** | Re-send the invite to an invited user |
| **Remove user** | Revoke access and remove the user. You can choose which active member inherits their agents, projects, and tables (defaults to you) |
| **Force sign out** | End all sessions for an active user across all devices |
| **Move assistants to yourself** | Transfer the user's personal assistants to your account |
## Seat limits
Your organization has a fixed number of seats. When the limit is reached, the **Add users** button is disabled with a "User limit reached" tooltip. You cannot invite new users until a seat is freed.
Need more seats? Contact [support@withrealm.com](mailto:support@withrealm.com) to increase your organization's
seat limit.
## Just-in-time (JIT) provisioning
With JIT provisioning, users are automatically created in Realm the first time they sign in, with no invite needed. This is useful with SSO, where new employees can start using Realm immediately after signing in with their company credentials.
JIT provisioning is scoped to specific email domains (e.g. `@company.com`). Only users whose email matches a configured domain are auto-provisioned. You can also configure which role JIT-provisioned users receive. The default role is Member.
JIT provisioning is configured by the Realm team on behalf of your
organization. Contact [support@withrealm.com](mailto:support@withrealm.com) to enable it or to update the
allowed domains and default role.
# API access
Source: https://docs.withrealm.com/admin/organization-settings/api-access
Control API access for your organization
The Realm API section in Organization Settings controls who can create API keys. Navigate to **Settings** > **Organization settings**.
## API keys for all users
By default, only admins can create API keys. Toggle **API Keys for All Users** on to allow everyone in the organization to create their own keys.
When disabled, only admins can create and manage API keys from the [API Keys](/admin/api) page. When enabled, all users can access the API Keys page from their Preferences.
For full details on creating keys, scopes, and managing tokens, see the [API Keys](/admin/api) page.
# Model configuration
Source: https://docs.withrealm.com/admin/organization-settings/model-configuration
Control which AI models are available to your organization
Model Configuration lets you control which AI models your team can use. Navigate to **Settings** > **Organization settings**.
## Available Models
The page lists all third-party AI models supported by Realm. Use the checkboxes to show or hide individual models for your organization.
* **Checked**: the model is available for users to select
* **Unchecked**: the model is hidden and cannot be used
These models work with file uploads but do not have access to your company's connected data sources. To use your company's data, use the built-in Realm assistant or a custom agent.
Hide models you don't want your team to use. This keeps the model picker clean and prevents accidental use of models that don't fit your organization's needs.
# Organization context
Source: https://docs.withrealm.com/admin/organization-settings/organization-context
Set organization-wide instructions and context for AI assistants
Organization Context lets you provide custom instructions that are included in every AI prompt across your Realm workspace. Navigate to **Settings** > **Organization settings**.
## How it works
The text you enter here is automatically prepended to all AI interactions (chat, agents, and RFP fills). Use it to give the AI background about your company, preferred tone, terminology, or any standing instructions.
For example:
* Company name, industry, and key products
* Preferred writing style or tone
* Terms or acronyms specific to your organization
* Instructions like "Always respond in British English"
## Auto-generated context
Realm automatically generates organization context based on public data sources. This is shown in a separate card below the manual editor. Use the **Include generated context in prompts** toggle to control whether it is included alongside your own context.
Review the generated context and use it as a starting point for writing your own.
## Editing Context
Use the text editor to write or modify your organization context. Click **Save** to apply. The new context takes effect immediately for all users. Use **Undo** to revert unsaved changes.
Organization context applies to all users and all AI interactions in your workspace. Keep it concise and relevant, as overly long context can reduce AI response quality.
# RFP settings
Source: https://docs.withrealm.com/admin/organization-settings/rfp-settings
Configure default RFP assistants, export formats, and column roles
RFP Settings let you configure organization-wide defaults for the RFP workflow. Navigate to **Settings** > **RFP settings**.
## Default RFP assistant
Choose which AI assistant is used by default when filling RFP cells. Users can still override this per project, but the default applies to all new RFP projects.
Use the **Default RFP Assistant** dropdown to pick a public assistant. If the selected assistant is deleted or made private, a warning will appear prompting you to select a new one.
## Answer profiles
Answer profiles are named styles for how RFP answers are written. Each profile combines two settings, and they apply to every generated answer, whichever assistant fills the RFP:
* **Answer length**: Choose **Concise** for short answers that cover the pertinent facts, or **Detailed** for answers that explain how each requirement is met using the specifics in your sources.
* **Instructions**: Free-form instructions applied to RFP answers only, for example tone of voice, terminology, spelling conventions, or which product the answers should focus on.
Create as many profiles as your RFPs need, for example one for enterprise RFPs and another for security questionnaires. One profile is the organization default, marked with a **Default** badge. It applies to every RFP that has not picked a profile of its own. Use the menu on a profile to edit it, set it as the default, or delete it. The default profile cannot be deleted; promote another profile first. When a profile is deleted, RFPs that used it switch to the organization default.
Profiles apply at three levels. The organization default covers everything, an RFP can pick its own profile in the RFP's settings, and a section can pick its own in the bar shown when filling. Each picker shows the profile currently in effect, so a section that has not been given one of its own shows the RFP's profile, and an RFP that has not been given one shows the organization default. See [RFP-level settings](/rfp/settings).
When you regenerate a single answer, the regenerate panel has a profile control of its own. It applies to that one answer and leaves the section's profile alone.
### Test a profile
Open **Test this profile** in the profile editor to see what the profile produces before you save it. Type an RFP question, or select **Use a real question** to search the questions in the RFPs you have access to, then select **Generate answer**.
Searching covers the questions in your Answer Library, so you can test the profile against the wording your customers actually use. Those questions come from RFPs you have finished, so a brand new organization sees none yet. **Examples** next to it offers a short list of generic questions to use instead.
The answer is generated the same way a real RFP fill generates it, searching your organization's sources. Nothing is saved: no RFP is changed and the answer is not added to the answer library.
When you have unsaved changes to the profile, the sandbox shows two answers side by side, one from the saved profile and one from your draft, so you can compare them before saving.
## Require explicit approval for export
When enabled, each row in the RFP must receive explicit approval before they can be exported. When disabled, RFPs can be exported at any time without requiring approval.
This is a default for new RFP projects. Individual projects can override this setting.
## Spreadsheet import instructions
Choose **Edit** to provide import instructions (up to 5,000 characters) for future
Excel/CSV files. **Save** your changes, or clear the field and save to restore
default behavior.
## Make all RFP answers public
Realm extracts question-answer pairs from completed RFPs into a searchable answer library. Normally, answers extracted from an RFP in a restricted project are only visible to that project's members.
When this setting is enabled, everyone in the organization can find all indexed RFP answers in search and chat, including answers from restricted projects. Enabling or disabling the setting takes effect immediately.
## Restrict Answer Library editing to admins
By default, any user can add or remove RFP answers from the answer library. When this setting is enabled, only organization admins can edit the answer library. The setting covers every route into the library, including [correcting it from a chat](/chat/special-features#correcting-the-answer-library).
## Only add approved rows to the Answer Library
Realm extracts question-answer pairs from an RFP once it is completed, and by default it takes every row, whether or not the row was approved.
When this setting is enabled, only approved rows are extracted. Rows still pending, in review, or declined when the RFP is completed are skipped, so an RFP finished with some rows unresolved does not teach the answer library from them.
The setting applies from the moment it is turned on. Answers already in the library stay there until the RFP they came from is extracted again.
## Answer age limit
By default, filling an RFP can reuse any answer in the Answer Library, however old. With an age limit set, answers whose source RFP was completed longer ago than the limit are not used when filling new RFPs.
The answers are not deleted. They stay in the Answer Library, and knowledge search and chat still find them. Only RFP filling skips them.
## Any member can manage RFPs
RFPs that are not part of a project can normally only be managed by their owners (the person who uploaded them plus any co-owners) and organization admins. Managing covers renaming, archiving, deleting, setting the deadline, and changing settings such as the assistant and languages.
When this setting is enabled, every member of the organization who can view such an RFP can also manage it. RFPs inside a project are not affected: any project member can already manage them.
## Create RFPs in projects only
When this setting is enabled, the button on the RFPs page creates a project instead of a standalone RFP, so every new questionnaire is filled inside a project. RFPs that already exist outside a project are not affected: they stay in the list and can still be opened, filled, and exported.
## Tags
Create, rename, recolor, and delete organization tags here. See [browsing knowledge](/knowledge/browsing) for how tagging affects search.
**Tags** narrow answers to specific source material. An RFP carrying a tag draws answers only from sources tagged the same way. Use tags for subject matter, such as a product area. In chat and when filling an RFP, Realm also sees each source's tags, so it can tell which product a source describes.
Nested folder and file exclusions are available after tag scopes have been activated for your workspace.
**Choose files** picks the connections, folders, and files a tag covers. Check a folder to include its contents, then clear the checkboxes for nested folders or individual files to create exceptions. Changing a parent clears its child selections. Direct file assignments remain independent of folder exceptions; an explicit file exclusion takes precedence. Right-click an item and choose **Use inherited selection** to clear its individual choice. Scope changes affect already indexed files immediately; new files still need to finish indexing. Under RFPs, checking an RFP adds the tag to the RFP itself, the same as its **Tags** column in the RFP list. Open an RFP to tag only some of its sections or answers instead.
**Always in scope** keeps a tag's content searchable for every RFP, whatever tags that RFP carries. Use it for general material such as company background. It cannot be added to a project. On an RFP, it can be added once the RFP is completed or imported, which shares that RFP's answers with every other RFP. It can be removed at any time.
## Project visibility
Controls who can access projects across the organization:
* **Public by default**: new projects can be accessed by everyone in the organization. Each project can still be restricted individually.
* **Private by default**: new projects are only shown to project members, but a member can make a project public afterwards.
* **Always private**: projects are only shown to project members and cannot be made public. Selecting this mode also makes all currently public projects private.
## Project roles
By default, project members can do almost everything project owners can. The permission matrix lets you restrict a small set of capabilities, for example limiting them to project owners:
* Manage project members
* Delete projects
* Mark an RFP completed
The matrix shows roles as columns and these permissions as rows. Use the checkboxes to enable or disable a permission for each role.
The **Owner** role is built-in and always has all permissions. Organization admins can always do everything in every project, regardless of their project role. You can create additional custom roles to match your team's workflow.
To create a role, click **Add Role**, give it a name, and configure its permissions. To edit or delete a role, use the buttons in the matrix header. Changes are batched, so you can edit multiple permissions and save them all at once.
### Approving rows
Approving rows is not part of the permission matrix. RFP owners and admins can always approve, and so can project members and the person assigned to a row. When you turn on **Enable reviewers** in RFP settings, questionnaires gain a Reviewer column and the assigned reviewer for a row can also approve it. Individual RFPs can override the organization default with the Reviewer column setting in their own RFP settings.
Turn on **Only reviewers can approve rows** in RFP settings to limit approval to a row's assigned reviewer, RFP owners, and admins. Members and assignees can then no longer approve rows, and only RFP owners and admins can mark an RFP completed from its options menu, since that also approves every row. The setting applies only to RFPs that have reviewers turned on.
## RFP owners and ownership transfer
An RFP can have more than one owner. Every owner has the same rights as the person who uploaded the RFP: managing it, marking it completed and reopening it, and editing the owner list. Owners are managed from the RFP's options menu under **Manage owners**. For RFPs inside a project, project owners can also edit the owner list, and a co-owner still needs access to the project to see the RFP.
Ownership can also be transferred. **Transfer ownership** in the RFP options menu hands the RFP to another user, for example when the current owner leaves or goes on vacation. The previous owner stays on as a co-owner until removed. Deadline reminders and summaries follow the new owner.
Projects can be transferred too: a project owner or admin can pick **Transfer ownership** in the member list under **Project Settings**.
# Search languages
Source: https://docs.withrealm.com/admin/organization-settings/search-languages
Search your knowledge base in more than one language
If your knowledge base contains documents in several languages, Realm can search it in all of them. Navigate to **Settings** > **Organization** and pick the languages under **Search languages**.
When a search runs, Realm translates the query into each selected language and searches with every version. Results from all languages are combined, so a question asked in English can still find a document written in, say, Finnish or German.
When filling an RFP, Realm searches in the selected languages and additionally always in the RFP's working language and in English.
## When to use it
Select a language when a meaningful part of your knowledge base is written in it. There is no need to select the language your team usually writes queries in, searches always run with the original query too.
Selecting many languages adds a small amount of time to each search, so only select languages your knowledge base actually contains. You can select up to 5 languages.
# Admin guide
Source: https://docs.withrealm.com/admin/overview
Manage users, data sources, integrations, and security for your Realm workspace
This guide covers everything an admin needs to set up and manage Realm for their organization.
Invite and manage users, roles, and access
Connect and manage data sources across your organization
Enable and configure tools and actions for agents
Compliance, permissions, and data protection
Configure models, RFP settings, and workspace preferences
View usage metrics, activity trends, and reports
# Overview
Source: https://docs.withrealm.com/admin/security
Data protection, compliance, and security controls in Realm
## Compliance and certifications
| Standard | Status |
| - | - |
| **ISO/IEC 27001:2022** | Certified. Covers infrastructure, applications, systems, and data handling. |
| **GDPR** | Fully compliant. A Data Processing Agreement (DPA) is signed with every customer. |
| **HIPAA** | Compliant. Business Associate Agreements (BAA) are available on request. |
| **CCPA** | Compliant. Realm acts as a service provider and does not sell or share customer data. |
| **EU AI Act** | Classified as a Limited Risk system. |
## Data residency and encryption
All customer data can be stored and processed within the EU, on Google Cloud Platform infrastructure in Finland (`europe-north1`) and the Netherlands (`europe-west4`). Geo-redundant backups are stored in the Netherlands.
| Protection | Standard |
| - | - |
| **Encryption in transit** | TLS 1.2 or higher for all communication |
| **Encryption at rest** | AES-256 or better, managed via GCP. API keys are additionally AES-256 encrypted before storage. |
### AI models and data privacy
By default, Realm uses a mix of US and EU based large language models. On request, we can configure your environment to use EU-only language models.
Realm uses private, enterprise-grade LLM endpoints with zero-data-retention policies. Customer data is never used to train, develop, or improve any AI models.
## Permission model
Realm's search is permission-aware. For sources like Slack, Google Drive, and SharePoint, Realm syncs the full permission structure, including nested groups and role-based access. Users can only see search results and chat responses based on data they should have access to in the original system.
Due to API limitations, some data sources, such as HubSpot and Notion, use user-level access checks (i.e. the user has a matching account) rather than document-level permissions. See the [Permissions](/admin/data-sources/overview#permissions) section in the data sources guide for details.
## Access control
### Authentication
Realm supports multiple sign-in methods. See [Login Methods](/admin/login-methods) for details.
| Method | Description |
| - | - |
| **Google SSO** | OAuth sign-in with Google |
| **Microsoft SSO** | OAuth sign-in with Microsoft |
| **SAML 2.0** | Enterprise SSO through your identity provider |
| **Email and password** | Standard email-based sign-in |
### Roles
Every user is assigned a role that determines what they can see and do. Roles are managed on the [Users](/admin/members-and-roles) page.
| Role | Access level |
| - | - |
| **Admin** | Full access to all features and settings |
| **Full Member** | All features except admin settings |
| **Collaborator** | Chat, search, and RFP editing only |
### Session management
Admins can force sign out individual users from the [Users](/admin/members-and-roles) page. Organization-wide session policies (automatic session expiration and idle timeouts) are available on request. Contact [support@withrealm.com](mailto:support@withrealm.com) to configure these.
## API token security
API tokens are scoped and can be set to expire on a specific date. By default, only admins can create and manage tokens. See [API Keys](/admin/api) for details.
## Data retention
Customer data is retained for the duration of the customer relationship. Upon contract termination, all data is erased. Stored chat history can also be configured for automatic deletion after a set number of calendar months. You can request deletion of specific data on demand, which is purged from indexes within an hour. Encrypted backups are retained for up to 90 days after termination before being automatically deleted.
## Infrastructure
Realm runs on Google Cloud Platform (GCP). Backend systems, databases, and search indexes are not publicly accessible. The architecture uses VPC peering for secure database access and network policies within Kubernetes to isolate internal traffic. A managed Web Application Firewall (WAF) is in place.
Realm undergoes annual third-party penetration testing and quarterly internal security audits, and uses continuous vulnerability scanning on its codebase.
### Deployment models
| Model | Description |
| - | - |
| **Single-tenant** | Dedicated infrastructure with isolated application servers, databases, and search indexes. Available for enterprise customers. |
| **Multi-tenant** | Strict logical separation of customer data using unique customer identifiers. |
## Incident response
Realm has a documented incident response framework adapted from NIST and SANS guidelines. In the event of a data breach, Realm notifies the affected customer without undue delay.
For security questions or to request documentation (DPA, BAA, penetration test reports), contact [support@withrealm.com](mailto:support@withrealm.com) or visit our [Drata trust center](https://app.drata.com/trust/0c273e99-bf79-4f9d-8479-5219416ca26c).
# Tools
Source: https://docs.withrealm.com/admin/tools
Connect external tools so your agents can take actions
Tools let agents take actions in external systems. Send emails, update CRMs, create tickets, post messages, and more.
**Tools vs Data sources:** Data sources sync knowledge *into* Realm so agents
can search and reference it. Tools let agents act *outward* by performing
actions in external systems.
To manage tools, go to **Agents** > **Tools** or **Settings** > **Tools** in the sidebar.
## Available tools
Realm includes tools for popular workplace apps:
### Built-in tools
Two tools are available out of the box with no setup required:
| Tool | Description |
| - | - |
| **Email** | Send emails to Realm users |
| **HTTP Request** | Send HTTP requests to external APIs and webhooks. Target APIs may still require their own authentication (e.g. headers or tokens). |
### Connection scope
Each tool uses one of two connection scopes. For organization-scoped tools, everyone in the workspace uses the same connection with the same permissions as whoever authenticated the tool. If you want specific access rights, you can create a dedicated account for Realm.
| Scope | Description |
| - | - |
| **Organization** | A single shared connection used by everyone in the workspace. An admin authenticates once and all users can use the tool. |
| **Personal** | Each user connects their own account. Actions are performed on behalf of the individual user. |
Some tools support only one scope. **Gmail**, **Google Calendar**, and
**Outlook** are personal-only (each user connects their own account).
**Slack** and **Vitally** are organization-only (one shared connection for the
whole workspace).
## Enabling a Tool
Go to **Agents** > **Tools** or **Settings** > **Tools** in the sidebar.
Browse the **Available** section for the tool you want to enable.
Click **Configure** or **Enable** on the tool.
Select **Organization** or **Personal** as the connection scope. Some tools support only one scope, so the selector is hidden. Gmail, Google Calendar, and Outlook are personal-only. Slack and Vitally are organization-only.
Click **Connect** or **Connect for everyone** to connect the tool.
For GitHub, GitHub may show **Request** or **Install and request** when an organization owner must approve the Realm GitHub Agent. Realm remains disconnected while approval is pending. After an owner installs the app, return to Realm and connect GitHub again.
## Managing tools
Once a tool is enabled, click **Configure** to manage its actions, settings, and connections.
### Actions
Each tool exposes individual actions (e.g. "Create Ticket", "Update Contact"). You can toggle specific actions on or off to control exactly what agents are allowed to do with a tool.
### Per-agent configuration
For more details on how tools work within agents, see the [User guide:
Agents](/agents/creating-agents#tools).
You can also configure actions and parameters per agent. To access this, go to **Agents** in the sidebar, click on an agent, then click **Edit** in the header. In the **Tools** section, click **Set rules...** on a connected tool.
**Action modes** control whether each action is allowed:
| Mode | Behavior |
| - | - |
| **On** | The agent can use this action freely |
| **Off** | The action is disabled for this agent |
| **Ask first** | The agent must get user confirmation before running the action |
**Parameter overrides** let you lock down specific parameters:
| Override | Behavior |
| - | - |
| **Preset parameters** | Lock a parameter to a specific value (e.g. always send to a specific Slack channel) |
| **Hidden parameters** | Hide a parameter from the model so it can't be changed or seen by the agent |
Some actions also include behavior settings. For Slack's post-message action,
turn off **Summary thread for long messages** if you want long messages posted
directly instead of as a short parent message with the full content in a thread.
### Settings
Each tool has a **Settings** section with configuration options.
**Admin Only** toggles the tool so only admins can see and use it. This is useful for tools that perform sensitive operations.
**Microsoft Admin Consent** is available for Microsoft tools like Outlook and Microsoft 365. Click **Grant Admin Consent** to grant consent for all users in your Microsoft tenant. This removes individual consent prompts, so users can connect the tool without going through Microsoft's approval flow themselves.
### Changing scope
You can switch a tool between **Organization** and **Personal** scope after it's been enabled.
Changing scope may remove existing connections. Users will need to
re-authenticate after the change.
### Disabling a Tool
Disabling a tool removes all connections and makes it unavailable across the workspace. You can re-enable it at any time.
### Connections
View all active connections for a tool, including:
* Who is connected
* Connection status
* Option to remove individual connections
For **Salesforce**, the list shows the Salesforce account that authorized the
connection, with the Realm user who ran the connect flow shown as
**Connected by**. Agent actions run with that Salesforce account's permissions,
not the Realm user's.
An organization-scope connection is shared by everyone in the workspace and
runs on a single Salesforce login. Consider authenticating with a dedicated
Salesforce integration user with a scoped permission set rather than a
personal account. The **Connections** list is where you verify which account
is in use.
### Google file picker
For **Google Drive** and **Google Sheets** tool connections, the **Connections** list includes a **Pick files** button.
Use this when you want to authorize specific Google files for an existing tool connection.
When you click **Pick files**, Realm opens the Google Picker using the credentials from that connection. You can choose one or more files from Google Drive, and Realm stores those selections on the connector for later tool use.
For the **Google Sheets** tool, pick every spreadsheet that agents need to read or update. Connecting Google Sheets authorizes the account, but the spreadsheets still need to be selected with **Pick files** before agents can update them through the Google Sheets tool.
The same applies to the **Google Drive** tool and existing Google Docs documents. Agents can always update documents they created themselves, but any document that already existed has to be selected with **Pick files** before an agent can write to it.
The picker uses the permissions of the connected Google account. It does not
grant access to files the account cannot already open in Google Drive.
To use it:
Go to **Agents** > **Tools** or **Settings** > **Tools**, then open **Google Drive** or **Google Sheets**.
In the **Connections** section, locate the connection you want to update.
Click **Pick files**. Google Picker will open in a popup window.
Select one or more files from Google Drive, then confirm the selection. For Google Sheets updates, select the spreadsheets the agent should be allowed to update. For Google Docs edits or full replacements, select the documents the agent should be allowed to change.
Realm adds the selected files to that connection immediately. If you use the picker again later, the new selection is merged with the files already stored on the connector.
## MCP Servers
MCP (Model Context Protocol) is a protocol for connecting agents to external tools and data sources. You can add custom MCP servers to extend what your agents can do.
MCP servers are not available on trial plans.
### Adding a Server
Click **Add MCP Server** from the Tools page. You can either connect a **Featured MCP Server** with one click, or add a custom server manually.
Provide the URL of the MCP server. Use the server's own documentation when
possible. As a rule of thumb, a URL ending in `/mcp` usually uses
Streamable HTTP, while one ending in `/sse` usually uses Server-Sent Events.
Select **Streamable HTTP** or **Server-Sent Events (SSE)** to match the
server.
Choose **OAuth**, **Bearer Token**, or **Custom Headers** and enter the
required credentials. You can add headers such as `x-api-key` or vendor
version headers. The `Authorization` header is managed separately by the
authentication type.
Optionally give the connection a descriptive name. This is useful when connecting to the same server multiple times with different credentials.
Click **Connect** to complete the setup.
### Featured servers
Realm highlights these featured MCP servers for quick one-click setup:
### Managing servers
Once added, you can **reconnect** or **delete** MCP servers from the Tools page. Use the trash icon next to a connected server to delete it directly from the list, or open the server's details page for the same option.
## Troubleshooting
### Salesforce: OAuth Error When Connecting
When connecting the Salesforce tool, Salesforce may show an **OAuth Error**
page saying that it cannot authorize you and reporting
`OAUTH_APPROVAL_ERROR_GENERIC`. It may describe the failure only as an
unexpected authentication error and tell you to try again or contact your
Salesforce administrator.
This is typically caused by a recent Salesforce security change that requires connected apps to be explicitly installed before they can be used. You can confirm this is the issue by checking the URL in your browser's address bar. If it contains `error=invalid_client&error_description=app+must+be+installed+into+org`, then the Realm app needs to be installed in your Salesforce org.
**To fix this:**
Log in to Salesforce as an admin and go to **Setup** > **Connected Apps OAuth Usage**.
Find the **Realm** app in the list and click **Install**.
Return to Realm and try connecting the Salesforce tool again.
For more details, see [this Salesforce article](https://help.salesforce.com/s/articleView?id=005132365\&type=1).
## Admin vs user permissions
| Capability | Admin | Regular User |
| - | - | - |
| Enable/disable tools | Yes | No |
| Change connection scope | Yes | No |
| Set admin-only restriction | Yes | No |
| Grant Microsoft Admin Consent | Yes | No |
| View all connections | Yes | No |
| Connect personal-auth tools | Yes | Yes |
| View enabled tools | Yes | Yes |
| Manage own connections | Yes | Yes |
# Trust center
Source: https://docs.withrealm.com/admin/trust-center
Access Realm's compliance documentation and security certifications
Realm's trust center is hosted on Drata and provides access to compliance documentation, security certifications, and audit reports.
View certifications, reports, and request documentation such as DPA, BAA, and penetration test reports
For questions, contact [support@withrealm.com](mailto:support@withrealm.com).
# Creating Agents
Source: https://docs.withrealm.com/agents/creating-agents
Follow these steps to create custom AI agents
## Name and description
Give your agent a name, icon, and short description. The description helps others quickly understand what the agent does.
### Triggers
A Trigger is an event that automatically starts an Agent, transforming it from an on-demand tool into a proactive agent running in the background. You can set up Triggers to run Agents based on a schedule, specific events in your other software, or incoming webhooks.
A Trigger is not required if you only plan to run an Agent manually.
#### Based on a schedule
This trigger runs an Agent on a recurring, time-based interval. You can set it to run daily, weekly, or monthly.
#### Based on a knowledge event
This trigger runs an Agent automatically when synced knowledge changes in one of your connected systems. After you choose a Source, the Trigger when menu shows source-specific options such as Opportunity updated, Deal updated, Call created, Thread created, or Thread reply added.
For updated events, add at least one Filter condition. The Agent runs when that field changes to the value you configured. For example, use Source = Salesforce, Trigger when = Opportunity updated, and If Stage equals Closed Won to run when an Opportunity moves to Closed Won.
#### Based on a webhook
This trigger runs an Agent when it receives an HTTP request from an external system. This is a powerful way to integrate with internal tools or any third-party platform that can send webhooks, even if it doesn't have a direct integration with Realm.
#### Based on a project status change
This trigger runs an Agent when a project's status changes, for example when a project is marked Completed. Choose the statuses that should start the Agent; with nothing selected, every status change starts it.
#### Based on a new project
This trigger runs an Agent once for each project that is created, after the project has left the setup wizard and its files have finished processing, so the Agent can read them.
For detailed step-by-step instructions on setting up each trigger type, see [Creating triggers](/agents/triggers).
### Agent instructions
Instructions are the most important part of an agent. They define how the agent behaves, what it should do, and how it should approach the task. You can write them manually or ask the Operator panel in the editor to draft or rewrite them.
Specificity improves results. Clear goals, step-by-step guidance, relevant context, and explicit references to tools or documents all help the agent perform more reliably.
The key concepts in agent instructions are:
* **Purpose**: Start by clearly describing what the agent is meant to do. For example: "Your task is to help me prepare for discovery calls. Gather relevant background information and produce a concise summary that helps me understand who the customer is, what they do, and how we might fit."
* **Step-by-step guidance**: Break the workflow into numbered steps. This makes the agent's process easier to follow and improves consistency.
* **References to the right context**: You can point the agent to specific documents, integrations, tools, or other agents. For example, you might ask it to review a specific document in one step, check HubSpot in another, or call another agent as part of the workflow. To insert these references, type the `@` character in the instructions field or click the insert icon. To add a subagent, select the agent from that selector.
* **Variables for reusable workflows**: Use `{{ }}` to define variables the user fills in when running the agent, such as `{{Customer}}` or `{{Deal}}`. This is useful for reusable workflows like a Customer Health agent, where the agent can run against any company based on the input provided.
For prompting best practices and how to delegate work to other Agents, see [Writing instructions](/agents/writing-instructions).
### Tools
Tools allow agents to take actions in external systems, such as sending emails, updating CRM records, creating tickets, or posting messages. Realm includes built-in tools and also supports integrations via MCP (Model Context Protocol).
In the agent editor, you can control which tools an agent can use and configure how each action behaves.
For each action you can choose:
| Setting | Description |
| - | - |
| **On** | The agent can run the action automatically |
| **Ask** | The agent must request user confirmation before running the action |
| **Off** | The agent cannot use the action |
You can also configure parameters for each action:
* **Preset parameters**: Lock a parameter to a fixed value (for example, always post messages to a specific Slack channel).
* **Hidden parameters**: Hide parameters from the model so they cannot be modified or accessed by the agent.
For more details on managing tools across your organization, see [Admin guide: Tools](/admin/tools).
### Knowledge
The Knowledge section defines what indexed context the agent can access when running.
When you add knowledge to an agent, it becomes searchable. The agent can use it when it's relevant, but it won't read everything by default.
If you need the agent to always consider a specific source, tag it. Tagged content is included every time the agent runs. Untagged content is only used when the agent decides it's relevant.
#### Allow all
The agent can access all connected knowledge sources. Existing document permissions are respected, so users only see information they already have access to.
#### Limited
Restrict the agent to specific folders, channels, or files. Selecting a folder includes all subfolders and content within it. Use this when the agent should only work with a defined set of sources.
#### No knowledge
The agent runs without access to internal company data and behaves like a general-purpose AI.
You can also control whether the agent can use Web Search. Set it to always enabled, turn it off, or leave it user selectable. User selectable starts on; if the user turns it off, Realm remembers that choice for the agent, including after you close and reopen the app. In the web chat UI, Research thinking mode always uses Web Search, even for an agent that has it turned off; the public API does not apply this override, so a Research request against an agent with Web Search turned off does not use it.
Additionally, you can upload files directly from your computer to include them in the agent's knowledge.
### Advanced settings
Advanced settings allow you to control how the agent reasons, performs research, and processes information.
* **Thinking mode**: Controls how deeply the agent reasons about a task. Fast prioritizes speed, Research performs deeper multi-step reasoning for complex tasks, and Auto lets Realm decide the best mode.
* **Image generation**: Allows the agent to generate or edit images using AI. Enable this if the agent needs to create visuals as part of its workflow.
* **Skip search**: Allows the agent to answer questions directly from the selected knowledge without running a search step. This setting is only available when the agent's knowledge base is small and clearly defined, typically less than 20 documents.
* **Search filters**: Defines default filters used when the agent searches for information. Filters can restrict results by attributes such as author, date, project, or other metadata.
* **Override model**: By default, Realm selects the best language model automatically. You can enable Override model to choose a specific model (for example, Claude Sonnet 5.5 or Gemini 3.7 Flash) for the agent's final answer.
### Testing and iterating
The agent editor provides a side-by-side chat view, allowing you to test your agent with different queries and see the results in real time. Refine the instructions, adjust knowledge sources, and tweak the configuration until the agent performs exactly as needed.
After publishing, the agent page summarizes the instructions, connected tools,
knowledge, and capabilities that users rely on when they run it. The side panel
also shows recent trigger runs, Chat usage for the last 30 days, configured
Slack channels, access, and triggers. Use this page to verify what an agent can
reach and how it has been used before changing its configuration.
### Version history
Realm keeps a version history of every agent. Each time you publish, the previous configuration is preserved, so you can always see how an agent has changed over time and go back to an earlier setup.
Open the history from the clock icon in the agent editor. The panel lists every version with its name, when it was created, and who created it. The published version is tagged **Up to date**, and unpublished edits appear at the top as a **Modified** version.
From the menu on a version you can:
* **Show difference**: See what changed, both compared to the currently published version and compared to the version that came right before it. Changes cover the agent's configuration, including instructions, knowledge, and advanced settings.
* **Restore version**: Make that version the published one again. The restored version becomes immediately available to everyone using the agent. If the agent is published and you have unpublished edits, Realm asks whether to publish or discard them first.
## Sharing agents with your team
Share an agent with your team so others can use it directly or customize their own copy. By default, team members with access can run the agent from the shared link or the agent page, and you can also give individual users access with User or Editor permissions.
You can control who can access the agent from the sharing menu:
* **Restricted**: Only people who already have access can use it through the link.
* **Anyone in Realm**: Anyone in your Realm workspace can use the agent.
* **Specific people**: Add individual teammates and choose whether they are a User or Editor.
Use Copy Link to share the agent quickly, and update access at any time from the sharing settings.
Workspace owners and admins see every agent in the workspace on the Agents page, including restricted agents nobody shared with them. The Access filter on the Agents page isolates them. Opening one shows a Grant edit access button, which lets an owner or admin review the agent and turn off its triggers if needed.
# Agent examples
Source: https://docs.withrealm.com/agents/examples
Pre-built agent templates for sales, customer success, support, and marketing
## Sales
| Template | Description |
| - | - |
| Competitive Intelligence | Proactively tracks competitor mentions in news, social media, and earnings calls. Delivers a weekly digest to a designated Slack channel, highlighting key product launches, pricing changes, and new customer wins. |
| Customer POV | After a discovery call, this agent analyzes call transcripts and notes to generate a "Point of View" document. It maps the prospect's stated business problems directly to your product's features and value propositions. |
| Deal Review | Performs an in-depth analysis of a specific deal in your CRM. It flags missing MEDDPICC criteria, identifies potential risks, and suggests next steps to increase the probability of closing. |
| Discovery Call Prep | Gathers and summarizes all relevant information for an upcoming discovery call. The prep-sheet includes the prospect's LinkedIn profile, company news, and a summary of previous interactions from your CRM. |
| MEDDPICC | Analyzes all documentation tied to an account (call notes, emails). It then summarizes the deal's qualification status against each element of the MEDDPICC framework, identifying gaps and strengths. |
| News Monitoring | Runs a daily web search for key developments at target accounts or existing customers. It identifies trigger events like funding rounds, executive changes, or expansion plans and sends alerts to the account owner. |
| Prospect Status | Provides a concise summary of the current engagement status with a prospect. It recaps the last five touchpoints (emails, calls, meetings) and highlights the prospect's last-known sentiment and next steps. |
| RFP Qualification | Analyzes an incoming RFP against your ideal customer profile and product capabilities. It provides a summary with a go/no-go recommendation to focus sales efforts effectively. |
| Sales Call Coaching | Reviews call recordings from the last two weeks to identify coaching opportunities. It highlights talk-to-listen ratios, surfaces common objections, and flags missed questions related to budget or timeline. |
## Customer success
| Template | Description |
| - | - |
| Customer Health Score | Continuously analyzes customer data from CRM, support tickets, and product usage. Calculates a real-time health score and flags at-risk accounts for immediate CSM follow-up. |
| QBR Prep | Automatically generates a data-rich presentation for a Quarterly Business Review. It summarizes product usage trends, support ticket history, achieved ROI, and identifies opportunities for expansion. |
| Churn Risk Alert | Monitors product usage data for negative trends, such as a drop in active users or feature adoption. If a significant decrease is detected, it automatically creates a task for the CSM to investigate. |
| Renewal Agent | Proactively tracks contracts up for renewal within the next 90 days. It compiles usage data, key conversation points from past interactions, and suggests a renewal strategy. |
| Onboarding Checklist Generator | Creates a tailored onboarding checklist for new clients based on their specific industry and use cases. |
| Expansion Signal Identifier | Analyzes customer usage patterns, feature requests, and executive engagement to flag potential expansion or upsell opportunities. |
| Customer Happiness Pulse | Monitors NPS survey results and sentiment from support tickets and calls over time to detect early signs of customer dissatisfaction or identify potential advocates. |
| Cross-Team Handoff Automator | Automates the creation of handoff documentation when a customer moves from sales to implementation or from implementation to ongoing support, ensuring a seamless customer journey. |
| Expansion Opportunity Finder | Analyzes product usage data of current customers to identify those nearing their license limits or heavily using features that are part of a higher-tier plan. It alerts the account owner of the upsell opportunity. |
## Customer support
| Template | Description |
| - | - |
| Support Ticket Resolution | When a new support ticket is created, this agent researches internal documentation and past tickets with similar issues. It then suggests a potential resolution and relevant articles to the support agent. |
| Proactive Support Agent | Analyzes product usage data to predict potential issues before they become support tickets. It can detect non-standard usage patterns that might lead to errors and trigger a proactive email to the customer with optimization advice. |
| Support Documentation Creator | Turns resolved support tickets, internal Slack discussions, and engineering notes into structured, clear customer-facing help center articles or internal knowledge base documents. |
| Virtual SE Assistant | Acts as a first line of defense for technical inquiries. It can field initial questions via an AI voice or chat interface, answering common questions and escalating more complex issues to a human Sales Engineer. |
| KB Update Alert | Monitors internal discussions and recently resolved tickets to identify when knowledge base articles have become outdated and alerts the documentation team to make updates. |
| Automated Ticket Triage | Analyzes the intent of incoming support tickets, automatically categorizes them, checks for known issues, and either provides an immediate resolution or escalates to the correct team with full diagnostic information. |
## Marketing
| Template | Description |
| - | - |
| ABM Intel | Gathers intelligence on a list of target accounts. It identifies key decision-makers, summarizes their recent social media activity, and finds relevant company news to personalize outreach campaigns. |
| Thought Leadership Engine | Transforms internal strategy documents, product updates, and interesting prospect conversations into drafts for LinkedIn posts, blog articles, and keynote presentation ideas for executives. |
| Website Content Auditor | Periodically audits the company website against the latest product documentation, call recordings, and CRM data to identify content gaps, outdated information, or missing marketing angles. |
| Social Proof Finder | Scans call transcripts and closed-won deal notes in the CRM to extract quotable moments, success stories, and positive customer feedback that can be used in marketing materials. |
| Partner Campaign Builder | Develops a complete co-marketing campaign plan for a new partner. This includes defining joint positioning, target personas, messaging, and content concepts for blogs, webinars, and social media. |
| Event Narrative Creator | Generates a concept and agenda for a regional marketing event based on an analysis of common customer pain points in that area. It can also create supporting materials like email invitations and website copy. |
| New Lead Enrichment | When a new lead enters the CRM, this agent automatically enriches the record by searching for the person's LinkedIn profile, company size, and recent company news, providing immediate context for the sales team. |
# Overview of Agents
Source: https://docs.withrealm.com/agents/overview
Build custom AI assistants for specific tasks and workflows
## What are agents?
Agents automate specific tasks and workflows. You define their instructions, what knowledge they can access, and which tools they can use.
When an agent runs, either manually or through a trigger, it uses a large language model to interpret the instructions, retrieve relevant context from your company's knowledge, and take actions in connected systems.
For example, a discovery preparation agent can help sellers prepare for upcoming meetings. Every morning at 9 AM it checks your calendar for upcoming calls, gathers context from the CRM and web search, and sends a short briefing to Slack.
## Key features
* **Instructions (Runbook)**: Define how the agent works. Write step-by-step instructions that specify its persona, task, process, and output format.
* **Triggers**: Run agents automatically on a schedule (for example every Monday at 9 AM) or in response to events, such as when a deal moves to a new stage in your CRM.
* **Tools and actions**: Allow agents to interact with external applications and perform actions in systems like your CRM or email.
* **Knowledge**: Control what information the agent can access. Select data sources, enable web search, or upload files to provide the right context.
* **Advanced settings**: Configure capabilities such as Research and Image Generation. The Realm agent automatically uses data analysis when a task requires computation or visualization. To let an agent delegate work to another agent, add that agent to the instructions with the `@` character or insert icon.
## How to find and use agents
* **Browse the agent gallery**: Navigate to the Agents section from the sidebar.
* **Use the @ keybind in Chat**: Type `@` to bring up a menu of available agents.
* **Pin favorite agents**: Pin your favorite agents to the home page.
* **Organize with categories**: Create categories such as Pre-Sales from Agent Categories in the bottom left of the agents gallery. You can then tag agents by opening them and adding a category at the bottom of the page.
The agent gallery has a search field and card or list views. You can sort by
popularity, creation date, or name, and filter by publication status, creator,
category, or **Favorites**. Status distinguishes agents that are published and
ready to use from drafts that are still being configured.
## Creating agents
There are three ways to create an agent: start from scratch, describe the agent to Realm, or get started with a template.
### Create from scratch
Build an agent from the ground up. Define its name, instructions, knowledge, and tools.
### Describe your agent
Describe what you want the agent to do; use @ to tag the sources, documents, and agents it should use. Realm opens a new draft in the editor and fills in the name, instructions, tools, and answering settings for you. The Operator panel stays open in the editor, so you can keep asking it to rewrite the instructions, add tools, or change the answering mode; it edits the draft and you publish.
For example: "Prepare me for discovery calls in the next 24 hours by identifying relevant meetings in my Google Calendar and only including true discovery calls. For each, gather context from HubSpot and Slack, run a web search for recent company updates, and generate a concise prep brief with key context, past interactions, risks or opportunities, and suggested questions and next steps."
### Start with a template
Choose a pre-built agent template and customize it for your task or workflow.
# Adding Agents to Slack channels
Source: https://docs.withrealm.com/agents/slack-channels
Configure AI agents to respond in specific Slack channels
Before adding agents to Slack channels, the Realm Slack app must be installed in your workspace by an admin. See [Slack app](/integrations/slack-app) for setup instructions.
## Adding an agent to a Slack channel
In the desired Slack channel, type @Realm and add the Realm app.
Click the channel name at the top and find the Channel ID at the bottom of the pop-up window.
In the Realm agent editor under Advanced Settings, paste the Channel ID into the Slack Integration section.
## How to interact with an agent in a channel
Team members can mention the agent with the `@` key followed by their question in the connected channel. The designated agent will post a threaded reply with the answer and source citations.
The way the answer appears depends on the Slack integration's **Public channel answer mode** setting:
| Mode | What users see |
| - | - |
| **Preview** | Realm first shows the answer as an "Only visible to you" preview for the person who asked. They can then share it to the thread or dismiss it. |
| **Share** | Realm posts the answer directly as a visible threaded reply. |
| **None** | Realm does not answer questions in channels. |
Admins can change this in the Slack data source settings under **Public channel answer mode**. Use **Share** if you want agents to reply directly in Slack threads without the private preview step.
When an agent is invoked from Slack, its normal response is sent back to the same Slack thread. You usually do not need to add or enable a separate Slack post-message tool for the agent to reply in that thread. Use the Slack post-message tool only when the agent should send a separate message to another channel, user, or thread; otherwise, it may create a new channel message instead of continuing the current thread.
## Example use cases
* **#sales-support**: An agent trained on product documentation, pricing, and competitive battle cards.
* **#customer-success**: An agent connected to your CRM and support systems for quick customer account summaries.
## Tips
* You can call a different agent than the default one by typing `@Realm `.
* If users see "Only visible to you" answers, the Slack integration is using **Preview** mode. Switch to **Share** mode to post answers directly to the thread.
* Do not add the Slack post-message tool just to answer Slack mentions. The agent's final answer is already returned to the thread where it was invoked.
Only users with an active Realm license can interact with agents in Slack.
# Tools and actions
Source: https://docs.withrealm.com/agents/tools
Allow agents to take actions in external systems
Tools allow agents to take actions in external systems, such as sending emails, updating CRM records, creating tickets, or posting messages. Realm includes built-in tools and also supports custom integrations via MCP (Model Context Protocol).
## Available tools
Realm includes tools for popular workplace apps:
Two tools are available out of the box with no setup required:
| Tool | Description |
| - | - |
| **Email** | Send emails to Realm users |
| **HTTP Request** | Send HTTP requests to external APIs and webhooks |
## Adding tools to an agent
In the agent editor, navigate to the **Tools** section to select which tools the agent can use. Only tools that have been enabled by an admin are available.
## Configuring actions
Each tool exposes individual actions, such as "Create Ticket" or "Update Contact". For each action you can choose:
| Setting | Description |
| - | - |
| **On** | The agent can run the action automatically |
| **Ask** | The agent must request user confirmation before running the action |
| **Off** | The agent cannot use the action |
Use **Ask** for actions that are hard to reverse or that carry risk, such as sending emails or updating records.
**Ask** requires a resumable interaction where you can respond to the confirmation. It works in Realm chat and the external chat API approval flow. In contexts that cannot pause and resume, including sub-agents and automated runs, actions set to **Ask** are unavailable to the agent rather than run without confirmation.
## Configuring parameters
You can also configure parameters for each action:
* **Preset parameters**: Lock a parameter to a fixed value. For example, always post messages to a specific Slack channel.
* **Hidden parameters**: Hide parameters from the model so they cannot be modified or accessed by the agent.
Use preset parameters for stable values that define where an action is allowed to operate, such as a Slack channel, a Google Sheets Spreadsheet ID, or a fixed sheet name. Let the agent fill parameters that depend on the current task, such as the message text, generated cell values, or the row that matched a CRM record.
For write actions, preset parameters are a useful guardrail. They keep the agent pointed at the intended system or document while still letting it decide the dynamic parts of the update from the trigger context and its instructions.
## Personal tools
Some tools, such as Gmail, Google Calendar, and Outlook, require each user to connect their own account. These are called personal tools. Users can connect their personal accounts from **Settings** > **Personal integrations**.
For organization-scoped tools, an admin authenticates once and all users share the same connection.
For details on enabling and managing tools across your organization, see
[Admin guide: Tools](/admin/tools).
## Updating Google Sheets
To let an agent update an existing Google Sheet, the Google Sheets tool must be connected and the spreadsheet must be selected with Google Picker.
An admin can do this from **Agents** > **Tools** or **Settings** > **Tools**:
Open **Google Sheets** and find the connection the agent will use.
In **Connections**, click **Pick files**. Google Picker will open in a popup
window.
Select each spreadsheet the agent should be allowed to update, then confirm
the selection.
Add the Google Sheets tool to the agent and turn on the update action, or
set it to **Ask** if users should confirm updates first.
Connecting Google Sheets only authorizes the account. The specific spreadsheets must also be picked before agents can update them through the Google Sheets tool.
## Updating Google Docs
Agents can create Google Docs documents, read them, and edit them in place.
For routine edits, the agent reads the document, copies the exact wording it wants to change, and replaces it, or appends new text at the end. Everything it did not match, including images, footnotes, tables and formatting, is left exactly as it was. If the text it looks for is not there, nothing changes and the agent is told so.
When you explicitly ask for a complete rewrite, the agent can instead replace one tab's entire content from new Markdown in a single approved action. The agent must provide the complete intended result, not only the changed part. This deletes and recreates the selected tab's content, so formatting, images, footnotes, suggestions and other structures not represented by the Markdown may be lost.
In a document with several tabs, the agent reads every tab and each edit names the tab it applies to, so wording that also appears in another tab is left alone. A replace covers a whole tab including its headers and footers, and the agent sees those in the same read, so it can tell you when a change reaches them.
Realm can only write to documents it created itself or that were selected with Google Picker. Editing any other document fails with a permission error, and the agent tells the user which setting to change.
An admin can grant access to existing documents from **Agents** > **Tools** or **Settings** > **Tools**:
Open **Google Drive** and find the connection the agent will use.
In **Connections**, click **Pick files**. Google Picker will open in a popup
window.
Select each document the agent should be allowed to edit, then confirm the
selection.
Add the Google Drive tool to the agent and turn on the edit actions, or set
them to **Ask** if users should confirm edits first.
Documents an agent created itself are already writable and do not need to be picked.
# Triggers
Source: https://docs.withrealm.com/agents/triggers
Automate agents with schedule, event, and webhook triggers
## What are triggers?
A Trigger is an event that automatically starts an Agent, transforming it from an on-demand tool into a proactive agent running in the background. You can set up Triggers to run Agents based on a schedule, specific events in your other software, or incoming webhooks.
A Trigger is not required if you only plan to run an Agent manually.
## Organize triggers with tags
Use trigger tags to label related triggers by team, workflow, customer, or purpose. Tags are shared across your workspace and can be created, renamed, recolored, or deleted from the tag picker on any trigger.
On the main Triggers page, use the Tags section in the sidebar to filter the list. Selecting more than one tag shows triggers that have any selected tag.
## How to create triggers
All trigger types include a **Timeout** setting. Choose 15, 30, 60, or 120 minutes, or choose **Uncapped** for runs that should not stop automatically. If you do not change this setting, Realm stops a trigger run after 60 minutes.
### Based on a schedule
This trigger runs an Agent on a recurring, time-based interval. You can set it to run daily, weekly, or monthly.
Choose the interval and execution time in the trigger form. For a weekly
schedule, also select the days of the week. The summary below the controls shows
the complete schedule and time zone; verify it before saving so the Agent runs
at the intended local time.
**Example**: An Agent could run every morning at 8 AM, scan your calendar for the day's meetings, gather recent news and background information on the attendees and their companies, and deliver a concise briefing document.
### Based on a knowledge event
This trigger runs an Agent automatically when synced knowledge changes in one of your connected systems. Use it when the Agent should react to new or updated records, documents, messages, tickets, calls, CRM objects, or activities.
When you create a knowledge-event trigger, you define what starts the Agent, where it happens, and under what conditions. The configuration options are:
* **Source**: The connected application where the event originates, such as Gong, Salesforce, HubSpot, Slack, Google Drive, Jira, or Zendesk. Only connected sources are shown.
* **Trigger when**: The item type and change type that starts the Agent. Realm builds these options from the selected source's supported content types, such as Opportunity updated, Deal updated, Ticket created, Call created, Thread created, or Thread reply added.
* **Filter conditions (optional)**: Rules that control precisely when the Agent runs.
* **If**: Set conditions based on the changed item. For example, only run the Agent when an Opportunity's Stage changes to Closed Won, when an Owner field is not empty, or when a call's duration is longer than 10 minutes. For Slack triggers, the **Mentions** and **Reply Mentions** fields match the people @-mentioned in the message, so an Agent can for example stay out of threads already addressed to named colleagues by requiring that Mentions is empty.
* **Folder or Channel**: Restrict the trigger to a specific folder, channel, or similar location within the source application. Slack triggers require a channel. Other sources can usually be left unrestricted.
* **Bot messages**: For Slack triggers, you can restrict which bots may start the Agent. An empty allowed-bots selection blocks every bot while still allowing messages from people. A workflow always ignores Slack messages produced by its own runs, even when other Realm messages are allowed. If you leave this off, messages from any bot or app (for example Linear or Jira notifications) can start the Agent.
#### Options of the Trigger when field
After you select a Source, Realm shows the event options available for that source. Each option pairs a supported item type with the event that can start the Agent:
| Pattern | Meaning | Example options |
| - | - | - |
| **Item created** | A new item of that type was synced | Opportunity created, Deal created, Call created |
| **Item updated** | An existing item of that type changed | Opportunity updated, Deal updated, Ticket updated |
| **Item reply added** or **Item activity added** | A new reply, comment, or activity was added to an existing parent item | Thread reply added, Opportunity activity added, Deal activity added |
Some item types only support updated events, so you may not see both created and updated for every item type. Salesforce also includes shortcuts such as Task created and Event created for activity-style automation.
For CRM automation, look for the CRM object in this menu rather than a separate generic event name. For example, a Salesforce Opportunity change is configured with Source = Salesforce and Trigger when = Opportunity updated. A HubSpot deal change is configured with Source = HubSpot and Trigger when = Deal updated.
#### Conditions on updated events
Updated events require at least one Filter condition. The Agent runs only when a condition field changed and the new value matches the condition.
For example, to run when a Salesforce Opportunity is moved to Closed Won:
* Source: Salesforce
* Trigger when: Opportunity updated
* Filter condition: If Stage equals Closed Won
This means the Agent runs when the Opportunity's Stage field changes to Closed Won. It does not run for every unrelated edit to the Opportunity.
Filter conditions can match a specific value, exclude a value, check whether text contains a value, match any value from a list, or check whether a field is empty or not empty.
Some fields can hold several values at once, such as Tags, Reviewers, Participants, and Mentions. A condition on these fields matches if any value matches. For example, If Tags equals escalated matches a ticket that has the escalated tag among its other tags. A condition that excludes a value, such as If Tags does not equal spam, matches only when no value is spam. On updated events, the Agent runs when the condition starts matching, for example when the escalated tag is added. It does not run again when other tags change on a ticket that already matched.
Created and reply/activity-added events can be left without conditions. If you leave them unrestricted, the Agent runs for every new matching item in the selected Source and folder or channel.
**Example: Analyze a Gong call transcript**
Goal: Automatically summarize every new sales call, identify mentioned competitors, and extract action items.
* Source: Gong
* Trigger when: Call created
* Agent action: The Agent receives the call transcript, summarizes it, searches for competitor names against a predefined list, and sends a summary with action items to a specific Slack channel.
**Example: Automate CRM updates**
Goal: When a deal is marked as "Closed Won" in Salesforce, automatically fill in a "Win Reason" field based on recent call notes and emails.
* Source: Salesforce
* Trigger when: Opportunity updated
* Filter: If Stage equals Closed Won
* Agent action: The Agent gathers context from recent activities, generates a concise "Win Reason", and updates the corresponding field in Salesforce.
**Example: React to a new CRM activity**
Goal: When a task or event is added to a Salesforce Opportunity, summarize what changed and notify the account owner.
* Source: Salesforce
* Trigger when: Opportunity activity added, Task created, or Event created, depending on the activity you want to catch
* Filter: Optional, such as If Reply Type equals Task
* Agent action: The Agent reads the Opportunity context and the new activity, then sends a Slack message to the owner.
**Example: Sync Salesforce Opportunities to Google Sheets**
Goal: Keep a Google Sheet up to date when relevant Salesforce Opportunities are created or updated.
Set up the Agent with these pieces:
* Add Salesforce as knowledge or as a tool, depending on whether the Agent only needs synced CRM context or also needs to run live Salesforce actions.
* Add the Google Sheets tool and enable the read and write actions the Agent needs.
* Make sure the spreadsheet is selected with Google Picker before the Agent writes to it. See [Updating Google Sheets](/agents/tools#updating-google-sheets) for the detailed setup.
* Set write actions to **Ask** while testing. Change them to **On** only after the Agent reliably writes the right rows and values.
* Use preset parameters for stable values the Agent should not choose, such as the Spreadsheet ID and a fixed sheet or range pattern.
* Let the Agent fill dynamic values, such as the row to update and the cell values, when those depend on the triggered Opportunity or the current sheet contents.
Then create a trigger:
* Source: Salesforce
* Trigger when: Opportunity created or Opportunity updated
* Filter: Add conditions for the changes you care about, such as If Stage equals Proposal or If ARR Growth is greater than 100000.
* Agent instructions: Tell the Agent to read the triggered Opportunity, check whether that Salesforce Opportunity ID already exists in the sheet, then update that row or add a new row.
Use a stable unique key, such as the Salesforce Opportunity ID, to match CRM records to spreadsheet rows. Names can change and are not always unique.
Event triggers react to future create, update, and activity events as Realm syncs them. They do not bulk-import every existing CRM record. For an initial backfill, run an Agent manually or on a schedule and instruct it to search Salesforce for the records to add before the event trigger handles future changes.
### Based on a webhook
This trigger runs an Agent when it receives an HTTP request from an external system. This is a powerful way to integrate with internal tools or any third-party platform that can send webhooks, even if it doesn't have a direct integration with Realm.
To set up a webhook trigger:
1. **Select trigger type**: Choose "Based on a webhook" when creating your trigger.
2. **Copy the webhook URL**: Realm will generate a unique URL for this trigger. Copy this URL.
3. **Configure the external system**: Paste the copied URL into the webhook configuration section of the external tool you want to trigger the Agent from.
4. **Choose authentication (optional)**: Select an authentication method to secure your webhook and ensure only authorized systems can trigger your Agent.
For a custom webhook, **Additional authentication** offers these choices:
| Method | Incoming request requirement |
| - | - |
| **None** | No extra authentication |
| **Basic auth** | HTTP Basic credentials with a username and password |
| **Bearer token** | An `Authorization: Bearer {token}` header |
| **HMAC SHA-256** | A request signature generated from the shared secret |
**Example**: A "Contact Us" form on your website could send a webhook to Realm for each new submission. An Agent could then analyze the submission, create a new lead in your CRM, and notify the appropriate sales representative in Slack.
### Based on a project status change
This trigger runs an Agent when a project's status changes, for example when a project is marked Completed. Use it to post updates to other systems as your projects move through their lifecycle.
To set up a project status trigger:
1. **Select trigger type**: Choose "Based on a project status change" when creating your trigger.
2. **Choose statuses**: Check the statuses that should start the Agent. With nothing selected, every status change starts it. A category's built-in status, such as Drafting, starts the Agent whenever a project enters that category; a custom status starts it when a project moves into that exact status. See [Project statuses](/rfp/settings#project-statuses).
The Agent receives the project name, a link to the project, and the old and new status, using your organization's status names. When the project is linked to a CRM opportunity, it also receives the opportunity name, account, and link.
**Example**: When a project is marked Completed, an Agent could summarize the outcome and post an update to the linked Salesforce opportunity as a note.
### Based on a new project
This trigger runs an Agent when a project is created. Use it to do the first pass of work on every new bid, such as reading the tender documents and drafting a brief.
To set up a new project trigger:
1. **Select trigger type**: Choose "Based on a new project" when creating your trigger.
There is nothing else to configure. Every project created in your organization starts the Agent once.
The Agent does not start the moment the project appears. Realm waits until the project has left the setup wizard and every file in it has finished processing, so the Agent can read the files rather than find them half parsed. A project whose files are still being processed starts its Agent when the last file is done, which can be several minutes after the project was created.
The Agent receives the project name, its project id, a link to the project, the description and deadline if they are set, and the names of the project's files. When the project is linked to a CRM opportunity, it also receives the opportunity name, account, and link. The Agent can read any of the files by listing them from the project and then reading the file it needs.
Each project starts the Agent at most once. Adding more files later does not start it again, and a trigger you create today does not run for projects that already exist.
**Example**: When a new project is created, an Agent could read the tender documents, summarize the scope, deadlines, and mandatory requirements, and post that brief to the bid team's Slack channel.
## Run history and monitoring
You can monitor a trigger from the Agents > Triggers list and from the trigger's detail page. In the list view, each trigger shows its Last run and Status, which makes it easy to scan whether a trigger is active and when it last ran.
Use the search field to find a trigger by name. The list can be narrowed by
trigger **Type** (Schedule, Event, or Webhook), **Status** (Active, Paused, or
Waiting for user), and ownership (**All automations** or **My automations**).
### Trigger details page
On the trigger detail page, the Execution history section shows individual runs for that trigger. Each run includes the run time, the trigger type shown as Scheduled run, and a Completed status.
#### What you can see
* Trigger status in the list view, such as Active
* Last run in the list view
* Execution history on the trigger detail page
* Configured timeout on the trigger detail page
* Run status for each execution, such as Completed or Timed out
#### Why it is useful
Use run history to:
* Confirm that a trigger is firing as expected
* Check when the trigger last ran
* Review whether recent executions completed successfully
* Track trigger activity over time
* Manually run a trigger with its normal input, a selected document, a webhook payload, or raw text input when testing
#### Monitoring tips
* After creating a trigger, check its Status and Last run in the list view to confirm it is active and running
* Open the trigger detail page to review Execution history
* Use the history table to verify that scheduled runs are completing as expected
## Sharing and permissions
A trigger has one owner and can be shared with other people in your organization. New triggers are private to their owner until the owner shares them. Triggers that were created before sharing was introduced stay visible to everyone in your organization.
### Roles
* **Owner**: The person who created the trigger. An owner can do everything an editor can do, and can also delete the trigger, manage its access list, and transfer ownership to someone else.
* **Editor**: Can change the trigger's configuration, enable or disable it, run it now, and retry, cancel, or resume runs. An editor cannot delete the trigger, share it, or transfer ownership.
* **Viewer**: Can open the trigger and read its configuration and run history. A viewer cannot change the trigger, its tags, and cannot start a run.
Only full members and admins can be added to a trigger, because viewing, changing, and running a trigger are all full-member actions. Collaborators cannot be given access to a trigger.
### Who can see a trigger
The owner chooses between two levels of visibility from the sharing menu:
* **Private**: Only the owner and the people on the access list can see the trigger. Add people individually and choose whether each of them is a viewer or an editor.
* **Everyone in your organization**: Anyone in your organization can open the trigger and follow its runs. Changing or running the trigger still requires the editor role.
You can switch between these two options at any time, and the named people on the access list keep the roles you gave them.
### Organization admins
Organization admins can see every trigger and can pause or resume any of them without being added to the access list. When an admin needs to change a trigger, they can grant themselves edit access in one click. That grant then appears in the trigger's access list, so the owner can always see who has access.
### Runs use the owner's permissions
A trigger always runs with its owner's permissions and connections. Changes made by an editor are carried out under the owner's identity, so a run can only reach the documents, agents, and calendars that the owner can reach. Transferring ownership changes which permissions later runs use.
Run status, timing, and errors are visible to editors and viewers. The chat transcript of a run is not shared: it stays with the person whose run created it.
Because of this, an editor can only pick an agent that the owner can reach, and the Google Calendar connection of a calendar trigger can only be changed by the owner. An editor sees the owner's calendar selection but cannot swap in their own connection.
### Transferring ownership
An owner can transfer a trigger to another full member or admin of the organization. The previous owner stays on the access list as an editor, so they can keep working on the trigger without owning it. Because later runs use the new owner's permissions, a transfer is refused when the new owner cannot reach the trigger's agent, and a calendar trigger can only be transferred to someone who has access to its Google Calendar connection.
### Triggers that need attention
A trigger stops running when it can no longer work as configured:
* Its agent was deleted or unpublished
* Its owner was removed from the organization
* Its owner no longer has access to its agent
The next time such a trigger fires, Realm skips the run and marks the trigger
**Needs attention** in the triggers list and on its detail page, with the cause
and what to do about it. The trigger's owner and your organization admins get
one notification, in the app and by email.
Fix the cause (for example, publish the agent or transfer the trigger to an
active member) and the trigger resumes on its next fire. If the trigger is still
broken 7 days after it was first marked, its next fire turns it off and Realm
notifies the same people again. Turn the trigger back on once it is fixed.
Temporary problems during a run, such as a timeout or an error from a connected
tool, do not mark a trigger. Those runs show as failed in the run history.
## Troubleshooting a trigger
If a trigger does not run as expected:
* Confirm the trigger is enabled and does not show **Needs attention**
* Check that the trigger conditions are correct
* Verify that the source system is sending the event or webhook
* Review the most recent run history for errors or skipped runs
Run history gives you visibility into how your Agents behave over time, making it easier to monitor, debug, and trust automated workflows.
# Writing instructions
Source: https://docs.withrealm.com/agents/writing-instructions
Best practices for writing effective Agent instructions
## Overview
Instructions are the most important part of an Agent. They define how the Agent behaves, what it should do, and how it should approach the task. You can write them manually or ask the Operator panel in the editor to draft or rewrite them.
In general, specificity improves results. Clear goals, step-by-step guidance, relevant context, and explicit references to tools or documents all help the Agent perform more reliably.
## Key Concepts
### Purpose
Start by clearly describing what the Agent is meant to do.
Example: "Your task is to help me prepare for discovery calls. Gather relevant background information and produce a concise summary that helps me understand who the customer is, what they do, and how we might fit."
### Step-by-Step Guidance
Break the workflow into numbered steps. This makes the Agent's process easier to follow and improves consistency.
```text theme={null}
1. Review the customer's website and recent news
2. Check the CRM for past interactions
3. Search for key contacts on LinkedIn
4. Compile findings into a brief summary
```
### References to the Right Context
You can point the Agent to specific Documents, Integrations, Tools, or other Agents. For example, you might ask it to review a specific document in one step, check HubSpot in another, or call another Agent as part of the workflow.
To insert these references, type the `@` character in the instructions field or click the insert icon.
To add a subagent, select an Agent from that menu. See [Delegating to subagents](#delegating-to-subagents) below for details.
### Variables for Reusable Workflows
Use `{{ }}` to define variables the user fills in when running the Agent, such as `{{Customer}}` or `{{Deal}}`. This is useful for reusable workflows like a Customer Health Agent, where the Agent can run against any company based on the input provided.
```text theme={null}
Research {{Customer}} and provide a health score based on:
- Recent interactions
- Product usage
- Support tickets
```
## Delegating to subagents
An Agent can hand off a focused task to another Agent, called a subagent. The subagent runs on its own, with its own instructions, knowledge, and tools, and returns a summary of what it found or did. This keeps the main Agent's workflow simple and lets you reuse specialists you have already built.
### Add a subagent
In the instructions field, type `@` (or click the insert icon) and select an Agent. The Agents you select are the ones this Agent is allowed to delegate to. Reference the subagent in the step where it should run.
Example step: "For each account, delegate to @CRM Researcher to pull the latest opportunities and open support tickets, then summarize the risks."
### When to delegate
* **Reuse a specialist**: Build one Agent that does a job well, such as deep CRM research or competitor analysis, and call it from higher-level Agents instead of duplicating the logic.
* **Split independent work**: Break a large task into focused subtasks, such as researching several accounts. Subagents run concurrently in the background, and the main Agent combines their results once they finish.
* **Keep context focused**: Push noisy retrieval into a subagent and get back only the summary, so the main Agent stays focused on the final output.
### Write clear delegation steps
A subagent does not see the full conversation or the parent Agent's context, so give it a self-contained task.
A subagent also does not inherit the parent Agent's tools. It can use only the tools set up on the subagent itself, and a general-purpose subagent has none of the parent's connectors. If a step needs an action in another system, such as posting a Jira comment, either add that tool to the subagent or have the subagent return the text and let the parent Agent post it.
* State exactly what to find or produce, and what to return.
* Keep each delegated task focused and independent so it can run on its own.
* Delegate to a few focused Agents rather than chaining many; deep chains of subagents are slower and harder to follow.
### Asynchronous tasks
Delegated work runs as asynchronous tasks. The main Agent splits the work, starts the tasks, and keeps working while they run. Up to four tasks run at the same time; the rest wait their turn and start as earlier tasks finish. Each task runs either an Agent you selected with `@` or a general-purpose subagent when no specialist fits.
* **Task panel**: The panel beside the chat lists every task with its live status. Expand a task to follow its own thread as it streams.
* **Questions mid-run**: A task can ask the main Agent a clarifying question while it runs, and the answer goes back to that task without restarting it.
* **Long documents**: For a multi-section document, the main Agent plans the outline, drafts the sections in parallel, and stitches them back together in order.
Live task progress is visible in the Realm app. The public API returns the final answer only.
## Best Practices
Provide specific objectives and detailed instructions. Longer prompts with relevant context outperform short queries.
Supply sufficient background information. Modern AI models can process complex information effectively.
Follow a logical order: role assignment, tone setting, background information, detailed task description with rules.
Show, don't just tell. Examples of desired outputs work better than descriptions of what you want.
Always define a persona to set the tone of the response. This guides how the model communicates.
Provide instructions for handling unusual situations. Focus on base cases first, then add edge case handling.
Evaluate prompts under various scenarios and refine based on results. Prompt engineering is an iterative process.
## Example Instruction Structure
```text theme={null}
# Role
You are [specific role] for [company/context].
# Task
Given [input], your job is to [specific task].
# Guidelines
- [Guideline 1]
- [Guideline 2]
- [Guideline 3]
# Output Format
[Describe expected format]
# Examples
Input: [example input]
Output: [example output]
# Constraints
- Only use information from the provided materials
- If unsure, say so rather than guessing
- [Other constraints]
```
## Create Instructions with AI
Ask the LLM in Realm to create instructions for you:
Start a new chat session.
Choose Claude, Gemini, or GPT.
Explain what you want the Agent to accomplish.
The AI will generate an optimized prompt for you.
Modern LLMs excel at creating effective prompts for themselves or other models, often producing better results than manually crafted prompts.
## Common Mistakes to Avoid
**Don't:**
* Use vague instructions like "be helpful"
* Assume the AI knows your company context
* Give contradictory instructions
* Make instructions too long without structure
## Next Steps
Configure what knowledge your Agent can access
Enable your Agent to take actions in external systems
# List agents
Source: https://docs.withrealm.com/api-reference/agents/list-agents
/api-reference/openapi.json get /agents
List all agents that the API token has access to
### Rate Limits
600 requests per minute.
# Create or continue a chat
Source: https://docs.withrealm.com/api-reference/chats/create-or-continue-a-chat
/api-reference/openapi.json post /chats
Create a chat with a specific agent, or continue an existing chat. Any document that you have access to that is in the agent's knowledge base could be used to answer questions.
### Rate Limits
600 requests per minute.
### Approval-required responses
If the agent reaches an ask-first action, this endpoint returns `200 OK` with `status: "approval_required"` instead of failing. Use the returned `assistant_message_id` and approval metadata to resume the chat via `POST /chats/{chat_id}/approvals`.
### Tools and documents
Use `tool_mode` to set action behavior for one request. `ask` requires approval for every configured action, `act` allows configured actions to run without approval, and `off` disables all actions. Use `tool_configs` to override individual configured actions in `ask` or `act` mode. Use `tool_connector_ids` to select a subset of the agent's configured external tools. These settings cannot add tools or change the agent's saved configuration.
Use `document_refs` to attach up to 20 exact documents by Realm API data source ID and source document ID. Realm checks that the API token's user can access each document before creating the chat.
### One answer at a time per chat
A chat answers one message at a time. If you send a request for a `chat_id` that is still generating an answer, Realm responds with `409 Conflict` and an error code of `generation_in_flight`, rather than running both turns and losing one of the answers.
The response includes a `Retry-After` header and a `retry_after_seconds` field with the number of seconds the in-flight answer may still run. Wait that long and retry, or omit `chat_id` to start a separate chat. Requests for different chats never conflict with each other.
# Create or continue a chat with a streaming response
Source: https://docs.withrealm.com/api-reference/chats/create-or-continue-a-chat-with-a-streaming-response
/api-reference/openapi.json post /chats-streaming
Create a chat with a specific agent, or continue an existing chat. Any document that you have access to that is in the agent's knowledge base could be used to answer questions.
### Rate Limits
600 requests per minute.
### Approval-required events
If the agent reaches an ask-first action while streaming, the stream emits a `tool_approval_request` event and then ends normally. Resume the paused chat with `POST /chats/{chat_id}/approvals`.
### Tools and documents
Use `tool_mode` to set action behavior for one request. `ask` requires approval for every configured action, `act` allows configured actions to run without approval, and `off` disables all actions. Use `tool_configs` to override individual configured actions in `ask` or `act` mode. Use `tool_connector_ids` to select a subset of the agent's configured external tools. These settings cannot add tools or change the agent's saved configuration.
Use `document_refs` to attach up to 20 exact documents by Realm API data source ID and source document ID. Realm checks that the API token's user can access each document before starting the stream.
### One answer at a time per chat
A chat answers one message at a time. If you send a request for a `chat_id` that is still generating an answer, Realm refuses the second turn rather than running both and losing one of the answers.
The stream has already started by the time Realm knows about the conflict, so it arrives as a terminal `generation_error` event with an `error` of `generation_in_flight` and a `retry_after_seconds` field holding the number of seconds the in-flight answer may still run. The stream then ends. Wait that long and retry, or omit `chat_id` to start a separate chat. Requests for different chats never conflict with each other.
# Delete a chat
Source: https://docs.withrealm.com/api-reference/chats/delete-a-chat
/api-reference/openapi.json delete /chats/{chat_id}
Delete a chat
### Rate Limits
600 requests per minute.
# Get chat's messages
Source: https://docs.withrealm.com/api-reference/chats/get-chats-messages
/api-reference/openapi.json get /chats/{chat_id}
Get a stored chat's messages.
### Rate Limits
600 requests per minute.
# List chats
Source: https://docs.withrealm.com/api-reference/chats/list-chats
/api-reference/openapi.json get /chats
List chats
### Rate Limits
600 requests per minute.
# Resume a paused chat after tool approval
Source: https://docs.withrealm.com/api-reference/chats/resume-a-paused-chat-after-tool-approval
/api-reference/openapi.json post /chats/{chat_id}/approvals
Submit ask-first approval decisions for a paused chat and continue the agent run.
### Rate Limits
600 requests per minute.
### When to use this endpoint
Use this endpoint after `POST /chats` returns `status: "approval_required"` or `POST /chats-streaming` emits a `tool_approval_request` event. Submit approval decisions for the pending tool calls to continue the same chat.
# Command line interface
Source: https://docs.withrealm.com/api-reference/cli
Drive the Realm API from your terminal with the Realm CLI
## Overview
The Realm CLI wraps the same REST API documented in this section. It gives you agent chats with live streaming answers, document management for API data sources, and an interactive chat session, all from a terminal. Every command accepts `--json`, so the CLI also works as a scripting tool in pipelines.
## Installation
The CLI ships as a single standalone executable. On macOS and Linux:
```bash theme={null}
curl -fsSL https://storage.googleapis.com/realm-cli/install.sh | bash
```
On Windows, in PowerShell:
```powershell theme={null}
irm https://storage.googleapis.com/realm-cli/install.ps1 | iex
```
The installer downloads the executable for your platform together with `SHASUMS256.txt`, verifies the SHA-256 checksum before installing, installs to `$HOME/.realm/bin/realm` (`%USERPROFILE%\.realm\bin\realm.exe` on Windows), adds that directory to your `PATH`, and runs `realm --version` to confirm the result. Nothing else is required: the executable carries its own runtime.
Prebuilt executables cover macOS x64 and arm64, Linux x64 and arm64 for both glibc and musl, and Windows x64 and arm64. Three environment variables change what the installer does: `REALM_INSTALL_DIR` selects the install directory, `REALM_VERSION` pins an exact version such as `0.2.0`, and `REALM_RELEASE_URL` points at an alternate release location, which `realm update` honors as well.
The CLI is also published to npm, which requires Node.js 22.12 or newer:
```bash theme={null}
npm install -g @realmtechnologies/cli
realm --version
```
### Upgrading
An executable installed with the install script updates itself:
```bash theme={null}
realm update
realm update --check
```
`realm update` downloads the latest release for the running platform, verifies its checksum, and replaces the running executable in place. `realm update --check` reports the latest release without installing it, and `realm update --json` prints `{current, latest, channel, target, update_available, updated}`.
When a newer release exists, an interactive run prints one notice on standard error, such as `Update available: 0.1.1 → 0.2.0. Run realm update.`. The version lookup runs in a detached background process at most once every 24 hours and is cached in the CLI configuration directory, so it never delays or fails a command. The notice is suppressed with `--json`, when standard error is not a terminal, when `CI` is set to anything other than `false`, and when `REALM_CLI_NO_UPDATE_CHECK=1`.
On an npm installation, `realm update` declines and points you at `npm install -g @realmtechnologies/cli@latest`.
Run `realm --version` to see which version is installed. An executable also reports its release target, for example `0.1.1 (linux-x64)`.
## Authentication
Create an API key first. See [API keys](/admin/api) for how to create and manage keys, and note that a key carries scopes: `chat:read`, `chat:write`, and `documents:write`.
### Interactive login
```bash theme={null}
realm auth login
```
The command prompts for your key, verifies it against `GET /agents`, and stores it in your operating system credential store. When no credential store is available, for example on a headless Linux host, the key is written to a configuration file with owner-only permissions instead.
The standalone executables always use that configuration file, because the credential-store binding is a per-platform native library that cannot be embedded in a cross-compiled executable. The npm installation uses the credential store whenever one is available. Everything else about the two installations is identical.
A key that carries only `documents:write` cannot list agents. Login still accepts and stores such a key, and notes that chat commands are unavailable with it. A key that fails authentication outright is never stored.
Check or remove the stored key:
```bash theme={null}
realm auth status
realm auth logout
```
### Continuous integration
Set `REALM_API_TOKEN` in the environment. It takes precedence over any stored key, so no login step is needed in a pipeline.
```bash theme={null}
export REALM_API_TOKEN="realm_api_..."
realm agents list --json
```
### Multiple tenants
The default base URL is `https://app.withrealm.com`. Single-tenant deployments live on their own host, which you select with `--base-url` on any command, or persist with `realm config set base-url`. The `REALM_BASE_URL` environment variable overrides the persisted value.
Keys are stored per host, because API keys are tenant scoped. Logging in against two hosts keeps two keys side by side, and each command uses the key of the host it targets. Storing a key for a host also clears any copy of it held by the other store, so a single key per host is all the CLI can ever resolve.
The base URL must use `https://`, because the key travels in an `Authorization` header. Plain `http://` is accepted only for local development hosts: `localhost`, `*.localhost`, `127.0.0.1`, and `::1`.
```bash theme={null}
realm config set base-url https://acme.withrealm.com
realm auth login
realm agents list --base-url https://app.withrealm.com
```
## Global flags
| Flag | Description |
| - | - |
| `--json` | Print the raw API payload with no decoration. |
| `--base-url ` | Target host for this invocation. |
| `--token ` | Use this key instead of the stored or environment key. |
## Command reference
### Authentication and configuration
| Command | Description |
| - | - |
| `realm auth login` | Prompt for an API key, verify it, and store it for the active host. |
| `realm auth status` | Show the active host, where its key came from, and a masked key prefix. |
| `realm auth logout` | Remove the stored key for the active host. |
| `realm config get base-url` | Print the configured base URL. |
| `realm config set base-url ` | Persist the base URL used by later commands. |
| `realm update` | Replace the running executable with the latest release. Accepts `--check`. |
### Agents and data sources
| Command | Description |
| - | - |
| `realm agents list` | List the agents your key can reach, including which one is the default. |
| `realm connectors list` | List the API data sources of your organization. Their IDs are the data source IDs used by the document commands. |
### Chat
```bash theme={null}
realm chat
```
Running `realm chat` without a subcommand opens an interactive session: pick an agent, send messages, and watch answers stream in. Tool calls that need approval are presented as a prompt, and answering continues the same chat. The session prints its chat ID on exit so you can resume the transcript with `realm chat messages`. The session needs a terminal on both input and output, so with `--json`, redirected output, or piped input the command points you at `realm chat ask` instead.
| Command | Description |
| - | - |
| `realm chat ask ""` | Send one message and print the answer. |
| `realm chat list` | List chats. Accepts `--limit`, `--after`, and `--order`. |
| `realm chat messages ` | Print the messages of a chat in full, one block per message headed by its ID and role. Accepts `--citation-style`. |
| `realm chat delete ` | Delete a chat. |
| `realm chat approve ` | Resume a chat that is waiting for tool approval. |
Flags for `realm chat ask`:
| Flag | Description |
| - | - |
| `--agent ` | Agent to ask. Required. |
| `--chat ` | Continue an existing chat instead of starting a new one. |
| `--stream` | Print the answer token by token as it is generated. |
| `--research` | Run the request in research mode. |
| `--tool-mode ` | One of `ask`, `act`, or `off`. |
| `--citation-style