WA-AKG: 전문적인 다중 세션 WhatsApp 게이트웨이, 대시보드 및 자동화 시스템

전문적이고 다중 세션(multi-session)을 지원하는 WhatsApp 게이트웨이, 대시보드 및 자동화 시스템입니다.

Next.js 15, React, 그리고 Baileys를 사용하여 고성능 메시징 자동화와 실시간 WhatsApp 봇 게이트웨이 서비스를 구축했습니다.

[!TIP]

최신 기능을 찾고 계십니까? 실험적인 소스를 확인하려면 베타 브랜치 또는 사전 출시 버전을 확인해 보세요.

기능 • 사용자 가이드 • API 문서 • 데이터베이스 설정 • 설치

WA-AKG는 개발자와 사용자 모두를 위해 설계된 광범위한 문서를 제공합니다.

마스터 프로젝트 문서: 아키텍처, 데이터베이스 및 로직 흐름을 다룹니다. API 문서: 모든 **109개 이상의 엔드포인트(endpoints)**에 대한 포괄적인 OpenAPI / Swagger 가이드를 제공합니다. API 빠른 참조: 사용 가능한 cURL/JavaScript 스니펫으로 즉시 통합을 시작할 수 있습니다. 환경 변수: 구성 및 보안 가이드입니다.

WA-AKG는 귀하의 WhatsApp을 완전히 프로그래밍 가능한 RESTful API로 변환합니다. 확장성, 신뢰성 및 사용 편의성을 염두에 두고 설계되어, 비즈니스 로직과 WhatsApp의 글로벌 도달점 사이를 연결하는 완벽한 다리 역할을 합니다. WhatsApp 봇 개발, 자동화 또는 고객 서비스 게이트웨이 구축에 탁월합니다.

graph LR
User([사용자 / 앱]) -->|REST API| API[WA-AKG 게이트웨이]
API -->|Baileys| WhatsApp[[WhatsApp 서버]]
...

📱 다중 세션 관리: 간단한 QR 코드 스캔을 통해 무제한의 WhatsApp 계정을 동시에 연결하고 관리할 수 있습니다. ⚡ 프로 WhatsApp 엔진: @whiskeysockets/baileys를 기반으로 합니다.

고속적이고 안정적이며 보안성이 뛰어난 WebSocket 연결을 위해 제공됩니다.📅 고급 스케줄러(Advanced Scheduler): 미디어 지원(이미지, 비디오, 문서)과 함께 정밀한 메시지 계획이 가능합니다.📢 안전 브로드캐스트(Safe Broadcast): 무작위 지연 시간(10~30초) 및 배치 처리를 통해 내장된 계정 차단 방지 메커니즘을 제공합니다.🤖 스마트 자동 응답(Smart Auto-Reply): 키워드 매칭과 함께 컨텍스트 지원(그룹/개인/전체) 및 미디어 첨부 기능을 갖추고 있습니다.🛡️ 세밀한 접근 제어(Granular Access Control): 봇 명령어와 자동 응답 모두에 대한 전체 화이트리스트(Whitelist) 및 블랙리스트(Blacklist) 지원을 제공합니다.🔗 엔터프라이즈 웹훅(Enterprise Webhooks): 메시지, 연결 상태, 상태 변경 및 그룹 업데이트에 대한 강력한 실시간 이벤트 포워딩 기능을 제공합니다.📇 고급 연락처 관리(Advanced Contacts): LID, 인증된 이름, 프로필 사진을 포함한 풍부한 연락처 관리를 지원합니다.🎨 크리에이티브 도구(Creative Tools): 배경 제거(remove.bg 통합) 기능이 있는 내장 스티커 메이커를 제공합니다.📘 오픈 API 명세(Open API Spec): swagger-ui-react를 통해 완벽하게 문서화되어 있습니다.

📂 웹훅 페이로드 예시 보기

