---
canonical_url: "https://docs.composio.dev/toolkits/microsoft_viva_engage"
markdown_url: "https://docs.composio.dev/toolkits/microsoft_viva_engage.md"
product: "platform"
version: null
last_updated: null
---

# Microsoft Viva Engage

Manage Viva Engage communities, members, owners, and engagement role discovery and assignments through Microsoft Graph.

- **Category:** team collaboration
- **Auth:** OAUTH2
- **Composio-managed OAuth available?** No
- **Tools:** 19
- **Triggers:** 0
- **Slug:** `MICROSOFT_VIVA_ENGAGE`
- **Version:** 00000000_00

## Tools

### Add Community Member

**Slug:** `MICROSOFT_VIVA_ENGAGE_ADD_COMMUNITY_MEMBER`

Add one Microsoft Entra user to a Viva Engage community by adding the user to its associated Microsoft 365 group. Requires group_id from community.groupId, not the Viva Engage community ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | Yes | Microsoft Entra user object ID to add as a community member. |
| `group_id` | string | Yes | Microsoft 365 group ID from community.groupId. This is not the Viva Engage community ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Add Community Members in Bulk

**Slug:** `MICROSOFT_VIVA_ENGAGE_ADD_COMMUNITY_MEMBERS_BULK`

Atomically add up to 20 users to a Viva Engage community's associated Microsoft 365 group. If any user reference is invalid, no users are added.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `group_id` | string | Yes | Microsoft 365 group ID from community.groupId. This is not the Viva Engage community ID. |
| `user_ids` | array | Yes | One to 20 unique Microsoft Entra user object IDs to add atomically. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Add Community Owner

**Slug:** `MICROSOFT_VIVA_ENGAGE_ADD_COMMUNITY_OWNER`

Make one Microsoft Entra user a Viva Engage community admin by adding the user as an owner of the community's associated Microsoft 365 group. This grants administrative privileges: confirm the target user and group before calling. Add the owner as a member separately if member capabilities are also required. Requires group_id from community.groupId, not the Viva Engage community ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | Yes | Microsoft Entra user object ID to make a community admin. |
| `group_id` | string | Yes | Microsoft 365 group ID from community.groupId. This is not the Viva Engage community ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Assign Engagement Role Member

**Slug:** `MICROSOFT_VIVA_ENGAGE_ASSIGN_ENGAGEMENT_ROLE_MEMBER`

Assign one predefined Viva Engage administrative or corporate communication role to a Microsoft Entra user. This changes the user's privileges; confirm both the role and target user before calling. Retain the returned member ID for safe removal; Graph currently uses the target user ID as that member ID when this route returns 204.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `role_id` | string | Yes | Predefined Viva Engage role ID returned by listing engagement roles. |
| `user_id` | string | Yes | Microsoft Entra user ID that will receive the Viva Engage role. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Community

**Slug:** `MICROSOFT_VIVA_ENGAGE_CREATE_COMMUNITY`

Start asynchronous creation of a Viva Engage community. This provisions Microsoft 365 tenant resources and returns an operation reference; poll the operation separately before treating the community as created.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `privacy` | string ("public" | "private" | "unknownFutureValue") | No | Community visibility setting. |
| `description` | string | No | Optional community description, up to 1024 characters. |
| `display_name` | string | No | Optional name for the new community. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Community

**Slug:** `MICROSOFT_VIVA_ENGAGE_DELETE_COMMUNITY`

Permanently delete a Viva Engage community and all associated Microsoft 365 content, including its connected group, OneNote notebook, and Planner plans. This destructive action cannot be undone.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `community_id` | string | Yes | ID of the Viva Engage community to permanently delete. Do not pass the community's Microsoft 365 group ID. Deletion cannot be undone and also removes the connected Microsoft 365 group, OneNote notebook, and Planner plans. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Community

**Slug:** `MICROSOFT_VIVA_ENGAGE_GET_COMMUNITY`

Get one Viva Engage community by community ID, including its distinct associated Microsoft 365 group ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `expand` | string | No | Microsoft Graph $expand expression for related community data. |
| `select` | string | No | Comma-separated Microsoft Graph community properties to return. |
| `community_id` | string | Yes | Viva Engage community ID. Do not pass the associated Microsoft 365 group_id here. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Engagement Async Operation

