Microsoft Teams Integration with SmythOS

Want to embed your business processes directly into your team's collaboration hub? Connect Microsoft Teams to SmythOS and empower your agents to send messages, create chats, and automate communication workflows.

TL;DR

Securely link your Microsoft 365 account to SmythOS by registering an application in Microsoft Entra to get a Client ID and Secret. Then, use our suite of components to automate interactions with your Teams channels and chats.

List of Microsoft Teams Components

Quickly compare Teams components by what they do and their key I/O. Click any component name to jump directly to its detailed guide.

Component	Action	What it Does	Inputs	Key Outputs	Use Case
Send Message in Channel	Write	Posts a message to a specific channel within a Team.	required team_id, channel_id, content	id, etag	Posting automated deployment status updates.
Send Message in Chat	Write	Sends a message to a one-on-one or group chat.	required chat_id, content	id, chatId	Sending a direct notification to a user.
Send Reply in Channel	Write	Replies to a specific message thread in a channel.	required team_id, channel_id, message_id, content	id, replyToId	Continuing a conversation started by an alert.
Create Chat	Write	Creates a new one-on-one or group chat with specified members.	required userId, Body	id, webUrl	Starting a new conversation for a project team.
List Messages in Chat	Read	Retrieves the message history from a specific chat.	required chat_id	values, count	Auditing a conversation or providing context to an LLM.
List Chats	Read	Retrieves a list of all chats a user is a member of.	required userId	values, data_count	Finding a specific chat ID to send a message to.
Get Chat	Read	Retrieves metadata and properties for a specific chat.	required chat_id	id, chatType	Checking if a chat is a group or one-on-one.
Get Message in Chat	Read	Retrieves a single, specific message from a chat.	required chat_id, message_id	content	Getting the text of a message that triggered a workflow.
Add Chat Member	Write	Adds a new user to an existing group chat.	required chat_id, Body	location	Adding a new team member to a project chat.

INFO

Why Integrate Microsoft Teams with Your Agent?

Microsoft Teams is the central nervous system for many organizations. Integrating it with SmythOS allows you to build powerful automations that live where your team works.

• Automated Alerts & Notifications: Create agents that monitor your infrastructure, applications, or other services and post real-time alerts to a specific Teams channel, ensuring rapid response.
• Streamline Business Processes: Use agents to bridge the gap between systems. For example, when a new high-priority ticket is created in your support system, an agent can automatically create a new chat with the on-call engineers.
• Interactive Agents: Build agents that can receive commands or data from Teams messages (requires a webhook setup), process the information, and post a result back into the chat.
• Centralized Reporting: Schedule agents to gather data from various sources (e.g., Google Analytics, GitHub, databases) and post a daily or weekly summary report directly into a team's channel.

Prerequisites

Before you begin, please ensure you have the following:

• An active SmythOS account. (Sign up here).
• A Microsoft 365 Account with administrative permissions to register applications in Microsoft Entra.
• Your application's Client ID and Client Secret from the Microsoft Entra portal.

Getting Started With Microsoft Teams

The connection is handled via OAuth 2.0, which requires you to register an application in Microsoft Entra to get your credentials. This is a one-time setup.

Step 1: Register an Application in Microsoft Entra

1. Navigate to the Microsoft Entra Portal.
2. Go to Azure Active Directory > App registrations and click + New registration.
3. Configure your application:
   • Name: Give it a descriptive name (e.g., "SmythOS Teams Integration").
   • Supported account types: Choose the option that best fits your organization's needs.
   • Redirect URI: Select Web and enter https://app.smythos.com/oauth/oauth2/callback.
4. Click Register.

Step 2: Get Client ID and Client Secret

1. Client ID: From your app's Overview page, copy the Application (client) ID.
2. Client Secret:
   • Navigate to Certificates & secrets > Client secrets.
   • Click + New client secret, add a description, and choose an expiration period.
   • Click Add. Immediately copy the Value of the secret. It will not be shown again.

Step 3: Configure API Permissions

1. In your app registration, go to the API permissions page.
2. Click + Add a permission, select Microsoft Graph, and choose Delegated permissions.
3. Add the necessary permissions. Common permissions for these components include:
   • Chat.Read, Chat.ReadWrite
   • ChannelMessage.Send
   • Team.ReadBasic.All
   • offline_access (essential for long-running automations)
4. After adding permissions, click the Grant admin consent for [Your Organization] button.

Step 4: Configure and Authenticate in SmythOS

