Feishu
사전 조건
1. Feishu 오픈 플랫폼 설정
-
Feishu 오픈 플랫폼에 접속합니다
-
기업 자체 개발 앱을 생성합니다(또는 기존 앱 사용)
-
앱 자격 증명을 가져옵니다:
- App ID(앱 ID)
- App Secret(앱 시크릿)
2. 봇 설정
Feishu 오픈 플랫폼 → App details → Features → Bot에서 봇 기능을 활성화합니다.
3. 리디렉션 URL 설정
Feishu 오픈 플랫폼 → App details → Security Settings → Redirect URLs에 다음을 추가합니다:
http://your-domain/agent/api/feishu-oauth/callback
4. 이벤트와 콜백
구독 방식: Feishu 오픈 플랫폼의 Events & Callbacks에서 이벤트와 콜백 모두 Receive through persistent connection을 선택하며, 공용 네트워크 요청 주소는 설정할 필요가 없습니다.
- 이벤트 설정:
im.message.receive_v1(메시지 수신 v2.0)을 추가하여 사용자가 봇에게 보낸 메시지, 이미지, 파일을 수신합니다. - 콜백 설정:
card.action.trigger(카드 콜백 인터랙션)를 추가하여 AskUserQuestion 질문 양식의 제출, 무시, 계속 작업에 사용합니다. - 앱 권한:
im:resource(사용자 이미지/파일 다운로드 및 생성 파일 업로드)와cardkit:card:write(인터랙티브 카드 생성, 스트리밍 업데이트, 교체)를 반드시 포함해야 합니다.im:resource가 없으면 텍스트 메시지는 정상일 수 있지만 이미지 읽기와 생성 파일 전송이 실패합니다. - 저장 및 게시: 권한, 이벤트 또는 콜백이 변경되면 반드시 Version Management & Release에서 새 버전을 만들어 게시하고, 사용 가능 범위에 대상 사용자가 포함되어 있는지 확인해야 합니다. 개발 설정만 저장해서는 이미 설치된 버전에 적용되지 않습니다.
검수 권장 사항: 채널을 시작한 후 먼저 롱 커넥션이 성공했는지 확인하고, 이어서 일반 텍스트, 이미지 읽기, AskUserQuestion 양식 제출, 생성 파일의 네이티브 첨부 파일 전송을 차례로 테스트합니다.
5. 앱 권한 설정
Feishu 오픈 플랫폼 → App details → Permissions & Scopes에서 다음 권한을 신청합니다:
메시지 관련 권한(Bot Token Scopes):
| 권한 | 설명 |
|---|---|
im:message | 메시지 보내기 |
im:message.group_at_msg:readonly | 그룹 채팅에서 봇을 @멘션한 메시지 읽기 |
im:message.group_msg | 그룹 메시지 보내기 |
im:message.p2p_msg:readonly | 1:1 채팅 메시지 읽기 |
im:message:send_as_bot | 봇 신분으로 메시지 보내기 |
im:message:readonly | 메시지 읽기 |
im:resource | 이미지 또는 파일 리소스 가져오기 및 업로드 |
cardkit:card:write | 카드 생성 및 업데이트 |
사용자 신원 권한(User Token Scopes):
| 권한 | 설명 |
|---|---|
contact:user.base:readonly | 사용자 기본 정보 가져오기(신원 인증에 필수) |
권한을 신청한 후 관리자 승인이 필요합니다.
일괄 가져오기:
{
"scopes": {
"tenant": [
"im:message",
"im:message.group_at_msg:readonly",
"im:message.group_msg",
"im:message.p2p_msg:readonly",
"im:message:readonly",
"im:message:send_as_bot",
"im:resource",
"cardkit:card:write"
],
"user": [
"contact:user.base:readonly"
]
}
}
권한을 일괄 가져올 때 추가로 확인하십시오: 가져온 결과에 im:resource와 cardkit:card:write가 반드시 포함되어야 합니다. 이전 버전 JSON에 이 두 항목이 없으면 Permissions & Scopes에서 추가한 후 앱 버전을 다시 게시하십시오.
그룹 채팅 메시지 분배를 위해 추가를 권장하는 권한:tenant:tenant:readonly(테넌트 정보 가져오기). 이 권한이 있으면 시스템 관리에서 채널을 확인한 후 바로 테넌트를 식별하고 채팅 공간을 표시할 수 있습니다. 이 권한이 없어도 자격 증명 확인과 메시지 송수신에는 영향이 없지만, 대상 그룹에서 처음으로 봇을 @멘션한 메시지가 도착해야 채팅 공간이 발견됩니다. 권한을 추가한 후에는 앱 버전을 다시 게시하고 채널 관리에서 다시 확인을 클릭하십시오.
6. 앱 게시
Feishu 오픈 플랫폼 → App details → Version Management & Release에서 앱 표시 범위 설정 & 앱 게시를 진행합니다
권한을 부여할 직원을 선택합니다. 표시 범위 내의 직원만 사용할 수 있습니다
심사를 통과하면 앱을 사용할 수 있습니다.
Agent 설정
1. 채널 관리 설정
시스템 관리에서 설정합니다:
-
시스템에 로그인하여 시스템 관리 → 에이전트 관리 → 채널 관리로 이동합니다
-
새 채널을 클릭하고 Feishu 타입을 선택합니다
-
설정 정보를 입력합니다:
- 채널 이름: 사용자 지정 이름(예: "Feishu 봇")
- APP ID & APP Secret
-
저장을 클릭하면 시스템이 설정을 자동으로 암호화하여 저장합니다
-
채널을 활성화합니다(활성화 스위치가 켜져 있는지 확인)
주의:
- 설정 정보는 데이터베이스에 암호화되어 저장되므로 보안성이 높습니다
- 앱이 시작되면 활성화된 모든 Feishu 채널에 자동으로 연결됩니다(WebSocket 롱 커넥션 사용)
- 설정을 수정한 후 서비스를 재시작할 필요 없이 즉시 적용됩니다
사용 절차
사용자 연동 절차
- 사용자가 시스템에 로그인합니다
- 왼쪽 하단의 사용자 아바타를 클릭하여 메뉴를 엽니다
- 채널 연결을 선택하고 Feishu 아래에서 연동할 채널 인스턴스를 찾아 연동 버튼을 클릭합니다
- Feishu 인증 페이지로 이동합니다
- 사용자가 인증을 확인합니다
- 자동으로 시스템으로 돌아와 연동 완료 페이지가 표시됩니다
- 인증 창을 닫으면 원래 페이지가 자동으로 새로 고쳐지고, 메뉴에 연동됨 상태가 표시됩니다
사용자 연동 해제 절차
- 왼쪽 하단의 사용자 아바타를 클릭하여 메뉴를 엽니다
- 채널 연결을 선택하고 Feishu 아래에서 연동된 채널 인스턴스를 찾아 연결 해제 버튼을 클릭합니다
- 연결 해제 작업을 확인합니다
- 연결 해제에 성공하면 메뉴에 연동되지 않음 상태가 표시됩니다
사용 설명서
사용자 지정 명령
Feishu 봇은 다음 명령을 지원합니다(모든 명령은 /로 시작합니다):
| 명령 | 설명 | 예시 |
|---|---|---|
/new | 새 대화를 시작하고 현재 대화 기록을 지웁니다 | /new 보내기 |
/agent <名称> <消息> | 지정한 이름의 Agent에게 메시지를 보냅니다 | /agent rhea 你好 |
/agent <消息> | 시스템 기본 Agent에게 메시지를 보냅니다 | /agent 你好 |
설명:
/로 시작하지 않는 메시지는 시스템 기본 Agent에게 바로 전송됩니다- Agent 이름은 사용자에게 접근 권한이 있는 Agent여야 합니다
- 명령 파라미터는 대소문자를 구분합니다
그룹 채팅 메시지 분배
그룹 채팅 메시지 분배를 사용하면 하나의 Feishu 봇이 규칙에 따라 서로 다른 질문을 서로 다른 Agent 또는 Team에 전달할 수 있습니다. 하나의 채팅 공간은 현재 Feishu 테넌트에 대응하며, 설정은 해당 테넌트 내에서 이 봇을 사용하는 그룹 채팅에 적용됩니다. Agentic Engine 계정을 연동하고 그룹에서 봇을 명시적으로 @멘션한 멤버만 작업을 시작할 수 있습니다.
관리자 설정
- 채널이 활성화되어 있고 앱이 게시되었으며
im.message.receive_v1과card.action.trigger를 구독했는지 확인합니다.tenant:tenant:readonly를 추가하는 것을 권장합니다. 이 권한이 있으면 시스템이 채널을 확인할 때 바로 Feishu 테넌트를 식별할 수 있습니다. 추가하지 않은 경우 대상 그룹에서 먼저 봇을 @멘션한 메시지를 한 번 보내야 시스템이 해당 채팅 공간을 발견합니다. - 시스템 관리 → 에이전트 관리 → 채널 관리로 이동하여 해당 Feishu 채널에서 메시지 분배를 엽니다. 채팅 공간이 여러 개이면 먼저 설정할 공간을 선택합니다.
- 기본 Agent/Team을 선택합니다. 그룹 채팅 분배를 활성화하기 전에 반드시 기본 항목을 설정해야 하며, 다른 규칙에 일치하지 않는 일반 메시지는 기본 항목이 처리합니다.
- 필요에 따라 규칙을 최대 19개까지 추가합니다. 규칙마다 Agent/Team을 하나 선택하고 필수 항목인 호출 명령을 입력하며, 키워드도 최대 10개까지 입력할 수 있습니다. 그런 다음 해당 규칙의 활성화 스위치를 켭니다.
- 저장한 후 그룹에서
@机器人 /help를 보내 설정을 검수하고, 목록에 현재 사용자가 사용할 수 있고 현재 실행 가능한 Agent/Team만 표시되는지 확인합니다.
| 구성 항목 | 규칙 |
|---|---|
| 기본 Agent/Team | 설정해야만 활성화할 수 있습니다. 호출 명령을 지정하지 않았고 키워드도 일치하지 않을 때 사용됩니다. |
| 호출 명령 | 필수, 1~32자. 영문자, 숫자, -, _를 사용할 수 있으며 시스템 예약 명령은 사용할 수 없습니다. 대소문자 및 전각/반각 차이는 서로 다른 명령으로 취급하지 않습니다. |
| 키워드 | 선택 사항. 규칙마다 최대 10개, 각 2~32자. 여러 키워드가 동시에 일치하면 더 긴 키워드를 우선 사용하며, 길이가 같아 규칙을 하나로 판단할 수 없으면 기본 Agent/Team을 사용합니다. |
| 선택 가능 범위 | 활성화되어 있고 실행 가능한 시스템/기업 에이전트와 현재 기업의 Team을 선택할 수 있습니다. 개인 에이전트는 그룹 채팅 분배 후보에 표시되지 않습니다. |
그룹 채팅에서 사용하는 방법
| 용도 | 예시 | 설명 |
|---|---|---|
| 사용 가능한 기능 보기 | @机器人 /help@机器人 能力清单 | 기본 항목, 호출 명령, 키워드를 나열합니다. 권한이 없거나 현재 실행할 수 없는 기능은 표시되지 않습니다. |
| Agent/Team 지정 | @机器人 /analysis 分析本周数据 | analysis는 관리자가 설정한 호출 명령입니다. @机器人 @analysis 分析本周数据를 보낼 수도 있습니다. |
| 키워드로 분배 | @机器人 帮我检查埋点方案 | 본문이 어떤 규칙의 키워드와 일치하면 해당 Agent/Team에 전달하고, 일치하지 않으면 기본 항목을 사용합니다. |
| 작업 취소 | @机器人 /cancel | 메시지 전체를 정확히 이 내용으로 보내야 합니다. 작업이 이미 출력한 본문은 유지되며, 취소 확인 메시지를 별도로 받습니다. |
| 이전 방식 호환 | @机器人 /agent analysis 分析本周数据 | 계속 사용할 수 있지만, 새 문서에서는 /analysis를 직접 사용하는 것을 권장합니다. |
명령 범위: 그룹 채팅 분배는 /new를 지원하지 않습니다. 1:1 채팅에서는 여전히 /new, /agent, /cancel을 지원합니다. 그룹 채팅에서 일반적인 새 작업은 먼저 봇을 @멘션해야 하며, 이미 작업이 답변을 기다리는 중일 때만 봇의 안내에 따라 원래 스레드나 인터랙티브 카드에서 이어서 답변할 수 있습니다.
공개 컨텍스트와 개인 데이터: 시스템은 최근에 봇을 명시적으로 @멘션하여 실제로 처리된 공개 그룹 채팅 회차만 참고로 사용합니다. 봇을 @멘션하지 않은 일반 그룹 메시지, 다른 그룹, 1:1 채팅, 사용자 메모리는 섞이지 않습니다. 이전 내용은 신뢰할 수 없는 참고 자료로만 사용되며, 현재 메시지만이 이번 회차의 지시입니다.
문제 해결
1. 콜백 URL 오류
오류 메시지: 리디렉션 URL이 올바르지 않습니다. 앱 관리자에게 문의하십시오
해결 방법:
- Feishu 오픈 플랫폼에 설정한 콜백 URL이 올바른지 확인합니다
- 프로토콜, 도메인, 포트, 경로가 완전히 일치하는지 확인합니다
- 로컬 개발 시 포트 번호에 주의합니다(예: 3000 vs 8686)
NEXT_PUBLIC_BASE_PATH를 사용하는 경우 콜백 URL에 해당 경로가 포함되어야 합니다
2. Feishu 채널 미설정
오류 메시지: Feishu 채널이 구성되지 않았거나 비활성입니다
해결 방법:
- 시스템 관리 → 에이전트 관리 → 채널 관리로 이동하여 Feishu 채널이 있는지 확인합니다
- 채널의 활성화 스위치가 켜져 있는지 확인합니다
- App ID와 App Secret이 올바르게 입력되었는지 확인합니다
- 앱 타입이 기업 자체 개발 앱인지 확인합니다
3. App Access Token 무효
오류 메시지: The app access token passed is invalid
해결 방법:
- 채널 관리의
App ID와App Secret이 올바른지 확인합니다 - 앱 타입(기업 자체 개발 앱)을 확인합니다
- 앱이 활성화되어 있는지 확인합니다
4. 권한 부족
오류 메시지: 권한이 부족하거나 권한 검증에 실패했습니다
해결 방법:
- Feishu 오픈 플랫폼에서 필요한 권한을 신청합니다
- 관리자의 권한 승인을 기다립니다
- 권한이 적용되었는지 확인합니다
5. 연동 실패
오류 메시지: 이 Feishu 계정은 다른 사용자에 연결되어 있습니다
해결 방법:
- 하나의 Feishu 계정은 하나의 시스템 사용자에만 연동할 수 있습니다
- 연동을 변경하려면 먼저 원래 계정에서 연결을 해제하십시오
관련 문서
관련 페이지와 다음 단계
- 다른 플랫폼의 연동 안내 보기: 채널 관리.
- 채널 연동과 계정 연동의 전체 흐름 알아보기: 채널 개요 및 연동.
- 사용할 Agent 설정: Agent.
- 플랫폼 내 대화 사용 방법 보기: 대화.