Microsoft Teams 노드를 사용하여 Microsoft Teams에서 작업을 자동화하고, Microsoft Teams를 다른 애플리케이션과 통합할 수 있습니다. n8n은 채널, 채팅, 채널 및 채팅 메시지, 채팅 멤버, 온라인 회의, 작업(task)을 포함하여 다양한 Microsoft Teams 기능을 기본적으로 지원합니다.

이 페이지에서는 Microsoft Teams 노드가 지원하는 작업(operation) 목록과 추가 리소스 링크를 확인할 수 있습니다.

작업#

• Activity Notification
  • Send
• Channel
  • Create
  • Delete
  • Get
  • Get Many
  • Update
• Channel Message
  • Create
  • Delete
  • Get
  • Get Many
  • Get Many Replies
  • Reply
  • Undo Delete
• Chat
  • Create
  • Get
  • Get Many
• Chat Member
  • Add
  • Get Many
  • Remove
• Chat Message
  • Create
  • Delete
  • Get
  • Get Many
  • Send and Wait for Response
  • Undo Delete
• Online Meeting
  • Create
  • Create or Get
  • Delete
  • Get
  • Update
• Task
  • Create
  • Delete
  • Get
  • Get Many
  • Update

멘션#

Channel Message의 Create 및 Reply 작업과 Chat Message의 Create 작업에는 Mentions 필드가 있습니다. 이 필드의 각 행은 한 명의 사용자 또는 하나의 팀 태그를 @멘션하며, n8n이 멘션을 메시지에 자동으로 추가합니다. 채널 메시지에서는 먼저 Mention Type을 User 또는 Team Tag로 설정하세요. 팀 태그는 팀에 속하므로 채팅 메시지에서는 사용자만 멘션할 수 있습니다. Microsoft Teams가 멘션을 저장하는 방식은 Microsoft의 chatMessageMention 리소스 유형을 참고하세요.

Message에 이름을 따로 입력하지 마세요. 이름이 두 번 표시됩니다.

작업의 Options 컬렉션에 있는 옵션인 Mention Placement는 멘션이 들어갈 위치를 정합니다. 기본값인 Start of Message는 @Jane please review this와 같이 만들고, End of Message는 please review this @Jane과 같이 만듭니다.

사용자 멘션#

Channel Message의 Create 또는 Reply에서 Mentions 행의 Mention Type을 User로 설정합니다. Chat Message의 Create에는 행이 이미 사용자이므로 Mention Type이 없습니다. 그런 다음 User 필드를 입력합니다.

• From List: Microsoft Entra 디렉터리를 검색하여 사용자를 선택합니다. 테넌트 안에서 표시 이름은 고유하지 않으므로 항목은 Jane Smith (jane@contoso.com)처럼 표시 이름과 사용자 계정 이름(UPN)을 함께 보여 줍니다. 게스트 사용자도 여기에서 사용할 수 있습니다.
• By ID: 사용자의 개체 ID(예: 7e2f1174-e8ee-4859-b8b1-a8d1cc63d276) 또는 UPN이나 이메일 주소(예: jacob@contoso.com)를 입력합니다. 게스트 사용자는 개체 ID를 사용하세요. 게스트의 UPN에는 #EXT#가 포함되어 있어 이 필드에서 거부됩니다.

n8n은 메시지를 보내기 전에 Microsoft Entra에서 사용자를 조회하므로, 멘션에는 입력한 텍스트가 아니라 디렉터리의 표시 이름이 나타납니다.

팀 태그 멘션#

팀 태그는 팀에 속하므로 태그 멘션은 채널 메시지에서만 사용할 수 있습니다. 작업의 Team을 태그를 소유한 팀으로 설정한 다음 Mentions 행을 추가하고, Mention Type을 Team Tag로 설정한 뒤 Team Tag 필드를 입력합니다.

• From List: 팀의 태그 중 하나를 선택합니다. 각 항목에는 Engineering (4 members)처럼 해당 태그를 가진 멤버 수가 표시됩니다.
• By ID: GET /v1.0/teams/<team-id>/tags가 반환하는 태그 ID를 입력합니다. 태그는 선택한 팀에 속해야 하며, 그렇지 않으면 노드가 태그를 조회할 때 실패합니다.

