Messenger 플랫폼용 Meta Webhooks

Meta Webhooks를 사용하면 Meta 소셜 그래프에 있는 특정 개체의 변경 사항에 대한 실시간 HTTP 알림을 받을 수 있습니다. 예를 들어 한 사용자가 비즈니스의 Facebook 페이지 또는 Instagram 프로페셔널 계정에 메시지를 보내면 Meta에서 해당 비즈니스로 알림을 보낼 수 있습니다. Webhooks 알림을 사용하면 수신 메시지와 메시지 상태 업데이트를 추적할 수 있습니다. 또한 Messenger 플랫폼 엔드포인트를 쿼리하여 이러한 변경 사항을 추적할 경우에 발생하는 사용 제한을 방지할 수도 있습니다.

Messenger 또는 Instagram 대화용 Webhooks를 성공적으로 구현하려면 다음 작업이 필요합니다.

Webhooks 알림인 JSON 개체를 수신하고 처리할 엔드포인트를 서버에 생성
앱 대시보드에서 Meta Webhooks 제품 구성
수신하려는 Meta Webhooks 알림 구독
비즈니스 또는 Instagram 프로페셔널 계정과 링크된 Facebook 페이지에 메시지 앱 설치

시작하기 전에

시작하기 전에 다음과 같은 필수 조건을 충족해야 합니다.

Messenger 플랫폼 개요 를 읽고 Meta로 개발하는 데 필요한 구성 요소를 구현합니다.

Node.JS 서버 구성

서버는 인증 요청과 이벤트 알림이라는 두 가지 유형의 HTTPS 요청을 처리할 수 있어야 합니다. 두 요청 모두 HTTPS를 사용하므로, 유효한 TLS 또는 SSL 인증서가 서버에 올바르게 구성되고 설치되어 있어야 합니다. 자체 서명된 인증서는 지원되지 않습니다.

아래 섹션에서는 각 유형의 요청에 포함되는 항목과 이에 대한 응답 방법을 설명합니다.

여기에 나와 있는 코드 샘플은 GitHub의 샘플 앱 에서 가져왔습니다. 전체 예제와 Webhooks 서버를 설정하기 위한 자세한 정보는 GitHub를 참조하세요.

엔드포인트 만들기

Messenger 플랫폼에서 Webhooks 알림을 수신하는 엔드포인트를 만들기 위해 app.js 파일은 다음과 같은 형식을 취할 수 있습니다.

// Create the endpoint for your webhook

app.post("/webhook", (req, res) => {
  let body = req.body;

  console.log(`\u{1F7EA} Received webhook:`);
  console.dir(body, { depth: null });
    
...

이 코드는 POST 요청을 수락하는 /webhook 엔드포인트를 만들고 요청이 Webhooks 알림인지 확인합니다.

`200 OK` 응답 반환

엔드포인트는 200 OK 응답을 반환해야 합니다. 이는 Messenger 플랫폼에 이벤트가 수신되었고 다시 보낼 필요가 없다는 것을 알려줍니다. 일반적으로 알림 처리를 완료하기 전에는 이 응답을 보내지 않습니다.

이벤트 알림에 응답하기

엔드포인트는 모든 알림에 다음과 같이 응답해야 합니다.

200 OK HTTPS 응답 사용
5초 이내

다음 코드는 app.js 파일의 app.post 안에 있고 다음과 같은 형식을 취할 수 있습니다.

...
  // Send a 200 OK response if this is a page webhook

  if (body.object === "page") {
    // Returns a '200 OK' response to all requests
    res.status(200).send("EVENT_RECEIVED");
...
    // Determine which webhooks were triggered and get sender PSIDs and locale, message content and more.
...
  } else {
    // Return a '404 Not Found' if event is not from a page subscription
    res.sendStatus(404);
  }
});

인증 요청

앱 대시보드에서 Webhooks 제품을 구성할 때마다 엔드포인트 URL에 GET 요청이 전송됩니다. 인증 요청에는 엔드포인트 URL의 끝에 추가된 다음과 같은 쿼리 문자열 매개변수가 포함됩니다. 이는 다음과 같이 표시됩니다.