{
"event": "message.received",
"sessionId": "xgj7d9",
...

WA-AKG는 n8n을 네이티브로 지원합니다! 공식 커뮤니티 노드를 사용하여 복잡한, 코딩 없이/적은 코드로(no-code/low-code) WhatsApp 자동화 워크플로우를 구축할 수 있습니다.

액션 노드(Action Node): n8n 워크플로우에서 메시징, 그룹, 세션, 연락처 및 라벨에 대한 완벽한 제어를 제공합니다.트리거 노드(Trigger Node): 실시간 웹훅(메시지 수신, 그룹 가입 등)을 즉시 포착하여 워크플로우를 자동으로 실행합니다.

• Node.js 20+ (Node.js 22 권장)
• MySQL 또는 PostgreSQL
• Git
• PM2 (전역 설치: npm install -g pm2)

# 클론 및 설치
git clone https://github.com/mrifqidaffaaditya/WA-AKG.git
cd WA-AKG
...

npm run dev

앱을 백그라운드에서 실행하고 서버가 재부팅되거나 충돌할 경우 자동으로 다시 시작하도록 하려면 PM2를 사용하여 배포하는 것을 권장합니다.

설정 확인, 종속성 설치, 데이터베이스 스키마 동기화, 프로덕션 에셋 컴파일 및 PM2 시작 또는 리로드를 자동화하는 내장 start.sh 스크립트를 제공합니다:

./start.sh

애플리케이션 빌드: npm run build

PM2로 시작하기: 내장된 ecosystem.config.js 설정 파일을 사용하여 다음 명령을 실행합니다:
pm2 start ecosystem.config.js

프로세스 관리:

• 상태 보기:
  pm2 status

• 로그 보기:
  pm2 logs wa-akg

• 프로세스 중지:
  pm2 stop wa-akg

• 프로세스 재시작:
  pm2 restart wa-akg

• 상태 보기:

서버 부팅 시 자동 시작 활성화: pm2 startup # 위 명령의 출력 내용을 복사하여 붙여넣기 pm2 save

PM2 사용을 강력히 권장하지만, Docker Compose를 사용하여 배포할 수도 있습니다:

환경 준비: cp .env.example .env

.env 파일을 편집합니다.
— DATABASE_URL (MySQL 컨테이너를 가리킴), AUTH_SECRET, 및 기타 브랜딩 설정을 설정합니다.

서비스 시작: docker compose up -d

이 명령은 MySQL 데이터베이스 컨테이너와 Next.js 게이트웨이 애플리케이션을 함께 실행합니다.

WA-AKG는 WhatsApp 메시징을 애플리케이션에 직접 통합할 수 있는 포괄적인 REST API를 제공합니다. 자세한 내용은 API_DOCUMENTATION.md를 참조하십시오.

팁:
대화형 탐색을 위해 내장된 Swagger UI를 /docs에서 사용하세요.

curl -X POST http://localhost:3000/api/messages/session_01/[email protected]/send \
-H

- 텍스트 상태 메시지(Text statuses)의 경우 사용자 지정 배경색이 올바르게 표시되지 않을 수 있습니다.
- 미디어 상태 메시지(Media statuses)(이미지/비디오)는 WhatsApp 서버에 업로드하는 데 실패할 수 있습니다.
- 이 기능은 현재 개발 중입니다.

따라서 중요한 워크플로우에서 이 엔드포인트를 사용하기 전에 다음 릴리스를 기다리는 것을 권장합니다.

**API 키 인증 (API Key Auth)**: `X-API-Key` 헤더를 사용하여 보안된 엔드포인트 제공.
**RBAC**: 다중 역할 지원 (`SUPERADMIN`, `OWNER`, `STAFF`).
**암호화된 비밀번호 (Encrypted Passwords)**: 모든 비밀번호는 bcrypt로 해시 처리됨.
**JWT 암호화 (JWT Encryption)**: 세션 토큰은 `AUTH_SECRET`으로 서명됨 (필수 입력 항목이며, 대체 옵션이 없습니다).
**입력 유효성 검사 (Input Validation)**: 중요 엔드포인트에 Zod 스키마 적용.
**미디어 보호 (Media Protection)**: 경로 탐색 방지(Path traversal prevention), 세션 범위 미디어 접근 제한.