openwa

OpenWA는 Meta의 공식 Cloud API에 의존하지 않고 WhatsApp 메시지를 주고받기 위한 HTTP 엔드포인트와 웹훅을 제공하는 무료 오픈소스 WhatsApp API 게이트웨이입니다. NestJS, TypeScript, React 대시보드로 구축되었으며 Docker 네이티브로 쉽게 배포할 수 있습니다. 아키텍처 OpenWA는 플러그형 아키텍처를 사용합니다. 데이터베이스 백엔드는 SQLite(구성 불필요) 또는 PostgreSQL을 사용할 수 있고, 스토리지 및 마이그레이션은 로컬 파일시스템 또는 S3 호환 서비스를 사용하며, 캐싱은 Redis를 통해 선택적으로 활성화할 수 있습니다. 미디어 파일은 자동으로 스토리지에 저장되지 않고 API 및 웹훅 소비자에게 인라인으로 반환됩니다. 엔진 각각 다른 장단점을 가진 두 가지 WhatsApp 엔진을 사용할 수 있습니다. - whatsapp-web.js: 실제 WhatsApp Web 트래픽을 모방하는 헤드리스 Chromium 인스턴스를 구동하여 차단 위험이 낮지만 세션당 RAM 사용량이 높습니다(약 300~500MB). - Baileys: 멀티디바이스 WebSocket 프로토콜을 직접 사용하여 메모리 사용량이 적지만(세션당 약 30~80MB) 지문 인식이 쉬워 차단 위험이 더 높습니다. 주요 기능 - 다중 세션 관리: 하나의 인스턴스에서 여러 WhatsApp 계정을 동시에 실행할 수 있습니다. - 메시징: 텍스트, 미디어(이미지, 비디오, 오디오, 문서), 반응, 메시지 수정을 보내고 받을 수 있으며 대량 메시징을 지원합니다. - 그룹 및 채널: 그룹 생성, 참여, 구성, 라벨 관리, WhatsApp 채널/뉴스레터를 지원합니다. - 웹훅: HMAC 서명 검증 및 선택적 사전 전송 필터가 있는 실시간 이벤트를 제공합니다. - API 인증: 운영자 및 뷰어 토큰을 사용하며 세션 범위 및 채팅 범위 액세스 제어를 통해 특정 세션이나 개별 채팅으로 통합을 제한할 수 있습니다. - 통화 처리: call.received 이벤트 및 세션별 자동 거부(Baileys 전용)를 지원합니다. - 인프라: Kubernetes용 상태 확인, 백엔드 간 데이터 마이그레이션, 세션별 프록시 지원, 구성 가능한 속도 제한 및 CIDR 화이트리스트를 제공합니다. 보안 프로덕션 Docker 스택은 dumb-init 및 gosu를 통해 Node 프로세스를 비루트 사용자로 실행하고, 볼륨 소유권 수정 후 권한을 낮추며, Docker 소켓을 직접 마운트하지 않고 전용 프록시 사이드카를 통해 라우팅합니다. 보안 문서는 SECURITY.md에 제공됩니다. 통합 샌드박스 통합 패브릭을 통해 Chatwoot 및 Typebot용 공식 플러그인을 사용할 수 있으며, n8n 워크플로 자동화용 커뮤니티 노드도 있습니다. ioBroker와 같은 타사 어댑터도 지원됩니다. 경고 OpenWA는 Meta의 공식 API가 아닌 리버스 엔지니어링된 클라이언트를 통해 연결하므로 계정 제한 또는 차단 위험이 항상 존재합니다. 유지관리자는 손실을 감수할 수 있는 전용 번호를 사용하고, 새 계정을 점진적으로 워밍업하며, 속도 제한을 준수하고, 중요한 흐름에는 SMS 또는 이메일을 대체 수단으로 유지할 것을 권장합니다. 규제 환경(의료, 금융, EU/GDPR 맥락)에서는 공식 WhatsApp Cloud API를 사용해야 합니다. 시작하기 가장 빠른 방법은 Docker Compose입니다. 저장소를 클론하고 docker compose -f docker-compose.dev.yml up -d를 실행한 다음 http://localhost:2785에서 대시보드와 API에 접속합니다. 프로덕션 배포는 compose 프로필을 통해 PostgreSQL, Redis, MinIO를 추가할 수 있습니다. 활성화된 경우 /api/docs에서 대화형 Swagger 엔드포인트를 사용할 수 있습니다.