클라우드 API

WhatsApp Business 플랫폼 > 클라우드 API

개요

Meta가 호스팅하는 클라우드 API를 사용하면 중대형 비즈니스가 대규모로 고객과 소통할 수 있습니다. 비즈니스는 이 API를 사용하여 수천 명의 고객을 상담원이나 봇과 연결하는 시스템을 구축함으로써 프로그래밍 방식 및 수동 통신을 지원할 수 있습니다. 또한 비즈니스는 이 API를 다양한 백엔드 시스템(예: CRM, 마케팅 플랫폼)과 통합할 수 있습니다.

HTTP 프로토콜

클라우드 API는 그래프 API를 기반으로 하므로 HTTP 프로토콜과 URL 매개변수, 헤더 및 요청 본문의 조합을 사용하여 요청이 이루어집니다. 예를 들어 UNIX 기반 명령줄에서 클라우드 API로 보내는 일반적인 호출은 다음과 같습니다.

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

그래프 API에 익숙하지 않을 경우 그래프 API 문서에서 기본 정보를 참조하세요. 그래프 API와 클라우드 API의 주된 차이점은 자주 사용하는 액세스 토큰 유형, 리소스 권한, 요청 구문, Webhooks 구문에 있습니다. 이러한 차이점은 클라우드 API 문서 세트의 해당 섹션에서 자세히 설명합니다.

리소스

API를 사용할 때 상호 작용하게 되는 주요 리소스는 다음과 같습니다.

비즈니스 포트폴리오

API를 사용하려면 비즈니스 포트폴리오가 있어야 합니다. 포트폴리오가 없을 경우 시작하기 프로세스 중에 포트폴리오를 만들라는 메시지가 표시됩니다. 비즈니스 포트폴리오는 WhatsApp Business 계정(WABA) 및 비즈니스 전화번호의 컨테이너 역할을 합니다.

비즈니스 포트폴리오에 대해 자세히 알아보려면 Meta Business Suite의 비즈니스 포트폴리오 정보 고객 센터 문서를 참조하세요.

WhatsApp Business 계정

WhatsApp Business 계정은 WhatsApp Business 플랫폼에서 비즈니스를 대표하고 주로 특정 비즈니스에 대한 메타데이터로 구성됩니다. WhatsApp Business 전화번호 및 WhatsApp 메시지 템플릿과 같은 대부분의 기타 WhatsApp 리소스가 WABA와 연결됩니다.

시작하기 문서에 나와 있는 단계에 따라 WABA를 만들 수 있습니다. WABA 및 WABA의 제약 사항에 대해 자세히 알아보려면 WhatsApp Business 계정을 참조하세요.

WhatsApp Business 전화번호

WhatsApp Business 전화번호(비즈니스 전화번호)는 실제 전화번호를 나타냅니다. 이 전화번호를 클라우드 API에 사용하도록 등록하고 나면 API를 통해 WhatsApp 사용자와 메시지를 주고받는 데 사용할 수 있습니다.

비즈니스 전화번호는 대부분 전화번호 자체와 비즈니스에 대한 메타데이터로 구성되고, 이 메타데이터는 사용자가 비즈니스 전화번호와 상호작용할 때 WhatsApp 클라이언트에 표시될 수 있습니다.

시작하기 문서에 나와 있는 단계에 따라 비즈니스 전화번호를 만들 수 있습니다. 비즈니스 전화번호와 그 용도에는 제약 사항이 있습니다. 자세한 내용은 비즈니스 전화번호 문서를 참조하세요.

WhatsApp 메시지 템플릿

WhatsApp 메시지 템플릿(템플릿)은 다양한 템플릿 구성 요소를 사용하여 API를 통해 구성할 수 있는 맞춤형 템플릿입니다. 생성된 템플릿은 자동으로 검토되며, 승인을 받은 후에는 템플릿 메시지에 사용할 수 있습니다.

API를 통해 보낼 수 있는 기본적인 메시지 유형 2가지는 자유 형식 메시지와 템플릿 메시지입니다. 이 두 가지 중에서 템플릿 메시지는 승인된 WhatsApp 메시지 템플릿을 사용해야 하므로 가장 제약이 많습니다. 그러나 템플릿은 검토를 거쳐 승인을 받은 다음에 사용해야 하므로, 템플릿 메시지는 수신자로부터 부정적 피드백을 받을 가능성이 더 낮습니다. 부정적인 피드백을 받을 경우, 고객에게 메시지를 전달하는 데 제약을 받게 될 수 있습니다.

