🏗️ 아키텍처
유연한 구조 설계 ⭐
GiftCall 시스템 (FastAPI + Vue.js)
↓
AlimTalkService (추상화 계층)
↓
Provider 선택 (환경변수)
├─ NHN Cloud
└─ 메가버드
↓
카카오 서버
↓
고객
✅ 핵심: 환경변수만 변경하면 파트너사 교체 가능
환경변수 설정
ALIMTALK_PROVIDER=nhn_cloud # 또는 megabird
코드 예시
# 파트너사 독립적
service = create_alimtalk_service() # 환경변수에서 자동 선택
result = service.send_delivery_notification(...)
파일 구조
backend/app/services/
└── alimtalk_service.py
├── AlimTalkProvider (추상 클래스)
├── NHNCloudProvider (구현)
├── MegabirdProvider (구현)
├── AlimTalkService (비즈니스 로직)
└── create_alimtalk_service() (팩토리)
새 파트너사 추가 방법
class NewProvider(AlimTalkProvider):
def send_message(self, phone, template_code, template_params):
# 새 파트너사 API 호출
pass
def get_message_status(self, message_id):
# 상태 조회
pass
def validate_config(self):
# 설정 검증
pass
💻 구현
Phase 1: 사전 준비 ✅
- ✅ 카카오톡 채널 생성
- ✅ 비즈니스 채널 전환 완료
Phase 2: 파트너사 선정 ⏳
| 항목 |
NHN Cloud |
메가버드 |
| 알림톡 |
8-15원 |
8원 |
| 친구톡 |
5-8원 |
13원 |
| 시작 |
프로젝트 생성 |
1,500원 충전 |
| 통합 |
카카오톡만 |
문자+카카오톡 |
| API 문서 |
공개 |
회원가입 후 |
NHN Cloud API
엔드포인트: https://api-alimtalk.cloud.toast.com/alimtalk/v2.3/appkeys/{appkey}
인증: X-Secret-Key
문서: https://docs.nhncloud.com/ko/Notification/KakaoTalk%20Bizmessage/ko/alimtalk-api-guide/
메가버드 API
웹사이트: https://www.megabird.com/
특징: 문자+카카오톡 통합, REST API/DB Agent/WEB 제공
문서: 회원가입 후 다운로드
Phase 3: 발신 프로필 & 템플릿
- 발신 프로필 등록 (senderKey 발급)
- 템플릿 1개 등록 (
EMART_DELIVERY_001)
- 카카오 검수 (1-2일)
🔹 메시징 전략 ⭐
✅ 하이브리드 방식
알림톡 (첫 메시지, 템플릿 필수)
↓
고객이 채널 친구 추가
↓
친구톡 (이후 대화, LLM 자동생성 가능)
🔹 템플릿 내용
안녕하세요 #{고객명}님,
이마트 #{점포명}입니다.
🎁 선물을 보내드립니다!
#{발신자명}님께서 #{상품명}을(를) 보내주셨습니다.
📍 배송지: #{주소}
📦 배송 가능일: #{배송일자}
위 내용이 맞으시면 아래 버튼으로 채널 친구 추가 후 답장 부탁드립니다.
감사합니다.
[버튼: 채널 추가하고 답장하기]
Phase 4: 개발 (2-3일)
🔹 Backend
service = create_alimtalk_service()
result = service.send_delivery_notification(
phone="010-1234-5678",
customer_name="홍길동",
store_name="이마트 역삼점",
sender_name="김철수",
product_name="한우 세트",
address="서울시 강남구",
delivery_date="2025-01-02"
)
🔹 Frontend
- 주문 등록 화면
- 수신자 목록 관리 (엑셀 업로드)
- 일괄 발송 화면
- 실시간 현황 모니터링
Phase 5: 테스트 (1일)
# 파트너사 교체 테스트
export ALIMTALK_PROVIDER=nhn_cloud
python prototypes/kakao-biz/test_nhn_alimtalk.py
export ALIMTALK_PROVIDER=megabird
python prototypes/kakao-biz/test_nhn_alimtalk.py
Phase 6: 운영 준비 (1일)
🔧 NHN Cloud 설정 가이드
Step 1: 회원가입 및 프로젝트 생성
- https://www.nhncloud.com/ 접속
- 회원가입 및 조직 생성
- 프로젝트 생성 (예: "GiftCall")
Step 2: Appkey와 Secret Key 발급
- KakaoTalk Bizmessage 서비스 활성화
- Appkey 확인 (화면 상단)
- Secret Key 생성 (URL & Appkey 메뉴)
⚠️ 중요: Secret Key는 다시 확인할 수 없으니 안전하게 보관!
Step 3: 발신 프로필 등록
- 발신 프로필 관리 > 발신 프로필 등록
- 카카오톡 채널 검색 ID 입력 (@포함)
- 관리자 휴대폰 번호 입력
- 카테고리 선택
- 인증 요청 → 카카오톡으로 6자리 토큰 수신
- 토큰 입력 → Sender Key 발급
Step 4: 템플릿 등록
- AlimTalk > 템플릿 관리 > 템플릿 등록
- 템플릿 코드:
EMART_DELIVERY_001
- 메시지 내용 및 변수 입력
- 버튼 추가: 채널 추가 (AC)
- 검수 요청 (1-2 영업일)
Step 5: 환경변수 설정
ALIMTALK_PROVIDER=nhn_cloud
NHN_ALIMTALK_APP_KEY=your_app_key
NHN_ALIMTALK_SECRET_KEY=your_secret_key
NHN_ALIMTALK_SENDER_KEY=your_sender_key
Step 6: 테스트 실행
cd prototypes/kakao-biz
pip install -r requirements.txt
python test_nhn_alimtalk.py