**Slug:** `MICROSOFT_VIVA_ENGAGE_GET_ENGAGEMENT_ASYNC_OPERATION`

Get the status and resulting resource reference for a Viva Engage asynchronous operation such as community creation. Make separate calls more than 30 seconds apart while polling.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `select` | string | No | Comma-separated engagement operation properties to return. |
| `operation_id` | string | Yes | Engagement asynchronous operation ID returned by a prior Viva Engage mutation. Wait more than 30 seconds between status checks. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Communities

**Slug:** `MICROSOFT_VIVA_ENGAGE_LIST_COMMUNITIES`

List Viva Engage communities in the tenant, one Microsoft Graph page at a time, including each community ID and associated Microsoft 365 group ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Opaque continuation cursor returned by a previous call; omit it for the first page. |
| `expand` | string | No | Microsoft Graph $expand expression for related community data. |
| `select` | string | No | Comma-separated community properties to return, such as id,displayName,groupId,privacy. |
| `order_by` | string | No | Sort expression for displayName, for example displayName asc. |
| `page_size` | integer | No | Maximum communities to request in this page; Microsoft Graph may return fewer. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Community Members

**Slug:** `MICROSOFT_VIVA_ENGAGE_LIST_COMMUNITY_MEMBERS`

List direct members of a Viva Engage community's associated Microsoft 365 group, one Microsoft Graph OData page at a time. Requires group_id from community.groupId, not the Viva Engage community ID. Hidden members are visible only when the connection also has Member.Read.Hidden.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Opaque continuation cursor returned by a previous call; omit it for the first page. |
| `expand` | string | No | Microsoft Graph $expand expression. Do not combine it with filter, search, or include_count. |
| `filter` | string | No | OData filter expression for direct members. |
| `search` | string | No | Microsoft Graph search on displayName or description using quoted property:value syntax, for example "displayName:Alex". |
| `select` | string | No | Comma-separated directory object properties to return. |
| `group_id` | string | Yes | Microsoft 365 group ID from community.groupId. This is not the Viva Engage community ID. |
| `page_size` | integer | No | Maximum members to request in this page (1-999). |
| `include_count` | boolean | No | Whether to include the total count as @odata.count. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Community Owners

**Slug:** `MICROSOFT_VIVA_ENGAGE_LIST_COMMUNITY_OWNERS`

List owners of a Viva Engage community's associated Microsoft 365 group, who are community admins, one Microsoft Graph OData page at a time. Requires group_id from community.groupId, not the Viva Engage community ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Opaque continuation cursor returned by a previous call; omit it for the first page. |
| `expand` | string | No | Microsoft Graph $expand expression. Do not combine it with filter, search, or include_count. |
| `filter` | string | No | OData filter expression for owners. |
| `search` | string | No | Microsoft Graph search on displayName or description using quoted property:value syntax, for example "displayName:Alex". |
| `select` | string | No | Comma-separated directory object properties to return. |
| `group_id` | string | Yes | Microsoft 365 group ID from community.groupId. This is not the Viva Engage community ID. |
| `page_size` | integer | No | Maximum owners to request in this page. |
| `include_count` | boolean | No | Whether to include the total count as @odata.count. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Viva Engage Role Members

**Slug:** `MICROSOFT_VIVA_ENGAGE_LIST_ENGAGEMENT_ROLE_MEMBERS`

List users assigned to one predefined Viva Engage role and return the selected assignment properties. Include id for later removal and userId for identity correlation. Requires a role_id from List Viva Engage Roles and a native-mode Viva Engage network; legacy and external networks are unsupported.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Opaque continuation cursor returned by a previous call; omit it for the first page. |
| `filter` | string | No | OData equality filter on userId or engagementRoleMember id. |
| `select` | string | No | Comma-separated assignment properties to return, such as id,userId,createdDateTime. Include id for later removal and userId for identity correlation. |
| `role_id` | string | Yes | Predefined Viva Engage role ID returned by List Viva Engage Roles. This is the role ID, not a role-member assignment ID or Microsoft Entra user ID. |
| `include_count` | boolean | No | Set true to request the total role-assignment count as @odata.count. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Viva Engage Roles

**Slug:** `MICROSOFT_VIVA_ENGAGE_LIST_ENGAGEMENT_ROLES`