인증 요청 샘플

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.verify_token=mytoken& hub.challenge=1158201444

인증 요청 검증하기

엔드포인트에서 인증 요청을 받을 때마다 다음과 같이 해야 합니다.

hub.verify_token 값이 앱 대시보드에서 Webhooks 제품을 구성할 때 인증 토큰 필드에서 설정한 문자열과 일치하는지 확인합니다(아직 이 토큰 문자열을 설정하지 않았음).
hub.challenge 값을 사용하여 응답합니다.

app.js 파일은 다음과 같은 형식을 취할 수 있습니다.

// Add support for GET requests to our webhook
app.get("/messaging-webhook", (req, res) => {
  
// Parse the query params
  let mode = req.query["hub.mode"];
  let token = req.query["hub.verify_token"];
  let challenge = req.query["hub.challenge"];

  // Check if a token and mode is in the query string of the request
  if (mode && token) {
    // Check the mode and token sent is correct
    if (mode === "subscribe" && token === config.verifyToken) {
      // Respond with the challenge token from the request
      console.log("WEBHOOK_VERIFIED");
      res.status(200).send(challenge);
    } else {
      // Respond with '403 Forbidden' if verify tokens do not match
      res.sendStatus(403);
    }
  }
});

매개변수	샘플 값	설명
`hub.mode`	`subscribe`	이 값은 항상 `subscribe`로 설정됩니다.
`hub.challenge`	`1158201444`	Facebook에 다시 전달해야 하는 `int`입니다.
`hub.verify_token`	`mytoken`	앱의 앱 대시보드에 있는 인증 토큰 필드에서 가져오는 문자열입니다. 이 문자열은 Webhooks 구성 설정 단계를 완료할 때 설정합니다.

참고: PHP는 매개변수 이름에서 마침표(.)를 밑줄(_)로 변환합니다 .

앱 대시보드를 사용 중이고 Webhooks 제품을 구성 중인 경우(따라서 인증 요청을 트리거 중인 경우) 대시보드에서 엔드포인트가 요청을 올바르게 검증했는지 표시합니다. 그래프 API의 /app/subscriptions 엔드포인트를 사용하여 Webhooks 제품을 구성하는 경우, API가 성공 또는 실패로 응답합니다.

이벤트 알림

Webhooks 제품을 구성할 때는 object 유형에서 특정 fields를 구독합니다(예: page 개체의 messages 필드). 이러한 필드 중 하나에 변경 사항이 있을 때마다 해당 변경 사항을 설명하는 JSON 페이로드가 포함된 POST 요청이 엔드포인트에 전송됩니다.

예를 들어 page 개체의 message_reactions 필드를 구독하는 데 어떤 고객이 앱에서 전송한 메시지에 공감한 경우 다음과 같은 POST 요청이 전송됩니다.

{
  "object":"page",
  "entry":[
    {
      "id":"<PAGE_ID>",
      "time":1458692752478,
      "messaging":[
        {
          "sender":{
            "id":"<PSID>"
          },
          "recipient":{
            "id":"<PAGE_ID>"
          },

          ...
        }
      ]
    }
  ]
}

페이로드 콘텐츠

페이로드에는 변경 사항을 설명하는 개체가 포함됩니다. Webhooks 제품을 구성할 때 페이로드에 변경된 필드의 이름만 포함해야 할지, 페이로드에 새로운 값도 포함해야 할지 나타낼 수 있습니다.

모든 페이로드는 JSON 형식으로 되어 있으므로 일반 JSON 구문 분석 메서드나 패키지로 페이로드를 구문 분석할 수 있습니다.

Facebook에서는 사용자에게 전송된 Webhooks 이벤트 알림 데이터를 저장하지 않으므로 보관하고 싶은 페이로드 콘텐츠가 있다면 캡처하여 저장하시기 바랍니다.

페이로드 검증하기

