Zoom Team Chat 설정 매뉴얼
1. 사전 조건
- Zoom 계정의 Owner 또는 Admin 권한이 있어 앱을 생성하고 설치할 수 있어야 합니다
- Agentic Engine 플랫폼의 관리자 권한이 있어야 합니다
- Agentic Engine에 Zoom이 접근할 수 있는 공용 네트워크 HTTPS 주소가 설정되어 있어야 합니다
- 그룹 채팅 메시지를 테스트할 기존 Zoom Team Chat 채널
2. Zoom App 생성 및 자격 증명 획득
Zoom App Marketplace로 이동하여 다음 단계에 따라 진행합니다:
- Develop → Build App으로 이동하여 General App을 생성합니다
- 조직 내부에서 사용할 경우 Admin-managed를 선택합니다. 개발 및 테스트 단계에서는 먼저 Development 환경을 사용할 수 있습니다
- 앱 이름, 설명, 개발자 연락처를 입력합니다
- 앱 기능에서 Zoom Team Chat / Chat Subscription을 활성화합니다
- Slash Command를 하나 생성합니다. 명령 이름은 자유롭게 정할 수 있습니다(예:
/ae). Bot Endpoint URL은 일단 비워 두고, 다음 장의 플랫폼 채널 설정을 완료한 후 입력합니다 - Scopes에서 앱에
imchat:bot권한이 포함되어 있는지 확인합니다. 없으면 직접 추가하십시오 - 현재 앱 환경의 다음 정보를 기록합니다:
| 자격 증명 | 설명 |
|---|---|
| Client ID | Zoom 앱의 클라이언트 식별자 |
| Client Secret | Client ID와 짝을 이루는 클라이언트 시크릿 |
| Secret Token | Zoom 콜백 요청 검증에 사용 |
| Bot JID | Chatbot의 식별자로, 일반적으로 robot_xxxxx@xmpp.zoom.us 형식 |
| Account ID | 현재 Zoom 계정의 식별자 |
Client Secret과 Secret Token은 민감한 자격 증명이므로 코드 저장소에 커밋하거나 채팅, 티켓으로 보내지 마십시오. Development와 Production의 자격 증명은 반드시 세트로 사용해야 하며 섞어 사용할 수 없습니다.
3. 플랫폼에서 Zoom Team Chat 채널 추가
관리자가 Agentic Engine에 로그인하여 시스템 관리 → 에이전트 관리 → 채널 관리로 이동합니다:
- 새 채널을 클릭하고 채널 타입으로 Zoom Team Chat을 선택합니다
- 다음 구성 항목을 입력합니다:
| 구성 항목 | 필수 여부 | 설명 |
|---|---|---|
| 채널 이름 | 필수 | 표시 이름(예: Zoom Team Chat) |
| Client ID | 필수 | Zoom 앱의 Client ID |
| Client Secret | 필수 | Zoom 앱의 Client Secret |
| Secret Token | 필수 | Zoom 앱 Chat Subscription의 Secret Token |
| Bot JID | 필수 | Zoom Chatbot의 Bot JID |
| Account ID | 필수 | Zoom 앱이 속한 계정의 Account ID |
| 연동 모델 | 선택 | 입력하지 않으면 시스템 기본 모델 사용 |
| 시스템 프롬프트 | 선택 | 이 채널 전용 Agent System Prompt |
- 채널을 저장하고 채널 목록으로 돌아가 자격 증명 확인을 클릭합니다
- 확인에 성공하면 채널을 활성화합니다
- 채널을 다시 편집하여 읽기 전용인 Bot Endpoint URL을 복사합니다
- Zoom App Marketplace로 돌아가 이 주소를 Chat Subscription의 Bot Endpoint URL에 붙여 넣고, Endpoint URL Validation을 완료한 후 저장합니다
- Zoom 페이지의 안내에 따라 앱을 현재 계정 또는 테스트 범위에 설치합니다
Endpoint URL Validation 전에 Agentic Engine 채널은 자격 증명 확인을 완료하고 활성화된 상태여야 합니다. 기존 채널을 편집할 때 Client Secret과 Secret Token을 비워 두면 기존 값이 유지됩니다.
4. 사용자 Zoom 계정 연동
일반 사용자는 처음 사용하기 전에 자신의 Zoom 계정을 Agentic Engine 계정과 연동해야 합니다:
- 개인 설정 → 채널 연결로 이동하여 사용할 Zoom Team Chat 채널을 선택합니다
- 시스템이 생성한 일회용 연동 코드를 복사합니다(예:
+bind ABC234) - Zoom Workplace → Team Chat을 열고 관리자가 설치한 Chatbot을 찾아 봇과의 1:1 채팅으로 들어갑니다
- 관리자가 실제로 설정한 Slash Command로 연동 코드를 보냅니다. 명령이
/ae라면/ae +bind ABC234를 보냅니다 - 연동 성공 안내를 받으면 바로 사용할 수 있습니다. 연동을 해제하려면 채널 연결 페이지로 돌아가 작업합니다
연동 코드의 유효 기간은 10분이며 한 번만 성공적으로 사용할 수 있습니다. 연동 명령은 봇과의 1:1 채팅에서만 사용할 수 있으며, 채널에서 보내면 연동이 완료되지 않고 연동 코드도 소모되지 않습니다.
하나의 Zoom 계정을 여러 Agentic Engine 사용자에게 동시에 연동할 수 없습니다. 계정이 이미 다른 사용자에게 연동되어 있다는 안내가 표시되면 먼저 원래 사용자 쪽에서 연동을 해제하십시오.
5. 그룹 채팅 메시지 분배
그룹 채팅 메시지 분배를 사용하면 하나의 Zoom Chatbot이 규칙에 따라 서로 다른 질문을 서로 다른 Agent 또는 Team에 전달할 수 있습니다. 규칙은 현재 Zoom 앱과 Account ID에 대응하는 진입점에서 설정하며, 해당 Chatbot이 이미 추가된 Team Chat 채널에 적용됩니다. 사용자는 Agentic Engine 계정을 연동한 상태여야 하며, 관리자가 설정한 Slash Command로 작업을 시작해야 합니다. 일반 채널 메시지나 단순히 봇을 @멘션한 메시지는 Agentic Engine으로 전달되지 않습니다.
추가 권한 확인
앱에 imchat:bot 권한이 포함되어 있고 현재 Zoom 계정에 설치되어 있어야 합니다. 특정 채널에서 사용하려면 권한이 있는 멤버가 앱을 해당 Team Chat 채널에 추가해야 합니다.
관리자 설정
- 사용할 Team Chat 채널에 Chatbot을 추가하고, 멤버가 실제로 설정된 Slash Command를 볼 수 있는지 확인합니다
- 시스템 관리 → 에이전트 관리 → 채널 관리로 이동하여 해당 Zoom Team Chat 채널에서 메시지 분배를 엽니다
- 기본 Agent/Team을 선택합니다. 그룹 채팅 분배를 활성화하기 전에 반드시 기본 항목을 설정해야 합니다
- 필요에 따라 규칙을 최대 19개까지 추가합니다. 규칙마다 Agent/Team을 하나 선택하고 필수 항목인 호출 명령을 입력하며, 키워드도 최대 10개까지 입력할 수 있습니다. 그런 다음 활성화 스위치를 켜고 저장합니다
- 채널에서
/ae +help를 보내 설정을 검수합니다. 실제 Slash Command가/ae가 아니면 관리자가 설정한 명령으로 바꾸십시오
| 구성 항목 | 규칙 |
|---|---|
| 기본 Agent/Team | 활성화하기 전에 반드시 설정해야 합니다. 호출 명령을 지정하지 않았고 키워드도 일치하지 않을 때 사용됩니다 |
| 호출 명령 | 필수, 1~32자. 영문자, 숫자, -, _를 사용할 수 있으며 시스템 예약 명령은 사용할 수 없습니다. 대소문자 및 전각/반각 차이는 서로 다른 명령으로 취급하지 않습니다 |
| 키워드 | 입력하지 않아도 됩니다. 규칙당 최대 10개, 각 2~32자입니다. 여러 키워드가 동시에 일치하면 더 긴 키워드를 우선하며, 길이가 같아 하나로 판단할 수 없으면 기본 Agent/Team을 사용합니다 |
| 선택 가능 범위 | 활성화되어 있고 실행 가능한 시스템/기업 Agent와 현재 기업의 Team을 선택할 수 있습니다. 개인 에이전트는 후보에 표시되지 않습니다 |
채널에서 사용하는 방법
아래 표의 예시는 Zoom에 설정된 Slash Command가 /ae라고 가정합니다.
| 용도 | 예시 | 설명 |
|---|---|---|
| 사용 가능한 기능 보기 | /ae +help | 현재 사용자가 사용할 수 있고 현재 실행 가능한 기능 표시 |
| Agent/Team 지정 | /ae +analysis 分析本周数据 | analysis는 관리자가 설정한 호출 명령입니다 |
| 키워드로 분배 | /ae 帮我检查埋点方案 | 키워드가 일치하면 해당 규칙을 사용하고, 일치하지 않으면 기본 항목을 사용합니다 |
| 작업 취소 | /ae +cancel | 명령 전체를 정확히 보내야 합니다 |
| 이전 방식 호환 | /ae +agent analysis 分析本周数据 | 계속 사용할 수 있지만, +analysis를 직접 사용하는 것을 권장합니다 |
명령 범위: 그룹 채팅 분배는 +new를 지원하지 않습니다. 봇과의 1:1 채팅에서는 여전히 +new, +agent, +cancel을 지원합니다. 채널에서 새 작업을 시작할 때마다 실제 Slash Command를 사용해야 합니다.
공개 컨텍스트와 개인 데이터: 채널 작업은 별도의 새 대화를 사용하며, 봇과의 1:1 채팅 내용이나 사용자 메모리를 읽지 않습니다. 채널의 질문과 답변은 채널 멤버에게 표시되므로 민감한 정보는 봇과의 1:1 채팅에서 보내십시오.
6. 자주 묻는 질문
자격 증명 확인 실패
- Client ID, Client Secret, Secret Token, Bot JID, Account ID가 같은 Zoom 앱 환경에서 가져온 것인지 확인합니다
- Zoom 앱에서 Chat Subscription이 활성화되어 있고
imchat:bot권한이 포함되어 있는지 확인합니다 - Development와 Production 자격 증명을 섞어 사용하지 않았는지 확인합니다
Endpoint URL Validation 실패
- Agentic Engine 채널에서 자격 증명 확인을 완료했고 채널이 활성화되어 있는지 확인합니다
- Zoom에 입력한 Bot Endpoint URL이 플랫폼에 표시된 주소와 완전히 일치하는지 확인합니다
- Zoom이 Agentic Engine의 공용 네트워크 HTTPS 주소에 접근할 수 있는지 확인합니다
- Secret Token이 현재 Zoom 앱 환경에서 가져온 것인지 확인합니다
사용자가 Zoom 계정을 연동할 수 없음
- 연동 코드를 봇과의 1:1 채팅에서 실제 Slash Command로 보냈는지 확인합니다
- 연동 코드가 아직 10분의 유효 기간 내에 있고 사용된 적이 없는지 확인합니다
- 해당 Zoom 계정이 다른 Agentic Engine 사용자에게 연동되어 있지 않은지 확인합니다
Bot이 채널 메시지를 받지 못함
- 일반 메시지나 단순히 봇을 @멘션한 것이 아니라 Zoom Slash Command를 사용했는지 확인합니다
- 앱이 대상 Team Chat 채널에 추가되어 있는지 확인합니다. 계정에 설치만 했거나 명령 후보가 보인다고 해서 앱이 채널에 추가된 것은 아닙니다
- 사용자가 봇과의 1:1 채팅에서 계정 연동을 완료했는지 확인합니다
Slash Command를 보낸 후 사라짐
- Zoom은 Slash Command를 일반 채널 메시지로 표시하지 않으며, 이는 정상적인 현상입니다
- 잠시 기다리면 봇이 질문자, 원래 질문, 답변을 포함한 메시지를 보냅니다
Bot이 명령은 받지만 답장할 수 없음
- Bot JID, Account ID,
imchat:bot권한이 올바르게 설정되어 있는지 확인합니다 - 채널이 여전히 활성화되어 있고, 앱이 여전히 현재 Zoom 계정의 설치 또는 테스트 범위에 있는지 확인합니다
관련 페이지와 다음 단계
- 다른 플랫폼의 연동 안내 보기: 채널 관리.
- 채널 연동과 계정 연동의 전체 흐름 알아보기: 채널 개요 및 연동.
- 사용할 Agent 설정: Agent.
- 플랫폼 내 대화 사용 방법 보기: 대화.