온프레미스 API FAQ

WhatsApp은 관리 중인 서버에서 API 엔드포인트를 관리하는 Business API 사용자와의 통신을 엔드투엔드 암호화로 간주합니다. 그 이유는 엔드포인트 사이에 제삼자 액세스가 없기 때문입니다.

WhatsApp Business API 엔드포인트의 관리를 타사 비즈니스 솔루션 제공업체에 위임하는 조직도 있습니다. 이와 같은 경우에도 통신은 여전히 동일한 신호 프로토콜 암호화를 사용합니다. 그러나 WhatsApp Business API 사용자가 엔드포인트 관리를 타사에 위탁했기 때문에 WhatsApp에서는 해당 메시지를 엔드투엔드 암호화로 간주하지 않습니다. 향후 2021년부터는 Facebook에서 호스팅하는 클라우드 기반 버전을 사용하는 비즈니스에도 이와 같은 정책이 적용됩니다.

또한 WhatsApp Business API 클라이언트에 호출을 보낼 때 HTTPS를 사용한다면 해당 데이터는 (백엔드 클라이언트에서 WhatsApp Business API 클라이언트까지) SSL로 암호화됩니다.

자세한 내용은 WhatsApp 암호화 개요 기술 백서를 참조하세요.

아니요, 인스턴스당 1개 계정을 운영할 수 있습니다. 두 번째 테스트 계정이 필요한 경우 두 번째 인스턴스에는 다른 번호를 사용하세요.

아니요! 언제든 하나의 전화번호에 대해 WhatsApp Business API 클라이언트 인스턴스는 하나만 실행할 수 있습니다. 두 번째 인스턴스를 등록하는 즉시 첫 번째 인스턴스가 작동하지 않고 실패합니다. Facebook에서는 이 기능을 사용할 수 있도록 적절한 해결책을 모색하는 중입니다. 업데이트가 있으면 알려드리겠습니다.

WhatsApp Business 온프레미스 API 클라이언트에는 비즈니스와 고객 간에 전송된 메시지를 복호화하는 키를 저장할 데이터베이스가 필요합니다. WhatsApp의 모든 메시지는 발송자와 수신자 키로 암호화됩니다. 고객 키는 모바일 기기에 저장되고 비즈니스 키는 비즈니스 데이터베이스에 저장됩니다. WhatsApp 보안에 대해 자세히 알아보세요.

WhatsApp Business 클라우드 API는 Meta가 비즈니스 데이터베이스를 호스팅하는 대안입니다. 클라우드 API를 사용하면 자체 서버를 호스팅하는 비용 없이 WhatsApp Business API를 구현할 수 있습니다. 자세히 알아보세요.

아니요. 현재 동일한 WhatsApp Business API 클라이언트 설정에서 여러 번호를 운영하는 방법은 없습니다. 향후 이를 지원할 수 있도록 적절한 솔루션을 개발 중입니다.

Yes, Whatsapp Flows can be sent with On-Premises API. You can learn more about Whatsapp Flows here, or learn how to get started with Whatsapp Flows and On-Premises API here.

네! 기본적으로 WhatsApp Business API 클라이언트는 포트 5222를 통해 chatd를 사용하여 통신을 시도합니다. 최적의 경험을 제공하려면 모든 아웃바운드 트래픽에 대해 포트 5222를 개방하세요. 트래픽은 데이터 센터에서만 발송되므로 보안 문제가 발생하지 않습니다.

포트 5222를 열 수 없다면 WhatsApp Business API 클라이언트는 포트 443을 사용하려고 시도합니다. 그래도 방화벽이나 프록시가 연결을 차단한다면 기술 지원에 질문을 제출해 WhatsApp 팀에 디버깅을 요청하세요.

아니요. WhatsApp Business API 클라이언트가 WhatsApp 서버의 포트 5222 또는 443으로 아웃바운드 TCP 연결을 엽니다. TCP 트래픽은 이 장기 연결을 통해 발생합니다. 보통은 방화벽이 이것을 "아웃바운드 트래픽 및 설정된 트래픽"을 허용하는 것으로 분류합니다. 물론 연결이 설정된 뒤에는 패킷이 오고 가게 되지만, 연결 시작이 WhatsApp Business API 클라이언트에 있으므로 인바운드 연결을 허용하는 규칙이 없어도 됩니다.

요구 사항은 작업 부하와 상황에 따라 달라집니다. 이 솔루션은 Docker가 실행되고 인터넷이 연결된 모든 컴퓨터에서 실행할 수 있습니다. 예를 들어 간단한 테스트는 노트북에서 진행할 수 있습니다.

단일 인스턴스 프로덕션 서버 설정에서는 250GB SSD, 16GB RAM, 4코어 CPU 이상의 사양을 권장합니다. HDD는 부하 시에 I/O 속도로 인한 병목 현상이 발생하므로 권장하지 않습니다.

다중 연결 프로덕션 서버 설정에서는 각 Coreapp/Master/Webapp 컨테이너에 대해 50GB SSD, 4GB RAM, 2코어 CPU 이상의 사양을 권장합니다.

