Developers
로그인

후원 이벤트

후원 이벤트를 구독하면 채널에서 발생하는 후원을 실시간으로 수신합니다. 현재 채팅 후원(CHAT), 영상 후원(VIDEO), 응원 후원(CHEERING) 세 가지 타입을 지원하며 모두 동일한 구독 엔드포인트로 수신합니다.

구독 엔드포인트: POST /api/openapi/open/v1/sessions/events/subscribe/donation

필요 Scope: READ:DONATION

이벤트 공통 스키마

{
  "event": "DONATION",
  "data": {
    "donationType": "CHAT" | "VIDEO" | "CHEERING",
    "channelId": "12345",
    "donatorChannelId": "67890",
    "donatorNickname": "후원자명",
    "donatorBadges": [
      { "id": "subscribe_tier1", "name": "티어1 구독자", "imageUrl": "https://..." }
    ],
    "payAmount": "10000",
    "donationText": "응원합니다!",   // CHAT / VIDEO 에만 포함
    "emojis": {},                  // CHAT / VIDEO 에만 포함
    "cheeringItems": [ /* CHEERING 에만 포함 */ ]
  }
}
필드 타입 설명
donationType string "CHAT" / "VIDEO" / "CHEERING"
channelId string 후원이 발생한 채널의 ID
donatorChannelId string | null 후원자의 채널 ID. 익명 후원 시 null
donatorNickname string | null 후원자 닉네임. 익명 후원 시 null
donatorBadges array 후원자의 뱃지 목록 (없으면 빈 배열)
payAmount string 후원 금액 (빔 단위)
donationText string 후원 메시지. CHAT·VIDEO에만 포함 (CHEERING에는 없음)
emojis object 이모티콘 토큰과 이미지 URL 매핑. CHAT·VIDEO에만 포함 (CHEERING에는 없음)
cheeringItems array 응원 후원(CHEERING)일 때만 포함되는 아이템 목록. 아래 스키마 참고

채팅 후원 (donationType: "CHAT")

사용자가 채팅과 함께 후원한 경우.

{
  "event": "DONATION",
  "data": {
    "donationType": "CHAT",
    "channelId": "12345",
    "donatorChannelId": "67890",
    "donatorNickname": "후원자명",
    "donatorBadges": [],
    "payAmount": "10000",
    "donationText": "응원합니다!",
    "emojis": {}
  }
}

영상 후원 (donationType: "VIDEO")

영상 링크와 함께 후원한 경우. 현재 donationText에 후원 메시지가 담깁니다.

{
  "event": "DONATION",
  "data": {
    "donationType": "VIDEO",
    "channelId": "12345",
    "donatorChannelId": "67890",
    "donatorNickname": "후원자명",
    "donatorBadges": [],
    "payAmount": "30000",
    "donationText": "이 영상 꼭 보세요!",
    "emojis": {}
  }
}

응원 후원 (donationType: "CHEERING")

응원봉·눈꽃·컨페티 등 응원 아이템을 골라 한 번에 여러 개 후원하는 포맷입니다.

  • donationText·emojis 필드는 포함되지 않습니다 (CHAT·VIDEO에만 있는 필드)
  • payAmount는 선택한 아이템들의 빔 합계
  • cheeringItems에 선택한 아이템의 종류·수량·이미지 URL이 포함됨
{
  "event": "DONATION",
  "data": {
    "donationType": "CHEERING",
    "channelId": "12345",
    "donatorChannelId": "67890",
    "donatorNickname": "후원자명",
    "donatorBadges": [],
    "payAmount": "80",
    "cheeringItems": [
      {
        "cnt": 3,
        "type": "CONCERT_1",
        "skinType": "CONCERT",
        "amount": 10,
        "imageUrl": "https://streaming.cf.ci.me/public/assets/images/donation/concert_1.webp",
        "overlayImageUrl": "https://streaming.cf.ci.me/public/assets/images/donation/concert_1_overlay.webp"
      },
      {
        "cnt": 1,
        "type": "CONCERT_4",
        "skinType": "CONCERT",
        "amount": 50,
        "imageUrl": "https://streaming.cf.ci.me/public/assets/images/donation/concert_4.webp",
        "overlayImageUrl": "https://streaming.cf.ci.me/public/assets/images/donation/concert_4_overlay.webp"
      }
    ]
  }
}

cheeringItems[] 필드

필드 타입 설명
cnt number 해당 아이템을 선택한 수량
type string 아이템 타입 코드
skinType string 응원 후원 스킨 타입 (예: CONCERT)
amount number 아이템 개당 빔 금액
imageUrl string 아이템 이미지 URL
overlayImageUrl string 채팅 메시지에 노출되는 아이템 이미지 URL

권장 구현 팁

  • 세 가지 donationType을 switch로 분기하여 UI를 구성하세요.
  • 응원 후원은 cheeringItems[].imageUrl을 그대로 사용해 자체 오버레이 효과를 그릴 수 있습니다. 추가 메타 API를 호출할 필요가 없습니다.
  • payAmount는 문자열이며 단위는 "빔" 입니다. 금액 비교가 필요하다면 Number(payAmount)로 변환해 사용하세요.

미션 후원 이벤트는 현재 지원하지 않습니다.