Microsoft Teams Integration Guide

Overview

The Microsoft Teams integration allows your NINA workflows to connect with Microsoft Teams via the Microsoft Graph API to manage teams, channels, chats, messages, users, and files. This integration enables automated messaging, channel management, file operations, and human-in-the-loop workflows directly from your automation platform.

Status

The integration supports comprehensive Microsoft Teams operations:

Team Management: Get team details, list joined teams, retrieve team members
User Operations: Get user information, list organization users, retrieve current user profile
Chat Operations: List chats, send messages, retrieve chat messages, send-and-wait for responses (human-in-the-loop)
Channel Management: Create, get, list, update, delete channels, send messages, retrieve channel messages
File Operations: Upload, download, get info, list, and delete files in chats or channels

Advanced features:

Human-in-the-Loop: Send a message and wait for user response with configurable timeout
Rich Messaging: HTML content, mentions, attachments, importance levels, subjects
Resource Locators: Dynamic team/channel/chat selection with searchable dropdowns
Flexible File Management: Upload/download files to chats or channels

Credential Configuration

Microsoft Teams integration uses OAuth2 authentication via Microsoft Azure Active Directory (Azure AD).

Authentication Method

OAuth2 via Azure AD

Field	Description	Example
Client ID	Application (client) ID from Azure app registration	`12345678-1234-1234-1234-123456789abc`
Client Secret	Client secret value from Azure app registration	`abc~123...`
Tenant ID	Azure AD tenant (directory) ID	`87654321-4321-4321-4321-abcdef123456`
Scope	OAuth2 permissions (default provided)	`openid offline_access User.Read...`
Auth URL	Authorization endpoint (auto-configured)	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize`
Access Token URL	Token endpoint (auto-configured)	`https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token`

How to Set Up Azure App Registration

Go to Azure Portal: Navigate to portal.azure.com
Azure Active Directory: Select "Azure Active Directory" from the left menu
App Registrations: Click "App registrations" → "New registration"
Register Application:
- Name: e.g., "NINA Teams Integration"
- Supported account types: Choose appropriate option (usually "Accounts in this organizational directory only")
- Redirect URI: Add your NINA callback URL
  - For POC environment: https://poc.zynap.com/api/v1/oauth2/callback
  - For Production environment: https://platform.zynap.com/api/v1/oauth2/callback
- Click "Register"
Copy Client ID and Tenant ID: From the Overview page, copy:
- Application (client) ID
- Directory (tenant) ID
Create Client Secret:
- Go to "Certificates & secrets" → "Client secrets" → "New client secret"
- Description: e.g., "NINA Integration Secret"
- Expiration: Choose appropriate duration
- Click "Add"
- Copy the secret value immediately (you won't see it again!)
Configure API Permissions:
- Go to "API permissions" → "Add a permission" → "Microsoft Graph" → "Delegated permissions"
- Add required permissions:
  - User.Read - Read user profile
  - User.ReadBasic.All - Read all users' basic profiles
  - Team.ReadBasic.All - Read basic team info
  - TeamMember.Read.All - Read team members
  - Channel.ReadBasic.All - Read basic channel info
  - ChannelMessage.Read.All - Read channel messages
  - ChannelMessage.Send - Send channel messages
  - Chat.ReadWrite - Read and write chats
  - Files.ReadWrite.All - Read and write files
- Click "Add permissions"
- Click "Grant admin consent for [Your Organization]" (requires admin privileges)

Creating a Microsoft Teams Credential

Navigate to the Credentials section in NINA
Click Add New Credential
Fill in:
- Integration Service: "Microsoft Teams"
- Auth Type: "OAuth2"
- Client ID: Your Azure app client ID
- Client Secret: Your Azure app client secret
- Tenant ID: Your Azure AD tenant ID
- Scope: (Use default or customize)
Click Authorize to complete OAuth2 flow
Click Save

Supported Resources and Operations

Team

Operation	Name	Description
get	Get	Get a team by ID
list	List	List all teams the user is a member of
getMembers	Get Members	Get all members of a team

User

Operation	Name	Description
get	Get	Get a user by ID
list	List	List all users in the organization
getProfile	Get Profile	Get the current user's profile

Chat

Operation	Name	Description
list	List	List all chats for the user
send	Send	Send a message to a chat
getMessages	Get Messages	Get all messages from a chat
sendAndWait	Send and Wait	Send a message and wait for a response (Human-in-the-loop)

Channel

Operation	Name	Description
create	Create	Create a new channel in a team
get	Get	Get a channel by ID
list	List	List all channels in a team
update	Update	Update a channel
delete	Delete	Delete a channel
send	Send	Send a message to a channel
getMessages	Get Messages	Get all messages from a channel

File

Operation	Name	Description
upload	Upload	Upload a file to a chat or channel
download	Download	Download a file
get	Get	Get file information
list	List	List files in a chat or channel
delete	Delete	Delete a file

Examples

List User's Teams

{
  "integration_service": "microsoft-teams",
  "resource": "team",
  "operation": "list",
  "returnAll": false,
  "limit": 50
}

Send Message to Chat

{
  "integration_service": "microsoft-teams",
  "resource": "chat",
  "operation": "send",
  "chatId": {"mode": "id", "value": "19:abc123..."},
  "messageType": "text",
  "message": "Alert: Security incident detected in production environment",
  "additionalFields": {
    "importance": "urgent",
    "subject": "Security Alert"
  }
}

Send Message to Channel

{
  "integration_service": "microsoft-teams",
  "resource": "channel",
  "operation": "send",
  "teamId": {"mode": "id", "value": "team-id-123"},
  "channelId": {"mode": "id", "value": "channel-id-456"},
  "messageType": "html",
  "message": "<h3>Incident Report</h3><p>Critical vulnerability detected.</p>",
  "subject": "Security Incident",
  "additionalFields": {
    "importance": "high"
  }
}

Human-in-the-Loop: Send and Wait for Response

{
  "integration_service": "microsoft-teams",
  "resource": "chat",
  "operation": "sendAndWait",
  "chatId": {"mode": "id", "value": "19:abc123..."},
  "message": "Approve deployment to production? (yes/no)",
  "responseTimeout": 3600
}

Create Channel

{
  "integration_service": "microsoft-teams",
  "resource": "channel",
  "operation": "create",
  "teamId": {"mode": "id", "value": "team-id-123"},
  "displayName": "Security Operations",
  "description": "Security incident tracking and coordination",
  "membershipType": "standard"
}

Upload File to Chat

{
  "integration_service": "microsoft-teams",
  "resource": "file",
  "operation": "upload",
  "uploadTarget": "chat",
  "chatId": {"mode": "id", "value": "19:abc123..."},
  "fileName": "incident-report.pdf",
  "fileContent": "base64-encoded-file-content"
}

Get Channel Messages

{
  "integration_service": "microsoft-teams",
  "resource": "channel",
  "operation": "getMessages",
  "teamId": {"mode": "id", "value": "team-id-123"},
  "channelId": {"mode": "id", "value": "channel-id-456"},
  "returnAll": false,
  "limit": 50
}

Send Message with Mentions

{
  "integration_service": "microsoft-teams",
  "resource": "chat",
  "operation": "send",
  "chatId": {"mode": "id", "value": "19:abc123..."},
  "messageType": "html",
  "message": "<at id='0'>John Doe</at> please review this alert",
  "additionalFields": {
    "mentions": [
      {
        "userId": "user-id-789",
        "displayName": "John Doe"
      }
    ]
  }
}

Best Practices

Manage Permissions Carefully: Request only the minimum required Microsoft Graph API permissions for your use case.
Use Resource Locators: Leverage searchable dropdowns for teams/channels/chats to improve user experience.
Handle Token Expiration: OAuth2 tokens expire; the integration handles refresh automatically with offline_access scope.
Message Formatting: Use html messageType for rich formatting; escape HTML properly to avoid rendering issues.
Human-in-the-Loop Timeouts: Set appropriate responseTimeout values (default 3600s/1hr) based on expected response time.
Pagination: Use returnAll: false with appropriate limit values for large result sets.
File Uploads: Ensure file content is base64-encoded before upload.
Error Handling: Implement retry logic for transient Microsoft Graph API errors (rate limits, timeouts).
Admin Consent: Ensure admin consent is granted for all required permissions in Azure AD.
Test with Non-Production Teams: Test workflows in dedicated test teams/channels before deploying to production.

Troubleshooting

Issue	Resolution
401 Unauthorized	Verify OAuth2 credentials and ensure admin consent granted for all permissions
403 Forbidden	Check that the user has access to the team/channel/chat and required Graph API permissions are granted
Token expired	Ensure `offline_access` scope is included; the integration will auto-refresh tokens
Team/Channel not found	Verify IDs are correct; use resource locators to select from available options
Message send failed	Check message format, ensure channel allows posting, verify `ChannelMessage.Send` permission
File upload failed	Verify file size limits, ensure file content is base64-encoded, check `Files.ReadWrite.All` permission
Human-in-the-loop timeout	Increase `responseTimeout` or check if user responded; review chat permissions
Rate limiting	Implement exponential backoff retry logic; reduce request frequency

Security Considerations

Protect Client Secrets: Store Azure client secrets securely; rotate regularly.
Least Privilege: Request only the minimum Graph API permissions needed.
Audit Access: Monitor Teams activity logs for integration actions.
Conditional Access: Consider Azure AD Conditional Access policies for added security.
Tenant Isolation: Use appropriate tenant ID to ensure isolation.

Overview​

Status​

Credential Configuration​

Authentication Method​

OAuth2 via Azure AD​

How to Set Up Azure App Registration​

Creating a Microsoft Teams Credential​

Supported Resources and Operations​

Team​

User​

Chat​

Channel​

File​

Examples​

List User's Teams​

Send Message to Chat​

Send Message to Channel​

Human-in-the-Loop: Send and Wait for Response​

Create Channel​

Upload File to Chat​

Get Channel Messages​

Send Message with Mentions​

Best Practices​

Troubleshooting​

Security Considerations​