보내기 API 참고 자료

Send API는 텍스트, 첨부 파일, 템플릿, 전송자 행동 등을 비롯한 메시지를 사용자에게 보내는 데 사용하는 주요 API입니다.

만들기

Facebook 페이지에 관심이 있는 사용자나 고객에게 메시지를 작성하고 보내세요.

시작하기 전에

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

  • 페이지에서 MESSAGE 작업을 수행할 수 있는 사용자가 요청한 페이지 액세스 토큰
  • pages_messaging 권한
  • 메시지 수신자는 최근 24시간 이내에 페이지에 메시지를 보낸 사람이거나 표준 24시간의 메시지 전송 기간 외에 페이지로부터 메시지를 수신하는 데 동의한 사람이어야 함

제한 사항

  • 메시지 태그는 홍보성 콘텐츠를 보내는 데 사용할 수 없습니다.

보내기 API는 메시지 수신자를 식별하기 위해 recipient.user_ref 또는 recipient.phone_number 를 사용하여 전송한 메시지에 대한 응답에 recipient_id 를 포함하지 않습니다.

요청 샘플

사용자에게 메시지를 보내려면 messaging_typerecipient 매개변수를 설정하고 메시지 내용을 포함하여 /PAGE-ID/messsages 엔드포인트로 POST 요청을 보냅니다.

가독성을 높이기 위해 형식을 지정했습니다.

다음의 예시는 페이지에서 보내는 메시지에 텍스트만 있을 경우의 메시지 응답입니다.

curl -X POST "https://graph.facebook.com/v21.0/{PAGE_ID}/messages" \
      -d "recipient={'id':'{PSID}'}" \
      -d "messaging_type=RESPONSE" \
      -d "message={'text':'hello, world'}" \
      -d "access_token={PAGE_ACCESS_TOKEN}"

성공할 경우 앱은 다음과 같은 JSON 응답을 받습니다.

{
  "recipient_id": "PAGE-SCOPED-ID",
  "message_id": "AG5Hz2U..."
} 

매개변수

매개변수설명

message

개체

페이지에서 보내는 메시지 유형입니다. 이 매개변수를 사용할 때는 text 또는 attachement를 설정해야 합니다.

  • attachment 개체 – URL을 미리 봅니다. 미디어 또는 구조화된 메시지를 포함한 메시지를 전송하는 데 사용합니다. text 또는 attachment를 설정해야 합니다.

    • type – 첨부 파일의 유형입니다. audio, file, image, template 또는 video일 수 있습니다. 최대 파일 크기는 25MB입니다.
    • payload템플릿 콘텐츠 또는 파일 콘텐츠를 포함하는 개체입니다.
  • metadatamessage_echo Webhooks에서 전달하고자 하는 추가적 데이터의 문자열입니다. 1,000자 미만이어야 합니다.

  • quick_replies – 메시지에서 전송할 빠른 답장의 배열입니다.
  • text – 텍스트만 포함한 메시지입니다. UTF-8이고 2,000자 미만이어야 합니다.

messaging_type

enum

필수

전송되는 메시지의 유형입니다.

  • RESPONSE – 수신된 메시지에 응답하는 메시지입니다. 여기에는 24시간 표준 메시지 전송 기간 내에 전송된 홍보성 메시지와 비홍보성 메시지를 포함합니다. 예를 들어 사용자가 예약 확인이나 상태 업데이트를 요청할 경우 이 태그를 사용하여 응답합니다.
  • UPDATE – 수신된 메시지에 응답하는 메시지가 아니라 미리 전송되는 메시지입니다. 여기에는 24시간의 표준 메시지 전송 기간 내에 전송된 홍보성 메시지와 비홍보성 메시지를 포함합니다.
  • MESSAGE_TAG메시지 태그가 있고 24시간의 표준 메시지 전송 기간 외에 전송하는 비홍보성 메시지입니다. 이 메시지는 태그에 허용된 사용 사례와 일치해야 합니다.

notification_type

enum

사용자가 수신할 푸시 알림의 유형입니다.

  • NO_PUSH – 알림이 없습니다.
  • REGULAR(기본) – 사용자가 메시지를 수신할 때 소리나 진동으로 알립니다.
  • SILENT_PUSH – 화면상의 알림만 제공합니다.

