Portal deweloperski
Eksperymentalne Platforma botów i aplikacji jest aktywnie rozwijana. Obsługa serwerów hostowanych samodzielnie pojawiła się 13.08.2026 i ma mniej funkcji niż chmura. Zobacz, co jest obsługiwane.
← Dokumentacja

Serwery hostowane samodzielnie

Klienci mogą uruchamiać GameVox na własnym sprzęcie, a twój bot tam działa. API w chmurze przekazuje zapytania REST i zdarzenia gatewaya w kształcie Discorda kanałem kontrolnym klienta, serwer hostowany samodzielnie wykonuje je na swojej lokalnej bazie danych, a odpowiedź wraca tą samą drogą. Większość endpointów działa przezroczyście. Nieobsługiwane wymieniamy poniżej.

Jak to działa

Gdy twój bot wywołuje GET /guilds/{id} lub POST /channels/{id}/messages, API botów w chmurze sprawdza plan docelowego serwera. Jeśli jest hostowany samodzielnie, serializujemy żądanie (metodę, ścieżkę, zapytanie, treść, bot_user_id) i wysyłamy je stałym połączeniem WebSocket kanału kontrolnego, które serwer klienta utrzymuje z nami. Proces hostowany samodzielnie wykonuje odpowiedni handler na własnych bazach SQLite i zwraca kopertę odpowiedzi, którą przekazujemy twojemu botowi bez zmian.

Przekazywanie odbywa się w warstwie API botów. Twoja biblioteka tego nie widzi. Ten sam token, ten sam URL gatewaya, to samo SDK. Twój bot łączy się z tym samym gateway.gamevox.com i wywołuje ten sam app-api.gamevox.com niezależnie od tego, czy gildia jest hostowana w chmurze, czy samodzielnie.

Opóźnienie

Czas w obie strony zależy od łącza WAN klienta i czasu zapytania SQLite, zwykle to 30–300 ms więcej niż przy wywołaniu w chmurze. Obowiązuje limit 12 s na całość. Jeśli serwer hostowany samodzielnie przestanie odpowiadać (offline, aktualizacja, awaria sieci), twój bot dostanie 504 Gateway Timeout w ciągu sekundy od upływu limitu.

Co działa

Wszystko poniżej działa na lokalnych danych serwera hostowanego samodzielnie, z odpowiedziami w tym samym kształcie co w chmurze.

  • Wiadomości: lista, pobieranie, wysyłanie, edycja, usuwanie, usuwanie zbiorcze.
  • Reakcje: dodawanie, usuwanie własnej, usuwanie cudzej, usuwanie wszystkich, usuwanie wszystkich dla emoji, lista użytkowników.
  • Przypięcia: przypinanie, odpinanie, lista.
  • Pisanie: POST /channels/{id}/typing.
  • Kanały: pobieranie, modyfikacja, usuwanie, lista, tworzenie, zmiana kolejności.
  • Serwer (guild): pobieranie, modyfikacja (nazwa i opis).
  • Członkowie: lista, wyszukiwanie, @me, pobieranie, modyfikacja, zmiana pseudonimu, wyrzucanie, dodawanie lub usuwanie roli.
  • Bany: lista, pobieranie, dodawanie, usuwanie.
  • Role: lista, pobieranie, tworzenie, modyfikacja, zmiana kolejności, usuwanie oraz uprawnienia ról.
  • Emoji: lista, pobieranie (należące do serwera).
  • Soundboard: lista, pobieranie (należące do serwera).
  • Dziennik audytu: GET /guilds/{id}/audit-logs, tylko wpisy istotne dla botów.
  • Własny URL (vanity): GET (zawsze pusty kształt).
  • Stan głosu: GET (na żywo z SFU), PATCH (wyciszenie, przeniesienie, rozłączenie).
  • Webhooki: pełny CRUD i execute. Wiersze są przechowywane w chmurze; wynikowa wiadomość jest zapisywana na kanale serwera hostowanego samodzielnie tą samą ścieżką przekazywania co wiadomości bota, więc wiadomości na kanale mają poprawne oznaczenia.
  • Komendy ukośnikowe: wywoływanie, z uprawnieniami sprawdzanymi względem grup samego serwera. Rejestracja jest taka sama jak w chmurze.
  • Komponenty wiadomości: przyciski, tekstowe listy wyboru, okna modalne i odpowiedzi efemeryczne, łącznie z endpointami callbacku interakcji, follow-up i original-response. Zobacz Komponenty wiadomości.

