DingTalk Bot 연동
Melso 에이전트를 자체 DingTalk 앱에 연결하세요 — DingTalk 오픈 플랫폼에서 Stream 모드 로봇을 만들고, AppKey + AppSecret을 복사해 Melso에 붙여넣은 다음, DingTalk 안에서 DM하거나 그룹에서 @로 멘션하거나 /issue를 입력하세요.
아무 에이전트나 DingTalk 봇에 연결하면, 팀이 DingTalk 안에서 바로 그 에이전트와 함께 일할 수 있습니다 — 봇에게 DM을 보내거나, 그룹에서 @로 멘션하거나, 스크린샷을 보내거나, /issue를 입력해 앱을 열지 않고도 Melso 이슈를 생성하세요.
DingTalk 연동은 커뮤니티가 유지관리합니다. 매 릴리스에 포함되지만 공식 지원 SLA는 제공되지 않습니다. 문제가 있으면 GitHub issues에 보고해 주세요.
DingTalk은 자체 앱 사용(BYO) 모델을 따릅니다. 워크스페이스 admin이 DingTalk 앱을 만들고 Stream 모드 로봇을 추가한 다음, 그 자격 증명을 Melso에 붙여넣습니다. 설정할 때 선택한 에이전트가 DM과 새로 발견된 그룹의 기본 에이전트가 됩니다. 같은 로봇을 여러 그룹에 추가하고 그룹마다 다른 에이전트로 라우팅할 수 있습니다. (바인딩이 스캔하여 설치하는 방식인 Lark와는 다릅니다.)
전체 설정은 아래에 있으며 약 5분이 걸립니다. 마지막에는 Melso에 붙여넣을 두 개의 자격 증명을 얻게 됩니다:
- AppKey — 앱의 client id
- AppSecret — 앱의 client secret
DingTalk 앱 설정하기
1. 앱을 만들고 Stream 모드 로봇 추가하기
- DingTalk 오픈 플랫폼으로 이동해 기업 내부 앱(企业内部应用)을 만듭니다.
- 그 앱을 열고 로봇(机器人) 기능을 추가합니다.
- 로봇 설정에서 메시지 수신 모드를 Stream 모드(推送模式)로 설정합니다. 이것이 봇으로 하여금 webhook을 받는 대신, 오래 유지되는 push 연결을 통해 밖으로 연결하게 합니다.
이것이 플랫폼 수준에서 Melso가 필요로 하는 전부입니다 — 봇이 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. Melso에서 연결하기
- Agents → 당신의 에이전트 → Integrations 탭(또는 왼쪽 사이드바의 Integrations 섹션)에서 에이전트를 엽니다.
- Connect DingTalk을 클릭합니다.
- AppKey와 AppSecret을 붙여넣은 다음 Connect를 클릭합니다.
- 에이전트에 Connected to DingTalk이 표시됩니다. 봇은 이제 자체 Stream 연결로 수신 대기합니다.
두 자격 증명은 같은 DingTalk 앱에서 와야 하며, 그 앱은 하나의 Melso 워크스페이스에 한 번만 설치할 수 있습니다. 두 번째 설치나 다른 워크스페이스 연결은 거부됩니다. 설치할 때 선택한 에이전트는 DM의 기본값으로 유지되고, 그룹은 앱을 다시 연결하지 않고 다른 에이전트로 라우팅할 수 있습니다.
하나의 로봇을 여러 에이전트에서 사용하려면 각 DingTalk 그룹에 추가하고 한 번 @ 멘션한 뒤, Settings → Integrations → DingTalk → 그룹 라우팅에서 그룹별 에이전트를 선택하세요. 별도의 봇 ID나 DM 에이전트가 필요할 때만 DingTalk 앱을 따로 설치하면 됩니다.
연동이 하는 일
| 위치 | 동작 |
|---|---|
| Agent → Integrations | owner와 admin에게는 Connect DingTalk이 보이며, 연결되면 Connected to DingTalk 배지와 Disconnect 컨트롤로 바뀝니다. |
| 봇에게 DM | 워크스페이스 멤버가 1:1 채팅에서 봇에게 직접 메시지를 보냅니다. 그 대화는 에이전트와의 Melso chat 세션이 되며, 모든 메시지를 읽습니다. |
그룹에서 @-멘션 | 봇을 그룹에 추가하고 @로 멘션하세요. 첫 멘션에서 그룹을 발견하고 처음에는 기본 에이전트를 사용합니다. owner 또는 admin은 그룹 라우팅에서 다른 에이전트를 선택할 수 있습니다. 멘션한 메시지만 읽습니다. |
| 이미지 보내기 | DM의 이미지, 또는 그룹에서 @-멘션과 함께 보낸 이미지는 대화에 들어가 에이전트가 볼 수 있습니다 — PNG, JPEG, GIF, WebP, BMP를 지원하며, 메시지당 최대 4장, 장당 10 MB까지입니다. 각 이미지는 Melso 스토리지로 복사되므로, DingTalk의 임시 링크가 만료된 뒤에도 대화에서 계속 보입니다. /issue와 함께 보낸 이미지는 채팅 turn이 아니라 생성된 이슈에 첨부됩니다. 파일과 음성은 지원하지 않습니다. |
/issue 명령 | /issue <제목>으로 시작하면 입력 내용에서 당신 이름의 Melso 태스크를 직접 동기적으로 만들고 같은 대화에 ID와 제목을 돌려줍니다. 다음 줄은 설명이 됩니다. 같은 DingTalk 메시지의 이미지는 생성된 태스크에 첨부됩니다. 명령 자체는 Melso Chat에 표시되지 않으며 생성된 태스크가 Melso에 기록되는 처리 결과입니다. |
/new 명령 | /new <당신의 메시지>로 시작하면 그 메시지를 이전 대화 맥락 없이 실행합니다. /new만 보내면 같은 fresh-start 의도가 다음 비어 있지 않은 메시지에 적용되며 빈 turn은 만들어지지 않습니다. 기존 대화 기록은 그대로 유지됩니다. |
| 답변 | 에이전트의 답변은 같은 1:1 채팅 또는 그룹으로 다시 게시됩니다. |
봇 사용하기 (멤버)
첫 메시지: 계정 연결하기
봇을 처음 @로 멘션하거나 DM하면, 계정을 연결하라는 안내로 답하며, 이는 제품 내 /dingtalk/bind 페이지를 가리킵니다. 링크를 탭하고 Melso에 로그인하면, 당신의 DingTalk 신원이 Melso 멤버십에 바인딩됩니다 — 바로 이 단계가 에이전트로 하여금 당신을 대신해 행동하게 합니다(예: /issue는 당신 이름으로 이슈를 생성합니다). 이 링크는 일회용이며 약 15분 후에 만료됩니다. 새 링크가 필요하면 봇에게 다시 메시지를 보내세요.
워크스페이스 멤버만 봇을 사용할 수 있습니다. 멤버가 아니거나 신원 연결을 건너뛰면 봇은 실행되지 않으며, 메시지는 폐기됩니다(감사 목적으로 기록되며, 내용은 저장하지 않습니다).
대화와 명령
- 그룹에서 — 봇을 그룹에 추가한 다음
@your-bot <당신의 메시지>로 보내세요. 후속 메시지마다 다시 멘션하세요(봇은 자신을 멘션한 메시지만 읽습니다). - 1:1 채팅에서 — 봇을 열고 직접 메시지를 보내세요. 멘션이 필요 없으며, 모든 메시지를 읽습니다.
- 이미지 보내기 — 텍스트가 있든 없든 스크린샷이나 사진을 보내세요. 대화에 들어가 에이전트가 참고할 수 있습니다. PNG, JPEG, GIF, WebP, BMP를 지원하며, 메시지당 최대 4장, 장당 10 MB까지입니다.
- 이슈 생성 —
/issue Safari에서 로그인 리다이렉트가 깨졌어요를 보내고 필요하면 다음 줄에 설명을 추가하세요. Melso가 이슈를 동기적으로 만들고, 같은 메시지의 이미지를 해당 이슈에 첨부한 뒤 ID와 제목을 채팅에 돌려줍니다. - 새로 시작하기 —
/new <당신의 메시지>를 보내 그 메시지를 이전 맥락 없이 실행하거나,/new만 보내 fresh-start를 다음 비어 있지 않은 메시지에 적용하세요. 어느 방식도 기존 대화 기록을 삭제하지 않습니다.
관리 및 연결 해제
워크스페이스 전체 관리는 Settings → Integrations에 있습니다:
- Connected bots는 워크스페이스 내 모든 봇과 각 봇이 바인딩된 에이전트를 나열합니다(모든 멤버에게 보입니다).
- 그룹 라우팅은 봇이 발견한 모든 그룹을 보여줍니다. owner와 admin은 그룹마다 고정 에이전트를 선택할 수 있고, 모든 멤버는 현재 라우팅을 볼 수 있습니다.
- 라우팅을 변경할 때마다 선택한 에이전트의 새 Chat 세션이 생성됩니다. 에이전트 A → B → A로 되돌려도 A의 이전 세션은 재개되지 않습니다. 할당된 에이전트를 보관하면 라우팅은 유지되지만, 해당 에이전트를 복원하거나 그룹을 다시 할당할 때까지 처리가 중지되고 사용할 수 없다는 안내가 표시됩니다.
- Disconnect는 owner / admin 전용입니다. 봇이 DingTalk 메시지 수신을 멈추고 연결이 해체됩니다. 설치 기록은 감사용으로 유지되며, 이후 다시 연결할 수 있습니다.
권한
- 연결 / 연결 해제에는 워크스페이스 owner 또는 admin이 필요합니다.
- 봇과 대화하기에는 DingTalk 신원이 연결된 워크스페이스 멤버여야 합니다. 그 외의 사람은 모두 폐기됩니다.
- 폐기된 메시지의 본문은 절대 저장되지 않으며 — 감사용 폐기 사유만 기록됩니다.
자체 호스팅 설정
Melso 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으로 폴백)에서 만들어집니다. 일반적인 배포에서는 이미 설정되어 있으므로 추가로 구성할 것은 없습니다.