1. Store Credentials: Add your Client ID and Client Secret to the SmythOS Vault for security.
2. Add a Component: Drag any Microsoft Teams component onto your agent graph.
3. Authenticate: Open the component's Settings, select your credentials from the Vault, and click the Authenticate button. You will be redirected to Microsoft to sign in and grant consent.

OAuth and Permissions

This OAuth 2.0 flow securely connects your Microsoft account. If you encounter permission errors later, ensure you have granted the correct API permissions in Microsoft Entra and provided admin consent.

Which Microsoft Teams Component Should I Use?

If you need to…	Target	Use this Component	Why this one?
Send a public alert to a project team	A team channel	Send Message in Channel	The standard way to post in a channel where all team members can see.
Notify a specific user or small group	A one-on-one or group chat	Send Message in Chat	Use this for direct, private communication instead of a public channel.
Start a new conversation about a specific issue	A list of user IDs	Create Chat	Perfect for dynamically creating group chats for incident response or new projects.
Get the history of a conversation	A chat_id	List Messages in Chat	Retrieves the messages in a chat, useful for providing context to an AI.
Find a chat with a specific group or person	A userId	List Chats	The best way to get a list of all chats to find the correct chat_id.
Add a new person to an ongoing discussion	A chat_id and a user's ID	Add Chat Member	The correct way to invite someone into an existing group chat.

Component Details

This section provides detailed information for each Microsoft Teams component.

Send Message in Channel

Posts a message to a specific channel within a Team.

Inputs

Field	Type	Required	Notes
team_id	string	Yes	The unique ID of the Team.
channel_id	string	Yes	The unique ID of the channel within the team.
content	string	Yes	The message content. Supports HTML.

Outputs

Field	Type	Description
id	string	The unique ID of the message that was sent.
etag	string	The ETag of the message.
channelIdentity	object	Contains the teamId and channelId.

Use Case

A CI/CD pipeline agent posts a message to the #deployments channel: Build 1.2.3 successfully deployed to production.

Send Message in Chat

Sends a message to an existing one-on-one or group chat.

Inputs

Field	Type	Required	Notes
chat_id	string	Yes	The unique ID of the chat.
content	string	Yes	The message content. Supports HTML.

Outputs

Field	Type	Description
id	string	The unique ID of the message that was sent.
chatId	string	The ID of the chat the message was sent to.

Use Case

An agent detects a critical error and sends a direct message to the on-call engineer's chat: URGENT: Database server is unresponsive.

Send Reply in Channel

Sends a reply to a specific message thread in a channel.

Inputs

Field	Type	Required	Notes
team_id	string	Yes	The ID of the team.
channel_id	string	Yes	The ID of the channel.
message_id	string	Yes	The ID of the message to reply to.
content	string	Yes	The content of the reply.

Outputs

Field	Type	Description
id	string	The ID of the sent reply message.
replyToId	string	The ID of the message that was replied to.

Use Case

An agent posts an alert. When the issue is resolved, it finds the original alert message and uses this component to post a "Resolved" message in the same thread.

Create Chat

Creates a new chat conversation.

Component-Specific Settings

• Body: A JSON editor where you define the chat type and members. For a group chat, it would look like: {"chatType": "group", "members": [{"@odata.type": "#microsoft.graph.aadUserConversationMember", "roles": ["owner"], "[email protected]": "https://graph.microsoft.com/v1.0/users('USER_ID_1')"}, ...]}

Inputs

Field	Type	Required	Notes
userId	string	Yes	The ID of the user creating the chat (typically the authenticated user).

Outputs

Field	Type	Description
id	string	The unique ID of the newly created chat.
webUrl	string	The URL to open the chat in the Teams client.

Use Case

When a new high-priority sales lead comes in, an agent creates a new group chat with the assigned sales representative and their manager to coordinate a strategy.

List Messages in Chat

Retrieves the message history from a specific one-on-one or group chat.

Inputs

Field	Type	Required	Notes
chat_id	string	Yes	The unique ID of the chat from which to retrieve messages.

Outputs

Field	Type	Description
values	array	An array of message objects from the chat.
count	integer	The number of messages retrieved in the current request.
nextLink	string	A URL to retrieve the next page of messages, if available.

Use Case

An agent retrieves the last 10 messages from a support chat to provide context to an LLM for generating a summary or a suggested reply.

List Chats

Retrieves the list of chats a user is part of in Microsoft Teams.

INFO

This component uses the OAuth 2.0 flow detailed in the Getting Started section.

Inputs

Field	Type	Required	Notes
userId	string	Yes	The ID of the user whose chats are being listed (use me for the authenticated user).

Outputs