Facebook에서는 SHA256 서명으로 모든 이벤트 알림 페이로드에 서명하고 요청의 'X-Hub-Signature-256' 헤더에 있는 서명을 포함합니다(앞에 'sha256='를 붙임). 페이로드 검증은 필수가 아니지만 페이로드를 검증하는 것이 좋습니다.

페이로드를 검증하는 방법은 다음과 같습니다.

페이로드와 앱의 앱 시크릿 코드를 사용하여 SHA256 서명을 생성합니다.
X-Hub-Signature-256 헤더의 서명(sha256= 이후 전체)과 자신의 서명을 비교합니다. 서명이 일치하면 페이로드는 진짜입니다.

서명은 소문자 16진수와 함께 페이로드의 이스케이프된 유니코드 버전을 사용하여 생성됩니다. 디코딩된 바이트에 대해서만 계산하는 경우에는 다른 서명을 얻게 됩니다. 예를 들어 문자열 äöå는 \u00e4\u00f6\u00e5로 이스케이프해야 합니다.

app.js 파일은 다음과 같은 형식을 취할 수 있습니다.

// Import dependencies and set up http server
const express = require("express"),
  bodyParser = require("body-parser"),
  { urlencoded, json } = require("body-parser"),
  app = express().use(bodyParser.json());
    
    ...


// Verify that the callback came from Facebook.
function verifyRequestSignature(req, res, buf) {
  var signature = req.headers["x-hub-signature-256"];

  if (!signature) {
    console.warn(`Couldn't find "x-hub-signature-256" in headers.`);
  } else {
    var elements = signature.split("=");
    var signatureHash = elements[1];
    var expectedHash = crypto
      .createHmac("sha256", config.appSecret)
      .update(buf)
      .digest("hex");
    if (signatureHash != expectedHash) {
      throw new Error("Couldn't validate the request signature.");
    }
  }
}

Webhooks 전송 재시도

서버로 알림 전송이 실패한 경우 즉시 몇 번 더 시도합니다. 이러한 경우 서버에서 중복 제거를 처리해야 합니다. 15분이 지나도 알림을 전달할 수 없는 경우 알림이 개발자 계정으로 전송됩니다.

알림 전송이 1시간 동안 계속 실패하는 경우 Webhooks 비활성화됨 알림을 수신하고 앱에서 페이지 또는 Instagram 프로페셔널 계정에 대한 Webhooks 구독이 취소됩니다. 이슈를 수정하고 나면 다시 Webhooks를 구독해야 합니다.

Webhooks 테스트

Webhooks 인증을 테스트하려면 인증 토큰으로 다음 cURL 요청을 실행합니다.

curl -X GET "localhost:1337/webhook?hub.verify_token=YOUR-VERIFY-TOKEN&hub.challenge=CHALLENGE_ACCEPTED&hub.mode=subscribe"

Webhooks 인증이 예상대로 작동한다면 다음과 같이 표시되어야 합니다.

WEBHOOK_VERIFIED는 노드 프로세스가 실행되고 있는 명령줄에 로깅됩니다.
CHALLENGE_ACCEPTED는 cURL 요청을 보낸 명령줄에 로깅됩니다.

Webhooks를 테스트하려면 다음 cURL 요청을 보냅니다.

curl -H "Content-Type: application/json" -X POST "localhost:1337/webhook" -d '{"object": "page", "entry": [{"messaging": [{"message": "TEST_MESSAGE"}]}]}'

Webhooks가 예상대로 작동한다면 다음과 같이 표시되어야 합니다.

TEST_MESSAGE는 노드 프로세스가 실행되고 있는 명령줄에 로깅됩니다.
EVENT RECEIVED는 cURL 요청을 보낸 명령줄에 로깅됩니다.

Meta Webhooks 구독

Webhooks 서버 엔드포인트 또는 샘플 앱이 준비되면 앱의 앱 대시보드 를 사용하여 Meta Webhooks를 구독합니다.

