WhatsApp Business 플랫폼 온프레미스 API

개발자 설정: 단일 인스턴스

이 문서에서는 테스트 목적으로 개발자 기기에서 WhatsApp Business API 클라이언트의 단일 인스턴스를 설정하는 방법을 안내합니다.

프로덕션 설정의 경우 프로덕션 설정에 나와 있는 관련 지침을 따르세요.

시작하기 전에

다음과 같은 항목이 필요합니다.

  • Docker
  • Docker Compose
    • Docker 설치와 함께 번들로 제공되어야 하지만, 제공되지 않은 경우 설치할 수 있습니다.
  • 로컬에서 설정한 개발 환경의 테스트 계정
    • 빠른 개발과 새 릴리스 테스트에 사용할 용도입니다.

WhatsApp Business API 클라이언트의 최초 설정

다음 단계에 따라 개발자 시스템에 WhatsApp Business API 클라이언트의 단일 인스턴스를 설치하세요.

1단계: 설정 스크립트를 위한 biz 디렉터리 만들기

WhatsApp Business API 클라이언트의 원하는 위치에서 다음 코드를 실행합니다.

mkdir ~/biz; cd ~/biz;

2단계: WhatsApp Business API 클라이언트 구성 파일 가져오기

WhatsApp Business API 클라이언트의 구성 파일은 WhatsApp-Business-API-Setup-Scripts GitHub 리포지토리에 있습니다. MySQL 또는 Postgres 데이터베이스 인스턴스로 WhatsApp Business API 클라이언트를 설정할 수 있습니다.

3단계: WA_API_VERSION 환경 변수 설정

WA_API_VERSION 환경 변수는 다음을 사용하여 최신 버전으로 설정해야 합니다.

export WA_API_VERSION=current-whatsapp-version

4단계: WhatsApp Business API 클라이언트 시작

데이터베이스 컨테이너 1개, Webapp 컨테이너 1개 및 Coreapp 컨테이너 1개를 포함한 WhatsApp Business API 클라이언트를 시작하려면 다음을 실행하세요.

docker-compose up -d

결과로 나오는 출력은 다음과 같습니다.

Creating volume "biz_whatsappMedia" with local driver
Creating volume "biz_mysqlData" with local driver
Creating biz_db_1 ... done
Creating biz_wacore_1 ... done
Creating biz_waweb_1  ... done

5단계: 컨테이너가 실행 중인지 확인

다음을 실행하여 모든 컨테이너가 UP 상태인지 확인할 수 있습니다.

docker-compose ps

기본적으로 Webapp 컨테이너는 9090 포트에서 실행되고 데이터베이스 컨테이너는 33060 포트에서 실행됩니다.

결과로 나오는 출력은 다음과 같습니다.

~/biz $ docker-compose ps
     Name                    Command               State                   Ports
-------------------------------------------------------------------------------------------------
biz_db_1       docker-entrypoint.sh mysqld      Up      0.0.0.0:33060->3306/tcp, 33060/tcp
biz_wacore_1   /opt/whatsapp/bin/wait_on_ ...   Up      6250/tcp, 6251/tcp, 6252/tcp, 6253/tcp
biz_waweb_1    /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:9090->443/tcp

6단계: 상태 점검 수행

명령줄을 사용하고 싶지 않은 경우 Postman 컬렉션을 다운로드하여 구성하면 WhatsApp Business API와 상호작용하는 데 사용할 수 있습니다.

health 노드에 API 호출을 보내서 WhatsApp Business API 클라이언트에 상태 점검을 수행할 수 있습니다.

결과로 나오는 출력은 다음과 같습니다.

{
    "health": {
        "gateway_status": "unregistered"
    }
}

응답에서는 unregistered의 gateway_status가 gateway_status로 표시되는데, WhatsApp Business API 클라이언트가 아직 등록되지 않았기 때문입니다.

7단계: WhatsApp Business API 클라이언트 등록

account 노드에 API 호출을 보내서 WhatsApp Business API 클라이언트를 등록할 수 있습니다.

8단계: 두 번째 상태 점검 수행

등록을 완료한 후에 health 노드로 API 호출을 보내서 WhatsApp Business API 클라이언트에 다시 한 번 상태 점검을 수행합니다.

결과로 나오는 출력은 다음과 같습니다.

{
    "health": {
        "gateway_status": "connected"
    }
}

connected의 gateway_status는 Coreapp 컨테이너가 WhatsApp 서버로 연결되어 연락처를 확인하고 메시지를 전송할 수 있다는 의미입니다.

WhatsApp Business API 클라이언트 업그레이드

