Alexgub84/meta-whatsapp-cloud-api

meta-whatsapp-cloud-api은(는) 무엇을 하나요?

이 절차는 2026-11-08에 실제 Meta Business Suite 및 개발자 콘솔을 대상으로 마지막으로 검증되었습니다. Meta는 이러한 화면, 필드 이름 및 마법사 흐름을 자주 그리고 예고 없이 변경합니다. 아래 단계가 실제 보이는 것과 일치하지 않으면 추측하지 말고 이 리포지토리에 이슈를 열고, 수정 사항을 찾으면 PR을 보내주십시오.

절대 하지 말 것

• 거부된 인증을 같은 날 재제출하지 마십시오. 실제 문제를 해결하고 24시간 기다린 후 제출하십시오. 같은 날 재시도는 더 긴 검토를 받는 경향이 있습니다.
• 비즈니스 정보에 입력된 법적 이름, 주소 또는 전화번호를 추측하거나 "정리"하지 마십시오. 이를 증명하기 위해 업로드할 문서에서 문자 그대로 복사하십시오.
• 장기간 pending 상태를 "Meta가 느린 것뿐"이라고 생각하지 말고 실제 상태 필드를 다시 확인하십시오(§2 참조). 조용히 "추가 정보 필요"로 바뀔 수 있으며, 알림 이메일은 아무도 적극적으로 확인하지 않는 받은 편지함에 도착하는 경향이 있습니다.
• 개인 사업자의 세금 등록 증명서를 법적 이름 또는 주소 증명으로 제공하지 마십시오. 해당 목적에 대해 Meta의 승인 문서 목록에 해당 지역의 등가물이 없는 경우 — §1의 작업 예시를 참조하십시오. Meta는 문서가 "승인되지 않은 유형"이라고 명확히 밝힙니다. 잘 알려진 공식 지역 문서라고 해서 승인될 것이라고 가정하지 말고 그 메시지를 읽으십시오.
• 웹사이트 실제 홈페이지에 법적 비즈니스 이름이 없는 상태에서 제출하지 마십시오. Meta는 소개 또는 이용약관 페이지가 아닌 /를 가져오며, 이름이 없으면 특히 이 문제로 인증에 실패합니다.
• 작업을 돕기 위해 외부 협력자를 전체 포트폴리오 사용자로 추가하지 마십시오. 이는 Meta 자체 목록에서 명시적인 거부 사유입니다. 대신 더 좁은 파트너/협력자 액세스 수준을 사용하십시오.
• 인증 코드, 2단계 PIN 또는 비밀번호를 계정 소유자가 입력하는 Meta 자체 콘솔 외부에 입력하지 마십시오.

1. 비즈니스 인증

인증이 무엇이고 무엇이 아닌지

