Meta Cloud API 자격 증명과 서명된 웹훅으로 WhatsApp Business 번호를 연결합니다.
Meta Cloud API 자격 증명과 서명된 웹훅으로 WhatsApp Business 번호를 연결합니다.
Meta 앱과 번호 준비하기#
Meta 공식 WhatsApp Cloud API 시작 가이드를 사용해 Meta 앱을 만들거나 선택하고 WhatsApp 제품을 추가한 뒤 WhatsApp Business 계정과 전화번호를 연결합니다.
같은 앱과 번호에서 다음 세 값을 수집하세요.
| Make Agent Fast 필드 | 제공자 값 | 참고 |
|---|---|---|
| 전화번호 ID | 숫자 Phone Number ID | 보이는 + 전화번호나 WABA ID가 아님 |
| 액세스 토큰 | Cloud API 액세스 토큰 | 대시보드 임시 토큰은 만료되므로 운영에서는 적절한 장기 시스템 사용자 토큰 사용 |
| 앱 시크릿 | Meta 앱 시크릿 | 웹훅 서명 검증에 쓰는 32자 16진수 시크릿 |
번호와 메시징 흐름에 필요한 권한만 부여하세요. 개발/테스트 자산은 운영 번호와 분리합니다.
자격 증명 저장 및 검증#
사이트의 커넥터 페이지에서 WhatsApp을 선택하고 세 값을 입력한 뒤 필요하면 음성으로 답하기를 선택하고 연결을 누릅니다.
Make Agent Fast는 액세스 토큰과 appsecret_proof를 사용해 Graph API에서 번호를 검증하므로 웹훅 트래픽 시작 전에 잘못된 번호, 토큰, 앱 시크릿을 찾습니다. 연결 후 커넥터 카드에 고유 웹훅 URL과 인증 토큰이 표시됩니다.
Meta 웹훅 설정하기#
같은 Meta 앱에서 다음을 수행합니다.
- WhatsApp 웹훅 설정을 엽니다.
- 커넥터 웹훅 URL을 콜백 URL로 붙여 넣습니다.
- 대소문자를 포함해 커넥터 인증 토큰을 정확히 붙여 넣습니다.
- 검증을 완료합니다.
- WhatsApp Business 계정/번호의
messages웹훅 필드를 구독합니다. - 대상 테스트 또는 운영 사용자가 앱과 비즈니스 자산을 사용할 수 있는지 확인합니다.
인증 토큰은 GET 검증 챌린지에서 소유권을 증명합니다. 런타임 POST 요청은 Meta 앱 시크릿 서명으로 별도 인증되므로 서로 바꿔 사용하지 마세요.
텍스트 및 음성 테스트#
먼저 허용된 테스트 번호에서 메시지를 보냅니다. Meta 개발 모드에서는 등록되지 않은 사용자가 앱에 접근하지 못할 수 있습니다. 대화의 스레드/채널과 커넥터 카드의 마지막 메시지를 확인합니다.
텍스트와 음성 수신을 지원합니다. 음성으로 답하기가 켜지고 음성이 설정되면 Make Agent Fast가 Cloud API로 생성 오디오를 업로드하고 텍스트 응답과 함께 보냅니다. 이미지, 위치, 연락처 등 지원하지 않는 메시지 유형은 무시됩니다.
운영 준비#
번호를 공개하기 전에 사용 사례에 필요한 Meta 비즈니스 검증, 앱 검토, 표시 이름, 템플릿, 메시징 정책 단계를 완료하세요. 이 요구 사항은 Meta가 제어하며 Make Agent Fast와 별도로 변경될 수 있습니다.
명확한 소유자와 만료/교체 절차가 있는 운영 자격 증명을 사용하세요. 운영자가 추측 없이 교체하도록 이 커넥터의 Meta 앱, 시스템 사용자, WABA, Phone Number ID를 기록합니다.
교체 또는 연결 해제#
같은 자산 접근 권한의 교체 토큰을 만들고 커넥터를 업데이트해 테스트한 뒤 이전 토큰을 폐기합니다. 앱 시크릿이 바뀌면 즉시 Make Agent Fast도 업데이트해야 하며 그렇지 않으면 모든 서명된 수신 웹훅이 실패합니다.
커넥터를 끄거나 삭제해도 Meta 웹훅 설정은 구독 해제/삭제되지 않습니다. 번호를 영구 종료할 때 제공자 구독도 제거하세요.
문제 해결#
| 증상 | 해결 방법 |
|---|---|
| 자격 증명 거부 | 토큰이 정확한 Phone Number ID를 읽을 수 있고 앱 시크릿이 같은 앱 값인지 확인 |
| Meta가 콜백 검증 실패 | 복사된 HTTPS URL과 정확한 인증 토큰을 사용하고 커넥터가 남아 있는지 확인 |
| 검증되지만 메시지가 오지 않음 | messages 구독, WABA/번호 연결, 앱 모드, 테스트 사용자, 제공자 전달 로그 확인 |
| 웹훅 unauthorized | 올바른 앱 시크릿 재입력; Meta POST 서명은 인증 토큰을 사용하지 않음 |
| 발신 응답 실패 | 토큰 만료, 번호 권한, 수신자 정책/기간, Graph API 오류 확인 |
| 텍스트는 되지만 오디오 실패 | 전사/음성 제공자 키와 토큰의 미디어 업로드/다운로드 권한 확인 |
브라우저 코드에 액세스 토큰이나 앱 시크릿을 노출하지 마세요. 커넥터 생성을 자동화할 때 Public API는 신뢰할 수 있는 서버에서만 사용합니다.