> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vivi.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# MS Teams & Copilot

**MS Teams & Copilot** is a messaging-based communication channel that enables your agent to interact directly with users within Microsoft Teams. It supports natural text-based conversations, allowing your agent to handle inquiries, provide support, share information, or deliver interactive experiences through the Teams platform.

Once installed, your agent becomes available as a custom app in Microsoft Teams, where users can interact with it through direct messages, group chats, team channels, and Microsoft Copilot. The agent responds naturally to questions and requests, providing automated assistance wherever your team communicates within Teams.

***

## Setup and Installation

### Channel Configuration

<video autoPlay muted loop playsInline className="w-full aspect-video rounded-xl" src="https://mintcdn.com/ksg-ea85c748/w0M6PxooWCiNQAbk/videos/vivi-teams.mp4?fit=max&auto=format&n=w0M6PxooWCiNQAbk&q=85&s=2477e00f6081db991df46af001f21f44" data-path="videos/vivi-teams.mp4" />

When creating a Microsoft Teams channel in VIVI, you'll configure the following settings:

* **Channel Name**: An internal identifier for your channel within VIVI
* **Display Name**: The name that will be displayed to users in Microsoft Teams and Copilot
* **Description**: A short description shown to users in Microsoft Teams that explains your agent's purpose (up to 80 characters)
* **Long Description**: Detailed description of your app (up to 400 characters)
* **Welcome Message**: An optional greeting shown when users start a conversation with your agent
* **Logo URL**: A custom logo image that represents your agent in Teams

<Tip>
  You can update these settings anytime by revisiting the channel's Settings after creation. Changes made after upload to MS Teams Admin Center will require re-uploading the app package to take effect.
</Tip>

#### Permissions

Configure the permissions your agent needs to function in Microsoft Teams:

<AccordionGroup>
  <Accordion title="User.Read" icon="user">
    Read basic user profile information such as display name and email address.

    <Danger>
      This permission is required
    </Danger>
  </Accordion>

  <Accordion title="ChannelMessage.Read.All" icon="comments">
    Enables message and attachment reading in Team channels:

    * **Thread context**: Access root message + up to 20 replies when mentioned
    * **File attachments**: Access attachment information when users share files in channels
  </Accordion>

  <Accordion title="ChatMessage.Read.All" icon="message">
    Enables message and attachment reading in group chats:

    * **Chat context**: Access last 20 messages when mentioned
    * **File attachments**: Access attachment information when users share files in chats
  </Accordion>

  <Accordion title="Files.Read.All" icon="file">
    Download and process file attachments from group chats and channels:

    * Download files from SharePoint (for channels) or OneDrive (for chats)
    * Process pasted screenshots in group conversations
    * File uploads are secured using SAS token generation for safe blob storage handling

    <Info>
      Not required for 1:1 chat attachments
    </Info>
  </Accordion>
</AccordionGroup>

### Installation Steps

After creating your channel, there will be a brief authentication period. Once authentication is complete, you'll receive a confirmation email indicating your channel is ready to install.

To install your agent in Microsoft Teams, follow the steps below.

<Note>
  You'll need Global Administrator access to your organization's Microsoft Teams Admin Center to grant admin consent during this process.
</Note>

<Steps>
  <Step title="Download the App Manifest">
    Download the app manifest file (.zip) which contains all the configuration needed to install your agent in Microsoft Teams.
  </Step>

  <Step title="Open Teams Admin Center">
    Navigate to the Microsoft Teams Admin Center and go to **Teams apps > Manage apps**.
  </Step>

  <Step title="Upload the App Package">
    Click the **Actions** dropdown and select **Upload new app**, then choose the manifest file you downloaded. This will register your bot as a custom app in your organization.
  </Step>

  <Step title="Grant Admin Consent">
    Open your app, go to the **Permissions** tab, and click **Grant admin consent** to approve the required permissions for your organization.
  </Step>

  <Step title="Connect and Test Your Channel">
    Before testing, ensure this channel is connected to an agent in the Agents section of VIVI. Then search for your app in Microsoft Teams, start a conversation, and verify it's working correctly.

    <Warning>
      Once installation is complete, your agent becomes **discoverable by anyone in your organization** through the Teams app directory. Verify Teams app permissions with your MS Teams Admin and test thoroughly before finishing installation. For a controlled rollout, you can share the agent's name only with specific testers, though anyone can still find it by searching for it by name.
    </Warning>
  </Step>
