개발자 포털
실험적 봇 & 앱 플랫폼은 활발히 개발 중입니다. 자체 호스팅 서버에서도 봇, 슬래시 명령어, 메시지 컴포넌트가 동작하며, 클라우드와는 몇 가지 차이가 있습니다. 지원 항목 보기.
← 문서

자체 호스팅 서버

고객은 자체 하드웨어에서 GameVox를 운영할 수 있고, 봇도 거기서 동작합니다. 클라우드 API가 Discord 형태의 REST 호출을 고객의 제어 채널로 전달하면, 자체 호스팅 서버가 로컬 데이터베이스에서 실행하고 같은 경로로 응답이 돌아옵니다. 게이트웨이 이벤트는 반대 방향으로 흐릅니다. 대부분의 엔드포인트는 투명하게 동작하며, 차이점은 아래에 정리했습니다.

동작 방식

봇이 GET /guilds/{id}나 POST /channels/{id}/messages를 호출하면, 클라우드 API가 대상 서버의 등급을 확인합니다. 자체 호스팅이라면 요청(메서드, 경로, 쿼리, 본문, bot_user_id)을 직렬화해, 고객의 서버가 계속 열어 두는 제어 채널 WebSocket으로 보냅니다. 자체 호스팅 프로세스는 자신의 역할을 기준으로 봇의 권한을 확인하고, 자신의 SQLite 데이터베이스에서 같은 핸들러를 실행해 응답 엔벌로프를 돌려주며, 저희는 그것을 봇에 전달합니다.

전달은 클라우드에서 이루어지므로 라이브러리는 이를 전혀 알지 못합니다. 다른 토큰도, 다른 게이트웨이 URL도, 다른 SDK도 필요 없습니다. 길드가 클라우드에 있든 자체 호스팅이든, 봇은 같은 gateway.gamevox.com에 연결하고 같은 app-api.gamevox.com을 호출합니다. 봇은 자체 호스팅 서버의 구성원이어야 하며, 그렇지 않으면 호출에 403이 반환됩니다.

지연

왕복 시간은 고객의 WAN 회선과 SQLite 질의 시간에 좌우되며, 보통 클라우드 호출에 30–300 ms가 더해집니다. 전체 12 초의 기한이 적용됩니다(파일이 담긴 메시지는 서버가 파일을 내려받기 때문에 90 초). 서버가 연결되어 있지 않으면 봇은 곧바로 503을 받습니다. 연결되어 있지만 제시간에 응답하지 않으면 봇은 504를 받습니다.

동작하는 것