List the predefined administrative and corporate communication roles that can be assigned in Viva Engage, one Microsoft Graph page at a time. Custom roles cannot be created, and this API supports only native-mode Viva Engage networks with a work or school account.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Opaque continuation cursor returned by a previous call; omit it for the first page. |
| `filter` | string | No | OData equality filter on displayName or id, for example displayName eq 'Network Admin'. |
| `select` | string | No | Comma-separated role properties to return, such as id,displayName. |
| `page_size` | integer | No | Maximum roles to request in this page; Microsoft Graph may return fewer. |
| `include_count` | boolean | No | Set true to request the total role count as @odata.count. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List My Assigned Viva Engage Roles

**Slug:** `MICROSOFT_VIVA_ENGAGE_LIST_MY_ASSIGNED_ENGAGEMENT_ROLES`

List Viva Engage roles assigned to the signed-in work or school user, one Microsoft Graph page at a time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Opaque continuation cursor returned by a previous call; omit it for the first page. |
| `filter` | string | No | OData equality filter on displayName or id. |
| `select` | string | No | Comma-separated role properties to return, such as id,displayName. |
| `include_count` | boolean | No | Whether to request the total assigned-role count as @odata.count. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List User Assigned Viva Engage Roles

**Slug:** `MICROSOFT_VIVA_ENGAGE_LIST_USER_ASSIGNED_ENGAGEMENT_ROLES`

List Viva Engage roles assigned to a specified Microsoft Entra user, one Microsoft Graph page at a time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cursor` | string | No | Opaque continuation cursor returned by a previous call; omit it for the first page. |
| `filter` | string | No | OData equality filter on displayName or id. |
| `select` | string | No | Comma-separated role properties to return, such as id,displayName. |
| `user_id` | string | Yes | Target office user's Microsoft Entra ID. |
| `include_count` | boolean | No | Whether to request the total assigned-role count as @odata.count. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Remove Community Member

**Slug:** `MICROSOFT_VIVA_ENGAGE_REMOVE_COMMUNITY_MEMBER`

Remove one user from a Viva Engage community's associated Microsoft 365 group, revoking community membership without deleting the user object. Dynamic-group memberships cannot be changed with this action. The request always retains the safety-critical /$ref suffix.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | Yes | Microsoft Entra user or directory object ID whose community membership will be removed. The user object itself is not deleted. |
| `group_id` | string | Yes | Microsoft 365 group ID from the Viva Engage community's groupId property. This is not the community ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Remove Community Owner

**Slug:** `MICROSOFT_VIVA_ENGAGE_REMOVE_COMMUNITY_OWNER`

Remove a user's community admin status by removing the user as an owner of the Viva Engage community's associated Microsoft 365 group. This is destructive to admin access: verify another user owner remains because Microsoft Graph does not allow removal of the last user owner. The request always retains the safety-critical /$ref suffix.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `user_id` | string | Yes | Microsoft Entra user or directory object ID whose community admin status will be removed. The last user owner cannot be removed. |
| `group_id` | string | Yes | Microsoft 365 group ID from community.groupId. This is not the Viva Engage community ID. Verify another user owner remains before removal. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Remove Engagement Role Member

**Slug:** `MICROSOFT_VIVA_ENGAGE_REMOVE_ENGAGEMENT_ROLE_MEMBER`

Revoke one user's Viva Engage role assignment. This can remove administrative or corporate communication privileges: confirm the role and assignment before calling. Use the role_member_id returned by listing or assigning role members; Graph currently uses the target user ID as this member ID on assignment.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `role_id` | string | Yes | Predefined Viva Engage role ID for the assignment. |
| `role_member_id` | string | Yes | engagementRoleMember ID returned by listing or assigning role members. Graph currently uses the target user's Microsoft Entra ID as this member ID on the assignment route. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Community

**Slug:** `MICROSOFT_VIVA_ENGAGE_UPDATE_COMMUNITY`

Update a Viva Engage community's name, description, or privacy by community ID. Provide at least one field; omitted fields remain unchanged.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `privacy` | string ("public" | "private" | "unknownFutureValue") | No | New community visibility setting. Omit to leave it unchanged. At least one update field is required. |
| `description` | string | No | New community description. Omit to leave it unchanged. At least one update field is required. |
| `community_id` | string | Yes | Viva Engage community ID. Do not pass the associated Microsoft 365 group ID. |
| `display_name` | string | No | New community name. Omit to leave the name unchanged. At least one update field is required. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |