전제 조건
연결을 만들기 전에 Meta에서 다음이 필요합니다:| 요구 사항 | 가져오기 |
|---|---|
| WhatsApp Business 계정 (인증됨) | Meta Business Manager |
| 시스템 사용자 액세스 토큰 | Meta Business Manager → 시스템 사용자 |
| 전화번호 ID | WhatsApp Manager → 전화번호 |
| Business 계정 ID | 선택 사항 — 고급 Graph API 호출에 필요 |
| 승인된 메시지 템플릿 | Meta Business Manager → 계정 도구 → 메시지 템플릿 |
연결 만들기
WhatsApp 툴킷은 에이전트 빌더와 워크플로우 빌더 모두에서 사용할 수 있습니다.- 에이전트 툴킷
- 워크플로우 툴킷
- 에이전트 빌더에서 에이전트를 엽니다
- 왼쪽 사이드바의 툴킷 탭으로 이동합니다
- WhatsApp을 찾고 에이전트에 추가를 클릭합니다
- 툴킷 패널에서 연결 선택 > 연결 만들기를 클릭합니다
- 나타나는 팝업에서 연결 이름, 시스템 사용자 액세스 토큰, Business 계정 ID를 입력합니다
- 액세스 토큰, Business 계정 ID(선택 사항), 연결의 표시 이름을 입력합니다
- 저장을 클릭합니다 — EKB가 저장하기 전에 자격 증명을 확인합니다
사용 가능한 도구
| 도구 | 설명 |
|---|---|
| Send Message | 24시간 세션 윈도우 내에서 일반 텍스트 메시지(최대 4,096자, UTF-8)를 보냅니다 |
| Send Media | 공개 HTTPS URL을 통해 이미지, 동영상, 오디오 또는 문서를 선택적 캡션 또는 파일명과 함께 보냅니다 |
| Send Template | 사전 승인된 템플릿 메시지를 보냅니다 — 24시간 세션 윈도우 외부의 아웃바운드 메시징에 필요 |
| Custom API Call | 고급 사용 사례를 위해 Meta Graph API 엔드포인트에 직접 호출을 합니다 |
구성 참고 사항
- 전화번호 형식: 항상 E.164 국제 형식을 사용하세요 (예:
+1...,+52...). 공백, 대시 또는 누락된 국가 코드는 전달 실패를 초래합니다 (오류1006). - 세션 윈도우: 일반 텍스트 및 미디어 메시지는 수신자의 마지막 메시지로부터 24시간 윈도우 내에서만 보낼 수 있습니다. 해당 윈도우 외부에서는 Send Template을 대신 사용하세요.
- 미디어 URL: HTTPS를 통해 공개적으로 접근 가능해야 합니다. 프라이빗, 로컬호스트 또는 만료된 URL은 다운로드 실패를 초래합니다 (오류
1011). - 템플릿: 사용 전에 Meta Business Manager에서 승인되어야 합니다. 매개변수 수와 순서가 승인된 템플릿과 정확히 일치해야 합니다.
- 속도 제한: WhatsApp Business API는 전화번호별 및 일일 메시징 제한을 시행합니다.
문제 해결
| 오류 코드 | 증상 | 해결 |
|---|---|---|
401 / 190 | 유효하지 않은 액세스 토큰 | Meta Business Manager에서 시스템 사용자 토큰을 재생성하고 연결 업데이트 |
33 | 유효하지 않은 전화번호 ID | WhatsApp Manager에서 전화번호 ID 확인 |
1006 | 유효하지 않은 전화번호 형식 | E.164 형식 사용 — +와 국가 코드 포함, 공백이나 대시 없음 |
131005 | 템플릿을 찾을 수 없음 | 템플릿 이름과 Meta Business Manager에 존재 여부 확인 |
131056 | 템플릿 일시 중지됨 | Meta Business Manager에서 템플릿 품질 등급 확인 |
1011 | 미디어 다운로드 실패 | 공개 HTTPS URL 사용하고 파일 유형과 MIME 유형이 지원되는지 확인 |