recipient

개체

필수

페이지에서 보내는 메시지를 받는 사용자입니다.

  • id – 최근 24시간 이내에 페이지에서 수신한 메시지에 대한 응답으로 메시지를 보내는 데 사용하거나 표준 24시간의 메시지 전송 기간 외에 페이지에서 메시지를 수신하는 데 동의한 사람의 페이지 범위 ID입니다.
  • user_ref – 확인란 또는 고객 채팅 플러그인에 대한 응답으로 메시지를 전송하는 데 사용한 사람에 대한 참조입니다.
  • comment_id – 페이지 게시물의 방문자 댓글에 대한 응답으로 비공개 답장을 메시지로 전송하는 데 사용한 댓글 ID입니다.
  • post_id – 페이지의 방문자 게시물에 대한 응답으로 비공개 답장을 메시지로 전송하는 데 사용한 페이지 게시물 ID입니다.

sender_action

enum

페이지가 사용자에게서 받은 메시지에 대해 취한 행동을 나타내기 위해 메시지 창에 표시되는 행동 아이콘입니다.

  • typing_on – 페이지가 응답을 준비할 때 입력 버블을 표시합니다.
  • typing_off – 입력 버블을 표시하지 않습니다.
  • mark_seen – 페이지가 확인한 메시지의 확인 아이콘을 표시합니다.

recipient 매개변수와만 전송할 수 있습니다. message 매개변수와 전송할 수 없지만 별도의 요청으로 보내야 합니다.

tag

enum

페이지가 표준 24시간의 전송 기간 외에 사용자에게 메시지를 전송할 수 있게 해 주는 태그입니다.

  • ACCOUNT_UPDATE – 고객에게 앱이나 계정에 대한 비정기적 업데이트로 전송하는 메시지를 태그합니다. 허용되는 사용 방법을 확인합니다.

    Instagram 메시지 API에는 제공되지 않습니다.

  • CONFIRMED_EVENT_UPDATE – 고객이 등록한 예정된 이벤트나 진행 중인 이벤트에 대한 알림으로 고객에게 전송하는 메시지를 태그합니다. 허용되는 사용 방법을 확인합니다.

    Instagram 메시지 API에는 제공되지 않습니다.

  • CUSTOMER_FEEDBACK – 고객에게 고객 피드백 설문조사 로 전송하는 메시지를 태그합니다. 고객 피드백 설문조사는 고객이 마지막으로 메시지를 보낸 날로부터 7일 이내에 전송해야 합니다. 허용되는 사용 방법을 확인합니다.

    Instagram 메시지 API에는 제공되지 않습니다.

  • HUMAN_AGENTInstagram 메시지 API에 필수입니다. 이 태그를 사용자에게 보내는 메시지에 추가할 경우, 인간 상담원이 사용자의 메시지에 응답할 수 있습니다. 메시지는 사용자가 메시지를 보낸 날로부터 7일 이내에 전송할 수 있습니다. 표준 메시지 전송 기간에 해결할 수 없는 문제에 대해서는 인간 상담원 지원이 제공됩니다. 허용되는 사용 방법을 확인합니다.
    • 앱은 개발자 앱 대시보드를 통해 Human Agent 권한을 신청해야 합니다. 앱 대시보드 -> 앱 검수 -> 권한 및 기능 -> 인간 상담원으로 이동합니다. 이전에 Human Agent 권한에 대한 베타 액세스가 승인된 앱은 액세스 권한을 다시 신청할 필요가 없습니다.

    표준 액세스 또는 개발 모드에서는 Human Agent 권한이 제공되지 않습니다. 앱 검수 절차를 완료해야 human agent 태그를 사용할 수 있습니다. 앱 검수를 위해 제출할 때는 환경 내에서 human agent 태그를 사용하는 방법에 대한 명확한 지침과 데모를 제공하세요.

  • POST_PURCHASE_UPDATE –고객의 최근 구매에 대한 업데이트를 제공하기 위해 고객에게 보내는 메시지를 태그합니다. 허용되는 사용 방법을 확인합니다.

    Instagram 메시지 API에는 제공되지 않습니다.

메시지 태그 사용