대부분의 경우 데이터베이스를 Core 및 Web 컨테이너와 분리된 물리적 서버에서 실행해야 합니다. 데이터베이스 서버는 컴퓨터에서 지연이 몇 밀리초 이내로만 발생해야 합니다.

이 설정은 초당 약 20개 메시지를 전송하도록 지원합니다.

MySQL 5.7.x, PostgreSQL 9.5.x, 9.6.x, 10.x 버전을 사용해야 합니다. 그 이하의 버전을 사용하면 Unable to initialize config store 오류가 발생합니다.

Docker를 사용하여 로컬에서 MySQL을 설정하려면 Docker MySQL 가이드를 따르세요.

Docker를 사용하여 로컬에서 PostgreSQL을 설정하려면 Docker PostgreSQL 가이드를 따르세요.

대부분의 경우 데이터베이스를 Core 및 Web 컨테이너와는 별개의 물리적 서버에서 실행해야 합니다. 데이터베이스 서버는 컴퓨터에서 지연이 몇 밀리초 이내로만 발생해야 합니다.

허용 리스트는 호스트 이름 또는 IP 주소로 작성할 수 있습니다.

자세한 내용은 네트워크 요구 사항 문서의 호스트 이름 섹션을 참조하세요.

예, TCP 연결이 필요합니다. 비즈니스에서 추가 포트를 열 수 없다면 terminated SSL을 사용하세요.

자세한 내용은 네트워크 요구 사항 문서를 참조하세요.

아니요, Facebook에서는 KOPS를 지원하지 않습니다. ECS 기반 AWS 솔루션은 지원합니다. 또한 일반적인 Kubernetes minikube 설정이 있습니다.

MySQL과 PostgreSQL이 지원됩니다. Docker를 직접 운영할 경우 연결할 컨테이너에 MySQL/PostgreSQL 데이터베이스를 제공해야 합니다. AWS 템플릿을 사용하면 기본적으로 MySQL 데이터베이스가 설정됩니다.

아니요. 현재 WhatsApp Business API 클라이언트는 Windows용 Docker에서 실행되지 않습니다. 개발에 필요한 경우 Linux Virtual 기기를 사용해서 Docker를 실행하는 것이 좋습니다. 프로덕션 작업 부하의 경우 Linux Server를 사용하여 호환성 및 성능 문제가 발생하지 않도록 하는 것이 좋습니다.

다음 코드를 실행하면 Docker 컨테이너를 다시 시작할 수 있습니다.

Coreapp Docker 컨테이너

docker restart wacore<Current_WABA_Version>

Webapp Docker 컨테이너

docker restart webapp<Current_WABA_Version>

다음과 같이 실행 중인 버전을 검사할 수 있습니다.

docker ps

예, Webapp 컨테이너와 Coreapp 컨테이너의 로그 로테이션은 약간 다르게 동작합니다.

• Webapp: 최근 30개 로그 파일이 보관됩니다. 용량이 20MB를 넘는 경우에만 로그 파일이 로테이션됩니다.
• Coreapp: 최근 30개 로그 파일이 보관됩니다. 용량이 15MB를 넘는 경우에만 로그 파일이 로테이션됩니다. 로테이션된 파일은 압축됩니다.

컨테이너의 오래된 로그를 정리하기 위해 외부에서 트리거할 수 있는 스크립트가 있습니다.

docker exec CONTAINER_NAME /opt/whatsapp/bin/cleanup.sh

스크립트는 Webapp과 Coreapp 컨테이너에서 모두 작동합니다. 이 스크립트를 실행하면 오래된 로그 파일이 삭제되고 컨테이너에는 30개 로그 파일만 남습니다.

용량이 차면서 시스템 속도가 점점 느려질 수 있습니다. 이런 일은 미디어 파일, 메시지 및 크기가 큰 로그 파일이 많아서 발생할 가능성이 있습니다. 로그 파일은 자동으로 로테이션되지만 용량이 커지기 시작하면 삭제하는 것이 안전합니다.

메시지는 데이터베이스에 저장됩니다. 메시지는 필요에 따라 삭제해도 됩니다. 또한 앱 설정에서 pass_through를 false로 설정하면 모든 메시지가 확실히 삭제할 때까지 데이터베이스에 저장됩니다.

사용자가 보내는 미디어 파일은 미디어 볼륨에 다운로드됩니다. 삭제할 미디어 파일을 선택할 결정권은 비즈니스에 있지만, 보통은 모든 미디어 파일을 삭제하는 것이 안전합니다. 미디어 볼륨 폴더가 어디 있는지 확인하려면 docker inspect your-container-id를 사용하면 됩니다.

예, 데이터베이스는 WhatsApp 관련 테이블을 건드리지 않고 다른 방식으로 사용할 수 있습니다.

데이터베이스 테이블은 앱 설정, 채팅 스레드, 메시지, 미디어 등과 관련된 정보가 저장됩니다. 이 정보들은 모두 앱이 작동하는 데 필요합니다.