Co zwraca 501 (akceptowane, niezaimplementowane)

  • PATCH .../voice-states/* z deaf. Serwerowe wyciszenie dźwięku nie jest obecnie prymitywem w SFU serwerów hostowanych samodzielnie. Wyciszenie mikrofonu, przeniesienie (przez channel_id) i rozłączenie (przez channel_id: null) działają.
  • PUT .../channels/{id}/permissions/{oid}. Serwery hostowane samodzielnie używają uprawnień na poziomie grup zamiast nadpisań kanałów, więc nie ma do czego zastosować nadpisania Discorda. DELETE zwraca 204 (usunięcie nieistniejącego nadpisania nic nie robi).
  • PATCH .../guilds/{id}/vanity-url. Serwery hostowane samodzielnie nie mają własnych URL-i (vanity).

Co zwraca 404 (nieroutowane na serwerach hostowanych samodzielnie)

Te endpointy dotyczą zasobów, które istnieją tylko w infrastrukturze chmurowej. Jeśli twój bot ich potrzebuje, wywołaj je dla gildii w chmurze.

  • Tworzenie kanałów wiadomości bezpośrednich (POST /users/@me/channels).
  • Wyszukiwanie użytkowników między serwerami (GET /users/{id}, GET /users/by-name/{name}).
  • GET /users/@me/guilds.

Zdarzenia gatewaya

Serwery hostowane samodzielnie publikują podzbiór zdarzeń wysyłanych przez chmurę. Twój bot otrzymuje je w tej samej sesji gatewaya. Model subskrypcji jest taki sam.

Obecnie wysyłane z serwerów hostowanych samodzielnie:

  • MESSAGE_CREATE, MESSAGE_UPDATE, MESSAGE_DELETE, MESSAGE_DELETE_BULK
  • MESSAGE_REACTION_ADD, MESSAGE_REACTION_REMOVE
  • CHANNEL_CREATE, CHANNEL_UPDATE, CHANNEL_DELETE
  • CHANNEL_PINS_UPDATE
  • GUILD_UPDATE (zmiany nazwy / opisu)
  • GUILD_MEMBER_ADD, GUILD_MEMBER_REMOVE, GUILD_MEMBER_UPDATE (zmiana pseudonimu lub roli)
  • GUILD_BAN_ADD, GUILD_BAN_REMOVE
  • GUILD_ROLE_CREATE, GUILD_ROLE_UPDATE, GUILD_ROLE_DELETE (wysyłane, gdy zmienia się model uprawnień serwera)
  • TYPING_START
  • VOICE_STATE_UPDATE (dołączenie, wyjście, wyciszenie własne/serwerowe, wyciszenie dźwięku)
  • INTERACTION_CREATE (komendy ukośnikowe, kliknięcia komponentów i wysłane okna modalne; przekazywane przez chmurę)

Jeszcze niewysyłane z serwerów hostowanych samodzielnie:

  • PRESENCE_UPDATE. Wymaga nowego nadajnika obecności na serwerach hostowanych samodzielnie.
  • Zdarzenia wiadomości bezpośrednich. Serwery hostowane samodzielnie nie mają wiadomości bezpośrednich między serwerami.

Znane rozbieżności

  • Wyciszenie własne a serwerowe: SFU na serwerach hostowanych samodzielnie śledzi jeden bit wyciszenia na uczestnika, zamiast rozdzielać self_mute i mute jak Discord. VOICE_STATE_UPDATE wpisuje tę samą wartość do obu pól; zdjęcie wyciszenia serwerowego może wyglądać tak, jakby użytkownik również wyłączył własne wyciszenie. Boty czytające tylko jedno z tych pól nie mają problemu; boty z maszyną stanów, które je łączą, powinny przy przełącznikach moderatora preferować mute.
  • Przeniesienie na kanale głosowym wywołuje dwa zdarzenia: PATCH Discorda na voice-states/{uid} z nowym channel_id wysyła jedno VOICE_STATE_UPDATE; na serwerach hostowanych samodzielnie przeniesienie jest realizowane jako wyjście + ponowne dołączenie, więc zobaczysz, jak channel_id użytkownika na chwilę zmienia się na null, a potem na nowy kanał. Traktuj kolejne aktualizacje tego samego użytkownika w odstępie kilkuset milisekund jako jedno przeniesienie.

Wykrywanie serwerów hostowanych samodzielnie

Obiekt guild nie ma obecnie flagi „hostowany samodzielnie” (zachowujemy identyczność bajt w bajt z Discordem). Jeśli twój bot musi rozróżniać te przypadki, niezawodnym sygnałem jest 501 lub 404 z jednego z powyższych endpointów, z treścią błędu JSON w rodzaju:

{ "code": 0, "message": "voice-state modify not supported on self-hosted yet" }

Jeśli tańszego wykrywania będzie potrzebować wystarczająco dużo botów, dodamy wpis features (np. "SELF_HOSTED") do payloadu gildii. Jeśli by ci to pomogło, zostaw opinię w zakładce Wsparcie swojej aplikacji.

Błędy

  • 502 Bad Gateway. Serwer hostowany samodzielnie zwrócił nieprawidłową odpowiedź. Rzadkie; zwykle rozbieżność wersji podczas aktualizacji.
  • 503 Service Unavailable. Kanał kontrolny nie jest obecnie połączony. Ponów z wykładniczym opóźnieniem (backoff).
  • 504 Gateway Timeout. Serwer nie odpowiedział w ciągu 12 s.

← Powrót do dokumentacji