다음의 표에는 각 메시지 태그에 대한 메시지 유형이 나와 있습니다.

메시지 태그사용 방법

ACCOUNT_UPDATE

허용되는 사용 방법

  • 앱 상태 변화에 대한 알림(예: 신용카드, 채용 지원)
  • 의심스러운 활동에 대한 알림(예: 사기 알림)

허용되지 않는 사용 방법(전체 내용은 아님)

  • 딜, 홍보, 쿠폰, 할인 반복 콘텐츠를 포함하되 이에 국한되지 않는 홍보 콘텐츠(예: 명세서 준비, 지불 기한, 새로운 채용 목록)
  • Messenger에서 과거에 주고받았던 인터랙션과 관련이 없는 모든 설문조사, 여론조사 또는 리뷰에 대한 프롬프트

Instagram 메시지 API에는 제공되지 않습니다.

CONFIRMED_EVENT_UPDATE

허용되는 사용 방법

  • 사용자가 예약한 예정된 수업, 약속 또는 이벤트에 대한 알림
  • 수락된 이벤트 또는 약속에 대한 사용자 예약이나 참석 확인
  • 사용자의 교통편이나 예약한 여행에 대한 알림(예: 도착, 취소, 수하물 지연 또는 기타 여행 상태 변경 사항)

허용되지 않는 사용 방법(전체 내용은 아님)

  • 홍보성 콘텐츠(예: 딜, 혜택, 쿠폰, 할인)
  • 사용자가 등록하지 않은 이벤트 관련 콘텐츠(예: 이벤트 티켓 구매 알림, 다른 이벤트 교차 판매, 투어 일정)
  • 지난 이벤트 관련 메시지
  • Messenger에서 과거에 주고받았던 인터랙션과 관련이 없는 모든 설문조사, 여론조사 또는 리뷰에 대한 프롬프트

Instagram 메시지 API에는 제공되지 않습니다.

CUSTOMER_FEEDBACK

허용되는 사용 방법

  • 구매 지원 피드백에 대한 설문조사
  • 이벤트 피드백에 대한 설문조사
  • 제품 리뷰

허용되지 않는 사용 방법(전체 내용은 아님)

  • 고객 피드백 템플릿에서만 태그를 사용할 수 있습니다. 다른 형태로 사용하는 것은 금지되며, 전송이 실패합니다.

Instagram 메시지 API에는 제공되지 않습니다.

HUMAN_AGENT

허용되는 사용 방법

  • 24시간 표준 메시지 전송 기간에 해결할 수 없는 이슈에 대한 인간 상담원 지원(예: 정상 업무 시간 이외의 이슈 해결, 해결하는 데 24시간 이상이 필요한 이슈)

허용되지 않는 사용 방법(전체 내용은 아님)

  • 자동 메시지
  • 사용자 문의와 관련이 없는 콘텐츠

Instagram 메시지 API에 필수입니다.

POST_PURCHASE_UPDATE

허용되는 사용 방법

  • 거래 확인(예: 청구서, 영수증)
  • 배송 상태 업데이트(예: 제품 배송 중, 출고됨, 배송 완료, 배송 지연)
  • 사용자가 본인이 진행한 주문에 대해 조치가 필요한 상태 업데이트(예: 신용카드 승인 거부, 이월 주문 품목, 사용자 조치가 필요한 기타 주문 업데이트)

허용되지 않는 사용 방법(전체 내용은 아님)

  • 홍보성 콘텐츠(예: 딜, 프로모션, 쿠폰, 할인)
  • 제품이나 서비스를 교차 판매하거나 상향 판매하는 메시지
  • Messenger에서 과거에 주고받았던 인터랙션과 관련이 없는 모든 설문조사, 여론조사 또는 리뷰에 대한 프롬프트

Instagram 메시지 API에는 제공되지 않습니다.

읽기

이 엔드포인트에서는 해당 작업을 수행할 수 없습니다.

페이지가 참여하는 대화에 대한 자세한 내용은 페이지 대화 참고 자료를 참조하세요.

업데이트

이 엔드포인트에서는 해당 작업을 수행할 수 없습니다.

삭제

이 엔드포인트에서는 해당 작업을 수행할 수 없습니다.

기타 참고 자료

개발자 지원