v2.25.x는 이전 릴리스에 비해 아웃바운드 및 인바운드 성능이 개선됩니다. 이 최적화는 추가 데이터베이스 연결이 생성됩니다. 일부 배포의 경우 데이터베이스 연결 수가 늘어나서 설정된 제한에 도달할 수 있습니다. 성능을 향상된 상태로 유지하려면 데이터베이스 서버가 수락할 수 있는 연결 수의 최댓값을 높입니다. 이러한 조치가 불가능할 경우, axolotl_context_striping_disabled 매개변수를 변경하여 이 동작을 비활성화할 수 있습니다. 변경 방법에 대한 자세한 내용은 앱 설정 문서를 참조하세요.

데이터베이스 가비지 컬렉션은 messages와 messages_reciept_log 테이블을 정기적으로 정리하여 데이터베이스 관리를 돕습니다.

가비지 컬렉터는 특정 메시지를 보관하여 성공적으로 전송/처리되도록 합니다. 예를 들어 일정 기간 수신되는 메시지를 보관하여 비즈니스 통합에서 해당 메시지를 읽음으로 표시하도록 합니다.

Coreapp이 임의의 간격(예: 몇 시간 간격)으로 가비지 컬렉션을 실행합니다. 이는 고가용성 스택에서 데이터베이스 충돌로 인해 성능이 저하되지 않도록 방지하기 위한 조치입니다.

가비지 컬렉션은 콜백 대기열과는 무관합니다. 예를 들어 Webhook 서버를 4일 동안 사용할 수 없을 경우 콜백을 저장하여 Webhook 서버 연결이 복원되었을 때 전송되도록 합니다.

데이터베이스 가비지 컬렉션 services API 엔드포인트를 사용하여 messageStore.messages 및 messageStore.messages_receipt_log 테이블에서 메시지와 해당 메시지 확인을 삭제합니다.

현재 설정을 백업하고 새 기기에서 복원할 경우, 구현과 함께 등록 정보도 이동합니다. 자세한 내용은 백업 및 복원 설정 문서를 참조하세요.

users 엔드포인트를 통해 사용자를 로그아웃시키면 해당 계정에 할당된 모든 인증 토큰이 무효화됩니다. 사용자를 삭제해도 같은 결과를 얻을 수 있지만, 이것은 훨씬 극단적인 방법입니다. 사용자를 users 엔드포인트를 통해 로그인시키면 새 인증 토큰이 반환되지만 해당 사용자에 대해 돌고 있는 인증 토큰이 무효화되지 않습니다. 이전에 프로비저닝된 토큰을 소유한 사람은 누구나 만료되거나 앞서 말씀드린 방법 중 하나로 무효화하기 전까지 해당 토큰을 계속 사용할 수 있습니다.

참고: WhatsApp Business API를 사용하여 동일한 수신자에게 반복적으로 동일한 메시지를 보내지 마세요.

전달률이 100%가 아닌 이유는 여러 가지가 있을 수 있습니다. 일반적인 사례로는 사용자가 네트워크에 산발적으로 액세스하거나, 일정 기간 비활성화 상태이거나 좋은 품질의 사용자 경험을 만들기 위해 전달되지 않은 경우가 있습니다.

WhatsApp으로 전송 가능한 메시지는 전달률이 매우 높습니다. 그러나 메시지가 전달되지 않는 이유는 여러 가지가 있습니다. 콜백을 모니터링하면 메시지의 정확한 상태에 액세스할 수 있습니다. 예를 들어 이는 SMS로 메시지를 전송하는 것과는 다른데, SMS로 메시지를 전송할 때는 최종 전달된 상태에 액세스할 수 없고 메시지를 다시 전송하면 다른 결과를 초래할 수 있습니다.

메시지가 전달되지 않은 이유는 사용자의 전화기를 사용할 수 없거나, 배터리가 모두 소모되었거나, 전화기를 분실해서 새로운 전화기를 구매했고 SIM을 비활성화했기 때문일 수 있습니다. 비즈니스 클라이언트가 네트워크에 연결하는 기능에 오류가 발생했을 수도 있습니다. 또한 콜백(Webhooks)이 전송되지 않았을 수도 있습니다. health 노드를 사용하여 이러한 상황을 모니터링할 수 있습니다. 서버 수신 콜백을 활성화하면 메시지가 WhatsApp 서버 클라우드로 전달되었는지 알 수 있습니다.

사용자가 네트워크에 다시 연결하면 전송한 모든 메시지가 전달됩니다. 동일한 내용의 메시지를 2번 이상 수신하는 것은 사용자에게 불쾌한 경험을 제공합니다. 그러면 사용자가 차단하거나 불만을 접수할 가능성이 크고 비즈니스가 차단될 가능성이 더욱 커집니다.

메시지를 전송하고 API로부터 메시지 ID를 받았다면 이 메시지 전송을 위해 할 수 있는 일을 완료한 것입니다. 동일한 내용을 동일한 수신자에게 다시 보내지 마세요.

오랫동안 전달률이 낮게 유지되면 기술 지원에 지원 티켓을 제출하세요.

