MultiWA 구축: 오픈소스 자체 호스팅 WhatsApp API 게이트웨이

Source: Dev.to

(번역할 텍스트를 제공해 주시면 한국어로 번역해 드리겠습니다.)

내가 MultiWA를 만든 이유

비즈니스 애플리케이션을 위해 WhatsApp 자동화가 필요했지만, 공식 WhatsApp Cloud API는 메시지당 요금이 부과되고 Meta 호스팅을 요구합니다. 기존 오픈소스 대안들은 단일 세션에만 제한되었거나 적절한 관리자 도구가 부족했습니다.

그래서 저는 MultiWA를 만들었습니다 — 완전 자체 호스팅형, 다중 세션 WhatsApp API 게이트웨이로, 관리자 대시보드, 시각적 자동화 빌더, AI 기반 자동 응답 기능을 제공합니다.

MultiWA란?

MultiWA는 오픈‑소스 WhatsApp Business API 게이트웨이로, 다음을 할 수 있게 해줍니다:

• 여러 WhatsApp 번호를 단일 통합 API를 통해 연결합니다
• whatsapp‑web.js와 Baileys 엔진 어댑터 중 선택합니다
• 최신 관리자 대시보드를 통해 모든 것을 관리합니다
• 시각적 드래그‑앤‑드롭 흐름 빌더로 자동화를 구축합니다
• OpenAI 또는 Google AI를 사용해 AI‑기반 자동 응답을 설정합니다
• TypeScript, Python, PHP용 공식 SDK와 함께 REST API를 통해 메시지를 전송합니다

아키텍처

┌──────────────────────────────────────────────┐
│               Nginx (SSL/Proxy)               │
├──────────────────┬───────────────────────────┤
│  Admin (Next.js) │     API (NestJS/Fastify)   │
│  Port 3001       │     Port 3000              │
│                  │  WhatsApp Engine Adapters   │
│                  │  ├─ whatsapp-web.js         │
│  Worker (BullMQ) │  └─ Baileys                │
│                  │  PostgreSQL │ Redis         │
└──────────────────┴───────────────────────────┘

기술 스택

Source: …

주요 기능

다중 세션 관리

무제한 WhatsApp 계정을 연결할 수 있으며, 각 계정은 자체 QR 코드 인증, 상태 모니터링 및 메시지 라우팅을 통해 독립적으로 실행됩니다.

플러그 가능한 엔진 어댑터

MultiWA는 WhatsApp 엔진을 위한 어댑터 패턴을 사용합니다. 현재 whatsapp‑web.js(Chromium 기반)와 Baileys(경량, 브라우저 불필요)를 지원합니다. 애플리케이션 코드를 변경하지 않고도 세션별로 엔진을 전환할 수 있습니다.

시각적 자동화 빌더

드래그‑앤‑드롭 인터페이스로 메시지 자동화 흐름을 생성합니다. 트리거(키워드 매치, 정규식, 웹훅), 조건, 액션(답장, 포워드, API 호출)을 정의할 수 있으며 코드를 작성할 필요가 없습니다.

AI 지식 베이스

문서를 업로드하면 AI가 고객 문의를 자동으로 처리합니다. OpenAI와 Google AI를 제공자로 지원합니다. 시스템은 RAG(검색 기반 생성)를 사용해 지식 베이스에서 관련 답변을 찾아 제공합니다.

엔터프라이즈 기능

• 리프레시 토큰을 포함한 JWT 인증
• 범위 지정 및 만료 기능이 있는 API 키 관리
• 실시간 이벤트 알림을 위한 웹훅 구독
• 예약 메시지 및 일괄 전송
• 감사 로그 및 분석 대시보드
• GDPR 준수 데이터 내보내기 및 삭제

Docker 빠른 시작

git clone https://github.com/ribato22/MultiWA.git
cd MultiWA
cp .env.production.example .env
docker compose -f docker-compose.production.yml up -d

API는 Swagger 문서와 함께 3333 포트에서 실행되며, 관리자 대시보드는 3001 포트에서 실행됩니다.

첫 번째 메시지 보내기

curl -X POST http://localhost:3333/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "profile-uuid",
    "to": "6281234567890",
    "message": "Hello from MultiWA!"
  }'

SDK 지원

공식 SDK는 세 가지 언어에서 사용할 수 있습니다. TypeScript 예시:

import { MultiWA } from '@multiwa/sdk';

const client = new MultiWA({
  baseUrl: 'http://localhost:3000',
  apiKey: 'your-api-key',
});

await client.messages.send({
  profileId: 'profile-uuid',
  to: '6281234567890',
  message: 'Hello!',
});

Contributing

MultiWA는 MIT 라이선스를 따르며 기여를 환영합니다. 버그 보고, 기능 요청, 풀 리퀘스트 등 모든 형태의 참여를 환영합니다.

GitHub:

아키텍처에 대한 질문이 있거나 설정에 도움이 필요하면 댓글로 문의하거나 GitHub에서 토론을 열어 주세요.