태그를 멘션하면 그 태그를 가진 모든 사람에게 알림이 갑니다. Microsoft Teams 노드는 팀에 이미 있는 태그만 멘션할 수 있으며 새 태그를 만들 수 없습니다.

멘션 권한#

사용자 멘션에는 User.Read.All 권한이, 팀 태그 멘션에는 TeamworkTag.Read 권한이 필요합니다. Teams OAuth2 자격 증명은 기본적으로 두 권한을 모두 요청합니다. 자격 증명에서 Custom Scopes를 사용하거나 **Microsoft OAuth2 (Graph)**로 인증하는 경우에는 직접 추가하세요. Microsoft Entra 관리자가 이 권한에 동의해야 합니다.

n8n 2.41.0 이전에 Teams OAuth2 자격 증명을 연결했다면 TeamworkTag.Read가 적용되도록 다시 연결하세요. 이 스코프가 없으면 팀 태그 멘션이 권한 오류로 실패합니다.

멘션은 Service Principal (App-Only) 자격 증명에서 사용할 수 없습니다. 이 자격 증명은 멘션을 지원하는 세 작업을 하나도 실행할 수 없습니다. Service Principal 자격 증명 지원을 참고하세요.

메시지 삭제 및 복원#

Channel Message와 Chat Message의 Delete 작업은 메시지를 소프트 삭제합니다. Microsoft Teams는 메시지를 채널이나 채팅에서 숨기지만 보관하므로, 같은 리소스의 Undo Delete 작업으로 복원할 수 있습니다. 두 작업 모두 로그인한 사용자로 실행됩니다. 자신의 메시지는 삭제하고 복원할 수 있습니다. 다른 사람의 메시지를 삭제할 수 있는지는 팀 내 역할과 조직의 Microsoft Teams 메시징 정책에 따라 달라집니다. Microsoft Teams가 허용하지 않으면 작업이 권한 오류로 실패합니다.

두 작업 모두 Message ID가 필요합니다. 찾으려면 Microsoft Teams에서 메시지 링크를 복사하세요. 메시지 ID는 링크 경로 끝의 ? 앞에 있는 숫자입니다. 채팅 메시지에는 Chat도 필요합니다. 채널 메시지에는 Team과 Channel도 필요합니다. 채널의 답글을 삭제하거나 복원하려면 Parent Message ID 옵션을 추가하고 답글이 속한 메시지의 ID를 입력하세요. 이 값은 답글 링크의 parentMessageId 매개변수입니다.

채널 메시지를 삭제하고 복원하려면 ChannelMessage.ReadWrite 스코프가 필요하며, Teams OAuth2 자격 증명은 n8n 2.40.0부터 이 스코프를 기본적으로 요청합니다. n8n 2.40.0 이전에 연결한 자격 증명에는 이 스코프가 없으므로 자격 증명을 다시 연결할 때까지 Delete와 Undo Delete가 403 오류로 실패합니다. 자격 증명에서 Custom Scopes를 사용한다면 다시 연결하기 전에 Enabled Scopes에 이 스코프를 추가하세요.

ChannelMessage.ReadWrite에는 관리자 동의가 필요합니다. Microsoft Entra 관리자가 아니라면, 먼저 관리자에게 앱의 새 권한에 대한 관리자 동의를 요청하세요. 예를 들어 관리자가 직접 자격 증명을 다시 연결하면서 Consent on behalf of your organization을 선택하면 됩니다. 이 동의 없이 다시 연결하면 Microsoft가 Approval required 단계에서 멈추고 자격 증명에 토큰이 없는 상태가 되어, 삭제뿐 아니라 모든 작업이 실패합니다.

채팅 메시지는 자격 증명에 이미 포함된 Chat.ReadWrite 스코프를 사용합니다. Microsoft OAuth2 (Graph) 자격 증명을 사용하는 경우 스코프를 직접 추가하세요.

Delete 및 Undo Delete 작업은 Service Principal (App-Only) 자격 증명에서 사용할 수 없습니다. Microsoft Graph가 이 작업을 로그인한 사용자에게만 제공하기 때문입니다. Service Principal 자격 증명 지원을 참고하세요.

채팅 및 채팅 멤버#

