WhatsApp Business 플랫폼용 Webhooks

WhatsApp Business 블로그

Node.js를 사용하여 Webhooks 구현

Webhooks를 사용하면 특정 개체의 변경 사항에 대해 실시간 HTTP 알림을 받을 수 있습니다. 예를 들어 Meta에서는 사용자가 메시지를 전송하거나 메시지 템플릿의 상태가 변경되었을 때 여러분에게 알림을 보내 드릴 수 있습니다. 이 방법을 사용하면 발생 여부가 확실치 않은 개체 변경 사항에 대해 API에 쿼리할 필요가 없고 사용 제한에 도달하지 않도록 하는 데 도움이 됩니다.

이 문서에서는 Webhooks에 대한 개요를 제공하며, 이는 WhatsApp Business Management API, WhatsApp Business 플랫폼 클라우드 API, WhatsApp Business 플랫폼 온프레미스 API에 적용됩니다.

개체, 필드 및 값

각 API에는 여러 개체 유형이 있을 수 있으므로 Webhooks를 구성할 때마다 먼저 개체 유형을 선택해야 합니다. 개체마다 필드가 다르기 때문에 해당 개체 유형에 대해 특정 필드를 구독해야 합니다. 개체 필드에 값이 변경될 때마다 알림을 받게 됩니다.

알림은 HTTP POST 요청으로 전송되며, 여기에는 변경 사항을 설명하는 JSON 페이로드가 포함되어 있습니다.

사용 가능한 Webhooks

다음 표에는 Webhooks에서 받을 수 있는 정보가 요약되어 있습니다.

API	개체
클라우드 API	고객이 비즈니스 메시지에 답장하는 등의 행동을 수행합니다. 고객이 전화번호를 업데이트합니다. 비즈니스에서 메시지를 전송하거나, 메시지가 고객에게 전달되었거나, 고객이 메시지를 읽었으며, 메시지에 가격 정보가 포함되어 있습니다. 메시지에 오류가 발생했습니다.
온프레미스 API	고객이 비즈니스 메시지에 답장하는 등의 행동을 수행합니다. 고객이 전화번호를 업데이트합니다. 비즈니스에서 메시지를 전송하거나, 메시지가 고객에게 전달되었거나, 고객이 메시지를 읽었으며, 메시지에 가격 정보가 포함되어 있습니다. 메시지에 오류가 발생했습니다.
WhatsApp Business Management API	공식 비즈니스 계정 상태와 표시 이름 상태가 변경되었습니다. WhatsApp Business 계정 검토 상태가 변경되었습니다. 정책 위반 사항을 비롯한 WhatsApp Business 계정 정보가 업데이트되었습니다. WhatsApp Business 계정의 기능이 변경되었습니다(예: 전화번호 1개당 대화 수 관련 변경 사항). 메시지 템플릿이 승인, 거부 또는 비활성화되었습니다. 전화번호와 연결된 표시 이름이 승인 또는 거부되었습니다. 전화번호의 품질 관련 상태가 변경되었습니다.

문자 메시지 알림 예시

다음의 예시는 사용자가 비즈니스에 문자 메시지를 보냈을 때 비즈니스에 전송되는 Webhooks 알림을 나타냅니다.

클라우드 API

클라우드 API의 경우 개체는 언제나 whatsapp_business_account이지만 field는 전송되는 정보 유형을 나타냅니다.

{
  "object": "whatsapp_business_account",
  "entry": [{
    "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": PHONE_NUMBER,
          "phone_number_id": PHONE_NUMBER_ID
        },
        "contacts": [{
          "profile": {
            "name": "NAME"
          },
          "wa_id": PHONE_NUMBER
        }],
        "messages": [{
          "from": PHONE_NUMBER,
          "id": "wamid.ID",
          "timestamp": TIMESTAMP,
          "text": {
            "body": "MESSAGE_BODY"
          },
          "type": "text"
        }]
      },
      "field": "messages"
    }]
  }]
}

온프레미스 API

온프레미스 API의 경우 클라이언트가 Meta 대신 Webhooks를 전송하므로 개체는 contacts 및 messages, errors 또는 statuses 및 pricing이 됩니다.

{
  "contacts": [{
    "profile": {
      "name": "NAME"
    },
    "wa_id": "WHATSAPP_BUSINESS_ACCOUNT_ID"
  }],
  "messages":[{
    "from": "PHONE_NUMBER",
    "id": "wamid.ID",
    "timestamp": "TIMESTAMP",
    "text": {
      "body": "MESSAGE_BODY"
    },
    "type": "text"
  }]
}

HTTPS 서버

모든 Webhooks는 HTTPS를 사용하여 전송되므로 서버에서 HTTPS 요청을 받아서 처리할 수 있어야 하며 유효한 TLS/SSL 인증서가 설치되어 있어야 합니다. 자체 서명된 인증서는 지원되지 않습니다.

더 알아보기

특정 API의 Webhooks에 대해 자세히 알아보세요.

다음 단계

시작하기 - 비즈니스에 어떤 API가 적절한지 확인하세요.
표시 이름 - WhatsApp 메시지에 표시되는 비즈니스 이름을 설정하세요.
전화번호 - 전화번호를 WhatsApp Business 계정에 연결하세요.
가격 - 가격과 결제를 설정하는 방법에 대해 알아보세요.

WhatsApp Business 플랫폼 | 클라우드 API | 온프레미스 API | Business Management API