비즈니스 메시지용 전환 API: 온보딩 가��드

전환 API는 비즈니스 메시징 파트너가 권한을 부여받은 클라이언트 데이터를 자신의 서버에서 직접 공유할 수 있도록 해 주는 Meta 비즈니스 도구이며, Meta 사용자 개인정보 보호 관리 기능을 자동으로 준수하도록 설계되었습니다. 따라서 비즈니스 메시징 파트너는 비즈니스 채팅에서 발생하는 클라이언트의 중요한 고객 상호작용에 대한 데이터를 안정적으로 전송하여, 클라이언트의 WhatsApp, Messenger, Instagram 연결 광고에 대해 이해하고 성능을 개선함으로써 운영 효율을 높이고 비즈니스를 성장시킬 수 있습니다.

이 가이드는 비즈니스 메시징 파트너가 클라이언트를 대신하여 WhatsApp, Messenger, Instagram용 전환 API의 기술적 통합을 완료하는 데 도움을 드리도록 설계되었습니다. 이 가이드에서는 다음과 같은 내용을 다룹니다.

통합 전 요구 사항
통합 단계
전환 API를 통해 이벤트 보내기
이벤트 관리자로 이벤트 확인

참고: 전환 API는 광고주가 웹사이트, 앱, 오프라인(오프라인 매장 포함), CRM 이벤트를 Meta로 전송하는 기능도 지원합니다. 현재 다른 사용 사례에 대해 전환 API와 통합한 비즈니스 메시징 파트너도 비즈니스 메시지용 전환 API와 통합하기 위해 다음 단계를 거쳐야 합니다.

Messenger 연결 광고

통합 전 요구 사항

통합을 시작하기 전에 적절한 기술적 기반을 구축하고 해당 자산과 플랫폼에 대해 관련 액세스 권한을 부여받아야 합니다.

Facebook 개발자 앱 생성

Facebook 개발자 앱이 아직 없는 경우, 이 지침에 따라 만드세요.

Messenger API와 통합

다음에 대한 고급 액세스 권한 보유:

page_events 권한
- 개발자 앱 대시보드의 '권한 및 기능' 섹션에서 page_events 권한에 대한 고급 액세스 권한을 신청해야 합니다. pages_messaging 권한에 대한 고급 액세스 권한이 이미 있는 경우, 권한을 신청하면 앱에 page_events 권한이 자동으로 승인됩니다.
'광고 관리 표준 액세스' 기능. 추가 지침이 여기에 나와 있습니다.
- 고급 액세스 기능을 이용하려면 최근 15일 내에 오류율 10% 미만으로 마케팅 API 호출 총 1,500회를 성공시켜야 합니다. 여기에는 앱에서 역할이 부여된 사용자가 전환 API를 통해 보낸 호출이 포함됩니다.

통합 단계

1. 액세스 토큰 가져오기

데이터 세트 API와 전환 API를 호출하려면 다음과 같은 필수 권한이 부여된 액세스 토큰이 있어야 합니다.

page_events

비즈니스용 Facebook 로그인에서 생성된 토큰을 다시 사용합니다.

2. page_id 가져오기

이벤트를 보고하고자 하는 페이지의 페이지 ID를 알아야 합니다.

3. 데이터 세트 설정

전환 API를 통해 이벤트 데이터를 Meta에 공유할 때 Meta에서 해당 이벤트와 연결된 소스가 무엇인지 알아야 합니다. 데이터 세트를 사용하면 웹사이트, 모바일 앱, 오프라인 매장 위치, 비즈니스 채팅과 같은 여러 소스의 이벤트 데이터를 한곳에서 연결하고 관리할 수 있습니다. 데이터 세트에 대한 자세한 내용은 여기를 참조하세요.

데이터 세트는 파트너 플랫폼을 통해, 또는 이벤트 관리자에서 직접 생성됩니다. 비즈니스는 데이터 세트를 소유합니다. 또한 비즈니스가 파트너와 협력하는 경우에는 데이터 세트에 대한 액세스 권한이 파트너에게도 부여됩니다.

page_id와 access_token을 사용하여 데이터 세트 API로 POST 호출을 보내서 데이터 세트를 만드세요. 해당 페이지와 연결된 기존의 dataset_id가 이미 존재할 경우, 해당 ID가 반환됩니다. 샘플 호출은 아래와 같습니다.

https://graph.facebook.com/v16.0/{PAGE_ID}/dataset?access_token={TOKEN}

