Messenger 플랫폼

Messenger 플랫폼용 대화 API

이 문서에서는 Messenger와 Instagram 메시지 대화에 관한 정보를 얻는 방법을 설명합니다. 얻을 수 있는 정보는 다음과 같습니다.

  • Facebook 페이지 또는 Instagram 프로페셔널 계정의 대화 리스트
  • 각 대화 내의 메시지 리스트
  • 메시지가 전송된 시점과 보낸 사람을 포함한 각 메시지의 상세 정보

시작하기 전에

이 튜토리얼에서는 Messenger 플랫폼 개요와 Instagram 메시지 개요를 읽었고 필수적인 구성 요소를 구현한 것으로 가정합니다.

다음과 같은 항목이 필요합니다.

  • 비즈니스의 Facebook 페이지 ID 또는 Instagram 프로페셔널 계정에 연결된 Facebook 페이지
  • 페이지에서 MESSAGING 또는 MODERATE 작업을 수행할 수 있는 사용자가 요청한 페이지 액세스 토큰
  • 고급 액세스 권한(메시지 앱, Instagram 프로페셔널 계정, Facebook 페이지 또는 비즈니스에서 역할이 부여되지 않은 사용자와 비즈니스 사이의 대화에 액세스할 때 필요함)

페이지와 사용자가 Messenger를 통해 대화를 나누려면 앱에 다음의 항목이 필요합니다.

Instagram 프로페셔널 계정과 사용자가 Instagram 메시지를 통해 대화를 나누려면 앱에 다음의 항목이 필요합니다.

  • Instagram Business 계정에 연결된 페이지에서 MESSAGING 작업을 수행할 수 있는 사용자가 요청한 페이지 액세스 토큰
  • instagram_basic, instagram_manage_messages 및 pages_manage_metadata 권한
  • 앱은 인증된 비즈니스가 소유해야 함

제한 사항

  • 공유를 위한 이미지 또는 동영상 URL만 API 호출이나 Webhooks 알림에서 반환된 데이터에 포함됩니다.
  • 계정이 비공개 키(예: 이메일, 전화번호)를 사용하여 연결된 경우 이들 계정 사이의 대화를 검색할 수 없습니다. Facebook 사용자와 Instagram 계정 한 개 사이의 대화만 제공됩니다. 앱이 고급 액세스에 대한 승인을 받으면 이 이슈가 해결됩니다. Instagram 앱의 계정 센터에서 여러 계정이 연결되어 있으면 모든 연결된 계정 사이의 대화를 가져올 수 있습니다.
  • 30일 동안 활동이 없는 요청 폴더 내의 대화는 API 호출에서 반환되지 않습니다.

Instagram 비즈니스 계정을 앱에 새로 연결하면 이 API를 통해 받은 메시지함에서 과거 대화를 동기화할 수 있습니다.

대화 리스트 가져오기

대화 리스트를 가져오려면 /PAGE-ID/conversations 엔드포인트로 GET 요청을 보내고 platform 매개변수를 instagram 또는 messenger로 설정합니다.

요청 샘플

가독성을 높이기 위해 형식을 지정했습니다.
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &access_token=PAGE-ACCESS-TOKEN"

성공 시 앱에서 비즈니스와 사용자 사이의 대화에 대한 ID 리스트 및 메시지가 전송된 가장 최근 시각이 포함된 JSON 개체를 받게 됩니다.

{
  "data": 
    {
      "id": "CONVERSATION-ID-1",  
      "updated_time": "UNIX-TIMESTAMP"
    },
    {
      "id": "CONVERSATION-ID-2",   
      "updated_time": "UNIX-TIMESTAMP"
    }
    ...
  ]
}

특정 사용자와의 대화 찾기

Instagram 프로페셔널 계정 또는 Facebook 페이지와 특정 사용자 간의 대화를 가져오려면 /PAGE-ID/conversations 엔드포인트로 GET 요청을 보냅니다. 이때 platform 매개변수와 user_id 매개변수를 해당 사용자의 Instagram 범위 ID 또는 페이지 범위 ID로 설정합니다.

요청 샘플

가독성을 높이기 위해 형식을 지정했습니다.
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/conversations
    ?platform=PLATFORM
    &user_id=INSTAGRAM-OR-PAGE-SCOPED-ID
    &access_token=PAGE-ACCESS-TOKEN"

성공 시 앱에서 대화의 ID를 받게 됩니다.


{
  "data": [
      {
        "id": "CONVERSATION-ID"
      },
  ]
}

대화에서 메시지 리스트 가져오기

대화에서 메시지 리스트를 가져오려면 /CONVERSATION-ID 엔드포인트로 GET 요청을 보내고 messages 필드를 포함합니다.

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/CONVERSATION-ID
    ?fields=messages
    &access_token=PAGE-ACCESS-TOKEN"

성공 시 앱에서 메시지 ID 리스트와 각 메시지가 생성된 시각을 받게 됩니다.

{
  "messages": {
    "data": [
      {
        "id": "Message ID-1",      
        "created_time": "UNIX-TIMESTAMP-MOST-RECENT-MESSAGE"  
      },
      {
        "id": "Message ID-2",
        "created_time": "UNIX-TIMESTAMP"
      },
      {
        "id": "Message ID-3",
        "created_time": "UNIX-TIMESTAMP"
      },
...
    ]
  },
  "id": "Conversation ID", 
}

메시지에 대한 정보 가져오기

메시지에 대한 정보(예: 보낸 사람, 받는 사람, 메시지 내용)를 가져오려면 관심이 있는 필드를 포함하여 /MESSAGE-ID 엔드포인트로 GET 요청을 보냅니다.

기본 필드는 id와 created_time입니다.

참고:/CONVERSATION-ID 엔드포인트에 대한 쿼리는 대화 내의 모든 메시지 ID를 반환합니다. 그러나 대화에서 가장 최근 메시지 20개에 대한 상세 정보만 가져올 수 있습니다. 최근 20개보다 오래된 메시지를 쿼리할 경우 메시지가 삭제되었다는 오류 메시지가 표시됩니다. 

curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/MESSAGE-ID
    ?fields=id,created_time,from,to,message
    &access_token=PAGE-ACCESS-TOKEN"

성공 시 앱은 다음과 같은 JSON 응답을 받습니다. 이 예시에서 고객은 Instagram 프로페셔널 계정으로 일반 문자 메시지를 보냈습니다.

{
  "id": "aWdGGiblWZ...",
  "created_time": "2022-07-12T19:11:07+0000",
  "to": {
    "data": [
      {
        "username": "INSTAGRAM-PROFESSIONAL-ACCOUNT-USERNAME",
        "id": "INSTAGRAM-PROFESSIONAL-ACCOUNT-ID"
      }
    ]
  },
  "from": {
    "username": "INSTAGRAM-USERNAME",
    "id": "INSTAGRAM-SCOPED-ID"
  },
  "message": "Hi Kitty!"
}

더 알아보기

다음에 대한 참고 자료를 참조하세요.

개발자 지원