업그레이드 과정에 가동이 중단되는 시간이 있습니다.

신속하게 다시 가동을 시작하고 실행할 수 있도록 업그레이드 전에 현재 애플리케이션 설정을 백업하는 것이 좋습니다. 백업 및 복원 문서를 참조하세요.

언제나 사용량이 가장 적은 시간에 업그레이드하는 것이 좋습니다.

1단계: WA_API_VERSION 환경 변수를 새 버전으로 변경

WA_API_VERSION 환경 변수는 다음을 사용하여 새 버전 번호로 업데이트해야 합니다.

export WA_API_VERSION=new-whatsapp-version

2단계: Docker 컨테이너 다시 시작

다음을 실행하여 Docker 컨테이너를 다시 시작합니다.

docker-compose up -d

결과로 나오는 출력은 다음과 같습니다.

biz_db_1 is up-to-date
Recreating biz_wacore_1 ... done
Recreating biz_waweb_1  ... done

MySQL 데이터베이스 사용자를 v2.23.x 이상으로 업그레이드

이제 앱이 실행 중일 때 데이터베이스를 업그레이드할 수 있는 데이터베이스 업그레이드 서비스를 사용하여 앱이 중단되지 않도록 할 수 있습니다.

1단계: 구성 파일 다운로드

dbupgrade-compose.yml 파일에 컨테이너 버전을 나타내는 필드가 있습니다.

예:

services:
  dbupgrade:
    image: docker.whatsapp.biz/coreapp:v${WA_API_VERSION:-2.21.3}

2단계: 컨테이너 시작

설치를 업그레이드하려면 WA_API_VERSION 환경 변수를 최신 버전으로 설정한 dbupgrade-service 컨테이너를 시작합니다.

WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.yml up -d

참고: 종료 코드와 관계없이 종료 시 컨테이너를 다시 시작하는 오케스트레이션을 사용하고 있을 경우 EXIT_ON_SUCCESS 환경 변수를 FALSE로 설정한 상태에서 서비스를 시작해야 종료 코드가 0일 때 컨테이너가 종료되는 것을 방지할 수 있습니다.

3단계: 업그레이드가 완료될 때까지 대기

데이터베이스 업그레이드에 성공하면 컨테이너가 코드 0과 함께 종료됩니다. 다음 Docker 명령을 사용하여 상태를 추적할 수 있습니다.

docker wait your-database-upgrade-container-name

dbupgrade-service 컨테이너의 종료 코드가 출력됩니다.

4단계: Coreapp과 Webapp 컨테이너 다시 시작

WA_API_VERSION 환경 변수를 최신 버전으로 설정하고 Coreapp과 Webapp Docker 컨테이너를 다시 시작합니다.

WA_API_VERSION=new-whatsapp-version docker-compose up -d

WhatsApp Business API 클라이언트 제거

제거하기 전에 현재 앱 설정을 백업하는 것이 좋습니다. 백업 및 복원 문서를 참조하세요.

모든 컨테이너를 삭제하여 개발 환경을 재설정해야 하는 경우 docker-compose.yml 파일이 포함된 디렉터리에서 다음 명령을 실행하세요.

docker-compose down

결과로 나오는 출력은 다음과 같습니다.

Stopping biz_waweb_1  ... done
Stopping biz_wacore_1 ... done
Stopping biz_db_1     ... done
Removing biz_waweb_1  ... done
Removing biz_wacore_1 ... done
Removing biz_db_1     ... done

컨테이너와 함께 docker-compose.yml 파일에 정의된 모든 볼륨을 제거하려면 -v 매개변수로 down 명령을 실행하세요.

docker-compose down -v

문제 해결

더욱 효과적인 문제 해결을 위해 WADebug를 사용하는 것이 좋습니다. WADebug는 WhatsApp Business API 설정에 관한 모든 잠재적인 이슈를 찾아내고, 더욱 효과적으로 WhatsApp 지원에 도움을 요청할 수 있는 명령줄 도구입니다.

WADebug를 사용할 수 없거나 도구 반환 오류를 실행하는 경우 다음 명령을 실행하여 모든 컨테이너에서 로그를 수집하세요.

docker-compose logs > debug_output.txt

특정 서비스의 로그를 수집하려면 서비스 이름(waweb 또는 wacore)을 docker-compose logs 명령에 추가하세요.

docker-compose logs waweb > debug_output.txt

현재 디렉터리의 debug_output.txt 파일에서 로그를 찾을 수 있습니다.

이 소프트웨어는 LGPLv2.1에 따라 라이선스가 부여된 FFmpeg 코드를 사용하고 소스는 여기에서 다운로드할 수 있습니다.