WhatsApp Business 설정

WhatsApp을 연결하면 고객이 WhatsApp Business 번호로 보낸 메시지가 소셜 받은 편지함에 표시되고, 팀(또는 Lora)이 NextCRM에서 답할 수 있습니다. NextCRM은 Meta의 공식 WhatsApp Business Platform(Cloud API)을 사용합니다. 휴대폰의 일반 WhatsApp Business 앱은 연결할 수 없습니다.

처음 설정하는 데는 약 30-60분이 걸립니다. 작업은 두 곳에서 진행합니다: Meta for Developers / Meta 비즈니스 설정, 그리고 NextCRM의 구성 > 소셜.

NextCRM이 지원하는 WhatsApp 기능

• 수신: 텍스트 메시지, 버튼 응답, 이미지와 문서의 캡션. 그 밖의 메시지 유형(예: 음성 메시지나 스티커)은 [audio] 같은 자리 표시자로 표시됩니다. 미디어 파일 자체는 내려받지 않습니다.
• 발신: 소셜 받은 편지함의 일반 텍스트 답장, 자동 조종 모드의 Lora 답장, WhatsApp 캠페인.
• 지원되지 않음: 승인된 메시지 템플릿 발송, 전송 및 읽음 확인, 연결 이전 채팅 가져오기.

시작하기 전에

• 워크스페이스 관리자 또는 영업 관리자 역할과 소셜 받은 편지함이 포함된 요금제가 필요합니다.
• 관리자 권한이 있는 Meta 비즈니스 계정(비즈니스 포트폴리오)이 필요합니다.
• WhatsApp용 전화번호가 필요합니다. 이 번호는 휴대폰의 WhatsApp 또는 WhatsApp Business 앱에서 사용 중이면 안 되며, 사용 중이라면 먼저 플랫폼으로 이전해야 합니다. 테스트용으로는 Meta가 무료 테스트 번호를 제공합니다.

각 값을 얻는 곳

WhatsApp 카드에서 설정을 클릭하면 각 필드 옆에 있는 (i) 아이콘에도 같은 정보가 표시됩니다.

NextCRM 필드	얻는 곳	링크
앱 비밀	Meta for Developers > My Apps > 내 앱 > App settings > Basic > App secret(Show 클릭). Meta가 모든 웹훅에 이 값으로 서명합니다.	https://developers.facebook.com/apps
액세스 토큰	시스템 사용자의 영구 토큰: Meta 비즈니스 설정 > Users > System users > Generate new token에서 whatsapp_business_messaging 및 whatsapp_business_management 권한으로 생성합니다.	https://business.facebook.com/settings/system-users
전화번호 ID	전화번호 자체가 아니라 번호의 ID입니다: Meta for Developers > 내 앱 > WhatsApp > API Setup에서 From 번호 아래에 표시됩니다.	https://developers.facebook.com/apps
확인 토큰	직접 정한 비밀번호. Meta for Developers > 내 앱 > Webhooks(WhatsApp: WhatsApp > Configuration)에서 같은 값을 Verify token으로 입력합니다.	https://developers.facebook.com/apps
웹훅 URL	처음 저장한 후 카드에 표시됩니다. 공급자의 웹훅 설정에 콜백 URL로 그대로 붙여 넣습니다.	https://developers.facebook.com/apps

설정 순서: WhatsApp이 포함된 Meta 앱 만들기(1단계) > 영구 액세스 토큰 만들기(2단계) > 값과 확인 토큰을 NextCRM에 붙여 넣고 저장(3단계) > Meta에서 웹훅 연결(4단계) > 테스트 메시지 보내기(5단계).

1단계: WhatsApp이 포함된 Meta 앱 만들기

1. Meta for Developers를 열고 앱을 만듭니다. WhatsApp을 제공하는 비즈니스 유형 또는 사용 사례를 선택하고 비즈니스 포트폴리오에 연결합니다.
2. 앱에 WhatsApp 제품을 추가합니다.
3. WhatsApp API Setup 페이지를 엽니다(이름이 약간 다를 수 있습니다). 여기에서 다음을 확인할 수 있습니다.

• 테스트 번호 또는 자체 번호의 Phone number ID,
• WhatsApp Business Account ID,
• 테스트용 임시 액세스 토큰.

4. 앱의 기본 설정에서 App secret을 복사합니다. NextCRM에는 App ID와 WhatsApp Business Account ID가 필요하지 않습니다.

참고: 전화번호 자체가 아니라 Phone number ID를 복사하세요. Meta가 전화번호 옆이나 아래에 표시하는 긴 숫자입니다.

2단계: 영구 액세스 토큰 만들기

