Skip to main content

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.

ComponentActionWhat it DoesInputsKey OutputsUse Case
Send Message in ChannelWritePosts a message to a specific channel within a Team.required team_id, channel_id, contentid, etagPosting automated deployment status updates.
Send Message in ChatWriteSends a message to a one-on-one or group chat.required chat_id, contentid, chatIdSending a direct notification to a user.
Send Reply in ChannelWriteReplies to a specific message thread in a channel.required team_id, channel_id, message_id, contentid, replyToIdContinuing a conversation started by an alert.
Create ChatWriteCreates a new one-on-one or group chat with specified members.required userId, Bodyid, webUrlStarting a new conversation for a project team.
List Messages in ChatReadRetrieves the message history from a specific chat.required chat_idvalues, countAuditing a conversation or providing context to an LLM.
List ChatsReadRetrieves a list of all chats a user is a member of.required userIdvalues, data_countFinding a specific chat ID to send a message to.
Get ChatReadRetrieves metadata and properties for a specific chat.required chat_idid, chatTypeChecking if a chat is a group or one-on-one.
Get Message in ChatReadRetrieves a single, specific message from a chat.required chat_id, message_idcontentGetting the text of a message that triggered a workflow.
Add Chat MemberWriteAdds a new user to an existing group chat.required chat_id, BodylocationAdding 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…TargetUse this ComponentWhy this one?
Send a public alert to a project teamA team channelSend Message in ChannelThe standard way to post in a channel where all team members can see.
Notify a specific user or small groupA one-on-one or group chatSend Message in ChatUse this for direct, private communication instead of a public channel.
Start a new conversation about a specific issueA list of user IDsCreate ChatPerfect for dynamically creating group chats for incident response or new projects.
Get the history of a conversationA chat_idList Messages in ChatRetrieves the messages in a chat, useful for providing context to an AI.
Find a chat with a specific group or personA userIdList ChatsThe best way to get a list of all chats to find the correct chat_id.
Add a new person to an ongoing discussionA chat_id and a user's IDAdd Chat MemberThe 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

FieldTypeRequiredNotes
team_idstringYesThe unique ID of the Team.
channel_idstringYesThe unique ID of the channel within the team.
contentstringYesThe message content. Supports HTML.

Outputs

FieldTypeDescription
idstringThe unique ID of the message that was sent.
etagstringThe ETag of the message.
channelIdentityobjectContains 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

FieldTypeRequiredNotes
chat_idstringYesThe unique ID of the chat.
contentstringYesThe message content. Supports HTML.

Outputs

FieldTypeDescription
idstringThe unique ID of the message that was sent.
chatIdstringThe 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

FieldTypeRequiredNotes
team_idstringYesThe ID of the team.
channel_idstringYesThe ID of the channel.
message_idstringYesThe ID of the message to reply to.
contentstringYesThe content of the reply.

Outputs

FieldTypeDescription
idstringThe ID of the sent reply message.
replyToIdstringThe 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"], "user@odata.bind": "https://graph.microsoft.com/v1.0/users('USER_ID_1')"}, ...]}

Inputs

FieldTypeRequiredNotes
userIdstringYesThe ID of the user creating the chat (typically the authenticated user).

Outputs

FieldTypeDescription
idstringThe unique ID of the newly created chat.
webUrlstringThe 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

FieldTypeRequiredNotes
chat_idstringYesThe unique ID of the chat from which to retrieve messages.

Outputs

FieldTypeDescription
valuesarrayAn array of message objects from the chat.
countintegerThe number of messages retrieved in the current request.
nextLinkstringA 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

FieldTypeRequiredNotes
userIdstringYesThe ID of the user whose chats are being listed (use me for the authenticated user).

Outputs

FieldTypeDescription
valuesarrayA list of chat objects, each containing details like id, topic, and chatType.
data_countintegerThe count of chat objects returned in the current response.
ResponseobjectThe full, raw JSON response from the Microsoft Graph API.
HeadersobjectThe 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

FieldTypeRequiredNotes
chat_idstringYesThe unique ID of the chat you wish to retrieve.

Outputs

FieldTypeDescription
idstringThe unique ID of the chat.
chatTypestringThe type of chat (e.g., group, oneOnOne).
webUrlstringThe URL to view the chat in a web browser.
tenantIdstringThe 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

FieldTypeRequiredNotes
chat_idstringYesThe ID of the chat containing the message.
message_idstringYesThe ID of the specific message to retrieve.

Outputs

FieldTypeDescription
contentstringThe content of the retrieved message (can be HTML).
ResponseobjectThe 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: {"user@odata.bind": "https://graph.microsoft.com/v1.0/users('USER_ID_TO_ADD')"}.

Inputs

FieldTypeRequiredNotes
chat_idstringYesThe ID of the group chat to which the member will be added.

Outputs

FieldTypeDescription
locationstringThe location header indicating the URL of the newly added member resource.
ResponseobjectThe 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.