Skip to main content
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

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
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.

​
Permissions

Configure the permissions your agent needs to function in Microsoft Teams:
Read basic user profile information such as display name and email address.
This permission is required
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
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
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
Not required for 1:1 chat attachments

​
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.
You’ll need Global Administrator access to your organization’s Microsoft Teams Admin Center to grant admin consent during this process.
1

Download the App Manifest

Download the app manifest file (.zip) which contains all the configuration needed to install your agent in Microsoft Teams.
2

Open Teams Admin Center

Navigate to the Microsoft Teams Admin Center and go to Teams apps > Manage apps.
3

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.
4

Grant Admin Consent

Open your app, go to the Permissions tab, and click Grant admin consent to approve the required permissions for your organization.
5

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.
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.

​
Where to Use Your Agent

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

​
Commands

Your agent supports the following commands in personal chats:
The /new command is only available in personal (1:1) chats with your agent, and is not supported in group chats or channels.

​
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.
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.

​
How it works

Proactive messaging is built from two pieces:

Targets

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.

Actions

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.
The key rule to understand:
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.
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

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.
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.
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.

​
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.
1

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.
2

1:1 and group chats register with a command

In a personal or group chat where the app is installed, send:
Replace Housekeeping with a label that helps you recognize the destination later. The bot replies to confirm:
Registered “Housekeeping” as a Teams message target.
3

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.
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.
Targets come in three types: 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.
Add action is only available when the channel has an assigned agent and at least one active target.
1

Choose a target

Select the destination this action sends to. The target is fixed — the agent cannot change it later.
2

Name the action

A short, descriptive name (up to 128 characters), such as Notify Housekeeping. This is how the action appears to your agent.
3

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.
4

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.
5

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.
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.
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.

​
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.
1

Open the test dialog

Select Test on the target you want to check.
2

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.
3

Confirm delivery in Teams

Open the chat or channel in Microsoft Teams and verify the message arrived.
The 7,000-character limit applies to all proactive messages, including those your agent sends.

​
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.