DingTalk Bot 연동
Multica 에이전트를 자체 DingTalk 앱에 연결하세요 — DingTalk 오픈 플랫폼에서 Stream 모드 로봇을 만들고, AppKey + AppSecret을 복사해 Multica에 붙여넣은 다음, DingTalk 안에서 DM하거나 그룹에서 @로 멘션하거나 /issue를 입력하세요.
아무 에이전트나 DingTalk 봇에 연결하면, 팀이 DingTalk 안에서 바로 그 에이전트와 함께 일할 수 있습니다 — 봇에게 DM을 보내거나, 그룹에서 @로 멘션하거나, 스크린샷을 보내거나, /issue를 입력해 앱을 열지 않고도 Multica 이슈를 생성하세요.
DingTalk 연동은 커뮤니티가 유지관리합니다. 매 릴리스에 포함되지만 공식 지원 SLA는 제공되지 않습니다. 문제가 있으면 GitHub issues에 보고해 주세요.
DingTalk은 자체 앱 사용(BYO) 모델을 따릅니다: 워크스페이스 admin이 DingTalk 앱을 만들고, 거기에 Stream 모드 로봇을 추가한 다음, 그 자격 증명을 Multica에 붙여넣습니다. 각 에이전트가 자체 DingTalk 앱을 갖습니다 — 그래서 하나의 조직 안에서 여러 에이전트가 각각 별개로 @로 멘션할 수 있는 봇을 가질 수 있습니다. (바인딩이 스캔하여 설치하는 방식인 Lark와는 다릅니다.)
전체 설정은 아래에 있으며 약 5분이 걸립니다. 마지막에는 Multica에 붙여넣을 두 개의 자격 증명을 얻게 됩니다:
- AppKey — 앱의 client id
- AppSecret — 앱의 client secret
DingTalk 앱 설정하기
1. 앱을 만들고 Stream 모드 로봇 추가하기
- DingTalk 오픈 플랫폼으로 이동해 기업 내부 앱(企业内部应用)을 만듭니다.
- 그 앱을 열고 로봇(机器人) 기능을 추가합니다.
- 로봇 설정에서 메시지 수신 모드를 Stream 모드(推送模式)로 설정합니다. 이것이 봇으로 하여금 webhook을 받는 대신, 오래 유지되는 push 연결을 통해 밖으로 연결하게 합니다.
이것이 플랫폼 수준에서 Multica가 필요로 하는 전부입니다 — 봇이 Stream 모드로 밖으로 연결하므로, 공개 주소를 구성할 필요가 없습니다:
| 설정 | 이유 |
|---|---|
| 기업 내부 앱 | 로봇을 담고 AppKey / AppSecret 자격 증명을 발급하는 앱 컨테이너입니다. |
| 로봇 기능 | @로 멘션되고 답변을 게시하는 봇 신원을 생성합니다. |
| Stream 모드 | 봇이 오래 유지되는 Stream 연결로 밖으로 연결합니다 — 공개 webhook / URL이 필요 없습니다. |
| 로봇 전송 권한 | 봇이 DingTalk으로 메시지를 다시 보낼 수 있게 합니다(에이전트의 답변과 능동적 메시지). |
| 메시지 읽기 권한 | 봇이 1:1 메시지와, 자신을 @로 멘션한 그룹 메시지를 받을 수 있게 합니다. |
webhook URL도 OAuth redirect URL도 없습니다. 로봇이 Stream 모드로 동작하고, BYO는 OAuth를 사용하지 않기 때문입니다.
DingTalk에는 기본 입력 중 / 반응 표시기가 없으므로 — Slack과 달리 — 봇이 처리를 시작하면 짧은 "처리 중" 안내를 먼저 보내고, 전체 답변은 에이전트가 끝난 뒤에 도착합니다. 짧은 시간에 연달아 보낸 메시지는 하나의 안내로 합쳐집니다.
2. 로봇에 권한 부여하기
로봇이 메시지를 받고 메시지를 다시 보낼 수 있도록 필요한 스코프(로봇 메시지 전송 권한)를 부여하세요. 전송 권한이 없으면 에이전트는 실행되더라도 답변을 전달할 수 없습니다.
3. AppKey와 AppSecret 복사하기
앱의 凭证与基础信息(자격 증명 및 기본 정보)을 열고 복사합니다:
- AppKey — 이것이 앱의 client id입니다
- AppSecret — 이것이 앱의 client secret입니다
4. Multica에서 연결하기
- Agents → 당신의 에이전트 → Integrations 탭(또는 왼쪽 사이드바의 Integrations 섹션)에서 에이전트를 엽니다.
- Connect DingTalk을 클릭합니다.
- AppKey와 AppSecret을 붙여넣은 다음 Connect를 클릭합니다.
- 에이전트에 Connected to DingTalk이 표시됩니다. 봇은 이제 자체 Stream 연결로 수신 대기합니다.
두 자격 증명은 같은 DingTalk 앱에서 와야 하며, 그 앱은 정확히 하나의 에이전트에 매핑됩니다. 이미 다른 에이전트나 워크스페이스에 연결된 앱을 연결하는 것은 거부됩니다. 앱을 다른 에이전트로 옮기려면 먼저 연결을 해제하세요. 새 앱으로 에이전트를 다시 연결하면 그 에이전트의 봇이 그 자리에서 갱신됩니다.
여러 에이전트에 설정하나요? 에이전트당 전체 과정을 한 번씩 반복하세요 — 각 에이전트가 자체 DingTalk 앱과 자체 AppKey / AppSecret을 가지며, 조직에 별개의 봇으로 나타납니다.
연동이 하는 일
| 위치 | 동작 |
|---|---|
| Agent → Integrations | owner와 admin에게는 Connect DingTalk이 보이며, 연결되면 Connected to DingTalk 배지와 Disconnect 컨트롤로 바뀝니다. |
| 봇에게 DM | 워크스페이스 멤버가 1:1 채팅에서 봇에게 직접 메시지를 보냅니다. 그 대화는 에이전트와의 Multica chat 세션이 되며, 모든 메시지를 읽습니다. |
그룹에서 @-멘션 | 봇을 그룹에 추가하고 @로 멘션하세요. 멘션한 메시지만 읽으며, 봇이 그룹 전체를 듣지는 않습니다. |
| 이미지 보내기 | DM의 이미지, 또는 그룹에서 @-멘션과 함께 보낸 이미지는 대화에 들어가 에이전트가 볼 수 있습니다 — PNG, JPEG, GIF, WebP, BMP를 지원하며, 메시지당 최대 4장, 장당 10 MB까지입니다. 각 이미지는 Multica 스토리지로 복사되므로, DingTalk의 임시 링크가 만료된 뒤에도 대화에서 계속 보입니다. 파일과 음성은 지원하지 않습니다. |
/issue 명령 | /issue <제목>으로 시작하면 입력 내용에서 당신 이름의 Multica 이슈를 직접 동기적으로 만들고 같은 대화에 ID와 제목을 돌려줍니다. 다음 줄은 설명이 됩니다. 같은 DingTalk 메시지의 이미지는 채팅 메시지에만 첨부되고, 직접 만든 이슈에는 복사되지 않습니다. |
/new 명령 | /new <당신의 메시지>로 시작하면 그 메시지를 이전 대화 맥락 없이 실행합니다. /new만 보내면 같은 fresh-start 의도가 다음 비어 있지 않은 메시지에 적용되며 빈 turn은 만들어지지 않습니다. 기존 대화 기록은 그대로 유지됩니다. |
| 답변 | 에이전트의 답변은 같은 1:1 채팅 또는 그룹으로 다시 게시됩니다. |
봇 사용하기 (멤버)
첫 메시지: 계정 연결하기
봇을 처음 @로 멘션하거나 DM하면, 계정을 연결하라는 안내로 답하며, 이는 제품 내 /dingtalk/bind 페이지를 가리킵니다. 링크를 탭하고 Multica에 로그인하면, 당신의 DingTalk 신원이 Multica 멤버십에 바인딩됩니다 — 바로 이 단계가 에이전트로 하여금 당신을 대신해 행동하게 합니다(예: /issue는 당신 이름으로 이슈를 생성합니다). 이 링크는 일회용이며 약 15분 후에 만료됩니다. 새 링크가 필요하면 봇에게 다시 메시지를 보내세요.
워크스페이스 멤버만 봇을 사용할 수 있습니다. 멤버가 아니거나 신원 연결을 건너뛰면 봇은 실행되지 않으며, 메시지는 폐기됩니다(감사 목적으로 기록되며, 내용은 저장하지 않습니다).
대화와 명령
- 그룹에서 — 봇을 그룹에 추가한 다음
@your-bot <당신의 메시지>로 보내세요. 후속 메시지마다 다시 멘션하세요(봇은 자신을 멘션한 메시지만 읽습니다). - 1:1 채팅에서 — 봇을 열고 직접 메시지를 보내세요. 멘션이 필요 없으며, 모든 메시지를 읽습니다.
- 이미지 보내기 — 텍스트가 있든 없든 스크린샷이나 사진을 보내세요. 대화에 들어가 에이전트가 참고할 수 있습니다. PNG, JPEG, GIF, WebP, BMP를 지원하며, 메시지당 최대 4장, 장당 10 MB까지입니다.
- 이슈 생성 —
/issue Safari에서 로그인 리다이렉트가 깨졌어요를 보내고 필요하면 다음 줄에 설명을 추가하세요. Multica가 이슈를 동기적으로 만들고 ID와 제목을 채팅에 돌려줍니다. 같은 메시지의 이미지는 채팅에 남고 이슈에는 첨부되지 않습니다. - 새로 시작하기 —
/new <당신의 메시지>를 보내 그 메시지를 이전 맥락 없이 실행하거나,/new만 보내 fresh-start를 다음 비어 있지 않은 메시지에 적용하세요. 어느 방식도 기존 대화 기록을 삭제하지 않습니다.
관리 및 연결 해제
워크스페이스 전체 관리는 Settings → Integrations에 있습니다:
- Connected bots는 워크스페이스 내 모든 봇과 각 봇이 바인딩된 에이전트를 나열합니다(모든 멤버에게 보입니다).
- Disconnect는 owner / admin 전용입니다. 봇이 DingTalk 메시지 수신을 멈추고 연결이 해체됩니다. 설치 기록은 감사용으로 유지되며, 이후 다시 연결할 수 있습니다.
권한
- 연결 / 연결 해제에는 워크스페이스 owner 또는 admin이 필요합니다.
- 봇과 대화하기에는 DingTalk 신원이 연결된 워크스페이스 멤버여야 합니다. 그 외의 사람은 모두 폐기됩니다.
- 폐기된 메시지의 본문은 절대 저장되지 않으며 — 감사용 폐기 사유만 기록됩니다.
자체 호스팅 설정
Multica Cloud에서는 연동이 이미 사용 가능합니다 — 이 섹션은 건너뛰세요.
자체 호스팅의 경우, DingTalk은 at-rest 암호화 키를 설정하기 전까지 꺼져 있습니다. 이 키는 각 앱의 AppSecret을 데이터베이스에 저장하기 전에 암호화합니다. AppKey는 비밀이 아닌 installation 라우팅 식별자로 평문 저장됩니다. BYO에는 배포 수준의 OAuth client id/secret이 필요 없습니다 — 각 installation은 admin이 붙여넣은 자격 증명을 사용합니다.
-
32바이트 키를 생성해 API 서버에 설정합니다:
MULTICA_DINGTALK_SECRET_KEY=<base64-encoded 32-byte key>예를 들면:
openssl rand -base64 32. -
API를 재시작하세요. 키가 설정되기 전까지 Settings → Integrations에는 "DingTalk integration not enabled" 안내가 표시되고, Connect DingTalk 진입점은 숨겨진 채로 유지됩니다.
키는 정확히 32바이트로 디코딩되어야 하며 — openssl rand -base64 32가 이를 충족합니다. 오래 유지되는 시크릿으로 다루세요: 키를 회전하거나 잃으면 이미 저장된 자격 증명을 복호화할 수 없게 되어, 모든 봇이 다시 연결해야 합니다. "계정을 연결하세요" 링크는 웹 앱 URL(MULTICA_APP_URL, 없으면 FRONTEND_ORIGIN으로 폴백)에서 만들어집니다. 일반적인 배포에서는 이미 설정되어 있으므로 추가로 구성할 것은 없습니다.