솔루션 파트너 시작하기

이 가이드에서는 고객에게 클라우드 API를 제공하기 위해 솔루션 파트너가 진행해야 하는 절차를 살펴봅니다. 단계는 크게 4가지로 나뉩니다.

1. 준비 및 계획
2. 자산 설정
3. 계약 체결
4. 통합 빌드

단계를 모두 완료하면 월간 업데이트를 확인해 주세요.

준비 및 계획

문서 읽기

시작하기 전에 개발자 문서와 Postman 컬렉션을 읽는 것이 좋습니다. 그러면 클라우드 API를 시작하고 전화번호를 마이그레이션하는 방법 등의 클라우드 API 사용 방법을 이해하는 데 도움이 됩니다.

온보딩 및 마이그레이션 계획

임베디드 가입을 사용하여 새로운 고객을 클라우드 API에 온보딩해야 합니다. 아직 하지 않았다면 임베디드 가입을 통합하고 출시하세요. 임베디드 가입은 고객을 등록하는 가장 빠르고 쉬운 방법이며, 고객이 5분 내로 메시지 전송을 시작할 수 있습니다.

이제 먼저 어떤 고객을 클라우드 API로 마이그레이션할지 생각해 보세요. 일반적으로는 모든 고객을 온프레미스에서 클라우드 API로 마이그레이션하는 것을 권장하지만 각 고객의 요구 사항이 다를 수 있습니다. 마이그레이션할 고객을 생각할 때 다음을 고려해 보세요.

어떤 고객이 마이그레이션할지 아는 경우 마이그레이션 계획과 일정을 빌드할 수 있습니다.

계획을 세우는 동안 두 가지 시나리오에 대비해서 시스템을 디자인하세요. 하나는 신규 고객을 온보딩하는 것이고 다른 하나는 기존 고객을 온프레미스에서 클라우드 API로 마이그레이션하는 것입니다. 마이그레이션 시나리오의 경우 기존 온프레미스 인스턴스를 백업하고 해당 전화번호를 클라우드 API로 마이그레이션할 계획을 세우세요.

고객과의 의사소통 계획

먼저 기존 고객에게 마이그레이션에 대해 알릴지 결정해야 합니다. 그런 다음 클라우드 API 설정을 지원하기 위한 문서를 작성하거나 업데이트할지 결정해야 합니다.

가격 결정

클라우드 API의 호스팅 비용은 Meta에서 부담하므로 그에 맞게 가격을 업데이트할지 결정해야 합니다.

자산 설정

클라우드 API를 사용하려면 솔루션 파트너에 다음과 같은 자산이 필요합니다.

계약 체결

서비스 약관 수락

WhatsApp Business 메시징 클라우드 API에 액세스하려면 먼저 비즈니스를 대신해 WhatsApp Business 플랫폼 서비스 약관을 수락해야 합니다.

이를 위해서는 WhatsApp 관리자로 이동하여 정보 배너의 서비스 약관을 수락합니다.

클라우드 API의 기존 베타 파트너인 경우, 90일의 유예 기간이 주어집니다. 즉, 2022년 7월 5일 전까지 약관에 액세스해야 하며, 그렇지 않을 경우 액세스 권한이 상실됩니다.

온프레미스 API에서 마이그레이션하는 비즈니스를 비롯한 모든 신규 클라우드 API 비즈니스의 경우 클라우드 API를 사용하려면 서비스 약관을 수락해야 합니다. 서비스 약관을 수락할 때까지 등록 호출은 실패합니다.

통합 빌드

1단계: 시스템 사용자 액세스 토큰 가져오기

그래프 API 호출은 인증에 액세스 토큰을 사용합니다. 자세한 내용은 액세스 토큰을 참조하세요. 시스템 사용자를 통해 토큰을 생성하는 것이 좋습니다.

시스템 사용자 액세스 토큰을 생성하는 방법:

1. 비즈니스 관리자 > 비즈니스 설정 > 사용자 > 시스템 사용자로 이동하여 자신이 만든 시스템 사용자를 확인합니다.
2. 해당 사용자를 클릭하고 자산 추가를 선택합니다. 그러면 새 창이 열립니다.
3. 왼쪽 창의 자산 유형 선택에서 앱을 선택합니다. 자산 선택에서 사용하려는 Meta 앱을 선택합니다(앱에 올바른 권한이 있어야 함). 해당 앱에 앱 개발을 활성화합니다.
4. 변경 사항 저장을 선택하여 설정을 저장하고 시스템 사용자 메인 화면으로 돌아옵니다.
5. 이제 토큰을 생성할 준비가 되었습니다. 시스템 사용자 메인 화면에서 토큰 생성을 클릭하고 Meta 앱을 선택합니다. 앱을 선택하면 사용 가능한 권한 리스트가 표시됩니다. whatsapp_business_management와 whatsapp_business_messaging을 선택합니다. 토큰 생성을 클릭합니다.
6. 시스템 사용자, 할당된 앱, 액세스 토큰이 포함된 새 창이 열립니다. 토큰을 저장합니다.
7. 또는 토큰을 클릭하여 토큰 디버거를 확인할 수도 있습니다. 디버거에는 선택한 두 가지 권한이 표시될 것입니다. 토큰을 액세스 토큰 디버거에 직접 붙여 넣을 수도 있습니다.

2단계: Webhooks 설정

