클라우드 API에서 온프레미스 API로 마이그레이션

온프레미스 API에 대한 지원을 중단합니다. 자세한 내용과 차세대 클라우드 API로 마이그레이션하는 방법을 알아보려면 온프레미스 API 지원 중단 문서를 참조하세요.

이 문서에서는 클라우드 API에서 온프레미스 API로 비즈니스 전화번호를 마이그레이션하는 방법을 설명합니다. 온프레미스 API에서 클라우드 API로 마이그레이션하려면 온프레미스 API에서 클라우드 API로 마이그레이션을 참조하세요.

하나의 API에서 다른 API로 비즈니스 전화번호를 마이그레이션하는 방법은 한 WhatsApp Business 계정(WABA)에서 다른 계정으로 전화번호를 마이그레이션하는 것과 같지 않습니다.

마이그레이션해도 다음에는 영향을 미치지 않습니다.

비즈니스 전화번호의 표시 이름, 인증 상태 또는 품질 평가
비즈니스 전화번호에서 사용하는 템플릿 또는 그 상태
소유 권한이 있는 WABA, 공식 비즈니스 계정 상태 또는 메시지 한도

그러나 마이그레이션을 지원하려면 API의 차이점을 알고 이를 해결하기 위한 적절한 조치를 취한 다음, 이 문서에서 설명하는 마이그레이션 단계를 수행해야 합니다.

모범 사례

앱이 모든 API의 차이점을 처리할 수 있는지 확인한 후에는 먼저 소량의 비즈니스 전화번호를 마이그레이션하고 온프레미스 API를 통해 제공하고자 하는 모든 기능이 올바르게 작동하는지 확인해야 합니다. 모든 것이 올바르게 작동함을 확인하고 나면 전화번호를 추가로 마이그레이션합니다.

또한 온프레미스 API 배포에 대한 트래픽이 적을 때 마이그레이션을 수행하는 것이 좋습니다.

API 간 차이점

앱이 이러한 차이를 처리할 수 있는지 확인한 후에 마이그레이션 프로세스를 시작하세요.

Webhooks

클라우드 API 및 Business Management API Webhooks 페이로드 구조는 온프레미스 API 페이로드 구조와 다릅니다. 온프레미스 API Webhooks만 처리할 수 있는 새로운 Webhooks 엔드포인트를 만드는 것이 좋습니다.

다음 문서를 참고하면 페이로드의 차이를 이해하는 데 도움이 됩니다.

구성: WhatsApp용 Webhooks
클라우드 API Webhooks 페이로드: Webhooks 알림 페이로드 참고 자료
Business Management API Webhooks 페이로드: Webhooks 설정

온프레미스 API로의 마이그레이션이 완료되면 비즈니스 전화번호의 클라우드 API Webhooks가 더 이상 전송되지 않고 온프레미스 API Webhooks 전송이 시작됩니다.

미디어

클라우드 API에 업로드된 모든 미디어의 미디어 ID는 온프레미스 API를 통해 메시지를 전송할 때 사용할 수 없으므로 온프레미스 API를 사용하여 미디어를 다시 업로드하고 새 미디어 ID를 생성하거나, 미디어가 공개 서버에서 호스팅되는 경우에는 미디어 URL을 사용해야 합니다. 미디어 메시지 보내기를 참조하세요.

오류 코드

클라우드 API 및 Business Management API 오류 코드는 온프레미스 API 오류 코드와 다릅니다. 다음 문서를 참조하세요.

PPT(Push-To-Talk) 메시지

온프레미스는 messages.type을 voice로 설정하여 Webhooks에서 PPT(Push-To-Talk) 메시지를 식별하지만, 클라우드 API는 messages.audio.voice를 true로 설정하여 PTT 메시지를 식별합니다.

가동 중지 시간

가동 중지 시간은 등록 단계(3단계)를 수행하는 즉시 시작되고 몇 초 이내로 종료됩니다. 이 시간에는 WhatsApp 사용자가 전화번호로 전송한 메시지가 조용히 차단됩니다.

전화번호에서 활동이 적게 발생하는 시간에 마이그레이션 일정을 잡아서 가동 중지 시간이 미치는 영향을 최소화하는 것이 좋습니다.

1단계: 온프레미스 API 통합

온프레미스 API로 비즈니스 전화번호를 마이그레이션하고 있으므로 앱이 성공적으로 온프레미스 API 클라이언트를 사용하고 비즈니스 전화번호와 연결된 WhatsApp Business 계정에 Webhooks가 올바르게 구성되어 있는지 확인하세요.

2단계: 마이그레이션 준비

마이그레이션을 완료하는 동안은 메시지 전송을 중단하는 것이 좋습니다.

WhatsApp Business API 온프레미스 클라이언트는 WhatsApp 서버에 연결하기 위한 몇 가지 네트워크 요구 사항이 있습니다. 준비가 완료되었는지 확인하기 위해 네트워크 설정 및 디버깅을 확인하세요.

3단계: API 클라이언트 등록

온프레미스 API 클라이언트에서 비즈니스 전화번호를 등록합니다. 이를 위해서 /account 엔드포인트를 호출합니다.

POST /v1/account

{
    "cc": "COUNTRY_CODE",
    "phone_number": "PHONE_NUMBER_WITHOUT_COUNTRY_CODE",
    "method": "sms" or "voice",
    "cert": "VERIFIED_NAME_CERT_IN_BASE64",
    "pin": "EXISTING_6_DIGIT_PIN" # required if two-step verification is enabled
}

수신한 응답에 따라 등록 절차는 완료된 것으로 간주하거나 완료하는 데 다른 절차가 필요할 수도 있습니다. 성공하면 다음 HTTP 상태 코드 중 하나를 수신하게 됩니다. 수신한 응답과 일치하는 지침을 따르세요.

201 Created — 계정이 이미 존재합니다. 등록되어 있으므로 다른 절차가 필요하지 않습니다.
202 Accepted — 계정이 존재하지 않습니다. 요청에서 선택한 방법에 따라 SMS 또는 음성 통화로 등록 코드를 확인하세요. 이 응답에서 반환하는 페이로드는 적절한 표시 이름이 설정되었는지 확인하기 위한 cert 매개변수에서 디코딩한 vname이 포함됩니다. 적절한 이름이 설정되었다면 계정 등록 완료로 넘어가 등록을 완료하세요.

이 엔드포인트에 사용 가능한 모든 필드는 여기를 참조하세요.

등록이 완료되면 온프레미스 API 클라이언트에서 메시지를 받습니다.

4단계: 샤드 설정

클라이언트가 등록되면 필요에 따라 샤드를 설정할 수 있습니다.

5단계: 메시지를 보내기 시작

이제 고객에게 메시지를 보낼 준비가 되었습니다. 메시지 보내기 가이드에서 지침을 참조하세요.

WhatsApp Business 플랫폼 | 클라우드 API | Business Management API