WhatsApp Business Management API

개요

Business Management API를 사용하면 WhatsApp과 관련된 비즈니스 자산(예: WhatsApp Business 계정, 메시지 템플릿)을 만들고 관리할 수 있습니다. 이 API는 마케팅 API를 기반으로 하고 그 엔드포인트의 일부를 사용합니다. 그러므로 이 문서에는 경우에 따라 마케팅 API 문서에 대한 링크가 포함될 수 있습니다.

요구 사항

액세스 토큰

이 플랫폼은 다음의 액세스 토큰 유형을 지원합니다. 사용하는 유형은 누가 앱을 사용하는지와, 귀하가 솔루션 제공업체인지 여부에 따라 달라집니다.

시스템 사용자 액세스 토큰

시스템 사용자 액세스 토큰은 개발자, 비즈니스나 조직, 또는 비즈니스나 조직 내의 사람들을 대표합니다. 이 토큰의 가장 큰 장점은 만료 기간이 없다는 것이며, 비즈니스 내에서 사용자 입력이 필요하지 않은 자동화된 서비스를 대표할 수 있습니다.

시스템 사용자 액세스 토큰은 솔루션 파트너가 온보딩된 고객에게 크레딧 라인을 공유하는 데 사용할 수 있는 유일한 토큰 유형입니다.

시스템 사용자 액세스 토큰을 생성하기 전에 시스템 사용자를 만들어야 합니다. 대부분의 엔드포인트는 토큰에서 식별된 사용자가 쿼리된 리소스에 대한 액세스 권한이 있는지 확인합니다. 사용자가 리소스에 대한 액세스 권한이 없을 경우, 요청이 오류 코드 200와 함께 거부됩니다.

시스템 사용자는 직원 또는 관리자일 수 있습니다.

직원 시스템 사용자

직원 시스템 사용자는 Meta 비즈니스에서 소유하거나 Meta 비즈니스에서 공유한 개별 WhatsApp Business 계정에 대한 액세스 권한을 부여받아야 합니다. 앱이 비즈니스가 소유한 몇 개의 WhatsApp Business 계정에만 액세스해야 하는 경우, 직원 시스템 사용자로 충분합니다.

직원 시스템 사용자를 생성하고 나면 시스템 사용자가 액세스해야 하는 각각의 WhatsApp Business 계정에 대해 전체 또는 부분적 액세스 권한을 부여해야 합니다.

관리자 시스템 사용자

기본적으로 관리자 시스템 사용자는 개발자나 개발자의 비즈니스가 소유하거나 공유받은 모든 WhatsApp Business 계정과 자산에 대한 완전한 액세스 권한이 있습니다.

관리자 시스템 사용자는 앱이 비즈니스에 새로 공유된 WhatsApp Business 계정에 액세스해야 할 경우에 유용합니다. 직원 시스템 사용자를 사용할 경우, 공유된 각각의 WhatsApp Business 계정에 대한 액세스 권한을 수동으로 부여해야 합니다.

WhatsApp Business 계정별로 부분적 액세스 권한을 부여하면 관리자 시스템 사용자의 기본 액세스 권한을 재정의할 수 있습니다.

시스템 사용자 만들기

시스템 사용자를 만드는 방법은 다음과 같습니다.

  1. Meta Business Suite에 로그인합니다.
  2. 왼쪽 상단 드롭다운 메뉴에서 비즈니스 계정을 찾아 설정(톱니바퀴) 아이콘을 클릭합니다.
  3. 비즈니스 설정을 클릭합니다.
  4. 사용자 > 시스템 사용자로 이동합니다.
  5. 추가 버튼을 클릭하고 관리자 또는 직원 시스템 사용자 중 하나를 만듭니다.

시스템 사용자 액세스 토큰 생성

시스템 사용자를 만들고 나서 시스템 사용자 액세스 토큰을 생성하는 방법은 다음과 같습니다.

  1. Meta Business Suite에 로그인합니다.
  2. 왼쪽 상단 드롭다운 메뉴에서 비즈니스 계정을 찾아 설정(톱니바퀴) 아이콘을 클릭합니다.
  3. 비즈니스 설정을 클릭합니다.
  4. 사용자 > 시스템 사용자로 이동합니다.
  5. 시스템 사용자 리스트에서 적절한 시스템 사용자를 선택합니다.
  6. 새 토큰 생성 버튼을 클릭합니다.
  7. 토큰을 사용할 앱을 선택합니다.
  8. 앱이 제대로 작동하고 토큰을 생성하는 데 필요한 권한을 선택합니다.

비즈니스 통합 시스템 사용자 액세스 토큰

