WhatsApp 번호 온보딩 (Meta Cloud API)
번호 연결은 클릭 10번처럼 보이지만, 실제로는 단계의 순서, 어떤 포트폴리오가 무엇을 소유하는지, Meta 화면에서 "연결됨"이라고 표시되지만 아무것도 전달되지 않는 상황 등에서 실패합니다. 이 스킬은 안전한 순서와 실제 발생한 차단 상황 및 해결 방법을 제공합니다.
아래 사용된 신뢰도 태그: [official] = developers.facebook.com에 명시됨 (표에 URL 포함); [field] = 실제 온보딩에서 발생했으며 해결 방법이 실시간으로 확인됨; [unconfirmed] = 발견되었으나 원인이나 해결 방법이 입증되지 않음. [field] 또는 [unconfirmed]를 Meta 정책으로 제시하지 마십시오.
용어: 이 네 가지를 절대 혼동하지 마십시오
- 비즈니스 포트폴리오 (Business Manager): Meta 내의 회사.
- WhatsApp Business Account (WABA): 포트폴리오 내에 존재합니다. UI에서는 Messaging account ID를 사용하고, "WhatsApp account/presence" ID는 사용하지 마십시오 (후자는 "This API is not supported"를 반환합니다)
[field]. - 전화번호: WABA 내에 존재합니다. Phone number ID는 전화번호 자체가 아닙니다.
- Meta 앱: 개발자 계정에 존재하며 포트폴리오에 연결됩니다. 토큰, 앱 시크릿, 웹훅을 보유합니다.
한도를 언급할 때는 이 네 가지 중 어떤 것에 대한 한도인지 명시하십시오.
계획을 결정하는 한도 [official]
- 새 포트폴리오는 전화번호 2개를 등록할 수 있습니다. 비즈니스가 인증되거나 2,000 메시지 한도에 도달하면 한도가 20개로 상승합니다.
- 메시징 한도는 포트폴리오당, 모든 번호가 공유: 250 → 2,000 → 10,000 → 100,000 → 무제한. 바쁜 번호 하나가 모든 할당량을 소진할 수 있습니다.
- 등록 및 등록 취소: 번호당 72시간 동안 각각 10회 요청; 초과 시 오류 133016이 발생하고 번호가 72시간 동안 차단됩니다. 디버깅 중에 "활성화"를 반복해서 누르지 마십시오.
- WhatsApp Manager 또는 앱 대시보드에서 번호를 추가하는 것은 Cloud API에 등록하는 것이 아닙니다. 등록 호출이 여전히 필요합니다.
- WhatsApp (휴대폰 앱)에서 이미 사용 중인 번호는 해당 계정이 삭제될 때까지 등록할 수 없습니다.
- 번호 삭제: 포트폴리오 관리자만 가능하며, API를 통해서는 불가능하고, 2단계 PIN이 설정된 경우 필요하며, 최근 30일 내에 유료 메시지를 보낸 경우 불가능합니다. 삭제는 되돌릴 수 없는 것으로 간주하십시오.
시작 전 (한 번에 수집)
고객이 보게 될 비즈니스 이름, 법인명, 국가, 전체 주소, 전화번호, 웹사이트 또는 Facebook 페이지, 이메일, 로고, 연결할 번호. 번호에 WhatsApp이 설치되어 있으면 안 됩니다 (설치된 경우 해당 휴대폰에서 WhatsApp 계정을 먼저 삭제). 6자리 PIN을 누가 만들고 보관할지 결정합니다.
안전한 순서 (각 단계는 확인 점검으로 끝남)
- 포트폴리오 (business.facebook.com): 번호를 추가하기 전에 비즈니스 정보를 완전히 작성하십시오 (법인명, 주소, 전화번호, 웹사이트). 비어 있는 상태에서 온보딩은 "귀하의 비즈니스가 WhatsApp 정책을 충족하지 않습니다"(#2494070) 오류로 실패했습니다
[field]. - WhatsApp 계정 + 번호 (포트폴리오 설정 → 계정 → WhatsApp 계정 → 추가 → 새 번호). 표시 이름 = 클라이언트의 비즈니스 이름, 절대 에이전시 이름이 아닙니다. SMS 또는 유선전화의 경우 VOICE로 인증합니다
[official]. 확인 점검: 번호가 WABA 아래에 표시되는지 확인합니다. - Meta 앱 (developers.facebook.com → 앱 만들기 → WhatsApp 사용 사례), WABA를 소유한 동일한 포트폴리오에 연결합니다. 앱이 한 포트폴리오에 있고 WABA가 다른 포트폴리오에 있으면: 모든 것이 초록색으로 표시되고 메시지가 전달되지 않았습니다. 앱을 WABA의 포트폴리오로 이동하여 해결했습니다
[field]. 설정 → 기본: 개인정보/약관/데이터 삭제 URL이 200을 반환해야 하며, 카테고리, 아이콘을 설정합니다. - 시스템 사용자: 해당 포트폴리오에서 앱과 WABA를 자산으로 가지고,
whatsapp_business_messaging+whatsapp_business_management권한이 있는 만료되지 않는 토큰을 생성합니다. 사람이 토큰을 저장되는 곳에 붙여넣습니다. 절대 에코하지 마십시오. - ID (사람이 직접 입력하지 않고 읽어옴):
GET /{waba-id}/phone_numbers→ Phone number ID. 전화번호를 Phone number ID 변수에 저장하면 봇이 고장 났습니다[field]. - 환경 변수: 정확한 호스팅 프로젝트에 설정합니다. 여러 클라이언트 프로젝트에 동일한 변수 이름이 있는 경우: 프로젝트 이름을 말하고 저장 전에 제목을 확인하십시오. 한 클라이언트의 ID가 다른 클라이언트의 프로젝트에 들어가서 실시간 봇이 잘못된 번호를 가리켰습니다
[field]. - 웹훅 (앱 → WhatsApp → 구성):
https://<도메인>/webhook및 확인 토큰;messages필드를 구독합니다 (항상 켜져 있지는 않음). 그런 다음 WABA를 앱에 구독합니다:POST /{waba-id}/subscribed_apps. - 번호 등록:
POST /{phone-number-id}/register(6자리 PIN 사용). 번호에 이미 2단계 인증이 설정된 경우 기존 PIN을 사용합니다[official]. 확인 점검:GET /{phone-number-id}?fields=status,platform_type,name_status→CONNECTED및CLOUD_API. 이전에는PENDING/NOT_APPLICABLE이 표시됩니다[field]. - 앱 게시, 그런 다음 개인 휴대폰에서 "안녕하세요"를 보내고 봇이 응답하는지 확인합니다.
- 결제: 결제 방법, 시간대 및 통화를 WhatsApp 계정에 템플릿을 보내기 전에 설정합니다 (그렇지 않으면 131042 오류)
[official]. - 최종 확인: 번호 상태,
GET /{waba-id}/subscribed_apps에 이 앱만 표시되는지, 웹훅 URL 및 필드,debug_token으로 올바른 앱과 시스템 사용자 토큰을 확인합니다.
표시 이름은 번호가 이미 작동 중인 상태에서 며칠 동안 "검토 중"으로 남을 수 있습니다 [field]. 편집을 클릭하지 마십시오. 편집하면 검토가 다시 시작됩니다.
황금률
- 앱과 WABA는 동일한 포트폴리오에 있어야 합니다. 클라이언트 자체 포트폴리오가 검토 중이라면, 현장에서 검증된 방법은 번호를 작동 중인 포트폴리오(귀하의 것)의 WABA에 넣고, 앱도 같은 포트폴리오에 두는 것입니다 (2개 번호 한도 내에서)
[field]. 공식적인 장기 경로는 Tech Provider가 되어 Embeded Signup을 사용하는 것입니다. - 기본적으로 클라이언트당 하나의 앱을 사용합니다. 앱의 콜백 URL이 기본 대상입니다. Meta는 WABA별 및 번호별 웹훅 재정의를 지원하지만
[official], 테스트하지 않았다면 클라이언트당 하나의 앱을 유지하십시오. - 호스팅 도메인이 변경되면 그 즉시 Meta의 웹훅을 업데이트하고 확인 점검하십시오. 도메인 변경으로 인해 봇이 조용히 중단되었습니다
[field]. - Cloud API에 남아 있어야 하는 번호에 대해 휴대폰에 WhatsApp Business 앱을 설치하는 "계속" 경로를 절대 사용하지 마십시오. 이 경로는 번호를 API에서 제거합니다
[field]. - 먼저 아무것도 깨지 않는 것을 시도하십시오. 등록 취소, 삭제 또는 이동은 Meta가 요구하는 경우에만 최후의 수단으로 사용하십시오 (위의 한도 참조).
- 헬스 체크는 Meta가 초록색이라고 말할 때만 초록색입니다: Meta에서 전화 상태를 읽으십시오. 유효한 토큰은 번호에 대해 아무것도 증명하지 않습니다
[field]. - 포트폴리오 URL로의 리디렉션이 자산의 소유권을 증명하지는 않습니다. 화면에서 포트폴리오 이름을 확인하십시오
[field].
문제 해결
| 증상 | 원인 | 해결 방법 | 태그 / 출처 |
|---|---|---|---|
| 모두 초록색인데 아무것도 도착하지 않음 | 앱과 WABA가 다른 포트폴리오에 있음 | WABA의 포트폴리오에 새 앱 생성; 이전 앱의 웹훅 제거 | [field] |
| 메시지가 두 번 도착함 / "app secret mismatch" 경고 | 두 앱이 동일한 WABA에 구독되어 있음 | 이전 앱의 웹훅 및 구독 제거 | [field] |
| 배포 후 봇이 중단됨 | 웹훅이 여전히 이전 도메인을 가리킴 | 웹훅 업데이트 및 확인 점검 | [field] |
| 클라이언트가 WABA를 공유할 때 "No se pudo asignar el socio" (파트너 할당 불가) | 원인 불명 (새 포트폴리오, 미인증, 계정 검토 중) | 공유를 피하고 하나의 포트폴리오에서 구축 (황금률 참조) | 원인 [unconfirmed], 해결 [field] |
| 개발자 온보딩 중 "Business doesn't meet WhatsApp policy"(#2494070) | 비즈니스 정보 불완전 / 새 포트폴리오 | 비즈니스 정보 완료; 대신 WhatsApp Manager에서 번호 추가 | [field] |
| WABA ID로 "This API is not supported" | "WhatsApp account" ID 사용 | Messaging account ID 사용 | [field] |
상태 PENDING, 플랫폼 NOT_APPLICABLE | 추가했지만 등록하지 않음 | PIN으로 POST /register | [official] + [field] |
| 133005 | 잘못된 2단계 PIN | 번호의 기존 PIN 사용 | 오류 코드 |
| 133006 | 번호가 인증되지 않음 | SMS/VOICE로 인증 후 등록 | 오류 코드 |
| 133008 / 133009 | PIN 시도 횟수 너무 많음 / 너무 빠름 | details에 지정된 시간 동안 대기 | 오류 코드 |
| 133010 | 번호가 플랫폼에 등록되지 않음 | 등록 | 오류 코드 |
| 133015 | 최근에 삭제된 번호, 아직 삭제 중 | 5분 대기 | 오류 코드 |
| 133016 | 72시간 내 등록/등록 취소 요청 10회 초과 | 중단; 차단이 끝날 때까지 대기 | 등록 |
| 133000 | 이전 등록 취소 실패 | 다시 등록 취소 후 등록 | 오류 코드 |
| "Number already has WhatsApp" | 번호가 여전히 휴대폰 앱이나 다른 계정에 있음 | 먼저 해당 WhatsApp 계정 삭제 | 전화번호 |
| 템플릿에서 131042 | 결제 방법, 신용 한도, 시간대 또는 통화가 설정되지 않음, 계정 정지 | WhatsApp Manager에서 결제 수정; 사용자에게 Meta의 error_data.details 텍스트를 보여주고 추측하지 마십시오 | 오류 코드 |
| 소수의 수신자에게만 131042 | Meta 텍스트에 따르면 계정 전체 오류지만, 실제 확인에서 18개 템플릿 중 16개가 전달됨 | 계정 전체 오류로 판단하거나 일시 중지하기 전에 동일 기간의 전달 성공과 실패를 집계 | [field] 휴리스틱 |
| 131049 | "건강한 생태계 참여 유지"를 위해 전달되지 않음 | 재전송 전 최소 24시간 대기 | 오류 코드 |
| 131026 | 수신자가 받을 수 없음 (WhatsApp 없음, 구버전, 약관 문제) | 다른 방법으로 연락 | 오류 코드 |
| 131031 | 정책 위반으로 WABA 제한됨 | Policy Enforcement 및 Health Status API 참조 | 오류 코드 |
| 클릭 투 WhatsApp 광고를 위해 번호를 Facebook 페이지에 연결할 수 없음 | 표시 이름이 아직 검토 중일 가능성 높음 | 승인을 기다린 후, 페이지 → 연결된 계정 → WhatsApp | [unconfirmed] |
기타 공식 페이지: 시작하기 · 메시징 한도 · 웹훅 재정의.
확인되지 않음 (문제가 발생하면 이렇게 말하십시오)
- "No se pudo asignar el socio"의 실제 요구 사항.
- 새로 만들고 인증되지 않은 포트폴리오가 WABA를 생성할 수 있는지 여부.
- WABA 간 번호 이동: Meta 가이드에 따르면 새로운 계정 모델의 계정에서는 지원되지 않습니다. 현장에서 완료된 사례가 없습니다.
- 공식 표시 이름 검토 시간. 2026년 11월에 두 공식 URL이 404를 반환했습니다.
역할 분담
에이전트는 가능한 모든 화면과 API 확인을 수행합니다. 사람은 기계가 할 수 없는 것만 제공합니다: 휴대폰의 SMS/음성 코드, PIN, 비밀 붙여넣기, 신원 확인, 결제.