WhatsApp 채널 사용 설명서
이 문서는 Agentic Engine 플랫폼 관리자와 일반 사용자를 대상으로, 플랫폼에서 WhatsApp 채널을 개통하고 개인 계정을 연동한 후 WhatsApp 1:1 채팅 또는 그룹 채팅에서 Agent와 Team을 사용하는 방법을 설명합니다. 페이지 진입점이나 채널 상태에 이상이 있으면 시스템 관리자에게 문의하십시오.
규정 준수 안내: Baileys는 WhatsApp에서 공식 지원하지 않는 Web 자동화 방식으로, 계정 속도 제한, 이용 제한 또는 차단 위험이 있을 수 있습니다. 운영 환경에서 사용하기 전에 규정 준수 평가를 완료하고, 전용 테스트 계정을 우선 사용하며, 개인 주 계정을 연결하지 마십시오.
1. 시작 전 준비
- 플랫폼 관리자: 시스템 관리 → 채널 관리 권한이 있어야 하며, 회사 공유 봇 전용으로 사용할 WhatsApp 계정을 준비해야 합니다.
- 일반 사용자: 정상적으로 로그인할 수 있는 Agentic Engine 계정이 있어야 하며, 자신의 WhatsApp으로 공유 봇과 1:1 채팅을 할 수 있어야 합니다.
- 그룹 채팅에서 사용: 공유 봇이 먼저 대상 WhatsApp 그룹 채팅에 참여해야 하며, 그룹 멤버는 개인 계정 연동을 완료해야 합니다.
두 가지 신원을 혼동하지 마십시오: 관리자가 QR 코드를 스캔하는 것은 회사의 공유 봇을 플랫폼에 연결하기 위해서입니다. 일반 사용자는 QR 코드를 스캔할 필요 없이 워크벤치에서 일회용 연동 코드를 생성한 후, 자신의 WhatsApp으로 봇과 1:1 채팅을 하여 연동을 완료하면 됩니다.
2. 관리자의 WhatsApp 채널 추가
채널 관리 권한이 있는 관리자가 Agentic Engine에 로그인하여 시스템 관리 → 채널 관리로 이동합니다.
- 새 채널을 클릭하고 채널 타입으로 WhatsApp을 선택합니다.
- 채널 이름을 입력하고, 필요에 따라 기본 모델을 선택하고 시스템 프롬프트를 입력한 후 저장합니다.
- 채널의 활성화 스위치를 켭니다. 처음 활성화한 후 아직 QR 코드를 스캔하지 않았다면 오프라인으로 표시되며, 이는 정상 상태입니다.
- 채널 목록으로 돌아가 QR 코드로 연결을 클릭합니다.
- 공유 봇 휴대폰의 WhatsApp에서 설정/메뉴 → 연결된 기기 → 기기 연결로 이동하여 페이지의 QR 코드를 스캔합니다.
- QR 코드는 약 2분 후 만료됩니다. 만료되면 페이지에서 새 QR 코드 생성을 클릭합니다.
- QR 코드 스캔에 성공하면 채널 목록을 새로 고치고 상태가 온라인으로 바뀌었는지 확인합니다.
| 구성 항목 | 필수 여부 | 작업 설명 |
|---|---|---|
| 채널 이름 | 필수 | 채널 목록과 사용자 연동 페이지에서 식별하는 데 사용됩니다(예: "WhatsApp 봇"). |
| 채널 타입 | 필수 | WhatsApp을 선택합니다. |
| 기본 모델 | 선택 | 선택하지 않으면 플랫폼의 전역 기본 모델을 사용합니다. |
| 시스템 프롬프트 | 선택 | 해당 WhatsApp 채널을 통해 시작된 Agent 대화에만 적용됩니다. |
채널이 온라인으로 표시되어야 사용자가 워크벤치에서 해당 WhatsApp 채널의 연동 진입점을 볼 수 있습니다.
3. 사용자 연동 및 연결 해제
WhatsApp 계정 연동
- Agentic Engine에 로그인하여 워크벤치 사이드바에서 채널 연결을 엽니다.
- 사용할 WhatsApp 채널을 선택하고 연동을 클릭합니다.
- 팝업에 표시된 전체 연동 명령을 복사합니다. 연동 코드는 10분간 유효하며 한 번만 사용할 수 있습니다.
- 자신의 WhatsApp 계정으로 공유 봇에게 1:1 채팅으로 전체 명령을 보냅니다(예:
+bind ABC234). - "WhatsApp 계정 연동 성공"이 표시되면 워크벤치로 돌아가 상태가 연동됨으로 새로 고쳐졌는지 확인합니다.
연동 명령은 1:1 채팅에서만 보낼 수 있으며, 그룹 채팅에서 보내면 거부됩니다. 하나의 WhatsApp 신원을 여러 Agentic Engine 사용자에게 동시에 연동할 수 없습니다.
연결 해제 또는 플랫폼 계정 변경
- 워크벤치 사이드바에서 채널 연결을 엽니다.
- 해당 WhatsApp 채널을 찾아 연결 해제를 클릭하고 확인합니다.
- 다른 Agentic Engine 계정을 연동하려면 새 계정으로 로그인하고 연동 코드를 다시 생성하십시오.
4. WhatsApp에서 Agent 사용
1:1 채팅에서 사용
- 연동을 완료한 후 공유 봇에게 1:1 채팅으로 바로 질문을 보내면, 답변은 현재 1:1 채팅으로 돌아옵니다.
- 봇이 추가 정보를 요청하거나 계속 실행할지 확인을 요청하면, 텍스트 안내에 따라 바로 답장하면 됩니다.
- WhatsApp은 대화 thread를 지원하지 않으므로 모든 답변은 원래 1:1 채팅에 남습니다.
| 작업 | 작성 방법 | 설명 |
|---|---|---|
| 바로 질문 | 이번 주 데이터를 분석해 줘 | 채널 기본 Agent를 사용합니다. |
| 새 대화 시작 | +new | 1:1 채팅에서만 지원합니다. |
| Agent 지정 | +agent Agent名称 问题 | 예: +agent rhea 帮我分析数据 |
| 현재 작업 취소 | +cancel | 메시지 전체를 정확히 이 내용으로 보내야 합니다. |
그룹 채팅에서 사용
- 먼저 공유 봇이 대상 그룹 채팅에 참여했는지, 메시지를 보내는 멤버가 개인 계정 연동을 완료했는지 확인합니다.
- 메시지를 보낼 때는 반드시 WhatsApp 기본 @ 기능으로 공유 봇을 선택해야 합니다. 비슷한 이름을 직접 입력하는 것만으로는 트리거되지 않습니다.
- 봇을 @멘션하지 않은 일반 그룹 메시지는 무시되며 Agent 대화로 들어가지 않습니다.
- 그룹 채팅은
+new를 지원하지 않습니다. 작업을 취소할 때는@机器人 +cancel을 보냅니다.
관리자의 그룹 채팅 분배 설정
- 시스템 관리 → 채널 관리로 이동하여 해당 WhatsApp 채널의 메시지 분배를 엽니다.
- 기본 Agent 또는 Team을 선택합니다. 그룹 채팅 분배를 활성화하기 전에 반드시 기본 항목을 설정해야 합니다.
- 필요에 따라 호출 명령과 키워드 규칙을 추가한 후 저장합니다.
- 테스트 그룹에서
@机器人 +help를 보내 현재 사용자가 사용할 수 있는 Agent/Team을 확인합니다.
| 용도 | 예시 | 설명 |
|---|---|---|
| 사용 가능한 기능 보기 | @机器人 +help | 현재 사용자가 사용할 수 있는 Agent/Team을 표시합니다. |
| 기능 지정 | @机器人 +analysis 分析本周数据 | 관리자가 설정한 호출 명령에 따라 분배합니다. |
| 키워드로 분배 | @机器人 帮我检查埋点方案 | 규칙과 일치하면 해당 기능을 사용하고, 일치하지 않으면 기본 항목을 사용합니다. |
그룹 채팅 컨텍스트: 시스템은 최근에 봇을 명시적으로 @멘션하여 실제로 처리된 공개 그룹 채팅 턴만 참고합니다. @멘션하지 않은 일반 그룹 메시지, 다른 그룹 채팅, 개인 1:1 채팅은 섞이지 않습니다.
5. 첨부 파일 및 작업 알림
첨부 파일 보내기 및 받기
- 봇에게 JPEG/PNG 이미지와 TXT, Markdown, CSV, JSON, PDF, Word, Excel, PowerPoint 문서를 보낼 수 있습니다.
- 오디오, 동영상, 스티커는 현재 Agent에 전달되지 않으며, 봇이 처리할 수 없는 이유를 안내합니다.
- 기본적으로 파일 하나는 2 MiB 이하여야 하며, 메시지당 최대 5개의 첨부 파일을 처리합니다. 초과하면 파일을 압축하거나 나누어 보내십시오.
- Agent가 생성한 이미지나 지원되는 문서는 원래 1:1 채팅 또는 그룹 채팅으로 바로 전송됩니다.
Agent Team 작업 알림
- Agent Team 즉시 작업 또는 예약 작업을 생성할 때 알림 채널로 WhatsApp을 선택합니다.
- 작업이 끝나면 공유 봇이 작업 생성자가 연동한 WhatsApp 계정으로 1:1 메시지를 보냅니다.
- 긴 결과는 자동으로 여러 메시지로 나누어 전송됩니다.
알림을 받지 못했다면 개인 계정이 여전히 연동됨 상태인지, WhatsApp 채널이 온라인인지, 작업에서 WhatsApp 알림을 선택했는지 확인하십시오. 알림 전달에 실패해도 작업 자체의 최종 상태는 바뀌지 않습니다.
6. 연결 관리 및 자주 묻는 질문
관리자의 연결 관리
- 채널 연결에 성공하면 채널 목록의 QR 코드로 연결이 연결 관리로 바뀝니다.
- 채널에 다시 연결 필요 또는 WhatsApp 연결이 끊어졌습니다가 표시되면 연결 관리에서 안내에 따라 QR 코드를 다시 스캔합니다.
- 공유 봇 계정을 변경하기 전에 먼저 채널을 비활성화한 후 연결 초기화를 실행하고 새 계정으로 스캔합니다.
- 연결을 초기화하면 기존 사용자 연동이 해제되고 사용하지 않은 연동 코드가 무효화됩니다. 실행 전에 사용자에게 알리고, 완료 후 사용자가 다시 연동하도록 합니다.
- 채널을 삭제하면 해당 채널의 메시지 송수신이 중지됩니다. 더 이상 사용하지 않는 것이 확실할 때 삭제하십시오.
자주 묻는 질문
| 증상 | 처리 방법 |
|---|---|
| 워크벤치에 WhatsApp 연동 진입점이 없음 | 관리자에게 채널이 활성화되어 있고 QR 코드 스캔에 성공하여 온라인으로 표시되는지 확인을 요청하십시오. |
| 연동 코드가 유효하지 않거나 만료된 경우 | 워크벤치로 돌아가 다시 생성하고, 10분 이내에 올바른 공유 봇에게 1:1 채팅으로 전체 명령을 보내십시오. |
| 1:1 채팅은 정상이지만 그룹 채팅에서 응답 없음 | 봇이 그룹 채팅에 참여했는지, 보낸 사람이 연동되어 있는지 확인하고, WhatsApp 기본 @ 기능으로 봇을 선택하십시오. 그룹 채팅 분배를 활성화했다면 기본 Agent/Team도 설정해야 합니다. |
| QR 코드 만료 또는 로드 실패 | 새 QR 코드 생성을 클릭하십시오. 그래도 생성되지 않으면 시스템 관리자에게 문의하십시오. |
| QR 코드 스캔 후에도 오프라인으로 표시됨 | 잠시 기다린 후 채널 목록을 새로 고치십시오. 그래도 온라인이 되지 않으면 연결 관리에서 다시 연결하거나 시스템 관리자에게 문의하십시오. |
| 텍스트는 정상이지만 첨부 파일을 처리할 수 없음 | 파일 형식, 크기, 개수를 확인하고, 파일을 압축하거나 나누어 보내 보십시오. |
| Team 작업 알림을 받지 못함 | 계정 연동 상태, 채널 온라인 상태, 작업에서 WhatsApp 알림을 선택했는지 확인하십시오. |
| 연동된 플랫폼 계정을 변경해야 함 | 먼저 기존 Agentic Engine 계정의 채널 연결에서 연결을 해제한 후, 새 계정으로 로그인하여 연동 코드를 다시 생성하십시오. |
휴대폰에서 해당 공유 봇의 연결된 기기를 제거하면 채널 연결이 끊어지며, 관리자가 플랫폼에서 QR 코드를 다시 스캔하여 연결해야 합니다.
관련 페이지와 다음 단계
- 다른 플랫폼의 연동 안내 보기: 채널 관리.
- 채널 연동과 계정 연동의 전체 흐름 알아보기: 채널 개요 및 연동.
- 사용할 Agent 설정: Agent.
- 플랫폼 내 대화 사용 방법 보기: 대화.