Microsoft Teams
================

Connects an agent to a Microsoft Teams workspace via the Bot Framework REST API. Supports two-way conversations with Teams users and proactive outbound notifications to Teams channels.

* **Supported agents:** Agentic Flow, Chatbot
* **Route types:** Conversation, Notification

Route Overview
--------------

.. list-table::
   :widths: 20 20 60
   :header-rows: 1

   * - Route
     - Direction
     - Use when
   * - Conversation
     - Bidirectional
     - Receiving messages from Teams users and sending replies
   * - Notification
     - Outbound only
     - Sending proactive messages to a Teams channel via Incoming Webhook connector

Before You Start
----------------

**Required for both routes:**

1. In the **Azure Portal** (`portal.azure.com <https://portal.azure.com>`_), go to **Azure Active Directory → App Registrations → New Registration**.
2. Name the app (e.g. ``Neo-TeamsBot``). Set supported account types to **Multi-tenant**.
3. Note the **Application (client) ID** — this is your Bot App ID.
4. Under **Certificates & Secrets**, create a new **Client Secret**. Copy the value immediately.
5. Note the **Directory (tenant) ID** from the app overview.
6. Create a **Bot Service** in **Azure Bot Services** and set the **Messaging Endpoint** to the Neo webhook URL. The webhook URL is shown in Neo after you create the channel.
7. In Azure Bot Services, under **Channels**, enable the **Microsoft Teams** channel.

**For the Notification route only:**

In Microsoft Teams, create an **Incoming Webhook connector** for the target channel and copy the generated Webhook URL.

**For optional SharePoint/OneDrive file access (SSO):**

Create a separate Azure App Registration for delegated permissions. Required Microsoft Graph scopes: ``Files.ReadWrite.All``, ``Sites.Read.All``, ``User.Read``, ``offline_access``, ``openid``, ``profile``. A **Tenant Administrator must grant admin consent** for these scopes before any user can complete the SSO login.

Your agent must be published with an active version. The Channel Gateway MCP must be enabled:

* **Global:** Admin Panel → MCP Servers → Channel Gateway → Enable and Deploy
* **Workspace:** Workspace Settings → MCP → Channel Gateway → toggle ON

Conversation Route
------------------

**Credentials**

* **Bot App ID** — Application (client) ID of the Azure App Registration. Required.
* **Bot App Secret** — Client secret for bot token acquisition. Required.
* **Bot App Tenant ID** — Directory (tenant) ID. Required.

Optional SSO credentials (only if SharePoint/OneDrive access is needed):

* **SSO Client ID** — Client ID of the separate SSO App Registration.
* **SSO Client Secret** — Secret for the SSO app.
* **SSO Tenant ID** — Tenant for the SSO app (defaults to Bot App Tenant ID).

After entering SSO credentials, click **Login with Microsoft** to complete the OAuth consent flow. A Tenant Administrator must have granted admin consent before this will succeed for non-admin users.

**Route Settings**

* **Description** — Optional label for this channel instance.
* **Purpose** — Optional note on when the agent should use this channel.
* **Session Expiry (hours)** — Idle timeout before a session resets. Default: 4. Range: 0.01–48.

Notification Route
------------------

**Credentials**

* **Webhook URL** — The Incoming Webhook connector URL from Microsoft Teams. Required.

**Route Settings**

* **Description** — Optional label for this channel instance.
* **Purpose** — Optional note on when the agent should use this channel.
* **Max Retries** — Number of retry attempts if delivery fails. Default: 3. Range: 0–10.
* **Retry Delay (seconds)** — Delay between retries. Default: 60. Minimum: 10.

Channel Output Node (Agentic Flow)
-----------------------------------

For Agentic Flow agents using the Conversation or Notification route, add a **Channel Output** node to the flow and enable **Channel Delivery**. Configure the ``delivery_targets`` table to select the Teams route, event type (``message`` or ``adaptive_card``), recipients, and invocation mode (``automatic`` or ``agentic``).

See :doc:`/9_agentic_flow_builder/building_blocks` for details on the Channel Output node.

Troubleshooting
---------------

* **Bot not responding to messages** — Verify the messaging endpoint in Azure Bot Services matches the Neo webhook URL. Confirm the Microsoft Teams channel is enabled in Azure Bot Services.
* **SSO login button does nothing** — Save the credential before clicking Login with Microsoft. Ensure the redirect URI in the SSO App Registration matches your Neo domain. Check that admin consent has been granted.
* **Messages not reaching the agent** — Confirm the agent is published and the channel toggle is ON. Verify Channel Gateway MCP is enabled at both levels.
* **Notification webhook failing** — Test the Incoming Webhook URL directly with a POST request. Recreate the connector in Teams if the URL has expired.