메시지를 전송하는 즉시 메시지 ID로 돌아갑니다. 즉, 메시지 요청이 데이터베이스에 저장된 것을 의미합니다. WhatsApp Business API 클라이언트는 WhatsApp 서버에서 승인할 때까지 해당 메시지의 전송을 계속 시도합니다. 이 프로세스는 종료 시간이 정해져 있지 않습니다. 그러면 WhatsApp 서버에서 사용자 전화기로 해당 메시지를 전송하려고 시도할 것입니다. 사용자의 전화기가 온라인 상태가 아니라면 메시지는 30일간 보관되었다가 WhatsApp 서버에서 폐기합니다.

현재로서는 비즈니스를 차단한 사용자의 수 또는 사용자의 신원을 확인할 방법이 없습니다. 가장 좋은 지표는 상태 콜백을 수신하는 것입니다. delivered 상태가 수신되지 않는 경우, 해당 사용자가 비즈니스를 차단했거나 네트워크에 연결되지 않은 것입니다. 자세한 내용은 Webhook 문서를 참조하세요.

사용자가 비즈니스를 차단한 경우, 연락처 API가 계속해서 해당 전화번호를 유효한 WhatsApp 사용자로 반환합니다. 그러나 메시지를 전송하면 전달되지 않습니다. 메시지가 유료 메시지인 경우, 요금이 부과되지 않습니다.

일반적인 소비자 관련 상황에서 보내는 사람이 주소록에 없고 전에 이 보내는 사람에게 메시지를 보낸 적이 없다면 이렇게 되는 것이 맞습니다. 기업 관련 상황의 경우 비즈니스는 처음 사용자와 연락할 때 메시지 템플릿을 사용해 "신뢰"를 쌓아야 합니다. 이렇게 하면 WhatsApp Business API 클라이언트가 앱 내 자동 다운로드 설정을 준수합니다.

일반적인 소비자 관련 상황에서 보내는 사람이 주소록에 없고 전에 이 보내는 사람에게 메시지를 보낸 적이 없다면 이렇게 되는 것이 맞습니다. 기업 관련 상황의 경우 비즈니스는 처음 사용자와 연락할 때 메시지 템플릿을 사용해 "신뢰"를 쌓아야 합니다. 이렇게 하면 WhatsApp Business API 클라이언트가 링크를 렌더링하여 클릭할 수 있게 만듭니다.

물론입니다! WhatsApp 담당자에게 연락하여 요청하세요.

아니요, 메시지가 도착하는 순서는 보낸 순서와 동일하게 보장되지 않습니다. 사용 사례에서 순서가 중요한 경우 첫 번째 메시지의 전송된 콜백을 수신한 다음, 두 번째 메시지를 보내는 것이 좋습니다.

messages 노드를 사용하면 WhatsApp Business API 클라이언트의 Content-Type 헤더를 application/json로 설정해야 메시지 본문을 적절히 파싱할 수 있습니다. Authorization 헤더도 설정해야 하고 만료되지 않은 액세스 토큰을 포함해야 합니다. 토큰을 얻는 방법과 만료 시점에 대한 자세한 내용은 로그인 및 인증 문서를 참조하세요.

예, 메시지를 전송하기 전에 contacts 노드로 API 호출을 보내세요. contacts를 검사해서 얻은 정보는 컨테이너에서 캐싱되며, 이렇게 처리하지 않으면 Unkown Contact 오류가 발생할 수 있습니다. 자세한 내용은 연락처 확인 문서를 참조하세요.

If there is a delay in a subset of numbers, then it is likely not an issue affecting the customers integration but rather an issue on the recipients end, these delays in delivery can happen for a number of reasons. See Send Message Performance, Delays for more information.

No this is not possible. Numbers that are registered under WABAs (WhatsApp Business Accounts) can only message regular WhatsApp accounts.

발송 또는 수신되는 미디어 파일에 모두 정리 메커니즘이 없습니다. 파일 시스템에서 미디어 파일을 찾아서 직접 삭제할 수 있습니다.

미디어 볼륨의 마운트 지점을 찾으려면 도커 명령을 실행합니다.

요청

docker volume inspect whatsappMedia

응답

[
    {
        "Driver": "local",
        "Labels": {},
        "Mountpoint": "/var/lib/docker/volumes/whatsappMedia/_data",
        "Name": "whatsappMedia",
        "Options": {},
        "Scope": "local"
    }
]

수신되는 미디어 파일을 모두 확인하려면 다음과 같이 수신된 Mountpoint 파일 경로를 포함한 ls 명령을 실행합니다.

ls /var/lib/docker/volumes/whatsappMedia/_data/

AWS 설정에서는 미디어 볼륨이 호스트의 /mnt/wa/media 경로에 마운트됩니다.

최대 파일 업로드 용량은 64MB이며, 이 제한은 메시지에 포함한 모든 이미지, 문서 또는 동영상에도 적용됩니다.

미디어 삭제 시점은 귀하가 결정할 수 있습니다.

미디어를 업로드한 후 미디어 ID를 수신하는데, 이 ID를 사용하여 업로드된 미디어 요소를 포함한 메시지를 전송할 수 있습니다. 미디어 메시지를 전송할 때 WhatsApp Business API가 미디어를 암호화하여 WhatsApp 서버에 업로드합니다. 미디어는 서버에 14일간 저장됩니다. 그 이후에는 미디어 ID를 제공하여 미디어를 삭제하거나 보관했다가 나중에 사용할 수 있습니다. 미디어 보관 기간은 30일을 권장하지만 비즈니스 정책이나 사용 사례에 따라 보관 정책을 결정하시기 바랍니다.