Chat 리소스(n8n 2.41.0부터 사용 가능)는 로그인한 사용자의 채팅을 다룹니다. Get Many는 채팅 목록을 보여 주고, Get은 목록에서 고르거나 ID로 지정한 채팅 하나를 반환하며, Create는 새 채팅을 시작합니다. 채팅 ID는 19:로 시작합니다. Teams 웹 앱 주소 표시줄의 conversations/ 뒤에서, 또는 Chat Get Many 결과의 id 필드에서 찾을 수 있습니다. n8n이 새 채팅에 사용자를 자동으로 추가하므로 Other Participants에는 다른 사람만 나열하세요. Chat Type이 생성할 채팅의 종류를 정합니다.

• One-on-One: 사용자와 다른 한 사람 사이의 채팅입니다. 이미 그 사람과의 채팅이 있으면 Microsoft Teams가 새로 만들지 않고 기존 채팅을 반환합니다.
• Group: 다른 한 명 이상과 하는 채팅입니다. Topic을 지정할 수 있고, 나중에 Chat Member 작업으로 멤버를 추가하거나 제거할 수 있습니다.

각 참가자는 목록에서 사용자를 선택하거나 사용자 계정 이름 또는 개체 ID를 입력합니다. 테넌트의 게스트 계정은 Role을 Guest로 설정하세요. Microsoft Teams는 게스트를 소유자로 지정하는 것을 거부합니다. 다른 조직의 사람은 개체 ID와 해당 조직의 Tenant ID를 입력하세요.

Chat Member의 Remove 작업에는 사용자 ID가 아니라 멤버의 멤버십 ID가 필요합니다. 목록에서 멤버를 선택하거나 Chat Member Get Many 결과의 id 필드를 사용하세요. Microsoft Teams는 일대일 채팅에서 멤버를 제거하는 것과 그룹 채팅의 마지막 소유자를 제거하는 것을 거부합니다.

Chat 및 Chat Member 리소스는 Service Principal (App-Only) 자격 증명에서 사용할 수 없습니다. Service Principal 자격 증명 지원을 참고하세요.

Service Principal 자격 증명 지원#

Service Principal (App-Only) 자격 증명에는 로그인한 사용자가 없으므로, Microsoft Teams 노드는 사용자로서 동작하는 작업을 실행할 수 없습니다. 아래 목록은 리소스별로 사용 가능한 항목을 설명합니다. 사용할 수 없는 리소스와 작업은 이 자격 증명을 선택하면 노드가 해당 필드를 숨기고 안내를 표시합니다. 그래도 이를 사용하는 워크플로는 노드가 요청을 보내기 전에 오류와 함께 실패합니다.

• Activity Notification: Send. TeamsActivity.Send 애플리케이션 권한과, 수신자에게 설치된 동반 Teams 앱이 필요합니다. 활동 알림 전송을 참고하세요.
• Channel: 모든 작업.
• Channel Message: Get, Get Many, Get Many Replies. 앱 전용 Microsoft Graph는 채널 메시지에 대해 마이그레이션 가져오기만 지원하므로 Create와 Reply는 사용할 수 없습니다. Microsoft Graph가 Delete와 Undo Delete를 로그인한 사용자에게만 제공하므로 이 두 작업도 사용할 수 없습니다. 이 네 가지 작업에는 OAuth2 자격 증명을 사용하세요.
• Chat: 사용할 수 없음. 앱 전용 Microsoft Graph에는 채팅을 나열하거나 조회하거나 생성할 대상인 로그인한 사용자가 없습니다.
• Chat Member: 사용할 수 없음. 노드의 채팅 선택기는 로그인한 사용자의 채팅을 나열하는데 앱 전용 액세스로는 이를 할 수 없으므로, 노드는 ID로 지정한 채팅을 포함해 리소스 전체를 차단합니다.
• Chat Message: 사용할 수 없음. 노드는 로그인한 사용자로서 채팅 메시지를 보내고 읽습니다.
• Online Meeting: 모든 작업. 이 자격 증명을 선택하면 노드가 표시하는 Organizer 필드에서 선택한 사용자를 대신하여 실행됩니다. 목록에서 주최자를 선택하거나 사용자 계정 이름 또는 개체 ID를 입력하세요. 앱 등록에는 OnlineMeetings.ReadWrite.All 애플리케이션 권한(Get에는 OnlineMeetings.Read.All이면 충분), 목록에서 또는 사용자 계정 이름으로 주최자를 선택하기 위한 User.Read.All, 그리고 앱이 주최자의 회의에서 동작하도록 허용하는 Microsoft Teams 애플리케이션 액세스 정책이 필요합니다. 정책이 없으면 작업이 403 오류로 실패합니다. 설정 방법은 앱 전용 온라인 회의 허용을 참고하세요.
• Task: 모든 작업. Get Many는 항상 플랜의 작업을 나열합니다. 노드가 Tasks For 옵션을 숨기므로 Group Member는 사용할 수 없습니다. 또한 노드는 Team 선택기를 숨기며, Plan, Bucket, Assigned To 필드는 ID만 받습니다.