API Setup 페이지의 임시 토큰은 약 24시간 후에 작동을 멈춥니다. 일상적으로 사용하려면 시스템 사용자용 토큰을 만드세요.

1. Meta 비즈니스 설정을 열고 Users > System users로 이동합니다.
2. 시스템 사용자를 추가하거나(관리자 시스템 사용자도 괜찮습니다) 기존 사용자를 선택합니다.
3. 시스템 사용자에게 자산을 할당합니다: 앱과 WhatsApp 계정에 전체 권한을 부여합니다.
4. 새 토큰 생성을 클릭하고, 앱을 선택한 다음, 계정에서 제공하는 경우 만료되지 않는 토큰을 선택합니다.
5. 권한을 선택합니다. 예: whatsapp_business_messaging, whatsapp_business_management.
6. 토큰을 복사하여 안전하게 보관합니다. Meta는 토큰을 한 번만 표시합니다.

3단계: NextCRM에 정보 입력하기

::video[/help/videos/{lang}/social-connect.webm]{caption="동영상: 연결 방법 패널과 각 값을 붙여 넣을 위치" captions="/help/videos/{lang}/social-connect.vtt" poster="/help/videos/{lang}/social-connect.jpg"}

1. 구성 > 소셜을 열고(소셜 단계 열기) WhatsApp 카드를 찾아 설정을 클릭합니다. 필드, 실시간 커넥터 전송 상자, WhatsApp 연결 방법 패널은 이 버튼을 클릭한 후에만 나타납니다.
2. 다음 필드를 입력합니다.

NextCRM 필드	붙여 넣을 값
앱 비밀	Meta 앱의 App secret(필수: Meta가 모든 웹훅에 이 값으로 서명함)
액세스 토큰	2단계에서 만든 영구 시스템 사용자 토큰(필수)
확인 토큰	직접 정한 비밀번호(예: 길고 무작위적인 문자열, 필수)
전화번호 ID	API Setup 페이지의 Phone number ID(필수)

*가 표시된 필드는 필수입니다.

3. 저장을 클릭합니다. 이제 실시간 커넥터 전송 상자의 웹훅 URL이 ?hook=와 워크스페이스 코드로 끝납니다. 공급자 계정 ID에는 전화번호 ID가 표시됩니다.
4. 카드 상단의 비활성화됨을 클릭하여 활성화됨으로 바꿉니다. 카드가 활성화되어 있을 때만 메시지가 수신됩니다.

4단계: Meta에서 웹훅 연결하기

1. Meta 앱에서 WhatsApp > Configuration을 열고 웹훅을 편집합니다.
2. Callback URL: NextCRM의 웹훅 URL을 그대로 붙여 넣습니다. 예:

https://…/api/social/webhooks/whatsapp?hook=hook_EXAMPLE123

3. Verify token: NextCRM에 저장한 것과 같은 확인 토큰을 입력합니다.
4. Verify and save를 클릭합니다. Meta가 NextCRM을 호출하고, 토큰이 일치하면 NextCRM이 확인해 줍니다.
5. 웹훅 필드에서 messages를 구독합니다.

앱 비밀이 중요한 이유: Meta는 이 확인 과정에서만 확인 토큰을 보냅니다. 이후의 모든 메시지는 Meta가 앱 비밀로 서명하며, NextCRM은 서명이 일치하지 않는 메시지를 거부하므로 앱 비밀은 같은 앱의 것이어야 합니다. 콜백 URL에 확인 토큰을 추가하지 마세요. &token=...으로 끝나는 기존 콜백 URL도 해당 토큰이 저장된 값과 일치하는 한 계속 작동합니다.

5단계: 테스트하기

1. 테스트 번호를 사용하는 경우 API Setup 페이지에서 본인의 휴대폰 번호를 허용된 수신자로 추가합니다. 테스트 번호는 이곳에 추가한 소수의 번호와만 대화할 수 있습니다.
2. 휴대폰에서 비즈니스 번호로 WhatsApp 메시지를 보냅니다.
3. 소셜 받은 편지함을 엽니다(소셜 받은 편지함 열기). 대개 몇 초 안에 WhatsApp 아래에 채팅이 표시됩니다.
4. NextCRM에서 답하고 휴대폰에 도착하는지 확인합니다.

테스트 번호와 실제 번호: 테스트 번호는 무료이며 설정을 확인하는 데 적합하지만 실제 고객과는 사용할 수 없습니다. 실제 운영을 시작하려면 WhatsApp Manager에서 자체 번호를 추가하고 인증한 뒤, 비즈니스 인증과 표시 이름 승인 등 Meta가 요구하는 절차를 완료하세요. 그런 다음 NextCRM에서 전화번호 ID를 바꾸고 저장을 클릭합니다.

24시간 고객 서비스 기간

