MINARAMeta Cloud API를 통한 아웃바운드 메시징. 비즈니스 계정 필요, 엄격한 세션 윈도, 발신 전용.
🟢 런타임 준비 완료 : SDK 없이 Meta Cloud API v21에 직접 전송합니다.
죄송합니다. 지침을 다시 확인하겠습니다. em-dash를 제거해야 합니다.
title: WhatsApp description: Meta Cloud API를 통한 아웃바운드 메시징. 비즈니스 계정 필요, 엄격한 세션 윈도, 발신 전용.
🟢 런타임 준비 완료. SDK 없이 Meta Cloud API v21에 직접 전송합니다. 스트리밍 편집은 지원하지 않습니다. Cloud API의 편집 윈도가 15분에 불과하고 속도 제한이 엄격하여 복잡도 대비 가치가 없기 때문입니다. 헬퍼는 token을 버퍼링한 후 완료 시점에 한 번에 전송합니다.
제공 기능
- 인증된 Meta 비즈니스 번호에서 임의의 WhatsApp 번호(E.164 형식)로 메시지 전송
channel을 통한 메시지별 수신자 재정의- 메시지당 4,096자 제한(헬퍼 기본값과 동일)
시작 전 필요 사항
WhatsApp은 간단히 설정할 수 있는 프로바이더가 아닙니다. 다음이 필요합니다.
- Meta Business Portfolio (business.facebook.com)
- 해당 포트폴리오에 인증된 WhatsApp Business 전화번호 (SMS 또는 음성으로 제어 가능한 번호)
- WhatsApp 제품이 추가된 Meta Developer App (developers.facebook.com)
- 테스트 번호 외 프로덕션 메시징의 경우, Meta Business Suite에서 비즈니스 인증 완료 필요 (수 시간에서 수 일 소요)
우선 사용해 보고 싶다면, Developer App에 테스트 수신자 번호 5개가 무료로 제공됩니다. 앱의 WhatsApp 패널에서 SMS로 인증할 수 있습니다.
설정
1. 액세스 토큰 발급
- developers.facebook.com → 앱 선택 → WhatsApp → API Setup
- 초기 테스트용으로는 임시 액세스 토큰(24시간 유효)을 복사하고, 장기 사용에는 System User 액세스 토큰을 생성합니다. business.facebook.com → Settings → Users → System Users → 사용자 생성 → Generate new token (범위:
whatsapp_business_messaging+whatsapp_business_management)
2. 전화번호 ID 및 수신자 설정
- 동일한 API Setup 페이지에서 From 드롭다운으로 비즈니스 전화번호를 확인합니다. 그 아래에 표시되는 숫자 형식의 Phone number ID가 Minara에 필요한 값입니다(
+...형식의 번호 자체가 아닙니다). - To 항목에서 수신자를 추가하고 SMS로 인증합니다. E.164 형식 번호(
+12025551234)를WHATSAPP_RECIPIENT에 입력합니다.
3. Minara 설정
minara auth messaging add whatsapp또는 프로젝트 루트의 .env 파일에 직접 입력합니다.
WHATSAPP_ACCESS_TOKEN=EAAxxx...
WHATSAPP_PHONE_NUMBER_ID=1234567890
WHATSAPP_RECIPIENT=+120255512344. 테스트
minara auth messaging test whatsapp24시간 세션 윈도
이 부분은 누구나 한 번씩 겪는 함정입니다.
Meta는 비즈니스가 사용자에게 자유 형식 메시지를 보낼 수 있는 시간을 해당 사용자의 마지막 인바운드 메시지로부터 24시간 이내로 제한합니다. 이 윈도를 초과하면 사전 승인된 템플릿 메시지만 전송할 수 있습니다.
Agent 알림의 경우 활성 대화 중에는 문제가 없지만, 비요청 알림(예: 야간 Autopilot 거래)에는 불편할 수 있습니다. 대안은 다음과 같습니다.
- 자리를 비우기 전에 비즈니스 번호로 아무 메시지나 전송. 이 핑으로 24시간 윈도가 초기화됩니다.
- 승인된 템플릿 사용. Meta Business Suite에서
{{1}} {{2}} ({{3}}) triggered at {{4}}형태의 알림 템플릿을 등록합니다. 아웃바운드 템플릿 전송은 윈도 제한이 없습니다(템플릿별 별도 속도 제한은 적용됩니다). - 비요청 알림에는 다른 프로바이더 사용. Email, Telegram, 또는 Signal을 활용합니다.
Minara는 현재 일반 텍스트만 전송하며, 템플릿 지원은 향후 추가될 예정입니다.
수신자 재정의
send_message({
provider: "whatsapp",
channel: "+12025559999",
text: "Critical: position liquidation imminent",
})재정의 번호는 Meta Developer App에서 인증된 테스트 번호이거나, 프로덕션의 경우 인증된 비즈니스 발신자가 도달 가능한 번호여야 합니다.
문제 해결
"Recipient not in allowed list"
- 테스트 등급에서 재정의 수신자가 인증된 테스트 번호 5개에 포함되어 있지 않습니다. Developer App의 WhatsApp 패널에서 추가하세요.
"Token expired"
- 임시 토큰의 유효 기간은 24시간입니다. 프로덕션 환경에서는 System User 토큰으로 교체하세요.
"Message failed outside 24h window"
- 위의 세션 윈도 섹션을 참조하세요. 윈도를 다시 열려면 사용자가 비즈니스 번호로 아무 메시지나 전송하면 됩니다. 비요청 전송에는 템플릿을 등록하여 사용하세요.
"Rate limit exceeded"
- 신규 계정은 비즈니스 시작 대화가 하루 약 50건으로 제한됩니다. 비즈니스 인증 등급에 따라 확대되며, Meta의 확장 문서를 참고하세요.