아래 항목은 모두 자체 호스팅 서버의 로컬 데이터에 대해 실행되며, 클라우드와 같은 응답 형태를 반환합니다.

  • 메시지: 목록, 조회, 전송, 편집, 삭제, 일괄 삭제. 임베드, 컴포넌트, 답장(message_reference), 첨부 파일(multipart files[n]와 payload_json), 투표. tts는 받아들이지만 무시됩니다.
  • 반응: 추가, 본인 것 제거, 다른 사람 것 제거, 전체 제거, 이모지별 전체 제거, 사용자 목록.
  • 고정: 고정, 해제, 목록.
  • 입력 표시: POST /channels/{id}/typing.
  • 채널: 조회, 수정, 삭제, 목록, 생성(앱 채널 포함), 순서 변경.
  • 채널 권한 오버라이드: PUT과 DELETE .../channels/{id}/permissions/{oid}, 그리고 모든 채널 객체(및 CHANNEL_UPDATE)의 permission_overwrites. permission_overwrites 읽기는 현재 자체 호스팅에서만 지원합니다. 클라우드 채널 객체에는 이 필드가 없고, 클라우드 API는 PUT과 DELETE 쓰기만 지원합니다. 자체 호스팅 서버에는 역할 오버라이드만 있습니다. oid는 역할 ID이고 type은 0이어야 하며, 구성원 오버라이드(type: 1)는 거부됩니다. 오버라이드가 다루는 권한은 채널 보기, 메시지 보내기, 파일 첨부, 반응 추가, 연결, 말하기, 음성 감지 사용, 스트리밍입니다. allow는 역할 자체에 허용된 범위를 넘어 권한을 주지 않으므로, 역할에 없는 권한에 대한 allow는 반환되지 않습니다. 오버라이드가 없는 채널은 빈 목록을 반환합니다.
  • 서버(길드): 조회, 수정(이름과 설명).
  • 구성원: 목록, 검색, @me, 조회, 수정, 별명 변경, 추방, 역할 추가·제거.
  • 차단: 목록, 조회, 설정, 해제.
  • 역할: 목록, 조회, 생성, 수정(color 포함), 순서 변경, 삭제, 그리고 역할 권한.
  • 이모지: 목록, 조회(서버 소유).
  • 사운드보드: 목록, 조회(서버 소유).
  • 감사 로그: GET /guilds/{id}/audit-logs. 봇 API를 통해 이루어진 작업의 항목.
  • 베니티 URL: GET(항상 빈 형태).
  • 음성 상태: GET(SFU에서 실시간), 그리고 mute, deaf, channel_id(이동, 또는 null로 연결 해제)를 자유롭게 조합한 PATCH. mute와 deaf는 서버 플래그이고, self_mute와 self_deaf는 구성원 자신의 플래그입니다.
  • 웹훅: 완전한 CRUD와 실행. 웹훅 레코드는 클라우드에 있고, 실행된 메시지는 자체 호스팅 채널에 기록되어 웹훅 이름으로 표시됩니다.
  • 예약 이벤트: 목록, 생성, 조회, 수정, 삭제, 관심 있는 사용자 목록, 구성원의 참석 응답(RSVP) 설정 및 해제. 형태는 클라우드와 같습니다. 반복 설정은 저장되지만, 반복 이벤트의 이후 회차는 생성되지 않습니다.
  • 포럼 게시물: 게시물 작성(POST /channels/{forum}/threads), 읽기, 답글. 게시물의 첫 메시지는 10,000자로 제한됩니다(클라우드는 20,000자).
  • 슬래시 명령어: 호출을 지원하며, 권한은 해당 자체 호스팅 서버의 역할을 기준으로 확인합니다. 등록 방법은 클라우드와 같습니다.
  • 메시지 컴포넌트: 버튼, 문자열 선택 메뉴, 모달, 임시 응답. 인터랙션 콜백, 후속 응답, 원본 응답 엔드포인트를 포함합니다. 메시지 컴포넌트 참고.

501을 반환하는 것(수용하지만 미구현)

  • PATCH .../guilds/{id}/vanity-url. 자체 호스팅 서버에는 베니티 URL이 없습니다.

자체 호스팅 서버가 아니라 클라우드가 응답하는 것

이 엔드포인트들은 특정 서버가 아니라 GameVox 계정에 관한 것이므로, 모든 봇에 대해 클라우드가 응답합니다. 자체 호스팅 서버의 구성원도 일반 GameVox 계정입니다.

  • GET /users/{id}와 GET /users/by-name/{name}.
  • GET /users/@me/guilds. 앱이 설치된 자체 호스팅 서버도 포함됩니다.
  • POST /users/@me/channels는 DM 채널을 반환하지만, 그 채널로 메시지를 보내는 기능은 클라우드와 자체 호스팅 모두 아직 지원하지 않습니다.

게이트웨이 이벤트

자체 호스팅 서버는 클라우드와 같은 게이트웨이 세션으로 이벤트를 게시합니다. 구독 모델도 달라지지 않습니다. 채널 이벤트는 해당 채널을 볼 수 있는 봇에게만 전달되며, 인텐트는 클라우드와 똑같이 적용됩니다.