비즈니스 통합 시스템 사용자 액세스 토큰은 온보딩된 개인 고객으로 범위가 설정되며, 기술 제공업체와 솔루션 파트너가 온보딩된 고객 데이터에 액세스할 때 사용해야 합니다.

이러한 토큰은 고객 WhatsApp Business 계정에서 앱 사용자의 입력 없이, 또는 향후 재인증을 요구하지 않고 프로그래밍 방식의 자동화된 작업을 수행하는 앱에 유용합니다.

비즈니스 통합 시스템 사용자 액세스 토큰을 생성하려면 임베디드 가입(비즈니스용 Facebook 로그인으로 구성)을 구현하고 고객이 플로를 완료하면 반환되는 코드를 교환해야 합니다.

이러한 토큰과 생성 방법에 대한 자세한 내용은 임베디드 가입 문서와 비즈니스 통합 시스템 사용자 액세스 토큰 문서를 참조하세요.

사용자 액세스 토큰

사용자 액세스 토큰은 모든 앱 개발자가 지원하고 사용할 수 있기는 하지만, 처음으로 앱 대시보드를 사용해서 첫 테스트 메시지를 보낼 경우에만 사용할 가능성이 큽니다. 그러나 앱을 개발하면서 시스템 사용자 액세스 토큰으로 전환할 가능성이 큽니다(기술 제공업체이거나 솔루션 제공업체일 경우에는 최종적으로 비즈니스 시스템 사용자 액세스 토큰으로 전환하게 될 것입니다). 이는 사용자 액세스 토큰이 빨리 만료되므로 몇 시간마다 새로운 토큰을 생성해야 하기 때문입니다.

사용자 액세스 토큰을 생성하는 방법은 여러 가지가 있습니다.

  • 앱 대시보드 > WhatsApp > API 설정 패널에 액세스합니다. 이 패널은 방문할 때마다 항상 새로운 사용자 액세스 토큰을 생성합니다. 이 토큰은 사용자로 범위가 자동 설정됩니다. 왜냐하면 패널에 액세스할 때 개발자 계정으로 로그인하기 때문입니다.
  • 그래프 API 탐색기를 사용합니다.
  • Facebook 로그인을 구현합니다.

요청에서 토큰 사용하기

API 요청을 보낼 때 승인 요청 헤더에서 Bearer 뒤에 토큰을 포함하세요. 예를 들면 다음과 같습니다.

curl 'https://graph.facebook.com/v18.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \

WhatsApp Business 계정 액세스 권한

대다수의 엔드포인트는 API 요청에 토큰이 포함된 사용자가 쿼리 대상인 WhatsApp Business 계정(또는 자산)에 대한 부분적 또는 전체적 액세스 권한도 부여받을 것을 요구합니다. 사용자에게 액세스 권한이 없는 경우, API는 오류 코드 200을 반환합니다.

시스템 사용자를 비롯한 모든 사용자에 대해 세분화된 액세스 권한을 설정할 수 있습니다. 시스템 사용자에 대한 세분화된 액세스 권한은 사용자 그룹에 대해 특정 자산의 액세스 권한을 제한하고자 하는 경우에 유용할 수 있습니다. 예를 들어 대규모 비즈니스를 소유하고 있고 특정 부서만 WhatsApp Business 계정의 템플릿과 비즈니스 전화번호 데이터에 대한 읽기 액세스 권한만 가지기를 원하는 경우, 해당 부서의 시스템 사용자를 만들고 세분화된 읽기 전용 액세스 권한을 설정할 수 있습니다.

WhatsApp Business 계정 또는 자산에 사용자 액세스 권한을 지정하는 방법:

  1. Meta Business Suite에 로그인합니다.
  2. 왼쪽 상단 드롭다운 메뉴에서 비즈니스 계정을 찾아 설정(톱니바퀴) 아이콘을 클릭합니다.
  3. 비즈니스 설정을 클릭합니다.
  4. 계정 > WhatsApp 계정으로 이동합니다.
  5. 적절한 WhatsApp Business 계정을 선택합니다.
  6. WhatsApp 계정 액세스 탭을 선택합니다.
  7. +사용자 추가 버튼을 클릭합니다.
  8. 적절한 시스템 사용자를 선택하고 WhatsApp Business 계정에 대해 적절한 액세스 수준을 할당합니다.

엔드포인트 테스트

엔드포인트를 테스트할 때 Postman 컬렉션 또는 cURL을 사용하는 것이 좋습니다. 그래프 API 탐색기 도구를 사용할 수 있기는 하지만 이는 토큰을 쿼리 문자열 매개변수로 전달하므로 권장하지 않습니다(대신 요청 헤더에서 토큰을 전달하세요).