</Steps>

***

## Where to Use Your Agent

<video autoPlay muted loop playsInline className="w-full aspect-video rounded-xl" src="https://mintcdn.com/ksg-ea85c748/gv3Q9bcmU4Xo-lRD/videos/vivi-mscopilot.mp4?fit=max&auto=format&n=gv3Q9bcmU4Xo-lRD&q=85&s=8114e7d7281086d339c22746c2e232f9" data-path="videos/vivi-mscopilot.mp4" />

Your agent can be accessed in multiple locations within Microsoft Teams and Copilot. Each location offers different interaction patterns and capabilities:

| Location                 | How to Interact                                                                                                  | Interaction Behavior                                                                                                                                         | Context Awareness                                               | File Attachment Support                                         |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------- |
| **Microsoft Copilot**    | Message your agent directly via [portal.office.com](https://portal.office.com) or the Copilot interface in Teams | Responds automatically to all messages without requiring @ mention                                                                                           | Full conversation history                                       | Not supported (known Copilot limitation)                        |
| **Personal Chat (1:1)**  | Open a direct chat with your agent                                                                               | Responds automatically to all messages without requiring @ mention                                                                                           | Full conversation history                                       | Supported via "Attach cloud files" or "Upload from this device" |
| **1:1 Chat with Others** | Open a chat with another person, then mention **@AgentName** to add your agent                                   | Must be mentioned with **@AgentName** to respond; will not reply automatically                                                                               | Access to approximately the last 20 messages for thread context | Supported via "Attach cloud files" or "Upload from this device" |
| **Group Chats**          | Add agent to group chat by using **@AgentName**                                                                  | Must be mentioned with **@AgentName** to respond; will not reply automatically. The agent will send its welcome message whenever someone new joins the chat. | Access to approximately the last 20 messages for thread context | Supported via "Attach cloud files" or "Upload from this device" |
| **Team Channels**        | Mention your agent using **@AgentName** in a channel thread                                                      | Must be mentioned with **@AgentName** to respond within channel threads                                                                                      | Access to the specific channel thread it is mentioned on        | Supported via "Attach cloud files" or "Upload from this device" |

### Commands

Your agent supports the following commands in personal chats:

| Command | Description                                                               |
| ------- | ------------------------------------------------------------------------- |
| `/new`  | Clears your conversation history, starting a fresh session with the agent |

<Tip>
  The `/new` command is only available in personal (1:1) chats with your agent, and is not supported in group chats or channels.
</Tip>

***

## Proactive Messaging

By default, a Microsoft Teams agent is **reactive**: it answers when someone messages it. Proactive Teams messages flip that around — your agent can **start** a Teams conversation on its own, delivering a notification, alert, or hand-off to a pre-approved destination.

For example, a front-desk agent can notify the Housekeeping channel when a guest requests fresh towels, or a support agent can post to an on-call chat when it detects an outage.

A proactive message can be sent in four ways:

* **By your agent**, mid-conversation, when it decides an action is warranted.
* **From the portal**, using the **Test** button while you set things up.
* **From a scheduled task**, to send recurring or time-based messages.
* **From the API**, using the Trigger Conversations endpoint (for developers).

This section covers the first two. Scheduled tasks and the API are covered in their own sections.

<Note>
  Proactive Teams messages may need to be enabled for your workspace. If you don't see the **Proactive Teams messages** section on your channel, contact your VIVI representative.
</Note>

### How it works

Proactive messaging is built from two pieces:

<CardGroup cols={2}>
  <Card title="Targets" icon="location-dot">
    An approved destination the channel is allowed to message — a 1:1 chat, a group chat, or a channel inside a Team. You register targets once.
  </Card>

  <Card title="Actions" icon="paper-plane">
    A named instruction that tells your agent *when* to send a message and *what* to include. Each action is bound to a single target and becomes a tool your agent can use.
  </Card>
</CardGroup>

The key rule to understand:

<Warning>
  Your agent can only send proactive messages to a conversation the bot is **already part of**. That's why every destination has to be registered as a target first — by installing the app there or running the `/register` command. The bot cannot message a person or channel it has never interacted with.
</Warning>

An action always sends to a **fixed** target. The agent decides *whether* to send and writes the message text, but it can never choose or invent a recipient — so a proactive message can only ever reach a destination you've explicitly approved.

### Before you start

<AccordionGroup>
  <Accordion title="An active MS Teams channel" icon="microsoft">
    You need a fully set-up MS Teams & Copilot channel (see above) — the app registered, credentials configured, and the channel active. The **Proactive Teams messages** section stays disabled until the channel's app credentials are ready.
  </Accordion>

  <Accordion title="The app installed at each destination" icon="download">
    Because the bot can only message conversations it already belongs to, the Teams app must be installed in each chat or Team channel you want to reach. Installation is what lets VIVI register the destination as a target.
  </Accordion>

  <Accordion title="An agent assigned to the channel" icon="robot">
    To create actions, the channel must be connected to an agent. Without an assigned agent you can still register and test targets, but the **Add action** button stays disabled.
  </Accordion>
</AccordionGroup>

### Step 1 — Register a target

Targets are registered from **inside Microsoft Teams**, not from the portal. How you register depends on where you want the agent to send messages.

<Steps>
  <Step title="Team channels register automatically">
    When the Teams app is added to a channel inside a Team, that channel is registered as a target automatically. No command needed — it appears in your **Targets** table shortly after installation.
  </Step>

  <Step title="1:1 and group chats register with a command">
    In a personal or group chat where the app is installed, send:

    ```text theme={null}
    /register Housekeeping
    ```

    Replace `Housekeeping` with a label that helps you recognize the destination later. The bot replies to confirm:

    > Registered "Housekeeping" as a Teams message target.
  </Step>

  <Step title="Confirm in the portal">
    Open your MS Teams channel in VIVI and expand **Proactive Teams messages**. The new target appears in the **Targets** table with its name, type, and status.
  </Step>
</Steps>

<Note>
  **Already had the app installed before proactive messaging was enabled?** Existing chats and channels don't appear as targets automatically — a destination is only registered at the moment the app is installed or when you run `/register`. To register destinations that predate the feature:

  * **1:1 and group chats** — no reinstall needed. Just send `/register <label>` in the existing chat and the target is created immediately.
  * **Team channels** — because a channel is only registered when the app is *added*, **remove the app from the channel and add it again**. Re-adding it triggers registration, and the channel then shows up in your **Targets** table.

  Sending an ordinary message won't register an older destination — only a fresh install or the `/register` command will.
</Note>

Targets come in three types:

| Type           | Where it points           | How it's registered                                 |
| -------------- | ------------------------- | --------------------------------------------------- |
| **Personal**   | A 1:1 chat with a user    | `/register <label>` in that chat                    |
| **Group chat** | A multi-person group chat | `/register <label>` in that chat                    |
| **Channel**    | A channel inside a Team   | Automatically, when the app is added to the channel |

Each target shows a **status**:

* **Active** — ready to receive proactive messages.
* **Unavailable** — the bot can no longer reach the destination (for example, the app was uninstalled or its permissions were revoked). A target flips to this state automatically after a failed send. Re-install the app or re-run `/register` to restore it.

### Step 2 — Create an action

An action turns a target into something your agent can actually use. Open the **Proactive Teams messages** section, go to the **Agent message actions** table, and select **Add action**.

<Note>
  **Add action** is only available when the channel has an assigned agent and at least one **active** target.
</Note>

<Steps>
  <Step title="Choose a target">
    Select the destination this action sends to. The target is fixed — the agent cannot change it later.
  </Step>

  <Step title="Name the action">
    A short, descriptive name (up to 128 characters), such as `Notify Housekeeping`. This is how the action appears to your agent.
  </Step>

  <Step title="Write the trigger description">
    Describe *when* the agent should use this action (up to 4,000 characters). This is the most important field — the agent relies on it to decide whether to send. Be specific:

    > Use when a guest asks for housekeeping service such as fresh towels, extra pillows, or room cleaning. Include the room number and the request.
  </Step>

  <Step title="Add message guidance (optional)">
    Optionally describe *what* the message should contain (up to 4,000 characters) — tone, required details, or a format to follow. The agent writes the final text within these guidelines.
  </Step>

  <Step title="Enable the action">
    Leave **Action enabled** on to make it available to your agent immediately. Turn it off to keep the action defined but inactive.
  </Step>
</Steps>

Once saved and enabled, the action becomes available to the assigned agent. During a conversation the agent can decide, based on your trigger description, to fire the action and send its message to the target.

<Tip>
  Trigger descriptions are instructions to an AI, not keyword filters. Write them the way you'd brief a colleague: describe the situation and the intent, not just words to match. Clear, specific triggers produce far more reliable behavior than vague ones.
</Tip>

### Testing a target

Before you rely on an action, confirm the destination actually receives messages. In the **Targets** table, use the **Test** action on a row to send an ad-hoc message.

<Steps>
  <Step title="Open the test dialog">
    Select **Test** on the target you want to check.
  </Step>

  <Step title="Write and send a test message">
    Enter any message (up to 7,000 characters) and send. It's delivered to the destination exactly as a proactive message would be.
  </Step>

  <Step title="Confirm delivery in Teams">
    Open the chat or channel in Microsoft Teams and verify the message arrived.
  </Step>
</Steps>

<Info>
  The 7,000-character limit applies to all proactive messages, including those your agent sends.
</Info>

### Managing targets and actions

* **Rename a target** — use the **Rename** action to update a target's display name. This only changes the label; the underlying destination stays the same.
* **Delete a target** — deleting a target also removes every action bound to it. Any agent tools created from those actions stop working.
* **Edit or disable an action** — update an action's target, name, trigger description, or guidance at any time, or toggle **Action enabled** off to pause it without deleting it.
* **Watch for `Unavailable` targets** — if a target goes unavailable, its actions can't deliver. Re-install the app or re-run `/register` at the destination to bring it back.

***

## Best Practices

* Set appropriate expectations in your agent's prompt for **what it can and cannot help with** in the Teams environment.
* Use the **description field** to help users understand your agent's capabilities before they start a conversation.
* Create a **welcoming and informative welcome message** that sets the tone and provides guidance on how to interact with your agent.
* **Use /new command** on Teams after making changes to your agent on VIVI to ensure your conversation has the latest agent configuration.
* **Write triggers like briefings.** Spell out the situation, the intent, and any must-include details for proactive message actions. Specific triggers ("when a guest requests housekeeping, include the room number") behave far more reliably than vague ones ("when relevant").
* **One action per outcome.** Prefer several focused proactive message actions over a single catch-all — it's easier for the agent to choose correctly and easier for you to reason about.
* **Keep targets tidy.** Remove proactive message targets you no longer use so the list stays meaningful, and give them clear labels at registration time.
* **Test before you trust.** Send a test message to every target after registering it, and again if you suspect the app's install or permissions changed.
* **Set expectations in guidance.** Use message guidance to control tone and required detail so proactive messages read consistently, whoever the agent is talking to.