이미지 캡션은 설명으로 추가됩니다. 캡션 텍스트는 Android와 iPhone의 이미지에서 모두 전체 길이가 표시됩니다.

문서 캡션은 파일 이름을 대체합니다. 사용자 기기에 설명 텍스트로 표시되지 않고 파일 이름으로 표시됩니다. iPhone은 전체 텍스트를 표시하지만 Android는 파일 이름을 자릅니다. 이는 두 기기에서 실행하는 WhatsApp 최신 구현에 적용된 기술적 제한입니다.

WhatsApp Business API에서 이미지를 사진첩으로 전송할 때 4개 이상의 이미지를 연속으로 전송해야 합니다. 이미지를 수신하는 시점에서 사용자의 대화 뷰가 활성화된 상태라면 다음 방문 전까지 사진첩 뷰를 사용할 수 없습니다.

다음의 조건 중 하나라도 해당하면 사진첩이 생성되지 않습니다.

1. 캡션이 포함된 이미지
2. 읽지 않은 디바이더 - 사용자에게 일부 이미지가 보이지만 나머지는 보이지 않음
3. 날짜 헤더 - 전송 이미지 사이에 새로운 날 포함

아니요, 지금은 Coreapp과 Webapp 사이에서 미디어 볼륨을 공유하려면 AWS EFS를 사용해야 합니다.

아니요, 지금은 기본 경로를 미디어 스토리지(/usr/local/wamedia/)로 변경할 수 없습니다. 모든 미디어 스토리지는 이 기본 위치로 설정해야 제대로 작동합니다.

현재는 7일이 소요됩니다. 캐시가 7일 이상 업데이트되지 않으면 팩에 그 요소가 존재하는지 여부와 관계없이 서버에서 최신 언어 팩을 가져옵니다.

참고:fallback 언어 정책은 v2.27.8부터 사용이 중단되고 deterministic 언어 정책이 기본 정책이 됩니다.

새 언어로 번역을 생성할 때 해당 언어로 사용하는 모든 요소를 번역해야 합니다. 그렇지 않으면 수신자의 전화기가 그 언어에서 기대되는 요소를 찾지 못해 "사용할 수 없는 구조" 오류가 발생할 수 있습니다. "사용할 수 없는 구조" 오류는 폴백 정책을 사용하여 템플릿 메시지를 전송할 때 나타납니다.

현재 언어 번역을 생성할 수 없는 상황이라면 결정적 언어 정책을 사용하여 이 오류를 피할 수 있습니다.

WhatsApp Business API 클라이언트는 Coreapp 컨테이너를 통해 Webhook 콜백을 전송합니다. 따라서 Webhook 엔드포인트를 구성해야 Coreapp에서 인바운드 요청을 수락할 수 있습니다.

Webhook이 콜백을 전송하는 데 실패하면 콜백이 재시도 대기열에 들어갑니다. 최초 콜백이 실패한 후에 전송된 모든 콜백은 수신되지 않습니다. 최초 콜백이 성공해야 나머지 콜백도 수신됩니다.

어떤 이유로든 Webhook 이벤트가 전송되지 않거나(예: 클라이언트가 오프라인인 경우) Webhook 요청이 200 외에 다른 HTTP 상태 코드를 반환하면 Webhook 전송을 다시 시도합니다. 지연 시간이 점차 늘어나 특정 시간 초과에 도달하거나(일반적으로 24시간이지만 차이가 있을 수 있음) 전송이 성공할 때까지 다시 시도합니다.

메시지는 (정확히 한 번이 아니라) 적어도 한 번 수신하도록 보장되어 있기 때문에 WhatsApp Webhook으로 중복 메시지가 전송될 수 있습니다. 이로 인해 개발자 측에서 메시지를 처리하는 데 영향이 발생한다면 메시지 ID를 기준으로 Webhook 메시지의 중복을 제거하는 것이 좋습니다.

pass_through 앱 설정을 다시 한번 확인하세요. WhatsApp Business API 클라이언트 v2.29.1 이상으로 pass_through를 활성화했다면 읽기 상태 콜백을 수신할 수 없습니다.

읽기 상태 콜백을 수신하려면 pass_through 앱 설정을 비활성화하세요. 다만 pass_through를 비활성화하면 데이터베이스 스토리지가 빠르게 증가할 수 있습니다. 데이터베이스 관리에 대한 자세한 내용은 데이터베이스 관리 문서를 참조하세요.

이전 버전 iOS 클라이언트에 있는 버그로 인해 발생하는 오류입니다. 일반 집단 업그레이드로 점차 오류가 감소할 것으로 예상합니다.

먼저 중대한 오류의 콜백을 확인해 문제를 진단하세요.