템플릿에 대한 자세한 내용은 템플릿 문서를 참조하세요.

Webhooks

Webhooks는 HTTP 프로토콜을 사용하여 서버의 공개 엔드포인트로 전송되는 JSON 페이로드입니다. 클라우드 API는 Webhooks를 많이 사용합니다. WhatsApp 사용자가 비즈니스 전화번호에 보내는 모든 메시지의 내용이 Webhooks로 전송되고, 발신 메시지 전달 상태에 대한 모든 업데이트가 Webhooks를 통해 보고되기 때문입니다.

Meta에서는 Glitch에서 복제해서 테스트에 사용할 수 있는 샘플 Webhooks 앱을 제공합니다. 이 앱은 콘솔에 직접 Webhooks 페이로드를 표시하여 내용을 볼 수 있도록 합니다. 하지만 최종적으로는 자체적인 비즈니스 로직에 따라 Webhooks를 처리하는 자체 엔드포인트를 자체 서버에 빌드해야 합니다.

Meta Webhooks에서 Webhooks 및 처리 방법에 대한 자세한 내용을 참조하고 WhatsApp Business 계정용 Webhooks 문서를 확인하세요.

테스트 리소스

먼저 시작하기 문서에 나와 있는 단계를 완료하고 나면 테스트 WABA 및 테스트 비즈니스 전화번호가 자동으로 생성됩니다.

테스트 WABA 및 테스트 전화번호는 대부분의 메시지 제한을 우회하고 결제 수단을 등록하지 않아도 템플릿 메시지를 전송할 수 있으므로 테스트 목적으로 사용하기에 유용합니다.

다음과 같은 경우에 비즈니스 포트폴리오와 테스트 리소스를 삭제할 수 있습니다.

  • 앱과 연결된 비즈니스 포트폴리오의 관리자인 경우
  • 비즈니스 포트폴리오와 연결된 다른 앱이 없는 경우
  • 비즈니스 포트폴리오가 다른 WABA와 연결되지 않은 경우
  • WABA가 다른 비즈니스 전화번호와 연결되지 않은 경우

비즈니스 포트폴리오와 테스트 리소스를 삭제하는 방법은 다음과 같습니다.

  1. 앱 대시보드 > WhatsApp > 구성 패널로 이동합니다.
  2. 테스트 계정 섹션을 찾습니다.
  3. 삭제 버튼을 클릭합니다.

인증 및 승인

액세스 토큰

API는 다음 세 가지 유형의 토큰을 지원합니다.

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

사용해야 할 토큰 유형을 알아보려면 액세스 토큰을 참조하세요. 토큰은 쿼리 문자열 매개변수가 아니라 요청 헤더를 통해 전달해야 합니다.

권한

API는 다음 그래프 API 권한을 사용합니다. 앱에 필요한 권한의 정확한 조합은 앱에서 액세스하는 엔드포인트에 따라 달라집니다.

  • business_management — 비즈니스 포트폴리오와 상호작용하는 경우에 필요합니다.
  • whatsapp_business_management — WABA 및 관련 분석이나 템플릿 또는 비즈니스 전화번호와 상호 작용하는 경우에 필요합니다.
  • whatsapp_business_messaging — WhatsApp 사용자와 메시지를 주고받는 데 필요합니다.

이러한 권한은 일반적으로 Meta Business Suite에서 액세스 토큰을 생성할 때 부여됩니다. 액세스 토큰 문서에서 토큰 생성 섹션을 참조하세요.

버전 관리

버전 관리는 그래프 API의 버전 관리 프로토콜을 사용합니다. 즉, 모든 엔드포인트 요청에는 버전 번호가 포함될 수 있으며, 각 버전은 약 2년간 제공되다가 사용 중단되어 더 이상 호출되지 않을 수 있습니다.

처리량

각 등록된 비즈니스 전화번호에 대해 클라우드 API는 기본적으로 초당 최대 80건의 메시지(mps)를 지원하며 자동 업그레이드 시 최대 1,000건의 메시지를 지원합니다.

처리량은 수신 메시지와 발신 메시지 및 모든 메시지 유형을 포함합니다. 비즈니스 전화번호는 처리량과 관계없이 여전히 WhatsApp Business 계정의 비즈니스 사용 사례 제한과 템플릿 메시지 제한이 적용됩니다.