이 예시에서는 대시보드를 사용하여 Webhooks를 구성하고 messages 필드를 구독합니다. 고객이 앱에 메시지를 전송할 때마다 Webhooks 엔드포인트로 알림이 전송됩니다.

앱 대시보드에서 제품 > Messenger > 설정으로 이동합니다.
- 일부 Messenger 플랫폼 Webhooks는 Instagram 메시지에 제공되지 않습니다. Instagram용 Webhooks만 구현하고 Instagram 메시지에 사용 가능한 Webhooks를 알고 있다면 여기에서 Webhooks를 구독하셔도 됩니다. Instagram 메시지용 Webhooks만 확인하고 구독하려면 Instagram 설정으로 이동하세요.
콜백 URL 필드에 엔드포인트의 URL을 입력하고 인증 토큰 필드에 인증 토큰을 추가합니다. 이 문자열은 모든 인증 요청에 포함됩니다. 샘플 앱 중 하나를 사용하는 경우 이는 앱의 TOKEN 구성 변수에 사용한 것과 동일한 문자열이어야 합니다.
알림을 받으려는 필드를 구독하고 저장을 클릭합니다.
마지막 단계는 개별 필드를 구독하는 것입니다. messages 필드를 구독하고 테스트 이벤트 알림을 전송합니다.
엔드포인트가 올바르게 설정되면 페이로드를 검증하고 검증 성공 시 실행하도록 설정된 코드를 실행합니다. 샘플 앱을 사용 중인 경우 웹 브라우저에서 앱의 URL을 읽어들입니다. 그러면 페이로드 콘텐츠가 표시됩니다.

앱 대시보드를 사용하여 언제든지 Webhooks 구독이나 인증 토큰, API 버전을 변경할 수 있습니다.

참고: 최신 API 버전을 사용하여 각 Webhooks에 제공되는 모든 정보를 수신하는 것이 좋습니다.

/app/subscriptions 엔드포인트 를 사용하여 이 작업을 프로그래밍 방식으로 수행할 수도 있습니다.

사용 가능한 Messenger 플랫폼 필드

Webhook 이벤트	설명
`messages`	메시지 수신 이벤트를 받아봅니다.
`messaging_account_linking`	계정 링크 이벤트를 받아봅니다.
`messaging_checkout_updates`(베타)	결제 업데이트 이벤트를 받아봅니다.
`message_deliveries`	메시지 전달 이벤트를 받아봅니다.
`message_echoes`	메시지 반향 이벤트를 받아봅니다.
`messaging_game_plays`	인스턴트 게임 이벤트를 받아봅니다.
`messaging_handovers`(베타)	핸드오버 프로토콜 이벤트를 받아봅니다.
`messaging_optins`	포스트백 옵트인 이벤트를 받아봅니다.
`messaging_payments`(베타)	결제 이벤트를 받아봅니다.
`messaging_policy_enforcement`	정책 시행 이벤트를 받아봅니다.
`messaging_postbacks`	포스트백 수신 이벤트를 받아봅니다.
`messaging_pre_checkouts`(베타)	결제 사전 체크아웃 이벤트를 받아봅니다.
`message_reads`	메시지 읽기 이벤트를 받아봅니다.
`messaging_referrals`	리퍼럴 이벤트를 받아봅니다.
`standby`(베타)	핸드오버 프로토콜 대기 채널 이벤트를 받아봅니다.

앱 연결하기

Webhooks 앱을 페이지에 연결하고 수신하려는 Webhooks 알림에서 페이지를 구독해야 합니다.

앱 추가하기

Meta Business Suite > 모든 도구 > 비즈니스 앱 에서 앱을 페이지에 연결할 수 있습니다.

참고: 비즈니스의 모든 메시지 앱이 메시지 전송 Webhooks를 구독해야 합니다.

페이지 구독 설정

페이지에서 수신하려는 Webhooks 알림을 구독하도록 설정해야 합니다.

요구 사항