"충돌: 같은 번호를 공유하는 여러 인스턴스가 발견됨"이 표시된다면 컨테이너를 확인해야 합니다. 동일한 WhatsApp 계정을 사용하여 WhatsApp 서버로 연결하려고 시도하는 Docker 컨테이너가 여러 개 있는 게 원인일 가능성이 가장 큽니다. 컨테이너는 하나만 실행되도록 합니다. 오래된 컨테이너가 있을 경우 이를 종료하면 오류가 해결됩니다.

더욱 복잡한 고가용성 솔루션을 테스트하고 싶다면 고가용성 문서를 참조하세요.

이는 알려진 문제입니다. WhatsApp Business API 클라이언트를 CloudFormation 스크립트를 사용해 업그레이드하면 RDS DB 스택도 업그레이드해야 하게 되는 경우가 있습니다. 새 RDS 스택은 원래 스택과 호스트 이름이 같지 않으므로 Docker 컨테이너가 데이터베이스에 연결할 수 없게 됩니다. 이 문제를 해결하려면 CloudFormation으로 생성된 EC2 인스턴스에 SSH를 구축하여 새 호스트 이름으로 whatsapp.conf 파일을 업데이트한 다음 Docker 컨테이너를 다시 시작하여 새 설정을 따르게 하면 됩니다.

데이터베이스가 올바르게 설정하지 않으면 이 오류가 발생합니다.

• MySQL 5.7 이상 또는 PostgreSQL 9.5.x, 9.6.x, 10.x를 사용하는지 확인하세요.
• 데이터베이스 비밀번호에는 ?{}&~!()^와 같은 문자를 포함하지 말아야 합니다.
• AWS를 사용하고 있다면 스택 이름을 짧게 지정하세요. 자세한 내용은 설치 문서를 참조하세요.

Docker 브리지가 손상되면 발생하는 오류입니다. 가장 좋은 해결 방법은 Docker 서비스를 중단하고 다시 시작하는 것입니다. 컨테이너에서 docker restart를 시도해볼 수도 있습니다.

"연결이 거부됨" 오류가 발생했다면 Coreapp이 실행되고 있지 않을 가능성이 큽니다. docker ps를 사용하여 Coreapp이 실행되고 있는지 확인하세요. 실행되고 있지 않은 경우, Docker 로그를 살펴봅니다. Coreapp이 데이터베이스에 연결하지 못할 수 있습니다. 데이터베이스가 올바르게 설정되어 있어야 합니다.

이유는 여러 가지가 있습니다. Coreapp이 중단되었거나 데이터베이스가 올바르게 설정되지 않았을 수 있습니다. 이 경우가 아니라면 Coreapp 로그를 참조하세요(다중 연결을 실행 중이라면 마스터 Coreapp 로그 참조). 데이터베이스 연결 오류가 나타나면 데이터베이스가 연결되지 않았을 가능성이 큽니다. 이 오류에 대한 내용은 MySQL 문서 또는 PostgreSQL 문서를 참조하세요.

데이터베이스에서 데이터베이스 연결 수를 늘리는 것이 좋습니다. 데이터베이스 연결은 1000개가 안정적이지만 연결 개수는 정보에 입각하여 직접 결정해주세요. 오류가 지속되면 지원 티켓을 여세요.

이 오류가 표시되었지만 누락된 필수 매개변수가 json 본문에서 설정된 매개변수를 나타낸다면 json 파싱 오류일 수 있습니다. json 형식 지정 오류로 인해 json 페이로드 전체를 파싱할 수 없을 때 이 오류가 발생합니다. 이 매개변수 값에 잘못된 json 문자가 있는지 확인하세요(예: 끝에 캐리지 리턴). 매개변수가 json을 손상시키는 문자가 포함된 추가 공백과 같이 복사될 수 있습니다.

사용할 수 없는 구조 오류는 휴대폰에서 템플릿 메시지를 읽을 수 없을 경우에 발생합니다.

템플릿은 서버에 저장됩니다. 템플릿 메시지가 messages 노드를 사용하여 전송되는 경우전체 메시지가 아니라 네임스페이스, 언어, 요소 이름, 현지화된 매개변수만 전화번호로 전송됩니다. 이 값이 휴대폰으로 전달되면 메시지 렌더링을 시도합니다.

렌더링 중 오류가 발생할 경우 structure unavailable 오류가 받는 사람과 메시지 ID가 포함된 콜백 URL로 전송됩니다. 이 오류는 네임스페이스가 잘못되었거나, 현지화된 매개변수가 일치하지 않거나, 요소 이름이 잘못된 것 등이 원인일 수 있습니다.

Facebook 비즈니스 관리자의 WhatsApp 관리자에서 매개변수의 올바른 개수를 확인하세요. 네임스페이스가 올바른지, 요소 이름이 존재하는지 다시 한번 확인하세요.

가장 일반적인 오류 원인은 사용 중인 모든 템플릿에 번역을 생성하지 않은 것입니다. 예를 들어 일반적으로 전송하는 템플릿이 2개이고 하나의 템플릿에 새 언어 번역을 추가한다면 나머지 다른 템플릿에도 새 언어 번역을 추가해야 합니다. 2개 이상의 언어를 지원할 계획이라면 모든 지원되는 언어로 모든 템플릿에 번역문을 제공해야 합니다.

