DingTalk Bot

에이전트를 DingTalk에 연결해 DM이나 그룹 채팅에서 바로 작업을 요청합니다.

에이전트를 DingTalk에 연결하면 해당 에이전트가 속한 워크스페이스의 멤버는 봇에게 DM을 보내거나, 그룹에서 @ 멘션하거나, /issue 명령으로 Multica 작업를 바로 만들 수 있습니다. 대화와 실행 기록은 Multica 워크스페이스에 저장됩니다.

DingTalk 연동은 커뮤니티가 유지관리하며 공식 지원 SLA는 제공되지 않습니다. 문제가 있으면 GitHub issues에 보고해 주세요.

봇 연결하기

에이전트 생성자 또는 워크스페이스 owner/admin은 에이전트를 DingTalk에 연결할 수 있습니다. 에이전트와 DingTalk 봇은 1:1로 연결됩니다.

1. Stream 모드 로봇 만들기

DingTalk 오픈 플랫폼에서 기업 내부 앱을 만듭니다.
로봇 기능을 활성화하고 메시지 수신 모드를 Stream 모드로 설정합니다.

2. 로봇에 권한 부여하기

로봇 메시지 전송 권한(qyapi_robot_sendmsg)은 기본으로 추가되어 있습니다. Multica에 봇 이름을 표시하려면 DingTalk 그룹 기본 정보 관리 권한(qyapi_chat_manage)을 수동으로 추가하세요.

3. 앱 자격 증명 가져오기

凭证与基础信息(자격 증명 및 기본 정보) 페이지에서 **Client ID(AppKey)**와 **Client Secret(AppSecret)**을 복사합니다.

4. 에이전트를 DingTalk에 연결하기

Multica로 돌아가 에이전트 → 당신의 에이전트 → 기능 → 연동을 엽니다.
DingTalk 연결을 클릭합니다.
AppKey와 AppSecret을 입력한 뒤 제출합니다.

5. DingTalk 계정과 Multica 계정 연결하기

DingTalk에서 봇에게 DM을 보내거나 그룹에서 @ 멘션해 계정 연결을 한 번 요청합니다. 봇과의 DM으로 링크가 오며 약 15분 동안 유효합니다. 링크를 열어 연결 성공 안내가 표시되면 완료입니다.

DingTalk에서 에이전트에게 작업 요청하기

DM

봇에게 바로 메시지를 보내세요. 에이전트가 요청받은 일을 마치면 결과를 DM으로 보냅니다.

그룹 채팅

봇을 DingTalk 그룹에 추가한 뒤 @your-bot <메시지>를 보내세요. 후속 질문에서도 매번 봇을 다시 @ 멘션해야 합니다. 봇은 자신이 @ 멘션된 메시지만 처리합니다.

이미지 보내기

DM과 그룹 채팅 모두 텍스트와 이미지가 함께 있는 메시지를 지원합니다. PNG, JPEG, GIF, WebP, BMP 형식을 지원하며 메시지당 최대 4장, 이미지당 최대 10 MB까지 보낼 수 있습니다. 파일과 음성 메시지는 아직 지원하지 않습니다.

`/issue`로 작업 만들기

/issue <제목> 또는 /issue <제목>{줄 바꿈}<상세 설명>을 보내면 새 Multica 작업이 만들어지고 봇에 연결된 에이전트에 자동으로 할당됩니다. 같은 메시지의 이미지도 첨부 파일로 작업에 추가됩니다. 일반 대화 메시지와 달리 /issue 명령은 Multica의 “채팅”에 기록을 남기지 않습니다.

`/new`로 새 Chat 시작하기

/new를 보내면 비어 있는 새 Multica Chat이 생성되고 이후 DingTalk 메시지가 새 Chat으로 라우팅됩니다. /new <메시지>를 보내면 해당 메시지가 새 Chat의 첫 번째 대화가 됩니다. 이전 Chat은 Multica에 저장된 채 계속 사용할 수 있습니다.

`/clear`로 현재 컨텍스트 지우기

/clear를 보내면 현재 Multica Chat은 유지되고 다음 메시지에 새 에이전트 컨텍스트가 적용됩니다. /clear <메시지>는 해당 메시지를 경계 이후의 첫 번째 대화로 사용합니다. 전체 Chat 기록은 Multica에 계속 표시됩니다.

연결 관리

에이전트 → 당신의 에이전트 → 기능 → 연동 페이지에서 에이전트 생성자와 워크스페이스 owner/admin은 DingTalk에 연결하거나 연결을 해제할 수 있습니다. DingTalk에 연결하면 이 페이지에 봇 이름, 봇이 메시지를 정상적으로 처리한 적이 있는 DingTalk 그룹, 그리고 각 그룹에서의 봇 활동 상태 데이터가 표시됩니다. 에이전트 읽기 권한이 있는 워크스페이스 멤버는 모두 이 정보를 볼 수 있습니다. 최근 90일 동안 정상적으로 처리된 메시지가 없는 그룹은 장기 미활동에 모이며 펼칠 때 불러옵니다.
설정 → 연동 페이지에는 현재 워크스페이스에서 자신에게 읽기 권한이 있고 DingTalk에 연결된 모든 에이전트 목록과 DingTalk 그룹에서의 봇 활동 상태 데이터가 표시됩니다. 워크스페이스 owner/admin은 목록에 있는 에이전트의 DingTalk 연결을 여기서 바로 해제할 수도 있습니다. 연결을 해제하면 봇은 메시지 수신을 멈추지만 설치 기록은 감사용으로 보관됩니다. 워크스페이스 owner/admin은 그룹을 목록에서 삭제할 수도 있습니다. 이 작업은 대화나 메시지를 삭제하지 않습니다. 이후 DingTalk 계정을 연결한 워크스페이스 멤버가 같은 그룹에서 봇을 다시 @멘션하고 Multica가 해당 메시지를 정상적으로 접수하면 그룹이 다시 표시됩니다.

자체 호스팅 설정

Multica Cloud 사용자는 이 섹션을 건너뛸 수 있습니다. 자체 호스팅 배포에서는 DingTalk AppSecret을 암호화하기 위한 키를 먼저 설정해야 합니다.

MULTICA_DINGTALK_SECRET_KEY=<base64-encoded 32-byte key>

다음과 같이 생성할 수 있습니다.

openssl rand -base64 32

API 서비스를 재시작한 뒤 DingTalk에 연결하세요. 이 키는 계속 보관해야 합니다. 키를 바꾸거나 잃으면 기존 토큰을 복호화할 수 없어 다시 연결해야 합니다.

계정 연결 링크는 MULTICA_APP_URL을 사용하고, 설정하지 않으면 FRONTEND_ORIGIN으로 대체합니다. 멤버가 접근할 수 있는 Multica 주소여야 합니다.

채팅 연동 —— Channel 엔진, 세션, 권한 부여 방식
에이전트 · Chat · 작업
환경 변수 —— 전체 자체 호스팅 설정 참조

이 페이지에서