응답은 dataset_id를 나타내는 ID로 표시됩니다. 이제 이 ID와 비즈니스용 Facebook 로그인에서 생성한 액세스 토큰을 사용하면 전환 API를 호출하고 메시지 이벤트를 Meta에 전송할 수 있습니다.

참고: 페이지가 비즈니스 계정과 연결되어 있고 business_management 권한이 해당 비즈니스 계정에 부여된 경우, 데이터 세트가 비즈니스 계정 아래에 표시됩니다. 그러지 않은 경우에는 광고주에게 보이지 않습니다.

4. 페이지 범위 ID(PSID) 가져오기

페이지 범위 ID(PSID)는 사용자-비즈니스 간 대화에서 사용자를 나타내는 식별자입니다. 이 식별자는 메시지 Webhooks를 통해 노출되고 Send/Receive API 전체에서 사용됩니다. 또한 특정 사용자(PSID)에게 매핑된 전환 이벤트를 보낼 때 전환 API에서도 사용됩니다.

신호를 보고하고자 하는 페이지의 페이지 PSID를 알아야 합니다.

전환 API를 통해 이벤트 보내기

이제 통합의 마지막 단계에서 이전 단계에서 얻은 모든 정보(access_token, page_id, dataset_id, PSID)를 포함하여 전환 API를 통해 이벤트를 보낼 수 있습니다.

캠페인 기간 동안, 이벤트가 실시간으로 발생하면 dataset_id 및 access_token을 사용하여 전환 API를 통해 해당 이벤트를 Meta에 알립니다. 다음과 같이 이 API로 POST 요청을 보냅니다.

https://graph.facebook.com/v16.0/{DATASET_ID}/events?access_token={TOKEN}