각 작업에 필요한 애플리케이션 권한은 Microsoft Entra Service Principal 자격 증명을 참고하세요.

활동 알림 전송#

Activity Notification의 Send 작업은 한 사용자의 활동 피드, 즉 Microsoft Teams의 Activity 탭에 알림을 게시합니다. 채팅이나 채널 메시지를 보내는 것이 아니므로, 메시지를 보낼 수 없는 Service Principal (App-Only) 자격 증명에서도 동작합니다. 승인 기한이 다가올 때처럼 무인 워크플로에서 사람에게 알리는 용도로 사용하세요.

Microsoft Teams는 수신자에게 자격 증명의 클라이언트 ID를 지정한 동반 Teams 앱이 있어야만 알림을 표시합니다. 앱이 없으면 Microsoft Graph가 HTTP 403 오류로 요청을 거부합니다. 관리자가 테넌트당 한 번 앱을 설정한 다음 각 수신자에게 설치합니다. 동반 Teams 앱 설정을 참고하세요.

필드#

노드는 사용자에 대해 systemDefault 활동 유형으로 Microsoft Graph의 sendActivityNotification을 호출합니다. 성공하면 { "success": true }를 반환합니다. 팀 및 채팅 수신자와 사용자 지정 활동 유형은 지원되지 않습니다.

동반 Teams 앱 설정#

이 단계는 테넌트당 한 번 완료합니다. Microsoft Entra 관리자가 권한을 부여하고, Teams 관리자가 앱을 게시하고 설치합니다.

동반 앱은 자격 증명이 인증에 사용하는 앱 등록의 클라이언트 ID를 지정해야 합니다. Service Principal (App-Only) 자격 증명에서는 Application (Client) ID가 해당합니다. Teams OAuth2 또는 Microsoft OAuth2 (Graph) 자격 증명에서는 직접 만든 앱 등록의 Client ID가 해당합니다. n8n Cloud에서 Teams OAuth2 자격 증명은 n8n이 관리하는 앱 등록을 통해 연결할 수 있으며 이 경우 클라이언트 ID가 표시되지 않으므로, Service Principal 자격 증명이나 직접 만든 앱 등록을 사용하는 자격 증명을 대신 사용하세요.

Microsoft Graph 권한 부여#

• Service Principal (App-Only): Microsoft Entra 관리 센터에서 앱 등록을 열고 API permissions > Add a permission > Microsoft Graph > Application permissions를 선택한 다음 TeamsActivity.Send를 추가하고 관리자 동의를 부여합니다. 애플리케이션 권한 추가를 참고하세요. 수신자를 From List에서 선택하려면 User.Read.All도 추가하세요.
• Teams OAuth2: 자격 증명은 n8n 2.42.0부터 위임된 TeamsActivity.Send 스코프를 기본적으로 요청합니다. n8n 2.42.0 이전에 자격 증명을 연결했다면 이 스코프가 적용되도록 다시 연결하세요. 자격 증명에서 Custom Scopes를 사용한다면 먼저 Enabled Scopes에 TeamsActivity.Send를 추가하세요.
• Microsoft OAuth2 (Graph): 자격 증명의 Scope 필드에 TeamsActivity.Send를 추가하고 다시 연결하세요.

앱 패키지 빌드#

패키지는 세 파일로 이루어진 평면 zip 파일입니다. manifest.json, color.png라는 이름의 192x192 PNG, outline.png라는 이름의 32x32 PNG입니다. Microsoft Graph에서 의미가 있는 부분은 webApplicationInfo.id뿐이며, 이 값은 클라이언트 ID여야 합니다. 앱에는 봇, 탭 또는 다른 기능이 필요하지 않습니다.