다행히 structure unavailable 오류는 messages API 호출에서의 실수로 인해 발생하는 경우가 대부분이고 이는 전송 페이로드를 변경하면 수정할 수 있습니다.

메시지를 보내기 전에 먼저 해당 연락처가 존재하는지 확인해야 합니다. 그 방법에 대한 자세한 내용은 연락처 문서를 참조하세요.

Coreapp이 아직 초기화되지 않아서 발생하는 오류입니다. 등록이 성공적으로 완료되지 않았을 수 있습니다. 다른 엔드포인트를 호출하기 전에 등록을 시도해보세요. WhatsApp Business API를 설치한 후에 첫 단계는 로그인입니다. 두 번째 단계는 등록입니다. 이 두 단계를 거쳐야 다른 엔드포인트로 요청을 보낼 수 있습니다.

WhatsApp Business API 클라이언트의 모든 빌드에는 릴리스 날짜로부터 6개월의 만료기간이 있습니다. 이 오류가 표시되면 가능한 한 빨리 최신 릴리스 버전으로 업그레이드하세요.

WhatsApp은 WhatsApp Business API 알림이 사용자 경험과 제품 전반에 미치는 영향을 측정하고 이해하고자 실험을 수행합니다. 메시지를 보내려고 하는 사용자가 이런 실험에 속해 있다면 알림을 수신하도록 옵트인했더라도 알림을 받지 못할 수 있습니다.

AWS 배포를 설정할 때 다음과 유사한 오류를 수신하는 경우, 스택 이름을 8자 이하로 변경해보세요.

국가 이름(2자 코드) [AU]:주 또는 도 이름(전체 이름) [Some-State]:인근 지역 이름(예: 도시) []:조직 이름(예: 회사) [Internet Widgits Pty Ltd]:조직 부서 이름(예: 섹션) []:일반 이름(예: FQDN 서버 또는 q본인의 이름) []:문자열이 너무 깁니다. 길이가 64바이트 미만이어야 합니다. 일반 이름(예: FQDN 서버 또는 본인의 이름) []:이메일 주소[]:오류, 구성 파일에 지정된 개체가 없음, 인증서 요청 중 문제 발생, internal-wa-inc-name-LB-123456789.ap-southeast-1.elb.amazonaws.com에 대한 기기 키가 생성됨

비즈니스 프로필이 부분적으로만 채워져 있는 경우 빈 profile 개체가 반환됩니다. 이 문제를 해결하려면 v2.21.4로 업그레이드하세요.

비즈니스 프로필 작성에 대한 자세한 내용은 비즈니스 프로필 설정 문서를 참조하세요.

오류 코드 471은 품질에 기반한 사용 제한과 관련이 있습니다. 자세한 정보는 품질 기반 사용 제한 문서를 참조하세요.

다음은 메시지 템플릿 전송 측의 인증 오류와 그 이유입니다.

• "your-language 언어로 메시지 템플릿이 존재하지 않습니다" 또는 "your-language 언어 및 your-locale 로캘에 메시지 템플릿이 존재하지 않습니다" — 해당 언어 팩이 존재하지 않습니다. 비즈니스 관리자 계정을 확인하세요.
• "your-template-name 템플릿이 your-language 언어로 존재하지 않습니다" 또는 "your-template-name 템플릿이 your-language 언어 및 your-locale 로캘로 존재하지 않습니다" — 존재하지 않는(생성되지 않았거나 아직 승인되지 않은) 템플릿을 사용하려고 합니다. 삭제된 템플릿으로 메시지를 전송하려고 시도해도 이 오류가 발생합니다.
• "localizable_params num1 개수가 예상 params num2 개수와 일치하지 않습니다" — 예상 매개변수 개수와 일치하지 않는 매개변수를 포함하여 메시지 템플릿을 전송하려고 합니다. API 호출에서 올바른지 확인하세요.
• "your-template-name은(는) 서식이 있는 템플릿이므로 사용할 템플릿 메시지 API가 필요합니다" — 미디어 메시지 템플릿을 일반 메시지 템플릿으로 보내려고 시도합니다. 메시지 유형이 template인지 확인하세요. 자세한 내용은 미디어 메시지 템플릿 문서를 참조하세요.
• 비즈니스 관리자에서 템플릿을 승인하면(또는 삭제하면) WhatsApp Business API 클라이언트가 업데이트된 템플릿을 수신하기까지 최대 20분이 소요될 수 있습니다. 방금 승인을 받은 템플릿으로 메시지 전송을 시도하면 템플릿이 존재하지 않는다는 오류가 표시되고, 위의 지정된 시간만큼 기다린 이후에 메시지 전송을 시도할 수 있습니다.

v2.21.6을 실행하는 WhatsApp Business API 클라이언트는 클라이언트와 서버의 연결이 중단되면 몇 분(최대 4분)간 연결이 끊어진 상태로 유지되다가 다시 연결을 시도합니다. v2.23.4로 업그레이드하면 서버로 연결을 시도할 때 클라이언트 중단 시간이 감소합니다.

