DingTalk
1. 사전 조건
- DingTalk 오픈 플랫폼 계정 보유(기업 내부 앱, 서드파티 앱 모두 가능)
- Agentic Engine 플랫폼의 관리자 권한
2. DingTalk 앱 생성 및 자격 증명 획득
DingTalk 오픈 플랫폼에 접속하여 로그인한 후 다음 단계에 따라 진행합니다:
- Developer Console → App Development → Internal Enterprise Apps로 이동하여 Create App을 클릭합니다.
- 앱 이름과 설명을 입력합니다.
- 앱이 생성되면 앱 상세 페이지 → Credentials & Basic Info로 이동하여 다음 두 값을 기록합니다:
| 필드 이름 | 대응 플랫폼 필드 | 설명 |
|---|---|---|
| AppKey | Client ID | 앱 고유 식별자, OAuth 인증에 사용 |
| AppSecret | Client Secret | 앱 시크릿. 안전하게 보관하고 외부에 노출하지 마십시오 |
기업 CorpId 가져오기
DingTalk 개발자 플랫폼을 열고 로그인합니다. 홈 오른쪽의 기업 정보 카드에서 CorpId를 찾아 전체 값을 복사합니다. DingTalk 채널을 추가할 때 이 CorpId를 Client ID, Client Secret과 함께 반드시 입력해야 합니다.
CorpId는 현재 기업의 고유 식별자이며 기업마다 값이 다릅니다. 예시나 스크린샷의 값을 그대로 쓰지 말고, 자신의 기업 페이지에 표시된 전체 값을 사용하십시오.
- Add App Capabilities → Robot으로 이동하여 봇 설정에서 메시지 수신 모드를 Stream Mode로 선택합니다.
- 앱의 Permission Management에서 다음 권한을 활성화합니다:
Read personal contact information,Employee mobile number information,DingTalk group basic information management,Read member information,Send messages by enterprise robots,Write interactive card instances,AI card streaming updates,Write intelligent interactive cards. Enterprise Storage App Read 권한은 활성화할 필요가 없습니다: 이 권한은 기업 스토리지 관련 API에 사용되며, 현재 채널 구현에서는 이러한 API를 호출하지 않습니다. - Security Settings에서 Agentic Engine의 서버 IP를 아웃바운드 IP 화이트리스트에 추가하고, OAuth 리디렉션 URL(콜백 도메인)을 다음과 같이 설정합니다:
https://<your-domain>/api/dingtalk-oauth/callback - 설정을 수정할 때마다 Version Management and Release 섹션에서 View version details를 클릭하여 버전 번호와 버전 설명을 편집한 후 Publish를 클릭합니다.
3. 플랫폼에서 DingTalk 채널 추가
관리자가 Agentic Engine에 로그인하여 시스템 관리 → 에이전트 관리 → 채널 관리로 이동합니다:
- 새 채널을 클릭하고 채널 타입으로 DingTalk을 선택합니다.
- 다음 구성 항목을 입력합니다:
| 구성 항목 | 필수 여부 | 설명 |
|---|---|---|
| 채널 이름 | 필수 | 표시 이름(예: 기업 DingTalk) |
| Corp ID | 필수 | DingTalk 기업의 고유 식별자로, 기업 신원을 확인하고 채팅 공간을 생성하는 데 사용됩니다. DingTalk 관리 콘솔의 기업 정보에서 복사할 수 있습니다. |
| Client ID | 필수 | DingTalk 앱의 AppKey를 입력합니다. |
| Client Secret | 필수 | DingTalk 앱의 AppSecret을 입력합니다. |
| 대화형 질문 카드 템플릿 ID | 선택 | DingTalk AI Card 템플릿의 ID로, "xxxxxxxx.schema" 형식입니다. 게시된 상태이며 프로젝트 변수 규약을 충족하는 DingTalk AI Card 템플릿을 사용해야 합니다. 비워 두면 질문은 자동으로 텍스트 답변 방식으로 진행됩니다. |
| 기본 모델 | 선택 | 단일 Agent 채널 작업에 사용됩니다. 입력하지 않으면 시스템 전역 기본 모델을 사용합니다. Team은 각 멤버에 설정된 모델을 사용합니다. |
| 채널 입력 추가 안내 | 선택 | 매 회차 채널 입력의 추가 안내로 사용되며, Agent 자체의 시스템 프롬프트를 대체하지 않습니다. |
- 저장을 클릭합니다. 채널이 생성되면 상태가 실행 중으로 표시됩니다.
한 기업에서 여러 DingTalk 채널 인스턴스를 생성할 수 있지만, 같은 DingTalk 봇 신원을 같은 환경에 중복 설정할 수는 없습니다. Client ID, Client Secret 또는 Corp ID를 수정하면 다시 확인하고 해당 채팅 공간을 다시 활성화해야 합니다. 이름, 기본 모델 또는 채널 입력 추가 안내만 수정하는 경우에는 이미 확인된 공간이 무효화되지 않습니다.
4. 사용자 DingTalk 계정 연동
관리자가 채널 설정을 완료하면 일반 사용자는 사용자 메뉴의 채널 연결에서 자신의 DingTalk 계정을 연동할 수 있습니다:
OAuth 인증 연동
- AE의 사용자 메뉴를 열고 채널 연결로 들어가 DingTalk 아래에서 대상 채널 인스턴스를 찾은 후 연동을 클릭합니다.
- DingTalk OAuth 인증 페이지로 이동하면 QR 코드를 스캔하거나 DingTalk 계정에 로그인하여 인증을 완료합니다.
- 인증에 성공하면 자동으로 플랫폼으로 돌아오며, 연동 상태가 연동됨으로 바뀝니다.
연동을 클릭했을 때 연동 코드 대화 상자가 표시되면 DingTalk에서 봇과의 1:1 채팅으로 대화 상자에 표시된 전체 연동 명령을 보내십시오(연동 코드 유효 기간 10분). 자세한 내용은 채널 개요 및 연동을 참조하십시오.
5. 그룹 채팅 메시지 분배
그룹 채팅 메시지 분배를 사용하면 하나의 DingTalk 봇이 규칙에 따라 서로 다른 질문을 서로 다른 Agent 또는 Team에 전달할 수 있습니다. 하나의 채팅 공간은 설정의 기업 CorpId에 대응하며, 규칙은 해당 기업 내에서 이 봇을 사용하는 그룹 채팅에 적용됩니다. Agentic Engine 계정을 연동하고 그룹에서 봇을 명시적으로 @멘션한 멤버만 작업을 시작할 수 있습니다.
관리자 설정
- 앱이 Stream 모드를 사용하는지, Client ID, Client Secret, CorpId가 모두 입력되었는지, 그리고 그룹 기본 정보, 봇 메시지 전송, 인터랙티브 카드, AI 카드 스트리밍 업데이트 등 이 문서 앞부분에서 설명한 권한이 활성화되었는지 확인합니다.
- 시스템 관리 → 에이전트 관리 → 채널 관리로 이동하여 해당 DingTalk 채널에서 메시지 분배를 엽니다(팝업 제목은 그룹 채팅 메시지 분배). 확인에 성공하면 시스템이 CorpId를 기준으로 채팅 공간을 생성합니다.
- 기본 Agent/Team을 선택합니다. 그룹 채팅 분배를 활성화하기 전에 반드시 기본 항목을 설정해야 합니다.
- 필요에 따라 규칙을 최대 19개까지 추가합니다. 규칙마다 Agent/Team을 하나 선택하고 필수 항목인 호출 명령을 입력하며, 키워드도 최대 10개까지 입력할 수 있습니다. 그런 다음 활성화 스위치를 켜고 저장합니다.
- 그룹에서
@机器人 /help를 보내 설정을 검수합니다.
| 구성 항목 | 규칙 |
|---|---|
| 기본 Agent/Team | 활성화하기 전에 반드시 설정해야 합니다. 호출 명령을 지정하지 않았고 키워드도 일치하지 않을 때 사용됩니다. |
| 호출 명령 | 필수, 1~32자. 영문자, 숫자, -, _를 사용할 수 있으며 시스템 예약 명령은 사용할 수 없습니다. 대소문자 및 전각/반각 차이는 서로 다른 명령으로 취급하지 않습니다. |
| 키워드 | 선택 사항. 규칙마다 최대 10개, 각 2~32자. 여러 키워드가 동시에 일치하면 더 긴 키워드를 우선하며, 길이가 같아 하나로 판단할 수 없으면 기본 Agent/Team을 사용합니다. |
| 선택 가능 범위 | 활성화되어 있고 실행 가능한 시스템/기업 에이전트와 현재 기업의 Team을 선택할 수 있습니다. 개인 에이전트는 후보에 표시되지 않습니다. |
그룹 채팅에서 사용하는 방법
| 용도 | 예시 | 설명 |
|---|---|---|
| 사용 가능한 기능 보기 | @机器人 /help@机器人 能力清单 | 현재 사용자가 사용할 수 있고 현재 실행 가능한 기능만 표시합니다. |
| Agent/Team 지정 | @机器人 /analysis 分析本周数据 | @机器人 @analysis 分析本周数据를 보낼 수도 있습니다. |
| 키워드로 분배 | @机器人 帮我检查埋点方案 | 키워드가 일치하면 해당 규칙을 사용하고, 일치하지 않으면 기본 항목을 사용합니다. |
| 작업 취소 | @机器人 /cancel | 메시지 전체를 정확히 이 내용으로 보내야 합니다. 이미 출력된 본문은 유지되며, 취소 확인 메시지가 별도로 전송됩니다. |
| 이전 방식 호환 | @机器人 /agent analysis 分析本周数据 | 계속 사용할 수 있지만 /analysis를 직접 사용하는 것을 권장합니다. |
명령 범위: 그룹 채팅 분배는 /new를 지원하지 않습니다. 1:1 채팅에서는 여전히 /new, /agent, /cancel을 지원합니다. 일반적인 새 작업은 먼저 봇을 @멘션해야 하며, 사용자 답변을 기다리는 중에는 봇의 카드나 텍스트 안내에 따라 계속 진행합니다.
공개 컨텍스트와 개인 데이터: 시스템은 최근에 봇을 명시적으로 @멘션하여 실제로 처리된 공개 그룹 채팅 회차만 참고로 사용합니다. 봇을 @멘션하지 않은 일반 그룹 메시지, 다른 그룹, 1:1 채팅, 사용자 메모리는 섞이지 않습니다.
6. 자주 묻는 질문
채널 상태 이상 / 연결 불가
- Client ID와 Client Secret이 올바르게 입력되었는지 확인합니다.
- DingTalk 오픈 플랫폼에서 앱 상태가 Online 또는 In Development인지 확인합니다.
OAuth 콜백 실패
- DingTalk 앱의 Security Settings에 플랫폼 서버 IP 화이트리스트가 추가되었는지 확인합니다.
- 콜백 주소가 올바르게 설정되어 있고 플랫폼의 실제 배포 도메인과 완전히 일치하는지(프로토콜과 경로 포함) 확인합니다.
사용자가 계정을 연동할 수 없음
- DingTalk 앱에 관련 권한이 활성화되어 있는지 확인합니다.
- 앱 콜백 주소가 올바르게 설정되어 있는지 확인합니다.
관련 페이지와 다음 단계
- 다른 플랫폼의 연동 안내 보기: 채널 관리.
- 채널 연동과 계정 연동의 전체 흐름 알아보기: 채널 개요 및 연동.
- 사용할 Agent 설정: Agent.
- 플랫폼 내 대화 사용 방법 보기: 대화.