WhatsApp은 고객의 마지막 메시지로부터 24시간 이내에만 자유 형식 메시지를 허용합니다. 그 이후에는 기업이 사전 승인된 메시지 템플릿을 사용해야 합니다.

• 고객의 마지막 메시지로부터 24시간 이내에 소셜 받은 편지함에서 답하세요.
• NextCRM은 템플릿이 아닌 일반 텍스트만 보냅니다. 이 기간이 지나면 Meta가 메시지를 받아들이더라도 전달하지 않을 수 있습니다. NextCRM은 전송 보고서를 받지 않으므로, 고객이 메시지를 받지 못했더라도 NextCRM에서는 발송됨으로 표시될 수 있습니다.
• 24시간이 지난 후 연락해야 한다면 Meta 도구에서 템플릿을 사용하거나 고객에게 먼저 메시지를 보내 달라고 요청하세요.

WhatsApp 캠페인

캠페인 > 새 캠페인 > WhatsApp(WhatsApp 캠페인 열기)에서 퍼널의 리드에게 텍스트 메시지를 보낼 수 있습니다. 편집기는 이메일 캠페인과 같은 4단계 마법사입니다(기본 정보, 대상, 메시지, 예약 및 발송).

상단 배지에는 WhatsApp 카드가 활성화되어 있고, 액세스 토큰과 전화번호 ID가 있으며, Meta가 자격 증명을 수락한 경우에만 연결됨이 표시됩니다. 그렇지 않으면 구성되지 않음, 저장됨, 확인되지 않음 또는 자격 증명 거부됨이 표시됩니다. 캠페인 예약 또는 캠페인 보내기를 클릭했을 때 WhatsApp이 준비되지 않았다면 취소, 초안으로 저장, 초안 저장 및 WhatsApp 설정 열기가 있는 연결 필요 창이 나타납니다(설정을 열 수 없는 사용자에게는 마지막 버튼 대신 관리자에게 요청하라는 안내가 표시됨). 캠페인은 초안으로 보관됩니다.

캠페인은 답장과 같은 일반 텍스트 발송 방식을 사용하므로 24시간 규칙이 적용됩니다. 캠페인 메시지는 일반적으로 지난 24시간 이내에 WhatsApp 번호로 메시지를 보낸 리드에게만 도달합니다. 리드의 전화번호는 국제 형식이어야 합니다(예: +491701234567). 국가 코드가 없는 번호는 +1(미국/캐나다)로 처리됩니다.

자주 발생하는 오류

• Meta가 콜백 URL 또는 확인 토큰을 검증하지 못함: Meta의 확인 토큰이 NextCRM에 저장된 값과 다르거나, 처음 저장하기 전에 웹훅 URL을 복사한 경우입니다(?hook= 부분 누락). NextCRM에서 저장한 다음 URL을 다시 복사해 재시도하세요.
• 확인은 되었지만 메시지가 들어오지 않음: 같은 앱의 앱 비밀이 저장되어 있는지(Meta가 모든 메시지에 이 값으로 서명함), 카드가 활성화됨 상태인지, messages를 구독했는지 확인하세요. Meta의 테스트 메시지는 들어오는데 실제 메시지가 들어오지 않는다면, 앱이 WhatsApp Business 계정을 구독하고 있는지 확인하세요.
• 카드에 확인 필요 칩이 표시됨: 설정을 클릭해 세부 정보를 확인하세요. 대개 앱 비밀, 액세스 토큰, 확인 토큰 또는 전화번호 ID가 누락되었거나(값을 붙여 넣고 저장을 클릭하세요) Meta가 액세스 토큰을 거부한 경우입니다.
• 답장이 대기 중으로 표시되고 전송하려면 유효한 자격 증명이 필요하다는 안내가 있음: 액세스 토큰 또는 전화번호 ID가 없어서 아무것도 발송되지 않았습니다. 값을 추가하고 다시 보내세요.
• "Provider credentials are invalid, expired, or missing required permissions.": 토큰이 잘못되었거나, 만료되었거나(예: 24시간 테스트 토큰), WhatsApp 권한이 부족합니다. 2단계에서처럼 시스템 사용자 토큰을 만드세요.
• "Provider rejected the message with status 400.": Meta가 메시지를 받아들이지 않았습니다. 예를 들어 수신자가 테스트 번호의 목록에 없거나 번호 형식이 잘못된 경우입니다.
• "Provider rate limit reached. Please wait and try again.": 짧은 시간에 너무 많은 메시지를 보냈습니다. 잠시 기다리세요.

관련 문서

• 소셜 연결 개요
• Facebook 연결(Messenger 및 페이지 댓글)
• 이메일 캠페인
• 문제 해결