비즈니스에 대한 정보 가져오기

비즈니스에 대한 정보를 가져오려면 WhatsAppBusinessAccount 엔드포인트로 GET 요청을 보냅니다. 여기에서 <WHATSAPP_BUSINESS_ACCOUNT_ID>는 자신의 WhatsApp Business 계정 ID입니다.

요청 예시

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

응답 예시

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "timezone_id": "1",
  "message_template_namespace": "05155c78_261e_4b2f_82b3_d7958d4cf75f"
}

비즈니스에 대한 특정한 정보(예: 이름, 메시지 템플릿, 전화번호)를 가져오려면 WhatsAppBusinessAccount 엔드포인트로 GET 요청을 보내고(여기에서 <WHATSAPP_BUSINESS_ACCOUNT_ID>는 자신의 WhatsApp Business 계정 ID임) fields 매개변수를 반환하려는 항목의 리스트로 설정합니다.

요청 예시

curl -i -X GET 'https://graph.facebook.com/v19.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=id,name,message_templates,phone_numbers' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

응답 예시

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "message_templates": {
    "data": [
      {
        "name": "hello_world",
        "components": [
          {
            "type": "HEADER",
            "format": "TEXT",
            "text": "Hello World"
          },
          {
            "type": "BODY",
            "text": "Welcome and congratulations!! This message demonstrates your ability to send a message notification from WhatsApp Business Platform. Thank you for taking the time to test with us."
          },
          {
            "type": "FOOTER",
            "text": "WhatsApp Business Team"
          }
        ],
        "language": "en_US",
        "status": "APPROVED",
        "category": "ACCOUNT_UPDATE",
        "id": "307191531401674"
      },
      {
        "name": "sample_flight_confirmation",
        "components": [
          {
            "type": "HEADER",
            "format": "DOCUMENT"
          },
          {
            "type": "BODY",
            "text": "Confirmamos tu vuelo a {{1}}-{{2}} para el {{3}}."
          },
          {
            "type": "FOOTER",
            "text": "Este mensaje proviene de un negocio no verificado."
          }
        ],
        "language": "es",
        "status": "APPROVED",
        "category": "TICKET_UPDATE",
      },
      ...

사용 제한

앱이 WhatsApp Business Management API에 보낸 요청은 앱 호출 수에 반영됩니다. 앱의 호출 수는 앱이 1시간 동안 보낼 수 있는 호출 횟수입니다. 다음 WhatsApp Business Management API의 경우, 앱은 기본적으로 WhatsApp Business 계정(WABA) 1개당 앱별로 1시간에 200회의 호출을 보낼 수 있습니다. 등록된 전화번호가 1개 이상인 활성 상태의 WABA인 경우, 앱은 활성화된 WABA 1개당 앱별로 1시간에 5,000회의 호출을 보낼 수 있습니다.
호출 유형 엔드포인트

GET

/{whatsapp-business-account-id}

GET, POST 및 DELETE

/{whatsapp-business-account-id}/assigned_users

GET

/{whatsapp-business-account-id}/phone_numbers

GET, POST 및 DELETE

/{whatsapp-business-account-id}/message_templates

GET, POST 및 DELETE

/{whatsapp-business-account-id}/subscribed_apps

GET

/{whatsapp-business-account-to-number-current-status-id}

다음 크레딧 라인 API의 경우 앱별로 1시간에 5,000회의 호출을 보낼 수 있습니다.
호출 유형 엔드포인트

GET

/{business-id}/extendedcredits

POST

/{extended-credit-id}/whatsapp_credit_sharing_and_attach

GET 및 DELETE

/{allocation-config-id}

GET

/{extended-credit-id}/owning_credit_allocation_configs

사용 제한에 도달하지 않게 하려면 Webhooks를 사용하여 메시지 템플릿, 전화번호 및 WABA의 상태 업데이트를 추적하는 것이 좋습니다.

현재 사용량을 알아보는 방법에 대한 자세한 내용은 헤더를 참조하세요.

더 알아보기

  • Facebook SDK — Facebook 로그인을 사용하여 사용자에게 권한을 요청하기 위해 Facebook SDK 중 하나를 구현할 수 있습니다.
  • 마케팅 API 비즈니스 관리자 – 마케팅 API 비즈니스 관리자에 대해 자세히 알아보세요.
  • 앱 검수 – 자신이 소유한 데이터나 다른 사람이 소유한 데이터에 액세스하기 위한 프로세스에 대해 자세히 알아보세요.
  • WhatsApp Business 플랫폼 설정 동영상을 시청해 보세요.

다음 단계