자체 호스팅 서버에서 사람이 한 작업과 봇 자신의 REST 호출에 대해 발생하는 것:

  • MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE
  • MESSAGE_DELETE_BULK (추방이나 차단으로 구성원의 메시지가 삭제될 때도)
  • MESSAGE_REACTION_ADD, MESSAGE_REACTION_REMOVE
  • MESSAGE_POLL_VOTE_ADD, MESSAGE_POLL_VOTE_REMOVE
  • CHANNEL_CREATE, CHANNEL_UPDATE, CHANNEL_DELETE
  • CHANNEL_PINS_UPDATE
  • GUILD_UPDATE (이름 / 설명 변경)
  • GUILD_MEMBER_ADD
  • GUILD_MEMBER_REMOVE (나가기, 추방, 차단, 비활성 게스트 정리)
  • GUILD_MEMBER_UPDATE (역할 변경, 사용자 이름 또는 아바타 변경)
  • GUILD_BAN_ADD
  • GUILD_ROLE_CREATE, GUILD_ROLE_UPDATE, GUILD_ROLE_DELETE (생성, 이름 변경, 순서 변경, 색상 및 권한 변경)
  • GUILD_EMOJIS_UPDATE
  • TYPING_START
  • PRESENCE_UPDATE (GUILD_PRESENCES 인텐트 필요. 변경분만 전달되며, 연결 시점에 이미 온라인인 구성원의 스냅샷은 없습니다)
  • VOICE_STATE_UPDATE (참여, 나가기, 이동, 본인/서버 음소거와 스피커 음소거)
  • INTERACTION_CREATE (슬래시 명령어, 컴포넌트 클릭, 모달 제출. 클라우드가 중계합니다)

봇이 REST로 변경한 경우에만 발생하는 것:

  • GUILD_BAN_REMOVE (자체 호스팅 서버에는 사람이 차단을 해제하는 기능이 없습니다)
  • MESSAGE_REACTION_REMOVE_ALL, MESSAGE_REACTION_REMOVE_EMOJI (자체 호스팅 서버에는 사람이 할 수 있는 이 작업이 없습니다)

발생하지 않는 것(클라우드에서도 마찬가지):

  • THREAD_*, INVITE_*, GUILD_SCHEDULED_EVENT_*.

알려진 차이

  • 음성 채널 이동은 이벤트를 두 번 발생시킵니다: Discord에서 새 channel_id를 담아 voice-states/{uid}에 PATCH하면 VOICE_STATE_UPDATE가 한 번만 발생하지만, 자체 호스팅에서는 이동이 나가기 + 다시 참여로 구현되어 대상의 channel_id가 잠깐 null이 되었다가 새 채널로 바뀝니다. 같은 사용자에 대해 수백 밀리초 안에 연속으로 온 업데이트는 하나의 이동으로 처리하세요. 이동과 함께 보낸 mute나 deaf는 구성원이 다시 참여할 때 적용됩니다.
  • 첨부 파일 URL: 자체 호스팅 서버에서 첨부 파일의 url은 고객의 서버를 가리키며, 내려받으려면 구성원 세션이 필요합니다. 봇은 파일의 이름, 크기, 형식을 볼 수 있지만 아직 파일 자체를 가져올 수는 없습니다. width, height, description은 자체 호스팅에서 보존되지 않습니다.

자체 호스팅 감지하기

현재 guild 객체에는 “자체 호스팅”을 나타내는 플래그가 없습니다(Discord와 바이트 단위로 같게 유지하기 위해서입니다). 봇에서 분기해야 한다면, 위에 나열된 엔드포인트에서 오는 501이 신호이며, JSON 오류 본문에는 자체 호스팅 서버가 밝힌 이유가 다음과 같이 담깁니다.

{ "code": 0, "message": "vanity URL not supported on self-hosted" }

404("Unknown resource")는 리소스가 없다는 뜻이지, 서버가 자체 호스팅이라는 뜻이 아닙니다. 더 가벼운 감지가 필요한 봇이 많아지면 길드 페이로드에 features 항목(예: "SELF_HOSTED")을 추가하겠습니다. 도움이 될 것 같다면 애플리케이션의 지원 탭에서 의견을 남겨 주세요.

오류

  • 502 Bad Gateway. 자체 호스팅 서버가 잘못된 응답을 반환했습니다. 드물며, 대개 업그레이드 중의 버전 불일치입니다.
  • 503 Service Unavailable. 제어 채널이 현재 연결되어 있지 않습니다. 백오프를 두고 다시 시도하세요.
  • 504 Gateway Timeout. 자체 호스팅 서버가 12 초 안에 응답하지 않았습니다.

← 문서로 돌아가기