현재 처리량 수준에서 허용하는 것보다 많은 메시지를 전송하려고 시도하는 경우, 다시 허용된 수준 범위일 때까지 API가 오류 코드 130429를 반환합니다. 또한 처리량 수준은 서로 다른 WhatsApp 사용자 전화번호가 포함된 메시지 캠페인에 적용됩니다. 동일한 WhatsApp 사용자 전화번호로 너무 많은 메시지를 보내려고 시도하면 페어링 사용 제한 오류(오류 코드 131056)가 발생할 수 있습니다.

더 높은 처리량

자격 요건을 충족하는 경우, 초당 1,000건의 메시지를 보낼 수 있도록 비즈니스 전화번호를 무료로 자동 업그레이드해 드립니다. 처리량이 높아지더라도 추가 요금이 발생하거나 요금에 영향을 미치지 않습니다.

업그레이드 절차 자체는 최대 1분 정도 소요될 수 있습니다. 이 시간 동안은 해당 전화번호를 WhatsApp 플랫폼에서 사용할 수 없습니다. API 요청에 사용하는 경우 해당 API는 오류 코드 131057을 반환합니다. 일단 비즈니스 전화번호를 업그레이드하고 나면 향후 처리량을 높일 때 가동 중지 시간 없이 자동으로 업그레이드됩니다.

자격 요건

Webhooks

Webhooks 서버는 발송되는 메시지 트래픽 용량의 3배, 예상되는 수신 메시지 트래픽 용량의 1배까지 감당할 수 있어야 합니다. 예를 들어 예상 응답률이 30%일 때 1,000mps를 전송할 경우, 서버는 메시지 상태 Webhooks를 최대 3,000개, 추가적인 수신 메시지 Webhooks를 300개까지 처리할 수 있어야 합니다.

Meta에서는 Webhooks를 동시에 전송하려고 시도하므로 Webhooks 서버가 다음의 지연 기준에 따라 동시 요청을 처리하도록 구성하고 부하를 테스트하는 것이 좋습니다.

  • 평균 지연 시간이 250ms를 초과하지 않음.
  • 1s를 초과하는 지연 시간이 1% 미만임.

Meta에서는 지수 백오프를 적용하여 실패한 Webhooks를 최대 7일 동안 다시 전송하려고 시도합니다.

미디어 메시지

더 높은 처리량을 완전하게 활용하려면 자체 서버에서 자산을 호스팅하고 미디어 자산 URL을 사용하는 대신 미디어 자산을 서버로 업로드하고 미디어 메시지를 통해 반환된 미디어 ID를 사용하는 것이 좋습니다. 자체 서버에서 자산을 호스팅하는 것을 선호하는 경우(또는 반드시 호스팅해야 하는 경우) 미디어 캐싱을 사용하는 것이 좋습니다.

처리량 수준 가져오기

WhatsApp Business 전화번호 엔드포인트를 사용하여 전화번호의 현재 처리량 수준을 가져옵니다.

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

마이그레이션

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

사용 제한

각 WABA에는 API 호출 수 사용에 제한이 있습니다. 앱이 WABA 비즈니스 전화번호(즉, WhatsApp Business 전화번호 노드 또는 그 에지(예: 메시지 엔드포인트))로 보내는 각각의 API 호출에 제한이 적용되어 계산됩니다.

현재 제한은 WABA 1개에 대해 1시간 동안 API 호출 11,880,000회입니다.

예를 들어 1시간 이내에 앱이 WABA A와 연결된 WhatsApp 비즈니스 전화번호에서 API 호출을 11,880,000회 보내고 WABA B와 연결된 WhatsApp 비즈니스 전화번호에서 API 호출을 11,880,000회 더 보낼 수 있습니다. 또는 1시간 이내에 앱이 하나의 WABA와 연결된 여러 WhatsApp 비즈니스 전화번호를 합쳐서 API 호출을 총 11,880,000회까지 보낼 수도 있습니다.

제한에 도달하면 API가 오류 코드80007로 응답합니다.

Business Management API는 사용 제한이 다릅니다. WhatsApp Business Management API 사용 제한을 참조하세요.

이러한 사용 제한 외에도 각 리소스(예: 템플릿 메시지, 테스트 비즈니스 전화번호)에 더욱 세분화된 제한이 적용됩니다.