단일 구매 이벤트에 대한 샘플 API 호출은 다음과 같습니다.

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "messenger",
      "user_data": {
        "page_id": <PAGE_ID>,
        "page_scoped_user_id": <PSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

이벤트 관리자로 이벤트 확인

이벤트가 전환 API를 통해 Meta에 전송되고 나면 해당 데이터 세트에 대해 이벤트 관리자에 이벤트가 반영된 것을 확인할 수 있습니다. 이벤트 관리자와 그 사용 방법에 대한 자세한 내용은 여기를 참조하세요.

참고: 파트너인 경우, 이벤트를 수신했는지 확인하기 위해 이벤트 관리자에서 데이터 세트에 액세스하는 방법을 광고주에게 안내해야 합니다.

WhatsApp 연결 광고

통합 전 요구 사항

통합을 시작하기 전에 적절한 기술적 기반을 구축하고 해당 자산과 플랫폼에 대해 관련 액세스 권한을 부여받아야 합니다.

Facebook 개발자 앱 생성

Facebook 개발자 앱이 아직 없는 경우, 이 지침에 따라 만드세요.

다음에 대한 고급 액세스 권한 보유:

whatsapp_business_management 권한
whatsapp_business_manage_events 권한
- 개발자 앱 대시보드의 '권한 및 기능' 섹션에서 whatsapp_business_manage_events 권한에 대한 고급 액세스 권한을 신청해야 합니다. whatsapp_business_messaging 권한에 대한 고급 액세스 권한이 이미 있는 경우, 권한을 신청하면 앱에 whatsapp_business_manage_events 권한이 자동으로 승인됩니다.
앱에서 마케팅 API에 액세스하기 위한 '광고 관리 표준 액세스' 기능. 추가 지침이 여기에 나와 있습니다.
- 고급 액세스 기능을 이용하려면 최근 15일 내에 오류율 10% 미만으로 마케팅 API 호출 총 1,500회를 성공시켜야 합니다. 여기에는 앱에서 역할이 부여된 사용자가 전환 API를 통해 보낸 호출이 포함됩니다.

다음 WhatsApp Business 플랫폼 통합 옵션 두 가지 중 하나와 통합합니다.

Meta가 호스팅하는 클라우드 API(권장)
온프레미스 API(*Biz API 버전: 2.45.1): 전환 API를 통해 이벤트를 전송하는 데 필수적인 필드인 ctwa_clid는 Biz API 버전 2.45.1 이상의 메시지 Webhooks에서만 사용할 수 있습니다. 참고: WhatsApp Business 플랫폼은 향후 2년에 걸쳐 차세대 클라우드 API로 완전히 전환됩니다. 온프레미스 API 클라이언트의 최종 지원 버전은 2025년 10월 23일에 만료됩니다. 더 알아보기.

인증 및 승인을 위한 로그인 솔루션(임베디드 가입, 비즈니스용 Facebook 로그인)과 통합

통합 단계

1. 액세스 토큰 가져오기

데이터 세트 API와 전환 API를 호출하려면 다음과 같은 필수 권한이 부여된 액세스 토큰이 있어야 합니다.

whatsapp_business_management
whatsapp_business_manage_events

임베디드 가입과 통합된 경우 임베디드 가입 플로에서 생성된 토큰을 다시 사용하는 것이 좋습니다. 또는 필수적인 권한을 포함하고 있다면 비즈니스 통합 시스템 사용자 액세스 토큰, 시스템 사용자 액세스 토큰이나 사용자 액세스 토큰을 사용할 수도 있습니다.

2. WhatsApp Business 계정 ID 가져오기

WhatsApp Business 계정 ID(waba_id)는 임베디드 가입 플로를 완료하면 얻을 수 있습니다. 자세한 내용을 참조하세요.

3. 데이터 세트 API 설정

전환 API를 통해 이벤트 데이터를 Meta에 공유할 때 Meta에서 해당 이벤트와 연결된 소스가 무엇인지 알아야 합니다. 데이터 세트를 사용하는 Meta 비즈니스 솔루션 파트너는 클라이언트의 웹사이트, 모바일 앱, 오프라인 매장 위치, 비즈니스 채팅과 같은 여러 소스의 이벤트 데이터를 한곳에서 연결하고 관리할 수 있습니다. 데이터 세트에 대한 자세한 내용은 여기를 참조하세요. 데이터 세트는 클라이언트가 소유하며, 필수적인 권한이 있는 Meta 비즈니스 솔루션 파트너가 해당 데이터 세트에 액세스할 수 있습니다.

whatsapp_business_account_id 및 access_token을 사용하여 데이터 세트 API로 POST 호출을 보내서 데이터 세트를 생성할 수 있습니다. WhatsApp Business 계정과 연결된 기존의 dataset_id가 이미 존재할 경우, 해당 ID가 반환됩니다. 샘플 호출은 아래와 같습니다.

https://graph.facebook.com/v16.0/{WHATSAPP_BUSINESS_ACCOUNT_ID}/dataset?access_token={TOKEN}

dataset_id를 가져오려면 whatsapp_business_account_id 및 access_token을 포함하여 데이터 세트 API로 GET 호출을 보내야 합니다. 샘플 호출은 아래와 같습니다.

https://graph.facebook.com/v16.0/{WHATSAPP_BUSINESS_ACCOUNT_ID}/dataset?access_token={TOKEN}

응답은 dataset_id를 나타내는 ID로 표시됩니다. 이제 데이터 세트를 설정하고 사용할 수 있습니다. 그다음에는 이벤트를 보내기 위한 전환 API 호출에 필요한 ctwa_clid를 가져와야 합니다.

4. WhatsApp 연결 광고 클릭 ID 가져오기

WhatsApp 연결 광고 클릭 ID(ctwa_clid)는 ��릭별로 고유한 개인 식별자로, 사용자가 WhatsApp 연결 광고에서 시작된 대화에 입장할 때 비즈니스에 노출됩니다. 이 식별자는 전환 API 호출을 통해 Meta로 다시 전송되어야 합니다(아래 섹션을 참조하세요).

ctwa_clid 필드는 메시지 Webhooks(클라우드 API | 온프레미스) 아래에 있는 리퍼럴 개체에서 얻습니다.

ctwa_clid를 수신하고 나면 대화와 함께 저장하세요. 대화 내에서 전환이 일어날 경우 전환 API를 통해 해당 ctwa_clid를 보냅니다. ctwa_clid가 있는 리퍼럴 개체를 포함하여 수신된 메시지 샘플은 다음과 같습니다.

{
  "data": [
    {
  "contacts": [
    {
      "profile": {
        "name": "Kerry Fisher "
      },
      "wa_id": "16315551234"
    }
  ],
  "messages": [
    {
      "from": "12345678",
      "id": "ABGGFlA5FpafAgo6tHcNmNjXmuSf",
      "referral": {
        "body": "This is a great product",
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
        "headline": "Our new product",
        "image": {
          "id": "e144be57-12b1-4035-a520-703fcc87ef45"
        },
        "source_id": "1234567890",
        "source_type": "ad",
        "source_url": "https://fb.me/AAAAA"
      },
      "text": {
        "body": "Can I learn more about your business?"
      },
      "timestamp": "1678189586",
      "type": "text"
    }
  ]
}

전환 API를 통해 이벤트 보내기

이제 통합의 마지막 단계에서 이전 단계에서 얻은 모든 정보(waba_id, dataset_id, ctwa_clid)를 포함하여 전환 API를 통해 이벤트를 보낼 수 있습니다.

광고주의 캠페인 기간 동안, 이벤트가 실시간으로 발생합니다. dataset_id와 액세스 토큰을 사용하여 전환 API를 통해 해당 이벤트를 Meta에 알립니다. 다음과 같이 이 API로 POST 요청을 보냅니다.

https://graph.facebook.com/v16.0/{DATASET_ID}/events?access_token={TOKEN}

단일 구매 이벤트에 대한 샘플 API 호출은 다음과 같습니다.

{
  "data": [
    {
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "whatsapp",
      "user_data": {
        "whatsapp_business_account_id": <WHATSAPP_BUSINESS_ACCOUNT_ID>,
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

이벤트 관리자로 이벤트 확인

참고: 파트너인 경우, 이벤트를 수신했는지 확인하기 위해 이벤트 관리자에서 데이터 세트에 액세스하는 방법을 광고주에게 안내해야 합니다.

Instagram Direct 연결 광고

통합 전 요구 사항

통합을 시작하기 전에 적절한 기술적 기반을 구축하고 해당 자산과 플랫폼에 대해 관련 액세스 권한을 부여받아야 합니다.

Facebook 개발자 앱 생성

Facebook 개발자 앱이 아직 없는 경우, 이 지침에 따라 만드세요.

Messenger API와 통합

다음에 대한 고급 액세스 권한 보유:

instagram_manage_events 권한
- 개발자 앱 대시보드의 '권한 및 기능' 섹션에서 instagram_manage_events 권한에 대한 고급 액세스 권한을 신청해야 합니다. instagram_manage_messages 권한에 대한 고급 액세스 권한이 이미 있는 경우, 앱에 instagram_manage_events 권한이 자동으로 승인됩니다.
'광고 관리 표준 액세스' 기능. 추가 지침이 여기에 나와 있습니다.
- 고급 액세스 기능을 이용하려면 최근 15일 내에 오류율 10% 미만으로 마케팅 API 호출 총 1,500회를 성공시켜야 합니다. 여기에는 앱에서 역할이 부여된 사용자가 전환 API를 통해 보낸 호출이 포함됩니다.

통합 단계

1. 액세스 토큰 가져오기

데이터 세트 API와 전환 API를 호출하려면 다음과 같은 필수 권한이 부여된 액세스 토큰이 있어야 합니다.

instagram_manage_events

비즈니스용 Facebook 로그인에서 생성된 토큰을 다시 사용합니다.

2. 'instagram_user_id' 가져오기

이벤트를 보고하고자 하는 Instagram 계정의 instagram_user_id를 알아야 합니다.

3. 데이터 세트 설정

instagram_user_id 및 access_token을 사용하여 데이터 세트 API로 POST 호출을 보내서 데이터 세트를 만드세요. IG 사용자와 연결된 기존의 dataset_id가 존재할 경우, 해당 ID가 반환됩니다. 샘플 호출은 아래와 같습니다.

https://graph.facebook.com/v16.0/{IG_USER_ID}/dataset?access_token={TOKEN}

응답은 dataset_id를 나타내는 ID로 표시됩니다. 이제 이 ID와 비즈니스용 Facebook 로그인에서 생성한 액세스 토큰을 사용하면 전환 API를 호출하고 메시지 이벤트를 Meta에 전송할 수 있습니다.

4. Instagram 범위 ID(IGSID) 가져오기

Instagram 범위 ID(IGSID)는 사용자-비즈니스 간 대화에서 사용자를 나타내는 식별자입니다. 이 식별자는 메시지 Webhooks를 통해 노출되고 Send/Receive API 전체에서 사용됩니다. 이는 특정 사용자(IGSID)에 매핑된 전환 이벤트를 전송할 경우에 전환 API에서도 사용됩니다(자세한 내용은 다음 섹션을 참조하세요).

이벤트를 보고하고자 하는 Instagram 계정의 IGSID를 알아야 합니다.

전환 API를 통해 이벤트 보내기

이제 통합의 마지막 단계에서 이전 단계에서 얻은 모든 정보(dataset_id, 액세스 토큰, instagram_user_id, IGSID)를 포함하여 전환 API를 통해 이벤트를 보낼 수 있습니다.

캠페인 기간 동안, 이벤트가 실시간으로 발생하면 dataset_id 및 액세스 토큰을 사용하여 전환 API를 통해 해당 이벤트를 Meta에 알립니다. 다음과 같이 이 API로 POST 요청을 보냅니다.

https://graph.facebook.com/v16.0/{DATASET_ID}/events?access_token={TOKEN}

단일 구매 이벤트에 대한 샘플 API 호출은 다음과 같습니다.

{    
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "instagram",
      "user_data": {
        "instagram_business_account_id": <instagram_business_account_id>,
        "ig_sid": <IGSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

이벤트 관리자로 이벤트 확인

참고: 파트너인 경우, 이벤트를 수신했는지 확인하기 위해 이벤트 관리자에서 데이터 세트에 액세스하는 방법을 광고주에게 안내해야 합니다.

자주 묻는 질문

비즈니스 메시지용 전환 API는 어떤 유형의 메시지 이벤트를 지원하나요?

A: 현재 비즈니스 메시지용 전환 API는 비즈니스 메시지에 대해 다음과 같은 유형의 이벤트를 지원합니다.

Purchase
LeadSubmitted
InitiateCheckout
AddToCart
ViewContent
OrderCreated
OrderShipped
OrderDelivered
OrderCanceled
OrderReturned
CartAbandoned
QualifiedLead
RatingProvided
ReviewProvided

메시지 이벤트는 웹사이트와 같은 다른 채널에서 발생하는 전환이 아니라 메시지 스레드에서 발생하는 고객 상호작용만 나타내야 합니다. 통합 과정에서 해당 행동 출처를 선택하여 이벤트를 쉽게 구별할 수 있습니다.

서로 다른 전환 API 통합에 동일한 앱을 유지하거나 서로 다른 앱을 사용하라는 Meta의 지침이 있나요?

A: Meta가 파트너가 전송한 모든 이벤트를 식별할 수 있도록 파트너는 하나의 앱을 사용하는 것이 좋습니다. 이미 여러 앱을 보유하고 있는 파트너인 경우, partner_agent가 자신에게 할당된 파트너 에이전트 이름으로 설정되었는지 확인하세요. 확실하지 않은 경우 Meta 담당자에게 문의하세요.

메시지 스레드 외부에서 전환이 발생한 경우(예: 내 웹사이트 또는 앱) 이벤트를 Meta에 어떻게 전달하나요?

A: 메시지 스레드 외부에서 전환이 발생한 경우에도 관련 전환 API 제품을 사용하여 해당 이벤트를 Meta로 다시 전송해야 합니다. 예를 들어 전환이 웹사이트에서 발생한 경우, 웹용 전환 API를 사용하세요. 전환이 앱에서 발생한 경우, 앱 이벤트용 전환 API를 사용하세요. 이 이벤트는 여전히 웹용 전환 API에 대한 클릭 ID로 기여 분석됩니다. 매개변수의 전체 리스트는 여기에서 확인할 수 있습니다.

전환 API가 메시지 연결 광고에 대한 최적화를 지원하나요?

A: 전환 API를 사용하여 Messenger 연결 광고와 WhatsApp 연결 광고에 대해서만 구매 최적화에 액세스할 수 있으며, 현재 Instagram 광고 최적화에는 전환 API를 사용할 수 없습니다. Instagram 연결 광고의 경우, 광고 캠페인을 최적화하여 더 많은 대화를 유도할 수 있습니다.

비즈니스 메시지용 전환 API에 기존 데이터 세트를 재사용할 수 있나요?

A: 예, 기존 데이터 세트와의 연결을 지원합니다. 사용 가능한 옵션을 참조하여 비즈니스에 적절한 옵션을 결정할 수 있습니다.

현재 웹사이트용 전환 API를 사용하고 있는 경우, 동일한 통합에 비즈니스 메시지를 추가하면 기존 통합에 방해가 될까요?

A: 기존 CAPI 통합에 비즈니스 메시지를 추가해도 아무런 위험이 없습니다. 기여 분석은 페이지/데이터 세트 ID를 기반으로 하며 앱 ID와는 관련이 없습니다.

페이지에 연결할 수 있는 데이터 세트는 몇 개인가요?

A: 페이지에 하나의 데이터 세트만 연결할 수 있습니다.

비즈니스 메시지용 전환 API를 통해 이벤트를 전송하기 전에 중복을 제거해야 하나요?

A: Meta는 비즈니스 메시��용 전환 API에 대해 이벤트 중복 제거를 지원하지 않으므로, 광고주께서는 비즈니스 메시지용 전환 API를 통해 이벤트를 보내기 전에 중복을 제거하는 것이 좋습니다.

기타 참고 자료

전환 API 개요
전환 API 사용
전환 API 매개변수
모범 사례
Business API 버전이 2.45.1 이상인 WhatsApp 비즈니스 플랫폼(온프레미스 또는 클라우드 API)
Instagram 메시지 API