Field	Type	Description
values	array	A list of chat objects, each containing details like id, topic, and chatType.
data_count	integer	The count of chat objects returned in the current response.
Response	object	The full, raw JSON response from the Microsoft Graph API.
Headers	object	The HTTP headers from the API response.

Use Case

An agent needs to send a daily report to a specific "Project Phoenix" group chat. It first uses this component to list all of the user's chats, then finds the one with the topic "Project Phoenix" to get its chat_id.

Get Chat

Retrieves the properties and relationships of a specific chat, such as its type and web URL.

Inputs

Field	Type	Required	Notes
chat_id	string	Yes	The unique ID of the chat you wish to retrieve.

Outputs

Field	Type	Description
id	string	The unique ID of the chat.
chatType	string	The type of chat (e.g., group, oneOnOne).
webUrl	string	The URL to view the chat in a web browser.
tenantId	string	The ID of the tenant the chat belongs to.

Use Case

Before adding a member, an agent uses this component to check the chatType to ensure it's a 'group' chat.

Get Message in Chat

Retrieves a single, specific message from a chat using the chat ID and message ID.

Inputs

Field	Type	Required	Notes
chat_id	string	Yes	The ID of the chat containing the message.
message_id	string	Yes	The ID of the specific message to retrieve.

Outputs

Field	Type	Description
content	string	The content of the retrieved message (can be HTML).
Response	object	The full, raw JSON response from the API, containing the complete message object.

Use Case

When an agent is triggered by a specific message reply, it uses this component to fetch the full content of the original message that was replied to.

Add Chat Member

Adds a new user to an existing group chat.

Component-Specific Settings

• Body: A JSON editor where you define the user to be added. The structure should be: {"[email protected]": "https://graph.microsoft.com/v1.0/users('USER_ID_TO_ADD')"}.

Inputs

Field	Type	Required	Notes
chat_id	string	Yes	The ID of the group chat to which the member will be added.

Outputs

Field	Type	Description
location	string	The location header indicating the URL of the newly added member resource.
Response	object	The raw JSON response from the Microsoft Graph API.

Use Case

When a new developer joins a project team, an onboarding agent automatically adds them to the project's group chat in Teams.

Best Practices & Advanced Tips

• Secure Your Credentials: Always store your Client ID and Client Secret in the SmythOS Vault.
• Understand Permissions: The Microsoft Graph API has a granular permission model. Ensure your Entra App Registration has been granted the correct delegated scopes (e.g., Chat.ReadWrite, ChannelMessage.Send) for the actions you want to perform.
• Get User, Team, and Channel IDs: You'll need the unique IDs for users, teams, and channels to use these components. These can be found in the Teams client (by creating links) or retrieved programmatically with other Graph API calls.
• Use HTML for Rich Content: The content field for sending messages supports HTML. Use this to format your messages with bold text, lists, and links for better readability.

Troubleshooting Common Issues

• Error: 401 Unauthorized

  • Cause: The Client ID or Client Secret is incorrect, or the user's access token is invalid or expired.
  • Solution: Verify the credentials in your Vault. You may need to use the Sign Out and Authenticate buttons on the component settings to refresh your token.

• Error: 403 Forbidden

  • Cause: The application does not have the required API permissions (scopes) granted in Microsoft Entra for the action you are trying to perform.
  • Solution: Go to your App Registration in the Entra portal, navigate to API permissions, and ensure the necessary permissions (e.g., ChannelMessage.Send, Chat.Create) are added and have been granted admin consent.

• Error: 404 Not Found

  • Cause: An incorrect ID (team_id, channel_id, chat_id, message_id) was provided.
  • Solution: Double-check that the ID is correct and that the authenticated user has access to that resource.

What's Next?

You are now ready to build powerful communication and collaboration workflows with the SmythOS Microsoft Teams Integration!

Consider these ideas:

• Build an Agent That...

  • Monitors your GitHub repository. When a new pull request is opened, it posts a notification with a link to the PR in the relevant engineering channel.
  • Connects to your calendar. 10 minutes before a meeting, it sends a message to a group chat with all attendees, reminding them of the meeting and providing the agenda.
  • Gathers daily sales data from your CRM and posts a morning summary report to the #sales-team channel.

• Explore Other Integrations:

  • Combine Teams with the tl;dv Integration. After a meeting, an agent can fetch the summary and post it as a reply in the original meeting's chat thread.
  • Use an LLM component to summarize a long email, then post the summary to a Teams channel for quick review.
  • When a new file is uploaded to OneDrive, post a notification message with a link to the file in the appropriate team channel.