{
	"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
	"manifestVersion": "1.17",
	"version": "1.0.0",
	"id": "<new-guid>",
	"developer": {
		"name": "Contoso",
		"websiteUrl": "https://www.contoso.com",
		"privacyUrl": "https://www.contoso.com/privacy",
		"termsOfUseUrl": "https://www.contoso.com/terms"
	},
	"name": {
		"short": "n8n Notifications"
	},
	"description": {
		"short": "Lets n8n workflows post to your Teams activity feed.",
		"full": "Companion app that lets an n8n Microsoft Teams credential send activity feed notifications."
	},
	"icons": {
		"color": "color.png",
		"outline": "outline.png"
	},
	"accentColor": "#FF6D5A",
	"webApplicationInfo": {
		"id": "<application-client-id>",
		"resource": "api://<application-client-id>"
	}
}

<new-guid>는 앱의 새 GUID(예: uuidgen으로 생성)로, <application-client-id>는 두 곳 모두 클라이언트 ID로 바꾸세요. 그런 다음 세 파일을 폴더 없이 압축합니다.

zip -j n8n-notifications.zip manifest.json color.png outline.png

조직 카탈로그에 앱 게시#

Teams 관리 센터에서 Teams apps > Manage apps로 이동하여 Actions > Upload new app을 선택하고 zip 파일을 업로드합니다. 이 작업은 관리자만 할 수 있습니다. 앱 전용 액세스로는 카탈로그에 게시할 수 없으므로 n8n이 앱을 대신 설정할 수 없습니다.

각 수신자에게 앱 설치#

Microsoft Graph로 수신자의 개인 범위에 앱을 설치합니다. Graph Explorer에서 요청을 보낼 수 있습니다. Modify permissions를 열고 요청을 보내기 전에 AppCatalog.Read.All과 TeamsAppInstallation.ReadWriteForUser에 동의하세요. 앱 등록 자격으로 Microsoft Graph를 호출하는 다른 도구도 사용할 수 있으며, 이 경우 TeamsAppInstallation.ReadWriteForUser.All 애플리케이션 권한이 필요합니다.

먼저 앱의 카탈로그 ID를 조회합니다. 이 ID는 매니페스트의 id와 다르며, Microsoft Graph는 매니페스트의 id를 externalId라고 부릅니다.

GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '<manifest-id>'

그런 다음 응답의 id를 <catalog-app-id>로 사용하여 수신자에게 앱을 설치합니다.

POST https://graph.microsoft.com/v1.0/users/<user-id>/teamwork/installedApps
Content-Type: application/json

{
	"teamsApp@odata.bind": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/<catalog-app-id>"
}

HTTP 409 응답은 해당 사용자에게 앱이 이미 설치되어 있다는 뜻입니다. 알림을 받아야 하는 모든 사용자에 대해 설치를 반복하세요.

설치가 반영될 때까지 대기#

설치가 반영되는 데는 시간이 걸립니다. 반영되기 전까지 Microsoft Graph는 "not installed" HTTP 403 오류를 계속 반환합니다. n8n의 테스트에서는 설치 후 약 5분이 지나서 첫 알림이 전달되었습니다. 설치 직후의 403 오류가 설치 실패를 뜻하지는 않습니다.

Topic Link#

Teams는 사용자가 알림을 선택할 때 Topic Link를 엽니다. Microsoft Graph는 Microsoft Teams 링크만 허용하므로 알림에서 n8n 실행이나 다른 웹사이트로 연결할 수 없습니다. 노드는 요청을 보내기 전에 링크를 검사합니다. teams.microsoft.us와 같은 소버린 클라우드의 Teams 도메인 링크도 사용할 수 있습니다.

링크는 실제로 열리는 대상이어야 합니다. 그렇지 않으면 사용자가 알림을 선택할 때 Teams에 오류가 표시됩니다. 다음 중 하나를 사용하세요.

• https://teams.microsoft.com/l/chat/0/0?users=someone@contoso.com과 같은 채팅 링크. 해당 사람과의 채팅이 열립니다.
• Teams에서 복사한 채널, 메시지 또는 회의 링크. 해당 항목이 열립니다.

링크 형식은 Microsoft의 Teams 채팅, 채널, 메시지에 대한 딥 링크를 참고하세요.

일반적인 오류#

템플릿 및 예제#

Microsoft Teams 노드 문서 통합 템플릿 둘러보기 또는 모든 템플릿 검색

관련 자료#

서비스에 대한 자세한 내용은 Microsoft Teams API 문서를 참고하세요.