***

title: Multi-Tenant Chat Moveworks Setup Guide
position: 5
deprecated: false
hidden: false
metadata:
robots: index
-------------

## Overview

This guide explains how to enable users to access the same Moveworks bot from multiple Teams tenants or Slack instances within a single Moveworks organization.

**Example Use Case:** Connect Moveworks Commercial (Prod US) to both Azure Commercial and a separate Azure tenant (e.g., GCCH) simultaneously.

***

## Critical Considerations

### 1. Identity Resolution

Users must be joinable across tenants using a single key to ITSM/IDAM systems. Choose one approach:

#### Option A - Employee ID/GUID (Recommended)

* Add `employeeID` or GUID to the new tenant and ITSM
* Use this consistent identifier for joining user records

#### Option B - Email Prefix Standardization with SwapEmailDomainConverter

* **Use this when:** Chat tenant email domain ≠ ITSM email domain
* **Example scenario:** Users have `user@company.com` in ITSM but `user@subsidiary.com` in Teams tenant
* Use `SwapEmailDomainConverter` to normalize domains during identity merge
* Standardizes email prefixes across tenants (e.g., `john` from `john@domain1.com` and `john@domain2.com`)

#### Option C - Superset in ITSM

* **Use this when:** ITSM contains accounts for all email domains used across all chat tenants
* No conversion needed - direct email join works
* ⚠️ **Requires ITSM as primary/leftmost identity system**

### 2. Messaging Endpoint

Verify the bot forwards to the correct Moveworks endpoint (Commercial, GCCH, EU, CA) based on your deployment.

***

## Implementation Steps

Replace Graph/Teams with your chat system equivalent as needed.

### Step 1: Add MS Teams Connector

**Navigation:** Setup → Manage Connectors → System Connectors

1. Click "Add Connector"
2. Select **MS Teams** connector
3. Name it for the second tenant (e.g., `msteams_tenant_2_name`)
4. Complete the connector configuration
5. This connector handles bot messaging for the new tenant

### Step 2: Add MS Graph Connector

**Navigation:** Setup → Manage Connectors → System Connectors

1. Click "Add Connector"
2. Select **MS Graph** connector
3. Name it for the second tenant (e.g., `msgraph_tenant_2_name`)
4. Complete authentication and permissions
5. This connector handles identity/user data ingestion from the second tenant

### Step 3: Add Identity Source for Second Tenant

**Navigation:** Setup → User Identity → Import Users

1. Click "Add Identity Source"
2. Select the new MS Graph connector (`msgraph_tenant_2_name`) as the source
3. Configure identity ingestion from the second tenant
4. Add the `user_id_info.channel_id_info` for the `msteams_tenant_2_name` connector
   * **Note:** The channel will still be `MSTEAMS` even though it's a different tenant
5. Save the configuration

### Step 4: Configure Service Account with New Channel

**Navigation:** Setup → User Identity → Advanced Settings → Service Account

1. Locate the service account user configuration
2. Add a new `channel_id_info` entry for the second Teams tenant:

```json
"channel_id_info": [
  {
    "integration_id": "msteams",
    "user_channel_id": "28:{{BOT_ID_INSTANCE_ONE}}"
  },
  {
    "integration_id": "msteams_tenant_2_name",
    "user_channel_id": "28:{{BOT_ID_INSTANCE_TWO}}"
  }
]
```

3. Replace `{{BOT_ID_INSTANCE_ONE}}` and `{{BOT_ID_INSTANCE_TWO}}` with your actual bot IDs
4. Save the configuration

### Step 5: Create Chat Bot Config

**Navigation:** Setup → Manage Chatbots → Chatbots

1. Click "Add New Chatbot"
2. Configure for the new Teams tenant
3. Select the MS Teams connector created in Step 1 (`msteams_tenant_2_name`)
4. Complete the chatbot configuration
5. **Important:** Note the `integration_id` for use in later steps

### Step 6: Configure Identity Conversion (If Needed)

**Navigation:** Setup → User Identity → Import Users

⚠️ **Only required if using Option B** (email domains differ between chat tenant and ITSM)

1. Locate the identity source for the second tenant
2. Add `SwapEmailDomainConverter`
3. Configure the domain mapping:
   * **Source domain:** `subsidiary.com` (Teams tenant domain)
   * **Target domain:** `company.com` (ITSM domain)
4. This ensures `user@subsidiary.com` (Teams) joins with `user@company.com` (ITSM)

**Skip this step if:**

* Using Option A (Employee ID/GUID join)
* Using Option C (ITSM has all email domains)
* Email domains already match between chat tenant and ITSM

### Step 7: Validate Roster

**Navigation:** Setup → User Identity → View Users

1. Search for test users from each tenant
2. Verify expected users in each tenant have a valid `channel_id` for each integration
3. Confirm both `integration_id` values appear in user records
4. Verify identity ingestion ran correctly

### Step 8: Configure Notification Routes

**Navigation:** Setup → AI Assistant → Notification Routes

1. Set bot channel preference order
2. **Priority order matters:** List most-restricted tenant first
   * **Example:** Tenant 2 first (subset of users), then Tenant 1 (all users)
3. The system will notify users on the first available channel according to this priority

### Step 9: Update Launch Communications

**Navigation:** Setup → AI Assistant → Employee Communications

1. Configure route preferences using `integration_id`
2. Set up outbound messaging for both tenants
3. Test outbound notifications to both tenants

***

## Validation Checklist

Use this checklist to ensure all configuration steps are complete:

* [ ] MS Teams connector added for second tenant
* [ ] MS Graph connector added for second tenant
* [ ] Identity source configured in Import Users for second tenant
* [ ] Service account updated with new `channel_id_info` entry
* [ ] Chat Bot config created with unique `integration_id`
* [ ] Identity conversion configured (only if email domains differ)
* [ ] Roster shows users with both channel IDs
* [ ] Notification routes prioritized correctly
* [ ] Test inbound messages from both tenants
* [ ] Test outbound notifications to both tenants

***

## Common Issues & Troubleshooting

| Issue                            | Potential Cause                                  | Solution                                                                                        |
| -------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Bot doesn't respond in Tenant 2  | Incorrect messaging endpoint or `integration_id` | Verify messaging endpoint configuration and confirm `integration_id` matches in Chat Bot config |
| Users not found                  | Identity merge failure                           | Verify identity conversion settings and check roster merge configuration                        |
| Wrong bot receives notifications | Incorrect notification route priority            | Review notification route priority order - most restrictive tenant should be first              |
| Identity merge failures          | Missing or incorrect SwapEmailDomainConverter    | Confirm SwapEmailDomainConverter is configured if email domains differ between systems          |
| Missing channel IDs              | Service account not updated                      | Verify service account has `channel_id_info` entries for both tenants                           |
| Service account messages fail    | Incorrect `integration_id` or bot\_id            | Confirm service account `channel_id_info` includes correct `integration_id` and bot IDs         |

***

## Additional Resources

* MS Teams Connector Documentation
* MS Graph Connector Documentation
* Identity Resolution Best Practices
* Notification Routes Configuration

***

## Support

If you encounter issues not covered in this guide, please contact Moveworks Support with:

* Screenshots of your connector configurations
* Roster validation results
* Error messages or logs
* Test user examples from both tenants