오픈 소스 WhatsApp API 게이트웨이 (Open Source WhatsApp API Gateway)
기능 (Features) • 빠른 시작 (Quick Start) • 문서 (Docs) • API • 기여하기 (Contributing)
OpenWA는 벤더 종속 (vendor lock-in)이나 숨겨진 유료 결제 없이 메시징 인프라에 대한 완전한 제어가 필요한 개발자들을 위해 설계된 무료 오픈 소스 WhatsApp API 게이트웨이입니다.
**플러그형 아키텍처 (pluggable architecture)**를 기반으로 구축된 OpenWA는 애플리케이션 코드를 단 한 줄도 변경하지 않고도 데이터베이스 엔진 (SQLite/PostgreSQL), 스토리지 백엔드 (Local/S3), 캐시 레이어 (Memory/Redis)를 교체할 수 있습니다.
🔓 100% 오픈 소스 (Open Source) |
라이선스 비용 없음, 기능 제한 없음, 전체 소스 코드 접근 가능 |
🏗️ 플러그형 아키텍처 (Pluggable Architecture) |
설정을 통해 데이터베이스, 스토리지, 캐시 어댑터를 교체 가능 |
🖥️ 전체 대시보드 (Full Dashboard) |
세션, 웹훅 (webhook), API 키 관리를 위한 현대적인 React UI |
🔹 멀티 세션 지원 (Multi-Session Ready) |
하나의 인스턴스에서 여러 WhatsApp 세션을 동시에 실행 가능 |
🐳 Docker 네이티브 (Docker Native) |
설정 없이 즉시 프로덕션 환경 사용 가능 |
🔗 n8n 통합 (n8n Integration) |
워크플로 자동화를 위한 커뮤니티 노드 제공 |
| 기능 (Feature) | 상태 (Status) | 설명 (Description) |
|---|
| REST API | ✅ | HTTP 엔드포인트를 통한 전체 WhatsApp API |
| ... | | |
| 기능 (Feature) | 상태 (Status) | 설명 (Description) |
| --- | --- | --- |
| 텍스트 메시지 (Text Messages) | ✅ | 텍스트 메시지 송수신 |
| ... | | |
| 기능 (Feature) | 상태 (Status) | 설명 (Description) |
| --- | --- | --- |
| 그룹 API (Groups API) | ✅ | 그룹 생성, 관리 및 메시지 전송 |
| 라벨 관리 (Labels Management) | ✅ | 라벨을 통한 채팅 정리 |
| 프록시 지원 (Proxy Support) | ✅ | 세션별 프록시 설정 |
| 속도 제한 (Rate Limiting) | ✅ | 설정 가능한 요청 제한 |
| ... |
| 기능 (Feature) | 상태 (Status) | 설명 (Description) |
|---|
| SQLite | ✅ | 설정이 필요 없는 임베디드 데이터베이스 |
| ... | | |
# 클론 및 시작 (Clone and start)
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
...
# 리포지토리 클론 (Clone repository)
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
...
프로덕션 환경의 경우, 선택적 서비스를 포함한 메인 docker-compose.yml을 사용하세요:
# 기본 프로덕션 (SQLite, 로컬 스토리지)
docker compose up -d
# PostgreSQL 데이터베이스 사용 시
...
| 프로필 (Profile) | 서비스 (Services) |
|---|
postgres | PostgreSQL 데이터베이스 |
redis | Redis 캐시 (Cache) |
minio | S3 호환 스토리지 (S3-compatible storage) |
with-dashboard | 웹 대시보드 (Web dashboard) |
with-proxy | Traefik 리버스 프록시 (Reverse proxy) |
full | 위의 모든 서비스 |
개발 (Development) vs 프로덕션 (Production)
- 개발 (Development) (
docker-compose.dev.yml): SQLite, 로컬 스토리지, API 및 대시보드 모두 포함
- 프로덕션 (Production) (
docker-compose.yml): 설정 가능한 데이터베이스, 선택적 서비스를 위한 프로필 제공
| 서비스 (Service) | 포트 (Port) | 설명 (Description) |
|---|
| API | 2785 | REST API 엔드포인트 (Endpoints) |
| Dashboard | 2886 | 웹 관리 인터페이스 (Web management interface) |
| Swagger | 2785/api/docs | 대화형 API 문서 (Interactive API docs) |
curl -X POST http://localhost:2785/api/sessions \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
...
# 세션 시작 (Start the session)
curl -X POST http://localhost:2785/api/sessions/{sessionId}/start \
-H "X-API-Key: YOUR_API_KEY"
...
curl -X POST http://localhost:2785/api/sessions/{sessionId}/messages/send-text \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
...
curl -X POST http://localhost:2785/api/sessions/{sessionId}/webhooks \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
...
| 계층 (Layer) | 기술 (Technology) |
|---|
| 런타임 (Runtime) | Node.js 22 LTS |
| 프레임워크 (Framework) | NestJS 11.x |
| 언어 (Language) | TypeScript 5.x |
| WA 엔진 (WA Engine) | whatsapp-web.js |
| 데이터베이스 (Database) | SQLite / PostgreSQL |
| 캐시 (Cache) | Redis (선택 사항) |
| 스토리지 (Storage) | 로컬 (Local) / S3 / MinIO |
| ORM | TypeORM |
| 컨테이너 (Container) | Docker + Docker Compose |
openwa/
├── src/
│ ├── main.ts # 애플리케이션 진입점 (Application entry point)
...
상세한 문서는 docs/ 폴더에서 확인할 수 있습니다:
| 문서 (Document) | 설명 (Description) |
|---|
| 프로젝트 개요 (Project Overview) | 소개 및 목표 |
| ... | |
기여(Contribution)를 환영합니다! 시작하는 방법은 다음과 같습니다:
Fork를 통해 저장소를 복제하세요.
Create를 통해 기능 브랜치를 생성하세요 (git checkout -b feature/amazing-feature).
Commit을 통해 변경 사항을 커밋하세요 (git commit -m 'Add amazing feature').
)를 통해 브랜치에 **Push** 하세요 (git push origin feature/amazing-feature`).
Pull Request를 생성하세요.
코딩 표준 및 권장 사항(best practices)에 대해서는 개발 가이드라인(Development Guidelines)을 읽어주시기 바랍니다.
이 프로젝트는 MIT License에 따라 라이선스가 부여됩니다 – 개인적 및 상업적 용도로 자유롭게 사용할 수 있습니다.
자세한 내용은 LICENSE 파일을 참조하세요.