Agent Microsoft Teams Integration

Run conversational agents in Microsoft Teams with conversations tracked in your Elementum app

Overview

Conversational agents can interact with users in Microsoft Teams. Messages stay in Teams; conversation data is stored and managed in your Elementum app according to your routes and permissions.

Teams conversations are one-to-one with the bot (not channel-based). You configure routes in Organization Settings to choose which app and agent handle Teams chats and how user fields map to records.

---

Prerequisites

Organization admin access is required for the initial Teams app connection. Ensure you have proper permissions before starting.

You need:

• Organization admin access — to connect the Elementum Teams app to Microsoft Teams
• Active agent — at least one agent in your app with training appropriate for Teams
• Microsoft Teams access — permission to install or use apps in your tenant, per your organization’s policies

---

Permissions & Data Access

The Elementum Intelligence Teams app requests minimal permissions so the bot can chat with users and connect to Elementum.

Required Permissions

Personal Chat Access

What it means: The app can be used in 1:1 chats with individual users

Why we need it: To provide direct assistance to team members

What we DON’T access: Team channels, group chats, or organization-wide data

Notifications

What it means: The app can send notifications to users’ devices

Why we need it: To deliver responses and updates

Your control: Users can manage notification settings in Teams

Basic User Information

What it means: When you interact with the bot, we receive:

• Your display name
• Your Teams user ID
• Your email address
• Your organization’s tenant ID

Why we need it: To identify you and connect your Teams identity to your Elementum account

Note: This is automatic—Microsoft Teams provides this information to all bots

Network Access to Elementum Services

What it means: The app connects to *.elementum.io domains

Why we need it: To communicate with your Elementum backend and return responses

Security: All connections use encrypted HTTPS

What We Don’t Access

The Elementum Teams app does not have access to:

• Team or channel conversations
• Files or documents
• Calendar or email
• Call or video data
• Contacts beyond the current conversation
• Any Microsoft Graph data without explicit authentication

---

Setting Up Microsoft Teams Integration

1. Install Microsoft Teams App

   Install the Elementum Teams app in your Microsoft Teams environment.

   This step requires uploading a custom app package to Microsoft Teams. Your organization’s Teams administrator must have permissions to upload custom apps.

   Installation Process:

   1. Receive App Package: Your Elementum contact will provide a ZIP file containing the Teams app package
   2. Upload to Microsoft Teams: Follow Microsoft’s documentation to upload the custom app to your Teams environment:
      • Upload an app package to Microsoft Teams
      • You can upload the app for yourself, your team, or your entire organization
   3. App Availability: Once uploaded, the Elementum bot will be available in your Teams environment
   4. Receive Verification Code: When you first open the Elementum app in Teams, you will receive a verification code as the first message. Copy this code—you will need it in the next step.

   Keep the verification code handy. You’ll enter it in Elementum to complete the connection between your Teams environment and Elementum.

2. Connect and Configure Elementum Teams App

   Organization administrators complete the connection between Elementum and Microsoft Teams using the verification code from the previous step:

   How to Access:

   1. Navigate to Organization Settings → Integrations → Microsoft Teams → Configuration

   Configuration Process:

   1. Select an AI Service from the dropdown
      • This determines which model powers agent responses in Teams
      • If no AI services are available, use the AI Services link to set up a new service first (see AI Services)
   2. Configure the Default Conversation Timeout (e.g., 15 minutes)
      • This sets how long conversations remain active before automatically closing
      • After timeout, users receive a warning before the conversation closes
   3. Click Save to apply the configuration
   4. Once saved, the Verification Code field will appear
   5. Enter the verification code you received in Teams when you installed the app
   6. Click Verify to validate the connection
   7. Once verified, click Save to complete the setup
   8. Verify the connection status shows as Active on the page

   This step only needs to be completed once per organization by an administrator.

3. Create Agent Routes

   Routes determine which agents handle Teams conversations and how user data is captured:

   How to Access:

   1. In the Microsoft Teams integration page, locate the Routes section
   2. Click Create Route to open the route configuration dialog

   Basic Route Settings

   Fill in:

   • App Selection — The app that will receive and manage conversations
   • Route Name — A descriptive name (e.g., “Support Team Route”)
   • Agent Assignment — The agent that will handle conversations for this route
   • Route Responsibility — Short description of what this route handles (e.g., “Route conversations from Teams”)

   Field Mapping

   Configure how user information from Teams is captured in your app records:

   Available Source Fields

   • Country: User’s country information
   • Email: Teams user email address
   • First Name: User’s first name from Teams profile
   • Id: Teams user ID
   • Last Name: User’s last name from Teams profile
   • Locale: User’s locale/language setting
   • Name: Full display name
   • Platform: Always “Microsoft Teams”
   • Timezone: User’s timezone setting

   Mapping Process

   1. Source Field: Select which Teams user data to capture
   2. Target Field: Choose where to store this data in your app
   3. Add Field Mapping: Click to add additional field mappings as needed
   4. Map essential fields like Email, First Name, and Last Name for proper user identification

   Start with one route unless you have a clear need for multiple routes (for example, different apps or agents for different teams). Multiple routes add complexity; the platform works most reliably with a single primary route.

   Configuration Steps:

   1. Fill in Route Name and Route Responsibility
   2. Select the Agent that will handle Teams conversations
   3. Configure field mappings to capture relevant user information
   4. Click Save to create the route