쿼리 대상인 페이지에서 MODERATE 작업을 수행할 수 있는 사용자가 요청한 페이지 액세스 토큰
pages_messaging 및 pages_manage_metadata 권한

Webhooks 필드를 구독하려면 페이지의 액세스 토큰을 사용하여 POST 요청을 페이지의 subscribed_apps 에지로 보냅니다.

curl -i -X POST "https://graph.facebook.com/PAGE-ID/subscribed_apps
  ?subscribed_fields=messages
  &access_token=PAGE-ACCESS-TOKEN"

응답 샘플

{
  "success": "true"
}

페이지에 어떤 앱이 설치되었는지 확인하려면 대신 GET 요청을 보내세요.

요청 샘플

curl -i -X GET "https://graph.facebook.com/PAGE-ID/subscribed_apps
  &access_token=PAGE-ACCESS-TOKEN"

응답 샘플

{
  "data": [
    {
      "category": "Business",
      "link": "https://my-clever-domain-name.com/app",
      "name": "My Sample App",
      "id": "APP-ID"
      "subscribed_fields": [
        "messages"
      ]
    }
  ]
}

페이지에 앱을 설치하지 않았다면 API가 빈 데이터 세트를 반환합니다.

그래프 API 탐색기

또한 그래프 API 탐색기 를 사용하여 페이지가 Webhooks 필드를 구독하도록 요청을 전송할 수도 있습니다.

앱 드롭다운 메뉴에서 앱을 선택합니다.
토큰 가져오기 드롭다운을 클릭하고 사용자 액세스 토큰 가져오기를 선택한 다음, pages_manage_metadata 권한을 선택합니다. 그러면 앱 토큰이 pages_manage_metadata 권한이 부여된 사용자 액세스 토큰으로 변경됩니다.
다시 토큰 가져오기를 클릭하고 페이지를 선택합니다. 사용자 액세스 토큰이 페이지 액세스 토큰으로 변경됩니다.
GET 드롭다운 메뉴를 클릭하고 POST를 선택하여 작업 메서드를 변경합니다.
기본 me?fields=id,name 쿼리를 /subscribed_apps에서 팔로우하는 페이지의 id로 변경한 다음, 쿼리를 제출합니다.

액세스 요구 사항

앱에서 역할이 부여된 사용자(예: 앱 관리자, 개발자, 테스터)로부터 알림을 받기 위해서는 앱에 표준 액세스 권한만 있으면 됩니다. 앱에서 역할이 부여되지 않은 사용자인 고객으로부터 알림을 받기 위해서는 앱에 고급 액세스 권한이 필요합니다.

표준 액세스 및 고급 액세스 , 각 권한으로 액세스 가능한 데이터, 구현을 위한 요구 사항에 대해 자세히 알아보세요.

다음 단계

테스트 메시지 보내기 – 플랫폼을 사용하여 메시지를 전송하는 방법을 알아보세요.

샘플 앱 투어

– 샘플 앱 코드를 다운로드하여 Messenger 플랫폼에서 제공하는 기능에 대해 자세히 알아보세요.

기타 참고 자료

Messenger 핸드오버 프로토콜을 사용하여 한 앱에서 다른 앱으로 대화를 전달할 때 알림을 받는 방법을 알아보세요.
그래프 API용 Meta Webhooks에 대해 자세히 알아보세요.

Messenger 플랫폼용 Meta Webhooks

시작하기 전에

Node.JS 서버 구성

엔드포인트 만들기

200 OK 응답 반환

이벤트 알림에 응답하기

인증 요청

인증 요청 샘플

인증 요청 검증하기

이벤트 알림

페이로드 콘텐츠

페이로드 검증하기

Webhooks 전송 재시도

Webhooks 테스트

Meta Webhooks 구독

사용 가능한 Messenger 플랫폼 필드

앱 연결하기

앱 추가하기

페이지 구독 설정

요구 사항

응답 샘플

요청 샘플

응답 샘플

그래프 API 탐색기

액세스 요구 사항

다음 단계

기타 참고 자료

`200 OK` 응답 반환