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

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

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

클라우드 API에서 온프레미스 API로 마이그레이션하려면 클라우드 API에서 온프레미스 API로 마이그레이션을 참조하세요.

사용 방법

마이그레이션을 위해서는 비즈니스 전화번호에 대한 메타데이터를 생성한 후, 이 데이터를 사용하여 클라우드 API에 사용할 전화번호를 등록해야 합니다. 그러면 온프레미스 API에서 해당 전화번호의 등록이 해제됩니다. 전화번호는 한 번에 하나의 API에만 사용하도록 등록할 수 있기 때문입니다.

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

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

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

요구 사항

Meta 앱

온보딩한 고객 데이터와 함께 클라우드 API와 Business Management API를 사용할 수 있으며, 클라우드 API 및 Business Management API Webhooks를 처리할 수 있는 Meta 비즈니스 앱이 필요합니다. 이 앱은 인증된 Meta Business 계정과 연결되어 있거나 이러한 계정에서 소유권을 주장한 것이어야 합니다.

Meta 비즈니스 앱이 없거나 Meta 비즈니스 앱이 있더라도 WhatsApp 제품이 구성되어 있지 않은 경우, 클라우드 API 시작하기 가이드의 단계를 완료하세요. 이 단계를 완료하면 클라우드 API와 Business Management API를 테스트하는 데 필요한 모든 자산이 생성됩니다.

앱 검수

Meta 앱은 앱 검수를 거쳐서 whatsapp_business_messaging 및 whatsapp_business_management 권한에 대한 승인(즉, 고급 액세스 권한)을 받아야 합니다.

모범 사례

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

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

API 간 차이점

다음 온프레미스 API 기능은 클라우드 API에서 지원되지 않거나 다르게 처리됩니다. 앱이 이러한 차이를 처리할 수 있는지 확인한 후에 마이그레이션 프로세스를 시작하세요.

Webhooks

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

페이로드의 차이점을 이해하고 앱 대시보드를 사용하여 앱에서 Webhooks를 구성하는 방법을 알고 싶다면 다음 문서를 참조하세요.

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

비즈니스 전화번호를 클라우드 API로 마이그레이션하고 나면 WhatsApp Business 계정 > 구독한 앱 엔드포인트를 사용하여 Meta 앱이 해당 비즈니스 계정에 연결된 WABA의 Webhooks를 구독하도록 해야 합니다.

요청 구문

curl -X POST 'https://graph.facebook.com/v17.0/<WABA_ID>/subscribed_apps' \
-H 'Authorization: Bearer EAAJB...'

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

미디어

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

메시지의 무결성을 보장하기 위해 온프레미스 API에서 허용되는 일부 미디어 호스팅 도메인은 클라우드 API에서 허용되지 않습니다. 미디어에 호스팅 서비스를 사용하는 경우, 마이그레이션 전에 자유 형식 메시지 및 템플릿 메시지의 미디어 URL을 테스트하는 것이 좋습니다. 호스트가 잘못 차단되었다고 생각하는 경우, 지원팀에 문의하세요.

오류 코드

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

속성 검증

온프레미스 API는 메시지 POST 본문 페이로드에서 알려지지 않은 속성을 허용할 수 있지만, 클라우드 API는 이러한 요청을 거부하므로 메시지 전송 요청이 지원되는 속성만 사용하도록 하세요.
온프레미스 API를 사용하면 버튼이 하나뿐인 메시지를 보낼 때 버튼 인덱스를 생략할 수 있지만, 클라우드 API는 이러한 요청을 거부하므로 버튼을 포함하는 메시지 전송 요청에 인덱스와 해당 값도 포함해야 합니다.
온프레미스 API는 인터랙티브 메시지를 보낼 때 행동 및 버튼 개체 속성에서 선행/후행 공백(또는 공백만)을 포함하는 문자열을 허용하지만, 클라우드 API는 이러한 요청을 거부합니다.

PPT(Push-To-Talk) 메시지

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

스티커팩

클라우드 API는 스티커팩을 지원하지 않습니다.

가동 중지 시간

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

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

처리량

온프레미스 비즈니스 전화번호에 2개 이상의 샤드를 실행하는 다중 연결이 있는 경우, 클라우드 API에서 높은 처리량으로 자동 업그레이드됩니다.

공식 비즈니스 계정

공식 비즈니스 계정(OBA) 상태의 비즈니스 전화번호를 마이그레이션하는 경우 전화번호를 등록(3단계)할 때 (2단계에서 생성된) 메타데이터를 포함하면 상태가 보존됩니다. 이 데이터를 생략하면 해당 전화번호는 OBA 상태를 잃게 됩니다.

