Instagram 메시지용 Webhooks

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

요구 사항

Instagram 메시지용 Webhooks 알림을 수신하려면 다음 요구 사항을 구현해야 합니다.

• instagram_basic, instagram_manage_messages 및 pages_manage_metadata 권한
• 앱에서 역할이 부여되지 않은 사용자가 소유하거나 관리하는 데이터를 포함한 Webhooks 알림을 받으려면 앱에 Advanced Access가 있어야 함

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

앱 모드

• 개발 모드 – Webhooks는 앱에 Advanced Access 권한이 있더라도 앱 사용자에게 앱에서 역할이 부여된 경우에만 전송됩니다. 자신이 소유하거나 관리자인 데이터만 액세스할 수 있습니다.
• 라이브 모드 – 액세스 레벨에 따라 Webhooks가 전송됩니다.

  • 표준 액세스 – Webhooks가 앱 사용자에게 앱에서 역할이 부여된 경우에만 전송됩니다. 자신이 소유하거나 관리자인 데이터만 액세스할 수 있습니다.
  • Advanced Access – 필수 권한이 부여되어 있는 경우 누구든 앱을 사용할 때 Webhooks가 전송됩니다.

액세스 레벨 , 앱 모드 및 앱 역할에 대해 자세히 알아보세요.

제한 사항

• 고객이 Instagram 게시물의 슬라이드에 있는 이미지에 공감하거나 해당 이미지를 전달하는 경우에는 알림에 슬라이드의 첫 번째 이미지가 포함됩니다. 해당 이미지는 고객이 공감하거나 전달한 이미지가 아닐 수 있습니다.
• 고객이 공유를 포함하여 메시지를 전송할 때 공유된 미디어 또는 게시물의 URL만 알림에 포함됩니다.
• GIF와 스티커가 포함된 메시지는 지원되지 않습니다. 누군가가 GIF나 스티커가 포함된 메시지를 보낼 경우 Webhooks가 트리거되지 않고 Webhooks 알림이 전송되지 않습니다.

Webhooks 이벤트

알림 예시

비즈니스가 수신할 수 있는 Webhooks 알림 유형의 예시는 다음과 같습니다.

메시지

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGID",  // ID of your Instagram Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": { "id": "IGSID" },    // Instagram-scoped ID for the customer who sent the message
          "recipient": { "id": "IGID" },  // ID of your Instagram Professional account
          "timestamp": 1569262485349,
          "message": {
            "mid": "MESSAGE-ID",   // ID of the message sent to your business
      
            "text": "MESSAGE-TEXT"     // Included when a customer sends a message containing text
      
            "attachments": [           // Included when a customer sends multiple media attachments or a URL for a story mention or share
              {
                "type":"image",             // Can be audio, file, image (image or sticker), share, story_mention, or video
                "payload":{ "url":"LINK" }  
              },
              {
                "type":"video",
                "payload":{ "url":"LINK" }
              }
            ]
      
            "is_deleted": true         // Included when a customer deletes a message
      
            "is_echo": true            // Included when your business sends a message to the customer

            "is_unsupported": true,    // Included when a customer sends a message with unsupported media
      
            "quick_reply": {           // Included when a customer clicks a quick reply
              "payload": "CUSTOMER-RESPONSE-PAYLOAD"   // The payload with the option selected by the customer
            },      
      
            "referral": {              // Included when a customer clicks an Instagram Shop product
              "product": {
                "id": "PRODUCT-ID"
            }      
      
            "referral": {                   // Included when a customer clicks an CTD ad
              "ref": "REF-DATA-IN-AD-IF-SPECIFIED"
              "ad_id": AD-ID,
              "source": "ADS",
              "type": "OPEN_THREAD",
              "ads_context_data": {
                "ad_title": TITLE-FOR-THE-AD,
                "photo_url": IMAGE-URL-THAT-WAS-CLICKED,
                "video_url": THUMBNAIL-URL-FOR-THE-AD-VIDEO,
              }
            }

            "reply_to":{               // Included when a customer sends an inline reply
              "mid":"MESSAGE-ID"
            } 
      
            "reply_to": {               // Included when a customer replies to a story
              "story": {
                "url":"CDN-URL",
                "id":"STORY-ID"       
              }
            }
          }
        }
      ]
    }
  ]
}

메시지 공감

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGID",  // ID for your Instagram Professional account
      "time": 1569262486134,
      "messaging": [
        {
          "sender": {
            "id": "IGSID"  // Instagram-scoped ID for the customer who sent the message
          },
          "recipient": {
            "id": "IGID"  // ID for your Instagram Professional account
          },
          "timestamp": 1569262485349,
          "reaction" :{
            "mid" : "MESSAGE-ID",
            "action": "react",    // or unreact
            "reaction": "love", // optional, to unreact if there is no reaction field
            "emoji": "\u{2764}\u{FE0F}" // optional, to unreact if there is no emoji field
          } 
        }
      ]
    }
  ]
}  

메시지 Postback

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGSID",  // ID of your Instagram Professional account
      "time": 1502905976963,
      "messaging": [
        {
          "sender": { "id": "IGSID" },    // Instagram-scoped ID for the customer who sent the message
          "recipient": { "id": "IGID" },  // ID of your Instagram Professional account
          "timestamp": 1502905976377,
          "postback": {
            "mid":"MESSAGE-ID",           // ID for the message sent to your business
            "title": "SELECTED-ICEBREAKER-REPLY-OR-CTA-BUTTON",
            "payload": "CUSTOMER-RESPONSE-PAYLOAD",  // The payload with the option selected by the customer
          }
        }
      ]
    }
  ]
}

메시지 리퍼럴

{
  "object": "instagram",
  "entry": [
    {
      "id": "IGSID",  // ID of your Instagram Professional account  
      "time": 1502905976963,
      "messaging": [
        {
          "sender": {
            "id": "IGSID"  // Instagram-scoped ID for the customer who sent the message
          },
          "recipient": {
            "id": "IGID"  // ID of your Instagram Professional account
          },
          "timestamp": 1502905976377,
          "referral": {
                 "ref": "INFORMATION-INCLUDED-IN-REF-PARAMETER-OF-IGME-LINK"
                 "source": "IGME-SOURCE-LINK"  
                 "type":  "OPEN_THREAD"  // Only supported for existing conversations 
          }
        }
      ]
    }
  ]
}
  

확인한 메시지

{
   "object":"instagram",
   "entry":[
      {
         "id":"IGID",  // ID for your Instagram Professional account
         "time":1569262486134,
         "messaging":[
            {
               "sender":{
                  "id":"IGSID"  // Instagram-scoped ID for the customer who sent the message
               },
               "recipient":{
                  "id":"IGID"  // ID for your Instagram Professional account
               },
               "timestamp":1569262485349,
               "read":{
                  "mid":"MESSAGE-ID"
               }
            }
         ]
      }
   ]
}

기타 참고 자료

• Messenger 핸드오버 프로토콜 – 메시지를 처리하는 앱이 두 개 이상일 경우(예: 한 개의 앱은 자동화된 답변을 처리하고 한 개의 앱은 인간 상담원에 대한 에스컬레이션을 처리할 경우) 핸드오버 프로토콜을 구현하여 앱 사이에서 대화를 전달해야 합니다.
• Direct 연결 광고, CTD – Instagram Direct 연결 광고를 만드는 방법에 대한 자세한 내용은 비즈니스 고객 센터를 참조하세요.