Meta Business Suite의 비즈니스 인증은 유료 Meta Verified 구독과 다른 것이며, 인증 배지를 생성하지 않습니다. Meta는 이를 직접 명시합니다: "Meta Business Suite에서 비즈니스를 인증하는 것은 Meta Verified for businesses와 다르며 인증 배지를 제공하지 않습니다." (Meta Business Help Center, "How to verify your business in Meta Business Suite", https://www.facebook.com/business/help/2058515294227817, 2026-11-09 확인 — 동일한 문장은 https://www.facebook.com/business/help/2342133782492969에서도 재진술됨, 2026-11-09 확인). 인증 배지는 특히 Meta Verified 혜택입니다: "Meta Verified for businesses는 새로운 잠재 고객과의 신뢰를 구축하고 브랜드를 보호하는 데 도움이 되는 도구를 제공하는 유료 구독입니다. 이 구독에는 인증 배지, 향상된 지원, 사칭 방지 등과 같은 혜택이 포함됩니다." (https://www.facebook.com/business/help/308979828303560, 2026-11-09 확인). Meta Verified는 정기적으로 청구되며 이 스킬이 다루는 무료 인증 절차와는 별도의 구매입니다.

비즈니스 인증이 실제로 잠금 해제하는 것은 Meta 자신의 말로: "비즈니스 인증은 특정 광고, 개발자, 청구 및 지출 기능에 액세스하는 데 필요합니다." (https://www.facebook.com/business/help/2058515294227817, 2026-11-09 확인). https://www.facebook.com/business/help/1095661473946872 (2026-11-09 확인)에서 더 자세히 설명됨: 일일 지출 한도, 적격 개발자 기능, Meta Business Partners 액세스, 뉴스 페이지 색인, WhatsApp Business Platform, 페이지 투명성, 중국 기반 대행사, 금융 서비스 광고주 상태. WhatsApp Business Platform의 경우 동일 페이지에서: "WhatsApp Business Platform을 사용하는 비즈니스는 특정 기능에 액세스하기 위해 인증을 완료해야 할 수 있습니다." 개발자 측면에서: "고급 액세스에는 이제 비즈니스 인증이 필요합니다... 권한에 대한 고급 액세스를 요청하는 앱과 다른 비즈니스가 자체 데이터에 액세스할 수 있도록 허용하는 앱은 비즈니스 인증을 완료한 비즈니스에 연결되어야 합니다." (https://developers.facebook.com/docs/development/release/business-verification/, 2026-11-09 확인).

위 페이지 또는 WhatsApp 계정 확장 페이지(https://www.facebook.com/business/help/595597942906808, 2026-11-09 확인)에서 확인되었으나 찾을 수 없음: Meta가 중단하기 전에 몇 번 재제출해야 하는지 또는 문서를 다시 제출하지 말고 근본적으로 수정하라는 조언에 대한 어떠한 진술도 없습니다. 해당 조언은 타사 에이전시 블로그에서 흔하지만 Meta는 이 스킬을 위해 확인된 어느 곳에서도 말하지 않으므로 여기서 사실로 반복되지 않습니다. 아래 "절대 하지 말 것" 목록은 Meta 자체 페이지가 지원하는 내용(횟수가 아닌 타이밍 규칙)을 따릅니다.

올바른 문서 세트 선택

Meta 자체 승인 문서 카테고리(인증 시도가 실제로 실행된 후에만 나타나는 "세부 정보 및 다음 단계" 대화 상자에서 직접 읽음):

증명 대상	승인 유형
법적 비즈니스 이름	법인 등기 증명서/정관, 사업자 등록증 또는 허가증, 은행 거래 명세서, 은행 공문
주소	동일한 네 가지 유형에 추가로 수도·가스·전기·전화 공과금 고지서

등록된 회사의 경우 법인 등기 증명서가 일반적으로 가장 깔끔한 단일 문서입니다. 회사 등록이 없는 개인 사업자의 경우 정확히 동등한 문서가 없는 경우가 많습니다. 명백한 문서처럼 느껴지더라도 관할 구역의 일반적인 소규모 사업 세금 등록 증명서가 해당된다고 가정하지 마십시오. 작업 예시(이스라엘): 이스라엘 개인 사업자의 עוסק פטור/עוסק מורשה 증명서는 Meta에 의해 명시적으로 거부됩니다( "승인되지 않은 유형"), 이스라엘에서 합법적인 거래 상태의 표준 증명서임에도 불구하고. 대신 작동한 것은 법적 이름에 대한 은행 계좌 소유권 공문(대부분의 은행에서 비즈니스 인증을 위해 요청 시 발행 가능)과 주소에 대한 공과금 고지서였습니다 — 각각 승인된 두 카테고리 중 하나에서 각각 한 장의 문서로, 각 문서에 비즈니스 정보에 입력된 대로 이름 또는 주소를 정확히 인쇄합니다.

관할 구역에 관계없이 적용되는 일반 규칙:

• 이름과 주소를 완전하고 명확하게 모두 포함하는 단일 문서는 한 번의 업로드로 두 요구 사항을 모두 충족합니다.
• 히브리어 또는 비영어 스크립트는 그대로 허용되며 번역이 필요하지 않지만, 이름/주소에 대해 하나의 언어를 선택하고 비즈니스 정보, 웹사이트 홈페이지 및 문서 자체에서 일관되게 사용하십시오.
• 시도할 가치가 없는 것으로 간주하여 즉시 거부: 임대차 계약서, 개인(비사업) 청구서, 포털 페이지 스크린샷, 자르거나 주석 처리하거나 편집된 모든 것, 공식 등록 서류를 제외하고 약 90일보다 오래된 문서.
• 한 파일 형식에서 다른 형식으로의 충실한 전체 페이지 렌더링(PDF에서 고해상도 PNG 등)은 괜찮습니다. 어떤 부분을 자르거나 다시 입력하는 것은 허용되지 않습니다.

제출 전 포트폴리오 준비

• 비즈니스 정보 필드는 업로드된 문서를 구두점 및 법적 접미사까지 포함하여 정확히 반영해야 합니다(회사 접미사 "Ltd"는 두 곳에 모두 나타나거나 전혀 없어야 함). 표준화할 언어를 결정하고 모든 곳에서 사용하십시오.
• 웹사이트에 접속 가능해야 하고, HTTPS를 제공해야 하며, 어떤 페이지에도 오류나 공사 중 상태가 없어야 하고, 별도로 확인되며 접속 가능성과 독립적으로 실패하는 조건으로 홈페이지에 정확한 법적 이름이 표시되어야 합니다. 최근에 등록된 도메인은 의심을 더 받을 가능성이 있습니다. 약간의 연식이 있는 도메인이 더 유리합니다.
• 비즈니스 이메일은 웹사이트와 동일한 도메인에 있어야 합니다. 무료 소비자 이메일 도메인은 거부율을 눈에 띄게 높이고 그렇지 않은 경우에도 검토를 지연시킵니다.
• 비즈니스에 정직하게 맞는 목록 카테고리를 선택하십시오. 민감한 카테고리(금융, 건강, 도박, 주류)는 추가 심사와 추가 필수 문서를 초래합니다.
• 포트폴리오에 두 명의 관리자가 있고 둘 다 2단계 인증이 활성화되어 있으면 마찰이 줄어드는 경향이 있습니다. 보호되지 않은 단독 관리자는 그 자체로 거부 트리거로 나열됩니다.
• 인증해야 하는 자산(보통 WABA)은 시작하기 전에 이미 포트폴리오에 연결되어 있어야 합니다. 그렇지 않으면 인증 진입점 자체가 "자격 없음"으로 회색 처리됩니다.

위의 문제가 해결된 후에도 웹사이트가 자체 확인에 계속 실패하면 Meta는 작동하는 웹사이트 대신 비즈니스 신원을 확인하는 두 가지 대체 방법을 문서화합니다: 비즈니스와 진정으로 관련된 다른 도메인의 확인 이메일 또는 대신 비즈니스 전화번호로 확인.

확인 채널에 따라 필요한 문서가 변경됩니다

마법사 중에 선택한 확인 채널에 따라 업로드 단계에서 실제로 요청하는 내용이 변경됩니다:

• 채널로 전화 통화, SMS 또는 WhatsApp 메시지 → 마법사는 법적 이름 및 전화번호를 증명하는 문서를 요청합니다.
• 채널로 이메일 → 마법사는 법적 이름 및 주소 또는 전화번호를 증명하는 문서를 요청합니다.

따라서 실제로 얻기 가장 쉬운 문서에 맞게 채널을 선택하십시오(반대가 아니라). 은행 공문과 공과금 고지서가 가능한 경우 이메일을 선택하십시오.

제출

인증 진입점(현재 Meta 레이아웃의 Security Center)으로 이동하여 인증 대상과 일치하는 사용 사례를 선택하고(일반적으로 WhatsApp Business 계정 설정 전용 옵션이 있음 — 둘 다 존재하는 경우 일반 "앱 권한" 옵션보다 선호), 마법사를 진행합니다: 국가, 비즈니스 유형(미등록 개인 사업자는 일반적으로 "개인 사업"이며, 공식 회사 없이도 지역 세무 당국에서 등록 번호를 발급한 경우 "등록됨"으로 대답하는 경우가 많음), 비즈니스 세부 정보, CAPTCHA(항상 사람이 완료해야 하며 자동화된 에이전트는 안 됨), 공개 기록 일치 단계, 확인 채널, 문서 업로드, 최종 검토/제출.

해당 공개 기록 단계 및 업로드 단계에서 예상되는 두 가지 함정:

• Meta는 그럴듯해 보이지만 유사한 이름을 가진 다른 무관한 법인에 속하는 공개 기록 일치를 제공할 수 있습니다. 일치를 수락하기 전에 모든 식별 세부 정보(주소, 도메인, 표시된 세금 또는 등록 번호)를 확인하십시오. 다른 사람의 비즈니스 기록을 주장하는 것은 이 한 번의 인증 실패뿐만 아니라 전체 포트폴리오를 제한할 수 있는 정책 위반입니다. 의심스러우면 "내 비즈니스가 목록에 없습니다"를 선택하십시오.
• 일부 문서 업로드 단계는 놓치기 쉬운 토글("문서에 전화번호나 주소가 포함되어 있습니까?")의 기본값을 "아니요"로 설정하여, 대부분의 신청자가 가지고 있지 않은 완전히 별도의 두 번째 문서를 요구합니다. 이미 업로드된 단일 문서에 두 정보가 모두 포함되어 있으면 해당 토글을 "예"로 전환하면 추가 단계가 사라집니다.

제출 후 채널 확인 제출의 경우 약 1-2 영업일, 문서 기반 제출의 경우 3-7일(Meta의 정기 정책 업데이트 기간 동안 최대 14일)이 예상됩니다. "보류 중"인 동안 제출을 건드리지 마십시오 — 관리자를 추가하거나 설정을 변경하거나 충동적으로 지원 스레드를 열지 마십시오. 대기 중인 검토 속도를 높이는 것은 없으며, 제출된 내용과 불일치를 만드는 것은 해로울 수밖에 없습니다.

이메일에 의존하지 않고 "추가 정보 필요" 감시

상태 변경에 대한 Meta의 알림은 포트폴리오의 관리자 연락처로 설정된 이메일 주소로 전송됩니다. 이는 매우 자주 매일 확인하는 받은 편지함이 아닙니다. API 액세스가 이미 존재하는 경우 브라우저 없이 안정적인 확인 방법은 직접 API 호출입니다:

curl -s "https://graph.facebook.com/v21.0/$WABA_ID?fields=business_verification_status" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

실제로 확인된 값: pending(Meta 차례, 기다리는 것 외에 할 일 없음), pending_need_more_info(사용자 차례 — 콘솔에서 정확히 무엇을 요구하는지 읽으십시오. 이 필드만으로는 알 수 없음), verified. 알림을 기다리지 말고 정기적으로 이 값을 폴링하십시오. 상태가 조용히 "추가 정보 필요"로 전환되고 실제로 누군가 알아차리기까지의 간격으로 인해 실제 제출물이 전체 검토 주기를 잃은 사례가 있습니다.

2. Cloud API 구축(인증이 완료되기 전에도 작동)

아래의 모든 단계는 인증되지 않은 포트폴리오에서도 작동합니다. 인증은 메시징 볼륨 상한선만 변경할 뿐 API 자체의 작동 여부는 변경하지 않습니다. 하나가 완료될 때까지 기다리지 말고 병렬로 진행하십시오. 비즈니스 포트폴리오는 1단계 전에 이미 존재해야 합니다(business.facebook.com에서 생성). 아래 단계는 새 앱을 기존 포트폴리오에 연결할 뿐 새로 생성하지 않습니다.

1. 앱 생성. 개발자 콘솔에서 WhatsApp 중심 사용 사례("WhatsApp을 통해 고객과 연결" 또는 현재 콘솔에서 부르는 동등한 용어)를 사용하여 앱을 만들고 기존 비즈니스 포트폴리오에 연결하십시오. 이를 위해 새 포트폴리오를 만들지 마십시오. 인증이 처음부터 다시 시작됩니다.
2. WhatsApp Business Account(WABA) 연결 또는 생성. 앱의 WhatsApp 설정 패널은 기존 WABA에 연결하거나 새로 만듭니다. WABA ID와 테스트 전화번호의 ID를 영구적으로 기록해 두십시오.
3. 먼저 Meta에서 발급한 테스트 번호를 사용해 보십시오. 제한된 평가판 기간 동안 무료이며, 소수의 사전 승인된 수신자 번호(각각 허용 목록에 추가하는 일회성 코드 필요)를 지원하며, 실제 SIM이 개입되기 전에 웹훅 및 메시지 전송 코드가 작동하는지 증명하는 가장 빠른 방법입니다.
4. 시스템 사용자 액세스 토큰 생성(임시 사용자 토큰이 아님). 올바른 역할(관리 액세스 권한이 있는 앱에 할당됨)을 가진 시스템 사용자는 만료되지 않는 토큰을 생성할 수 있습니다. 필요한 권한은 일반적으로 메시징 및 WABA 관리 범위입니다. 통합이 API를 통해 인증 상태를 읽거나 WABA를 삭제해야 하는 경우 더 넓은 비즈니스 관리 범위도 필요합니다. 빠른 시작 가이드의 임시 토큰은 학습 목적으로는 괜찮지만 프로덕션에는 적합하지 않습니다. 시스템 사용자 생성은 Business Settings > Users > System Users에서 수행합니다.
5. 웹훅 구성 및 확인. 개발자 콘솔의 WhatsApp > Configuration > Webhook URL에 공개적으로 도달 가능한 HTTPS 엔드포인트를 설정합니다. 확인 토큰을 입력합니다. Meta가 GET 요청을 보내 hub.challenge를 반환하는지 확인합니다. 그런 다음 확인이 완료되면 구독할 이벤트(메시지, 상태, 템플릿)를 선택합니다.
6. 스모크 테스트. 테스트 번호를 사용하여 웹훅이 수신 메시지를 수신하는지 확인합니다. 그런 다음 API를 통해 발신 메시지를 전송합니다:

curl -X POST "https://graph.facebook.com/v21.0/$PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "$RECIPIENT_NUMBER",
    "type": "text",
    "text": {"body": "Hello from the WhatsApp Cloud API!"}
  }'

7. 실제 전화번호 추가. 테스트 번호가 작동하면 Business Manager에서 실제 전화번호를 추가합니다. 이 번호는 SMS 또는 음성 통화로 확인해야 하며 다른 WhatsApp Business Platform 인스턴스에서 사용 중이어서는 안 됩니다.
8. 메시지 템플릿 생성. 마케팅, 유틸리티, 인증 또는 서비스 업데이트 템플릿을 만듭니다. 각 템플릿은 사용하기 전에 Meta의 승인이 필요합니다. 승인은 일반적으로 영업일 기준 1-2일이 소요됩니다. 승인 대기 중인 템플릿은 사용할 수 없습니다.
9. 프로덕션 전환. 모든 것이 작동하면 테스트 번호에서 실제 번호로 전환하고, 시스템 사용자 토큰을 프로덕션 환경 변수로 이동하며, 인증이 완료되면 메시징 제한이 제거됩니다.

일반적인 문제 해결

문제	가능한 원인	해결 방법
인증이 "pending_need_more_info"로 표시됨	누락된 문서 또는 불일치	콘솔에서 정확한 요청 사항 확인 및 문서 업데이트
웹훅 확인 실패	엔드포인트에 도달할 수 없거나 잘못된 토큰	엔드포인트가 HTTPS를 제공하고 인터넷에서 액세스 가능한지 확인
메시지 전송 실패(오류 1006)	인증되지 않은 번호 또는 볼륨 제한 초과	번호 인증 상태 확인 또는 나중에 재시도
시스템 사용자 토큰이 작동하지 않음	잘못된 범위	토큰에 메시징 및 WABA 관리 권한이 포함되어 있는지 확인

참고 사항

• Meta는 예고 없이 콘솔 UI를 변경합니다. 단계가 정확하지 않으면 문제를 제출해 주십시오.
• 이 스킬은 무료 인증 절차를 다룹니다. Meta Verified(유료)는 별도 구매입니다.
• 모든 API 호출은 적절한 속도 제한을 준수해야 합니다. 자세한 내용은 Meta API 속도 제한 문서를 참조하십시오.

라이선스

MIT