v2.29.x 이전에는 버그로 인해 시간이 지날수록 발송 메시지 대기열이 늘어나는 경우가 있었습니다. 이 문제를 해결하려면 v2.29.3으로 업그레이드하세요.

Coreapp이 Coreapp 컨테이너에 있는 /usr/local/waent/data와 /usr/local/waent/log 디렉터리를 확인하여 저장 공간이 10MB 이상 남아 있는지 확인합니다. 그렇지 않을 경우 이런 치명적 오류가 발생합니다.

로그와 데이터 디렉터리에서 저장 공간이 충분한지 확인하세요.

지금은 채팅 기능을 비활성화할 수 없습니다. WhatsApp에서 사용자가 보낸 인바운드 응답을 처리할 수 없다면 적절한 지원 채널로 리디렉션되는 자동 답글 메시지를 전송하는 것이 좋습니다.

테스트를 위한 두 번째 전화번호를 등록하고 두 번째 CloudFormation 스택이나 Docker 인스턴스를 만들어야 합니다. 같은 전화번호를 사용하는 WhatsApp Business API 클라이언트가 두 개 있을 경우 암호화 키가 서로 충돌하므로 서버에서 퇴출됩니다. 프로덕션 클라이언트로 마이그레이션하기 전에 프로덕션이 아닌 인스턴스를 테스트하는 데 사용할 두 번째 환경을 준비하는 것이 좋습니다.

상태 확인은 무료이고 필요한 만큼 자주 쿼리할 수 있습니다.

쿼리할 수 있는 앱과 데이터베이스 통계에 관한 자세한 내용은 통계 문서를 참조하세요. 앱 통계는 메모리에 저장되고 쿼리 요금이 저렴합니다. 데이터베이스 통계는 더 많은 리소스가 요구되고 필요한 경우에만 쿼리해야 합니다.

고객이 WhatsApp 전화번호를 변경하더라도 비즈니스에 알리지 않습니다. contacts 노드를 사용하면 해당 전화번호의 상태가 invalid됩니다.

고객 전화번호가 비활성화되었지만 고객이 아직 WhatsApp을 사용한다면 해당 전화번호가 재할당되거나 재등록될 때까지 WhatsApp에 계속 액세스할 수 있습니다.

WhatsApp은 제공된 번호가 실제로 전화기에서 사용하는 번호인지 엄격히 확인합니다. 사용자에게 WhatsApp 계정이 있다는 것은 사용자가 전화번호를 인증하였고 그 이후에 그 번호를 WhatsApp에 등록한 사람이 없다는 증거입니다. 그러나 SIM 카드의 물리적 위치를 보증하지는 않습니다.

반면, 사용자의 전화기가 분실되거나 도난 당하는 경우 사용자가 WhatsApp 계정을 비활성화할 수 있습니다. 사용자가 계정을 비활성화할 수 있는 방법에 대해 자세히 알아보려면 전화기 분실 및 도난 FAQ를 참조하세요.

아니요, WhatsApp Business API를 사용하여 여러 기기가 동일한 번호를 사용하는지 확인할 방법은 없습니다.

사용자가 보내는 메시지 페이로드는 텍스트 또는 미디어 파일입니다.

텍스트의 경우, 확인된 위험은 없는 것으로 간주됩니다.

미디어 파일:

• 일반적으로 비즈니스에서는 각종 잠재적인 위협을 분석하기 위해 일종의 보호 소프트웨어(예: 바이러스 백신, 악성 코드 방지 등)를 확보하고 있을 것으로 예상됩니다.
• WhatsApp은 엔드투엔드로 암호화되어 있으므로 전송 중인 파일의 내용을 식별하거나 검사할 수 없습니다(텍스트만 있는 콘텐츠의 경우에도 마찬가지).
• WhatsApp Business API 클라이언트에서 미디어 파일이 자동으로 다운로드되지 못하게 하는 옵션이 있습니다. 비즈니스가 사용자로부터 파일을 수신하고 싶지 않을 경우 auto_download 필드를 빈 배열로 설정하면 됩니다.

지원에 문의하여 알고 있는 정보를 알려주세요. Facebook에서 조사를 통해 가짜 번호를 차단할 것입니다.

v2.18.26 릴리즈부터 앱 통계 엔드포인트에서 내부 지표를 Prometheus 텍스트 형식으로 내보낼 수 있게 되었습니다. 자세한 내용은 인스턴스 모니터링 문서를 참조하세요.

WhatsApp Business 온프레미스 API 클라이언트에는 비즈니스와 고객 간에 전송된 메시지를 복호화하는 키를 저장할 데이터베이스가 필요합니다. WhatsApp의 모든 메시지는 발송자와 수신자 키로 암호화됩니다. 고객 키는 모바일 기기에 저장되고 비즈니스 키는 비즈니스 데이터베이스에 저장됩니다. WhatsApp 보안에 대해 자세히 알아보세요.

WhatsApp Business 클라우드 API는 Meta가 비즈니스 데이터베이스를 호스팅하는 대안입니다. 클라우드 API를 사용하면 자체 서버를 호스팅하는 비용 없이 WhatsApp Business API를 구현할 수 있습니다. 자세히 알아보세요.