Webhooks를 설정하면 WhatsApp Business 플랫폼에서 실시간 HTTP 알림을 받을 수 있습니다. 즉, 예를 들어 고객에게 메시지를 받거나 WhatsApp Business 계정(WABA)에 변경 사항이 있을 때 알림을 받게 됩니다.

Webhooks를 설정하려면 Meta 및 WhatsApp의 요구 사항에 맞는 URL로 인터넷과 연결된 웹 서버를 만들어야 합니다. 그 방법에 대한 자세한 내용은 엔드포인트 만들기를 참조하세요. 테스트 목적으로 엔드포인트가 필요할 경우 테스트 Webhooks 엔드포인트를 생성할 수 있습니다.

앱 설정

엔드포인트가 준비되면 Meta 앱에서 사용하도록 구성합니다.

보유한 모든 앱에 대해 Webhooks를 한 번씩만 설정해야 합니다. 동일한 Webhooks를 사용하여 여러 WhatsApp Business 계정에서 여러 이벤트 유형을 수신할 수 있습니다. 자세한 내용은 Webhooks 섹션을 참조하세요.

3단계: WABA 구독

올바른 계정에 대한 알림을 받으려면 앱을 구독하세요.

curl -X POST \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps' \
-H 'Authorization: Bearer ACCESS_TOKEN'

아래와 같은 응답을 받을 경우 이 계정의 전화번호에 대한 모든 Webhooks 이벤트가 구성된 Webhooks 엔드포인트로 전송됩니다.

{
  "success": true
}

4단계: 전화번호 ID 가져오기

메시지를 전송하려면 사용하고자 하는 전화번호를 등록해야 합니다. 이는 시작하기 전에에서 언급한 비즈니스 전화번호입니다.

등록을 진행할 수 있으려면 해당 전화번호 ID를 찾아야 합니다. 전화번호 ID를 가져오려면 다음과 같이 API 호출을 보냅니다.

curl -X GET \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
-H 'Authorization: Bearer ACCESS_TOKEN'

요청이 성공할 경우 응답에는 WABA와 연결된 모든 전화번호가 포함됩니다.

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"
    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

등록하려는 전화번호의 ID를 저장합니다. 이 엔드포인트에 대한 자세한 내용은 전화번호 읽기를 참조하세요.

마이그레이션 예외

5단계: 전화번호 등록

전화번호 ID가 있으면 등록이 가능합니다. 등록 API 호출에서 다음과 같이 두 가지 작업을 동시에 수행합니다.

1. 전화번호를 등록합니다.
2. 6자리 등록 코드를 설정하여 2단계 인증을 활성화합니다. 이 코드는 비즈니스가 직접 설정해야 합니다. 이 코드를 나중에 요청할 수 있으므로 저장하고 기억해 둡니다.

2단계 인증 설정은 클라우드 API 사용을 위한 요구 사항입니다. 2단계 인증을 설정하지 않으면 다음과 같이 온보딩 실패 메시지를 받게 됩니다.

요청 샘플:

curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp","pin": "6_DIGIT_PIN"}'

응답 샘플:

{
  "success": true
}

임베디드 가입 사용자

6단계: 소비자 앱으로부터 메시지 수신

참여하는 고객이 비즈니스로 메시지를 보내면 24시간 동안 해당 고객과 무료로 메시지를 주고받을 수 있습니다. 이 기간을 고객 서비스 기간이라고 합니다. 테스트를 위해 원하는 만큼 메시지를 전송할 수 있도록 이 기간을 활성화하는 것이 좋습니다.

개인 WhatsApp iOS/Android 앱에서 조금 전 등록한 전화번호로 메시지를 보냅니다. 메시지가 전송되면 다음과 같은 형식의 알림과 함께 Webhooks로 메시지가 수신됩니다.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315551234",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16315555555"
              }
            ],
            "messages": [
              {
                "from": "16315555555",
                "id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXmuSf",
                "timestamp": "1602139392",
                "text": {
                  "body": "Hello!"
                },
                "type": "text"
                }
            ]
          },
        "field": "messages"
        }
      ]
    }
  ]
}

7단계: 테스트 메시지 전송

고객 서비스 기간을 활성화하면 이전 단계에서 사용한 소비자 번호로 테스트 메시지를 전송할 수 있습니다. 이를 위해서는 다음과 같이 API 호출을 보냅니다.

curl -X  POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp", "to": "16315555555","text": {"body" : "hello world!"}}'

호출에 성공하면 응답에 메시지 ID가 포함됩니다. 이 ID를 사용하여 Webhooks를 통해 메시지의 진행 상황을 추적합니다. 이 ID의 최대 길이는 128자입니다.

응답 샘플:

{
  "id":"wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}

월간 업데이트 확인

매월 첫 번째 화요일에 클라우드 API 업데이트를 릴리스합니다. 여기에는 새로운 기능과 개선 사항이 포함됩니다. 클라우드 API가 자동으로 업데이트되므로 새로운 기능을 사용하기 위해 별도의 조치를 취할 필요가 없습니다.

FAQ

일반 FAQ

기술적 구현 FAQ

What is the architecture of the Cloud API?

The Cloud API architecture significantly simplifies the Solution Partner's operational and infrastructure requirements to integrate with WhatsApp Business Platform. First, it removes the infrastructure requirements to run Business API docker containers (CAPEX savings). Second, it obviates the need of operational responsibilities to manage the deployment (OPEX savings). For details, refer to the architecture diagram comparing the On-Premises and Cloud API deployments.

고유 링크

데이터 공개 범위 및 보안 FAQ

규정 준수 FAQ