마이그레이션 지원

궁금한 점이 있거나 마이그레이션에 도움이 필요한 경우, 다음과 같이 기술 지원 티켓을 제출하세요.

주제: WABiz: 클라우드 API
요청 유형: 온프레미스 API -> 클라우드 API 마이그레이션 문제

1단계: 2단계 인증 비활성화

비즈니스 전화번호의 PIN을 아는 경우, 이 단계를 건너뛸 수 있습니다.

3단계를 수행할 때는 비즈니스 전화번호의 PIN이 필요합니다. 따라서 PIN을 모르는 경우, 먼저 비즈니스 전화번호에서 2단계 인증을 비활성화해야 합니다. 비즈니스 전화번호를 소유하지 않은 경우, 소유자에게 비활성화를 요청하세요.

2단계: 전화번호 메타데이터 생성

백업 및 복원 API를 사용하여 비즈니스 전화번호에 대한 메타데이터를 생성하세요.

요청 구문

POST /v1/settings/backup
{
  "password": "<PASSWORD>"
}

<PASSWORD>에는 어떤 문자열이든 사용할 수 있습니다. 이 값은 메타데이터를 인코딩하는 데 사용합니다. 따라서 다음 단계에 필요하므로 기억해 두시기 바랍니다.

응답

{
  "settings": {
    "data": "<METADATA>"
  },
  "meta": {
    "api_status": "<API_STATUS>",
    "version": "<API_VERSION>"
  }
}

이 API는 비즈니스 전화번호와 설정을 설명하는 data 속성에 할당된 인코딩된 문자열을 반환합니다. 이 값은 다음 단계에 필요하므로 캡처해 두시기 바랍니다.

<METADATA> — 비즈니스 전화번호와 설정을 설명하는 인코딩된 문자열입니다. 이 값은 다음 단계에 필요하므로 캡처해 두시기 바랍니다.
<API_STATUS> — 온프레미스 API 배포의 상태입니다.
<API_VERSION> — 현재 실행 중인 온프레미스 API 버전 번호입니다.

요청 예시

curl 'https://localhost:9090/v1/settings/backup' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "password": "tacocat"
}'

응답 예시

{
  "settings": {
    "data": "V0FCS..."
  },
  "meta": {
    "api_status": "stable",
    "version": "2.49.3"
  }
}

3단계: 전화번호 등록

위 2단계에서 얻은 백업 메타데이터가 올바르게 전달되고 3단계(이 단계)를 진행하는 중에 클라우드 API를 수정하지 않는 경우 일회용 비밀번호(OTP)가 필요하지 않습니다.

클라우드 API WhatsApp Business 전화번호 > 등록 엔드포인트를 사용하여 클라우드 API에 사용하도록 전화번호를 등록합니다.

인코딩된 비즈니스 전화번호 메타데이터 값과 이전 단계에서 얻은 비밀번호를 포함합니다. 이 데이터가 없어도 비즈니스 전화번호를 등록할 수 있지만, 이 전화번호를 포함하지 않을 경우 비즈니스 전화번호의 프로필 데이터가 사라집니다. 이는 WhatsApp Business 계정의 공식 비즈니스 계정 상태에 영향을 미칠 수 있습니다.

요청 구문

POST /<BUSINESS_PHONE_NUMBER_ID>/register

POST 본문

{
  "messaging_product": "whatsapp",
  "pin": "<NEW_OR_EXISTING_PIN>",
  "backup": {
    "password": "<PASSWORD>",
    "data": "<METADATA>"
  }
}

<NEW_OR_EXISTING_PIN> — 기존 PIN 또는 비즈니스 전화번호에 설정하고자 하는 PIN입니다.
<PASSWORD> — 이전 단계에서 비즈니스 전화번호 메타데이터를 생성하는 데 사용한 비밀번호입니다.
<METADATA> — 비즈니스 전화번호 및 설정을 설명하고 이전 단계에서 생성된 인코딩된 문자열입니다.

응답

{
  "success": <SUCCESS>
}

이 API는 등록이 성공할 경우 success를 true로 설정하여 응답하고, 오류가 있을 경우 false로 설정하여 응답합니다.

요청 예시

curl 'https://graph.facebook.com/v21.0/110200345501442/register' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "pin": "134568",
  "backup": {
    "password": "tacocat",
    "data": "V0FCS..."
  }
}'

응답 예시

{
  "success": true
}

4단계: 메시지 전송 상태 확인(선택 사항)

비즈니스 전화번호에서 health_status 필드를 요청하고 클라우드 API를 통한 메시지 전송에 사용할 수 있는지 확인합니다. 메시지 전송 상태를 참조하세요.

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