사용 가능한 지표

클라우드 API 사용자는 다른 지표 외에도 전송 및 전달된 메시지의 수를 확인할 수 있습니다. 자세한 내용은 계정 지표 가져오기를 참조하세요.

확장

클라우드 API는 Meta의 인프라 내에서 사용 제한(메시지 분량 및 WABA 계정의 수)을 초과하지 않으면서 워크로드를 처리하도록 자동으로 확장되고 조정됩니다.

데이터 개인정보 보호 및 보안

자세한 내용은 개인정보 보호 및 보안 개요를 참조하세요.

암호화

클라우드 API를 사용하면 모든 WhatsApp 메시지가 기기에서 내보내지기 전까지 메시지를 보호하는 신호 프로토콜 암호화로 계속 보호받게 됩니다. 즉, WABA에서 메시지를 보낼 때 각 비즈니스가 선택한 목적지까지 안전하게 전송됩니다.

클라우드 API는 업계 표준 암호화 기술을 사용하여 전송 중 데이터와 저장 데이터를 보호합니다. 이 API는 그래프 API를 사용하여 메시지를 전송하고 Webhooks를 사용하여 이벤트를 수신하며, 둘 다 TLS를 통해 보호되는 산업 표준 HTTPS를 매개로 하여 작동합니다. 자세한 내용은 암호화 개요 백서를 참조하세요.

자세한 내용은 암호화 개요 백서를 참조하세요.

도구

WhatsApp 관리자

WhatsApp 관리자는 WABA, 비즈니스 전화번호, 템플릿 등의 리소스를 수동으로 관리할 수 있는 웹 앱으로, 이러한 리소스에 대한 인사이트 및 품질 평가 또는 제한을 쉽게 확인할 수 있도록 합니다. WhatsApp 관리자에서 제공하는 대부분의 기능은 몇 가지 사소한 예외를 제외하고는 API를 통해서도 제공됩니다.

WhatsApp 관리자에 액세스하는 방법에는 여러 가지가 있습니다. 각 경로는 시작하기 문서에 나와 있는 모든 단계를 이미 완료한 것으로 가정합니다.

Meta Business Suite 사용

  1. Meta Business Suite에 로그인합니다.
  2. 여러 비즈니스 포트폴리오가 있는 경우 왼쪽에 있는 드롭다운 메뉴를 사용하여 WhatsApp 관리자에서 읽어들이고자 하는 WABA를 소유하거나 여기에 대한 액세스 권한이 있는 계정을 선택합니다.
  3. 왼쪽 메뉴에서 계정 > WhatsApp 계정으로 이동합니다.
  4. WABA를 선택합니다.
  5. 요약 탭에서 WhatsApp 관리자 버튼을 클릭합니다.

앱 대시보드 사용

  1. 내 앱으로 이동합니다.
  2. WhatsApp 관리자에서 읽어들이고자 하는 WABA와 연결된 앱을 선택합니다.
  3. 왼쪽 메뉴에서 WhatsApp > 빠른 시작으로 이동합니다.
  4. WhatsApp Business 섹션에서 계정 정보를 클릭합니다.

URL 사용

다음 링크를 방문하여 주어진 비즈니스 포트폴리오에서 소유하거나 이에 공유된 모든 WABA가 표시되는 WhatsApp 관리자 개요로 직접 이동할 수 있습니다.

https://business.facebook.com/wa/manage/home/

기본적으로 개요에서는 가장 최근에 생성했거나 액세스 권한을 부여한 WABA를 읽어들이지만, 왼쪽에 있는 드롭다운 메뉴를 사용하여 액세스하려는 WABA가 포함된 비즈니스 포트폴리오를 선택할 수 있습니다. 그러나 이렇게 하면 개요에서 나가게 되고 왼쪽에 있는 메뉴를 사용하여 계정 > WhatsApp 계정 > (원하는 WABA 선택 ) > 설정 > WhatsApp 관리자(버튼)로 이동해야 합니다.

또는 여러 비즈니스 포트폴리오가 있는 경우, URL 끝에 계정 ID를 붙이고 북마크를 저장하여 더 쉽게 액세스할 수 있습니다.

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

WhatsApp Business 플랫폼 작업 공간에는 자주 사용하는 쿼리가 있는 클라우드 API Postman 컬렉션이 있습니다.