---

Using Microsoft Teams Integration

Starting Conversations

After an administrator has installed the app and completed integration setup, users can open the Elementum app in Teams:

1. Find the App: Search for “Elementum” in Microsoft Teams apps or your organization’s app catalog
2. Add the App: Install the Elementum app if it is not already installed
3. Start Chatting: Open the app and send a message to begin interacting with your agent
4. Chat as you would with any other Teams contact

During a conversation:

• Messages are processed by the agent assigned on the route
• Responses appear in Teams in real time
• Context is maintained for the active session
• User fields are populated according to your route mappings

Conversation Behavior and Records

When a user starts a conversation in Teams, the system creates a record in the app selected on the route, captures mapped user information, associates the conversation with that record, and tracks the interaction for workflows.

Session rules:

• Single active conversation: Only one active conversation per user at a time
• Timeout: Conversations close after the configured timeout; users get a warning before closure
• After timeout: New messages start a new conversation and new record

---

Agent Tools for Teams

You configure agent tools—including endConversation—while you build and configure the agent. The behavior below applies to Teams.

EndConversation Tool

Agents can use the endConversation tool to close a Teams session when the interaction is complete.

Purpose:

• Allows agents to end conversations when appropriate
• Provides clear closure for support-style interactions
• Avoids leaving sessions open when no longer needed

Train your agents on when and how to use the endConversation tool so users are not left in ambiguous session states.

Example Training Instructions

When you have fully resolved the user's question or completed the requested task, 
use the endConversation tool to close the session. Always provide a brief summary 
of what was accomplished before ending the conversation.

---

Managing Teams Integration

Viewing and Editing Routes

In the Routes section of the Microsoft Teams integration settings you can see all routes, which agent each route uses, and edit mappings or assignments. Use the Edit action (pencil icon) on a route to change configuration, then Save.

---

Integration with Workflows

Agent Conversation Ended Trigger

When a conversation ends (timeout, endConversation, or equivalent), you can run automations with the Agent Conversation Ended trigger. The trigger exposes data such as the transcript, captured user fields, timing, and agent messages—similar to other agent channels. Use it to create tasks, send email, update records, or call other actions your organization needs.

Add this to an automation: In your app, open Automations and create an automation whose trigger is Agent Conversation Ended. Set Conversation Type to Teams when you only want Microsoft Teams conversations. For trigger options, variables, and examples, see Agent Conversation Ended in the triggers reference.

Nothing is sent to Teams automatically when a conversation ends unless you add an automation that posts to Teams (for example Send Message to Teams).

Viewing Teams Conversations

After a conversation ends:

1. Open the record that was created for the session
2. Use the Chat/Conversation area in record details
3. Confirm the conversation type is Microsoft Teams and review the transcript and metadata

---

Troubleshooting

Bot Not Appearing in Teams

• Verify your Teams administrator has uploaded the Elementum app package (ZIP file) to your Teams environment
• Ensure users have permission to install apps in Teams
• Contact your Teams administrator if app installation is restricted or if the app package has not been uploaded yet

Connection Not Working

• Confirm that you entered the verification code correctly in Organization Settings → Integrations → Microsoft Teams → Configuration
• The verification code is provided as the first message when you open the Elementum app in Teams
• Check that the integration status shows as Active in your organization settings

Agent Not Responding

• Verify the agent is configured and active
• Check that the AI service is available
• Review agent training for Teams-appropriate tone and closure behavior
• Ensure the route is saved and points at the correct app and agent

Field Mapping Not Working

• Verify source fields map to existing target fields with compatible types
• Confirm the target app is accessible to the integration

Conversations Not Creating Records

• Verify the route includes the correct app selection
• Check that field mappings are saved
• Ensure the target app allows record creation for the integration identity

Timeout and Training Tips

• Adjust Default Conversation Timeout to match typical interaction length (shorter for high volume, longer for complex support)
• Prefer concise, workplace-appropriate replies; train agents when to use endConversation

---

Security and Compliance

• User Information: Teams user data follows your organization’s retention and access policies in Elementum
• Conversation Storage: Interactions are stored in your Elementum environment with your usual access controls
• Microsoft Teams: App installation follows your tenant’s policies; the initial org connection requires an administrator

---

Best Practices

• Routes: Prefer one primary route until you need separate apps or agents for different audiences
• Timeouts: Revisit timeout values after you see real conversation patterns
• Automations: Use Agent Conversation Ended for follow-up work (tasks, notifications, CRM updates)—include a Teams notification only where it helps your process
• Training: Align agent tone with your organization; use endConversation when the thread is done